实战案例1：接口参数校验中的断言应用

接口参数校验，说白了就是给函数入口装个「安检门」。

我刚开始写Python那会儿，总觉得参数校验是浪费时间。直到有一次，一个接口因为传入了None值，导致整个服务挂了半小时。嗯，从那以后，我再也不敢轻视断言了。

1.1 一个真实的接口场景

假设我们有个用户注册接口。它接收用户名、年龄和邮箱三个参数。看起来很简单对吧？

但实际项目中，你永远不知道调用方会传什么鬼东西进来。空字符串、负数、乱码的邮箱……我见过最离谱的，有人传了个表情符号当用户名。

def register_user(username: str, age: int, email: str) -> dict:
    """
    用户注册接口
    :param username: 用户名，长度2-20，仅含字母数字下划线
    :param age: 年龄，18-120
    :param email: 邮箱，标准格式
    :return: 注册结果
    """
    # 这里先不写断言，看看会发生什么
    user = {
        "username": username,
        "age": age,
        "email": email
    }
    # 假设后续有数据库写入操作
    return {"status": "success", "user": user}

这段代码能跑吗？能。但隐患很大。你想想看，如果age传了个-5，或者username传了个空字符串，后续的逻辑会怎样？

1.2 用断言给参数上锁

我个人习惯，在函数入口处就做断言检查。这叫「防御性编程」——提前把问题扼杀在摇篮里。

def register_user(username: str, age: int, email: str) -> dict:
    """
    用户注册接口（带断言校验）
    """
    # 断言1：用户名不能为空，且长度在2-20之间
    assert username and 2 <= len(username) <= 20, \
        f"用户名长度需为2-20，当前为{len(username)}"
    
    # 断言2：用户名只能包含字母、数字、下划线
    assert username.isalnum() or '_' in username, \
        "用户名只能包含字母、数字和下划线"
    
    # 断言3：年龄必须在18-120之间
    assert isinstance(age, int) and 18 <= age <= 120, \
        f"年龄需为18-120的整数，当前为{age}"
    
    # 断言4：邮箱必须包含@和.
    assert '@' in email and '.' in email.split('@')[-1], \
        f"邮箱格式不正确：{email}"
    
    user = {
        "username": username,
        "age": age,
        "email": email
    }
    return {"status": "success", "user": user}

1.3 断言 vs 异常处理，怎么选？

很多新手会问：断言和try-except有什么区别？

我打个比方你就明白了。断言就像家里的烟雾报警器——它告诉你「着火了，快跑」。异常处理就像灭火器——它告诉你「别慌，我来处理」。

场景	用断言	用异常
参数类型错误	✅ 推荐	❌ 不推荐
参数值超出范围	✅ 推荐	❌ 不推荐
数据库连接失败	❌ 不推荐	✅ 推荐
网络超时	❌ 不推荐	✅ 推荐
用户输入校验	❌ 不推荐	✅ 推荐

1.4 断言在调试中的妙用

断言不只是用来校验参数的。它在调试阶段特别有用。我经常在代码里临时加断言，来验证我的假设是否正确。

def process_data(data: list) -> list:
    """
    处理数据，确保每个元素都是正整数
    """
    # 调试断言：确认输入不为空
    assert data, "数据列表不能为空"
    
    result = []
    for item in data:
        # 调试断言：确认每个元素都是整数
        assert isinstance(item, int), f"元素{item}不是整数"
        
        # 处理逻辑
        processed = item * 2 + 1
        
        # 调试断言：确认处理结果为正数
        assert processed > 0, f"处理结果异常：{processed}"
        
        result.append(processed)
    
    # 调试断言：确认输出长度与输入一致
    assert len(result) == len(data), "输出长度与输入不匹配"
    
    return result

你看，我在关键节点都加了断言。这些断言在开发阶段帮我抓到了不少bug。有一次，我发现某个元素处理完后变成了负数，一查才知道是上游数据出了问题。

1.5 断言的最佳实践总结

做了这么多年项目，我总结了几条断言的使用原则：

• 只检查「不应该发生」的情况——比如参数类型错误、数据状态异常
• 断言信息要写清楚——别写个空字符串，要写明「为什么失败」
• 不要用断言替代异常处理——用户输入校验用异常，内部逻辑校验用断言
• 调试阶段大胆用——我经常在代码里加几十个断言，上线前再酌情保留
• 性能敏感场景慎用——虽然断言很快，但循环里频繁调用还是有开销的

我曾经在一个项目里，因为没加断言，让一个空指针异常在线上跑了三天才被发现。从那以后，我写每个函数都会先问自己：「这个参数可能出什么问题？」然后加个断言兜底。

断言这东西，用好了是神器，用不好就是累赘。关键就一句话：断言是写给开发者看的，不是写给用户看的。

好了，这就是接口参数校验中断言的基本用法。记住，断言是你的调试利器，但别把它当万能药。该用异常的地方，还是得用异常。