从规范到架构解析Python代码审查的实战指南

# ❌ 不推荐：命名不规范，缩进混乱
def Calculate_Total(item_list):
  total=0
  for i in item_list:
      total+=i['price']
  return total

# ✅ 推荐：清晰的命名和格式
def calculate_total(items):
    """计算商品总价"""
    total = 0
    for item in items:
        total += item['price']
    return total

# ❌ 不推荐：含义模糊
def process(d):
    r = []
    for i in d:
        if i['s'] > 100:
            r.append(i)
    return r

# ✅ 推荐：意图清晰
def filter_high_value_orders(orders):
    """筛选金额超过 100 的订单"""
    high_value_orders = []
    for order in orders:
        if order['amount'] > 100:
            high_value_orders.append(order)
    return high_value_orders

# ❌ 危险：未处理空列表和除零
def calculate_average(numbers):
    return sum(numbers) / len(numbers)

# ✅ 安全：完善的边界处理
def calculate_average(numbers):
    """计算平均值，处理边界情况"""
    if not numbers:
        return 0.0
    
    if not all(isinstance(n, (int, float)) for n in numbers):
        raise ValueError("所有元素必须是数字")
    
    return sum(numbers) / len(numbers)

# ❌ 不推荐：捕获过于宽泛
def read_config(file_path):
    try:
        with open(file_path) as f:
            return json.load(f)
    except:  # 捕获所有异常
        return {}

# ✅ 推荐：精确捕获，明确处理
def read_config(file_path):
    """读取配置文件，返回字典"""
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            return json.load(f)
    except FileNotFoundError:
        logger.warning(f"配置文件不存在: {file_path}")
        return {}
    except json.JSONDecodeError as e:
        logger.error(f"配置文件格式错误: {e}")
        raise
    except Exception as e:
        logger.error(f"读取配置文件失败: {e}")
        raise

# ❌ 低效：O(n²) 复杂度
def find_duplicates(items):
    duplicates = []
    for i in range(len(items)):
        for j in range(i + 1, len(items)):
            if items[i] == items[j] and items[i] not in duplicates:
                duplicates.append(items[i])
    return duplicates

# ✅ 高效：O(n) 复杂度
def find_duplicates(items):
    """查找重复元素"""
    seen = set()
    duplicates = set()
    
    for item in items:
        if item in seen:
            duplicates.add(item)
        else:
            seen.add(item)
    
    return list(duplicates)

# ❌ 危险：可能导致文件句柄泄漏
def process_large_file(file_path):
    f = open(file_path)
    data = f.read()  # 如果这里抛异常，文件不会关闭
    return data.split('\n')

# ✅ 安全：自动管理资源
def process_large_file(file_path):
    """处理大文件，逐行读取节省内存"""
    with open(file_path, 'r', encoding='utf-8') as f:
        for line in f:  # 使用迭代器，不一次性加载全部
            yield line.strip()

# ❌ 危险：SQL 注入风险
def get_user(username):
    query = f"SELECT * FROM users WHERE username = '{username}'"
    return db.execute(query)

# ✅ 安全：参数化查询
def get_user(username):
    """安全地查询用户信息"""
    if not isinstance(username, str) or len(username) > 50:
        raise ValueError("无效的用户名")
    
    query = "SELECT * FROM users WHERE username = %s"
    return db.execute(query, (username,))

# ❌ 不安全：缺少权限检查
def delete_user(user_id):
    User.objects.filter(id=user_id).delete()

# ✅ 安全：完善的权限验证
def delete_user(user_id, operator):
    """删除用户，需要管理员权限"""
    if not operator.is_admin:
        raise PermissionError("需要管理员权限")
    
    user = User.objects.filter(id=user_id).first()
    if not user:
        raise ValueError("用户不存在")
    
    if user.is_system_user:
        raise ValueError("不能删除系统用户")
    
    user.delete()
    logger.info(f"管理员 {operator.username} 删除了用户 {user.username}")

# ❌ 职责混乱：一个类做太多事
class UserManager:
    def create_user(self, data):
        # 验证数据
        if not data.get('email'):
            raise ValueError("邮箱必填")
        
        # 发送邮件
        send_email(data['email'], "欢迎注册")
        
        # 保存数据库
        user = User(**data)
        user.save()
        
        # 记录日志
        logger.info(f"创建用户: {data['email']}")

# ✅ 职责分离：每个类专注一件事
class UserValidator:
    @staticmethod
    def validate(data):
        if not data.get('email'):
            raise ValueError("邮箱必填")
        return True

class UserRepository:
    @staticmethod
    def create(data):
        user = User(**data)
        user.save()
        return user

class UserService:
    def __init__(self, validator, repository, notifier):
        self.validator = validator
        self.repository = repository
        self.notifier = notifier
    
    def create_user(self, data):
        self.validator.validate(data)
        user = self.repository.create(data)
        self.notifier.send_welcome_email(user.email)
        logger.info(f"创建用户: {user.email}")
        return user

# ❌ 难以测试：硬编码依赖
class OrderService:
    def process_order(self, order_id):
        order = Database().get_order(order_id)  # 硬编码数据库
        PaymentGateway().charge(order.amount)   # 硬编码支付
        EmailService().send(order.user_email)   # 硬编码邮件

# ✅ 易于测试：依赖注入
class OrderService:
    def __init__(self, db, payment, email):
        self.db = db
        self.payment = payment
        self.email = email
    
    def process_order(self, order_id):
        order = self.db.get_order(order_id)
        self.payment.charge(order.amount)
        self.email.send(order.user_email)

# 测试时可以注入 Mock 对象
def test_process_order():
    mock_db = Mock()
    mock_payment = Mock()
    mock_email = Mock()
    
    service = OrderService(mock_db, mock_payment, mock_email)
    service.process_order(123)
    
    mock_payment.charge.assert_called_once()

# ✅ 好的测试：清晰、独立、覆盖边界
def test_calculate_discount():
    """测试折扣计算逻辑"""
    # 正常情况
    assert calculate_discount(100, 0.1) == 10.0
    
    # 边界情况
    assert calculate_discount(0, 0.1) == 0.0
    assert calculate_discount(100, 0) == 0.0
    assert calculate_discount(100, 1.0) == 100.0
    
    # 异常情况
    with pytest.raises(ValueError):
        calculate_discount(-100, 0.1)
    
    with pytest.raises(ValueError):
        calculate_discount(100, 1.5)

def calculate_compound_interest(principal, rate, time, frequency=1):
    """
    计算复利终值
    
    Args:
        principal (float): 本金
        rate (float): 年利率（小数形式，如 0.05 表示 5%）
        time (int): 投资年限
        frequency (int): 每年复利次数，默认为 1
    
    Returns:
        float: 复利终值
    
    Raises:
        ValueError: 当参数为负数时
    
    Examples:
        >>> calculate_compound_interest(1000, 0.05, 10)
        1628.89
    """
    if principal < 0 or rate < 0 or time < 0:
        raise ValueError("参数不能为负数")
    
    return principal * (1 + rate / frequency) ** (frequency * time)