1. 断言到底是个什么东西1.1 从一句日常对话理解断言你肯定听过这样的对话——“这杯奶茶是常温的吧”“对我摸过了不烫。”这个“我摸过了”就是一次断言说话的人基于自己的判断给出了一个确定性的结论并且这个结论一旦被后续事实推翻那前面的对话就出问题了。Python 里的assert干的就是类似的事。它的语法简单到不能再简单assert 条件表达式, 条件不成立时想说的话翻译成人话就是我笃定这个条件表达式的结果是True如果不是那就抛出一个AssertionError顺便把我留的那句话带出来。比如def calculate_discount(price, discount): assert 0 discount 1, f折扣率必须在0到1之间当前是{discount} return price * (1 - discount)调用calculate_discount(100, 1.5)的时候程序会直接炸掉告诉你折扣率不对。这就是断言最朴素的用法——在代码的关键位置埋一个“检查站”一旦有人传了不该传的参数立刻报警而不是让错误的数据继续往下跑最后在一个八竿子打不着的地方报一个莫名其妙的错。很多人第一次学断言的时候会觉得这不就是if not 条件: raise的简写吗没错从行为上看确实很像但断言的定位和使用场景跟普通的异常处理有本质区别这个区别后面会展开讲这里先记住一句话断言是给开发者自己看的不是给用户看的。1.2 断言和异常处理的本质区别新手最容易犯的错就是把assert当成if raise的替代品到处用。我见过有人这么写def withdraw(balance, amount): assert amount 0, 取款金额必须大于0 assert amount balance, 余额不足 return balance - amount这段代码在测试的时候跑得好好的一上线就出事了。为什么因为 Python 在优化模式python -O下运行的时候所有的 assert 语句会被整体移除相当于这些检查根本不存在。用户输入一个负数金额程序不但不报错还会把余额加上去。这就是断言和异常处理最核心的区别对比维度assert 断言if raise 异常设计目的检查“不可能发生”的情况处理“可能发生”的错误面向对象开发者自己最终用户或调用方优化模式下被完全移除正常执行适用场景内部逻辑自检、调试输入校验、业务规则错误性质代码有bug运行环境或输入有问题判断该用哪个的标准其实很简单如果这个条件不成立说明代码写错了用 assert如果这个条件不成立说明调用方用错了或者环境有问题用 raise。比如一个函数内部计算出来的中间结果按理说一定是正数如果出现负数那肯定是前面的逻辑写错了这种用 assert。而用户传来的参数你不能假设用户一定传对这种必须用 if raise。1.3 为什么进阶语法里要单独讲断言基础教程讲断言通常两句话就带过了assert 条件条件不成立就报错。但实际项目里断言的使用有很多讲究用得好能让代码质量上一个台阶用不好就是给自己埋雷。进阶的地方体现在几个方面。第一是断言的开关机制-O和-OO参数对断言的影响以及__debug__这个内置常量的用法。第二是断言在单元测试、契约式设计、类型收窄等场景下的高级应用。第三是断言的性能考量什么时候该用、什么时候不该用用错了会带来什么后果。第四是断言和日志、异常、类型提示这些机制的配合使用。这些内容在基础教程里基本不会涉及但在实际开发中天天都会遇到。我见过太多项目因为断言用得不对要么上线后检查全部失效要么在热路径里塞了一堆断言导致性能下降。所以单独拿出来讲一讲把踩过的坑和总结的经验都倒出来。2. 断言的底层机制与开关控制2.1debug常量与 -O 参数的关系Python 里有一个内置常量叫__debug__它的值在正常情况下是True。当你用python -O启动解释器的时候它变成False。而assert语句在编译成字节码的时候会被翻译成类似这样的逻辑if __debug__: if not 条件表达式: raise AssertionError(错误信息)也就是说assert本质上是一个被__debug__包起来的条件判断。当__debug__为False时整个判断连同里面的raise一起被优化掉连字节码都不会生成。你可以自己验证一下。写一个简单的脚本# test_assert.py assert 1 2, 这行会报错 print(程序继续执行)正常跑python test_assert.py会看到AssertionError。跑python -O test_assert.py会直接打印“程序继续执行”断言完全消失。这个机制的设计初衷是开发阶段打开断言做各种检查生产环境关掉断言提升性能。因为断言检查本身也是要消耗 CPU 的尤其是一些复杂的条件判断在热路径里频繁执行会影响性能。但这里有个坑很多人以为-O只是关掉断言实际上它还会影响其他东西。比如__debug__的值变了如果你的代码里有依赖__debug__的逻辑行为会不一致。另外-OO除了关断言还会去掉文档字符串docstring进一步减小内存占用。2.2 断言在字节码层面长什么样用dis模块可以直观地看到断言编译后的字节码。拿这段代码举例import dis def check(x): assert x 0, x必须为正数 return x dis.dis(check)输出大概是这样不同 Python 版本略有差异4 0 LOAD_GLOBAL 0 (AssertionError) 2 LOAD_CONST 1 (x必须为正数) 4 LOAD_FAST 0 (x) 6 LOAD_CONST 2 (0) 8 COMPARE_OP 4 () 10 POP_JUMP_IF_TRUE 18 12 RAISE_VARARGS 2 18 LOAD_FAST 0 (x) 20 RETURN_VALUE可以看到断言被编译成了加载AssertionError、加载错误信息、做比较、条件跳转、抛出异常这一系列操作。如果条件成立就跳过抛出继续往下执行。再用-O模式编译看看import dis def check(x): assert x 0, x必须为正数 return x dis.dis(check)在-O模式下assert那一行对应的字节码会完全消失只剩下return x的部分。这就是断言“零成本”的真相——不是运行时判断后跳过而是编译时直接不生成代码。理解这一点很重要因为它意味着断言里的表达式如果有副作用在-O模式下这些副作用会消失。比如assert self.check_and_log(x)如果check_and_log除了返回布尔值还做了日志记录那在优化模式下日志也不会记了。所以断言里绝对不要放有副作用的表达式。2.3 什么时候该关断言什么时候不该关关于生产环境要不要关断言社区里一直有争论。我的经验是分情况建议关断言的场景性能敏感的热路径比如每秒调用几万次的核心函数断言条件本身计算成本很高比如遍历一个大列表做检查已经通过单元测试充分验证过的稳定代码建议保留断言的场景关键业务逻辑的前置条件检查出错代价很大调试阶段的问题定位断言能快速暴露问题对外提供的库函数帮助调用方尽早发现误用实际操作中我通常的做法是开发环境和测试环境保留断言生产环境根据性能测试结果决定。如果性能测试显示断言开销可以忽略那就保留如果断言占了可观的 CPU 时间那就关掉。还有一个折中方案用if __debug__手动控制而不是依赖-O参数。这样可以在代码层面精细控制哪些检查在什么环境下生效if __debug__: # 这里放昂贵的检查逻辑 assert expensive_check(data)这样即使不用-O参数也能通过其他方式控制__debug__的值比如在启动脚本里设置比全局的-O更灵活。注意不要依赖-O参数来关闭断言作为安全手段。如果你的代码正确性依赖断言来保证那本身就是设计问题。断言是开发辅助工具不是运行时保护机制。3. 断言在真实项目中的典型用法3.1 前置条件与后置条件检查契约式设计Design by Contract是一个很老但很有用的概念。简单说就是每个函数都有前置条件和后置条件前置条件是调用方必须满足的后置条件是函数保证会满足的。断言就是实现这种契约的工具。前置条件检查def binary_search(sorted_list, target): assert isinstance(sorted_list, list), 必须传入列表 assert all(sorted_list[i] sorted_list[i1] for i in range(len(sorted_list)-1)), 列表必须有序 # 二分查找逻辑...后置条件检查def sort_list(data): result sorted(data) assert len(result) len(data), 排序后长度不变 assert all(result[i] result[i1] for i in range(len(result)-1)), 结果必须有序 return result前置条件检查的是“调用方有没有按规矩来”后置条件检查的是“函数自己有没有兑现承诺”。后置条件在调试阶段特别有用能帮你快速定位是哪个函数产生了不符合预期的结果。但要注意后置条件的检查成本往往比前置条件高。上面那个all(...)的检查是 O(n) 的如果排序本身是 O(n log n)那后置检查的开销相对可以接受。但如果函数本身是 O(1) 的加一个 O(n) 的后置检查就得不偿失了。我的经验是前置条件可以适当多写后置条件只在关键函数和调试阶段写。前置条件通常检查的是参数类型、范围、格式成本低后置条件往往要遍历结果成本高。3.2 类型收窄与类型提示的配合Python 3.5 之后有了类型提示type hints但类型提示只是给静态检查工具看的运行时并不强制。断言可以在运行时做类型收窄让后续代码更安全。from typing import Union, List def process_items(items: Union[List[int], None]) - int: assert items is not None, items不能为None # 到这里类型检查器知道 items 是 List[int] return sum(items)这种写法在配合 mypy 等静态检查工具时特别有用。assert items is not None之后mypy 会自动把items的类型从Optional[List[int]]收窄为List[int]后续代码就不需要反复判断 None 了。类似的还有def get_config(key: str) - Union[str, int, None]: value config.get(key) assert isinstance(value, str), f配置项{key}必须是字符串 return value.upper() # 这里 value 被收窄为 str这种用法的好处是既做了运行时检查又帮助了静态类型检查一举两得。而且这种断言通常成本很低isinstance和is not None都很快保留在生产环境也不会有明显性能影响。不过要注意类型收窄的断言不要写得太复杂否则静态检查器可能识别不了。比如assert type(x) int和assert isinstance(x, int)在类型收窄上的效果就不一样后者更通用。3.3 单元测试中的断言策略写单元测试的时候断言是核心工具。但测试里的断言和业务代码里的断言用法不太一样。业务代码里的断言是“我假设这是对的如果不对说明有bug”。测试里的断言是“我验证这是对的如果不对说明测试失败”。虽然底层都是assert但语义不同。测试里常见的断言写法def test_calculate_discount(): # 正常情况 assert calculate_discount(100, 0.5) 50 # 边界情况 assert calculate_discount(100, 0) 100 assert calculate_discount(100, 1) 0 # 异常情况 try: calculate_discount(100, 1.5) assert False, 应该抛出异常但没有 except AssertionError: pass但直接用assert写测试有个问题断言失败的时候错误信息不够详细。比如assert result expected失败你只知道不相等但不知道实际值是多少。所以专业的测试框架如 pytest提供了更丰富的断言方式def test_with_pytest(): result calculate_discount(100, 0.5) assert result 50, f期望50实际{result}或者用 pytest 的approx做浮点数比较from pytest import approx def test_float(): assert calculate_discount(100, 0.333) approx(66.7, abs0.1)在测试里我建议尽量用测试框架提供的断言工具而不是裸assert。因为测试框架的断言会提供更详细的失败信息还能做智能 diff定位问题快很多。另外测试里的断言不受-O参数影响因为测试通常不会用-O模式跑。但如果你用python -O -m pytest跑测试那测试里的assert也会被移除测试就全通过了——这显然不是你想要的结果。所以跑测试的时候千万别加-O。4. 断言的常见误用与避坑指南4.1 把断言当输入校验用这是最常见也最危险的误用。前面已经提过-O模式下断言会消失所以用断言做输入校验等于没做校验。错误示范def create_user(username, age): assert isinstance(username, str), 用户名必须是字符串 assert isinstance(age, int) and age 0, 年龄必须是正整数 # 创建用户逻辑...正确做法def create_user(username, age): if not isinstance(username, str): raise TypeError(用户名必须是字符串) if not isinstance(age, int) or age 0: raise ValueError(年龄必须是正整数) # 创建用户逻辑...判断标准很简单如果这个检查在优化模式下消失会导致程序行为错误那就不能用断言。输入校验、权限检查、业务规则验证这些都不能用断言。那断言能用在哪用在“如果这里不成立说明我前面的代码写错了”的地方。比如一个函数内部计算出来的索引按理说一定在合法范围内如果越界了说明前面的计算逻辑有bug这种可以用断言。4.2 在断言里放有副作用的表达式前面提过-O模式下断言里的表达式根本不会执行。所以如果表达式有副作用行为会不一致。错误示范assert save_to_database(data), 保存失败正常模式下会执行save_to_database优化模式下不会执行。这会导致数据丢失而且很难排查。正确做法result save_to_database(data) assert result, 保存失败这样无论是否优化模式save_to_database都会执行断言只负责检查结果。类似的还有assert len(process_items(items)) 0 # process_items 有副作用 assert self.validate_and_update() # validate_and_update 有副作用 assert log_and_check(x) # log_and_check 有副作用这些写法都要改成先执行、再断言结果。4.3 断言信息写得太随意断言失败时的错误信息很重要它直接决定了你排查问题的速度。但很多人写断言信息很随意比如assert x 0, 错误 assert isinstance(data, dict), 类型不对 assert len(items) expected, 长度不匹配这些信息在排查问题时几乎没用。好的断言信息应该包含期望什么、实际是什么、在什么上下文下。改进版assert x 0, fx必须为正数当前值{x} assert isinstance(data, dict), fdata必须是字典当前类型{type(data).__name__} assert len(items) expected, fitems长度应为{expected}实际为{len(items)}更进一步可以在断言信息里加上函数名、参数值等上下文def process(data, threshold): assert threshold 0, fprocess: threshold必须为正数当前值{threshold}data长度{len(data)}这样一看错误信息就知道是哪个函数、哪个参数出了问题不用再去翻代码。提示断言信息里不要用太复杂的表达式因为断言信息只在断言失败时才会被求值但有些 Python 实现可能会提前求值。简单直接的 f-string 是最稳妥的。4.4 在热路径里滥用断言断言的执行是有成本的。一个简单的assert x 0可能只消耗几十纳秒但如果放在每秒调用百万次的函数里累积起来就很可观了。我做过一个测试在一个简单的循环里加断言和不加断言性能差异大概在 5% 到 15% 之间具体取决于断言条件的复杂度。如果断言里包含函数调用、属性访问、列表遍历开销会更大。# 热路径每秒调用百万次 def hot_function(x): assert x 0, x不能为负 # 这个断言在优化模式下会消失但开发模式下有开销 return x * 2对于这种情况我的建议是热路径里的断言确保在-O模式下会被移除如果必须保留检查用if raise而不是assert这样至少行为是一致的定期用性能分析工具如 cProfile检查断言的开销import cProfile def with_assert(): for i in range(1000000): assert i 0 _ i * 2 def without_assert(): for i in range(1000000): _ i * 2 cProfile.run(with_assert()) cProfile.run(without_assert())跑一下就能看到断言的实际开销。如果开销占比很小比如小于 1%那保留也无妨如果占比明显就要考虑优化了。4.5 断言与日志的混淆有些人用断言来记录日志比如assert log_and_check(x), 检查失败这又是副作用的问题。而且断言失败会抛异常中断程序执行而日志通常不应该中断程序。正确的做法是分开处理if not check(x): logger.warning(f检查失败x{x}) # 根据情况决定是否继续断言和日志的定位不同断言是“这里出问题了程序不能再继续了”日志是“这里发生了什么事记录下来备查”。不要混用。5. 断言的高级技巧与实战经验5.1 自定义断言函数减少重复如果项目里有很多类似的断言可以封装成自定义函数def assert_positive(value, namevalue): assert value 0, f{name}必须为正数当前值{value} def assert_type(value, expected_type, namevalue): assert isinstance(value, expected_type), \ f{name}必须是{expected_type.__name__}当前类型{type(value).__name__} def assert_range(value, min_val, max_val, namevalue): assert min_val value max_val, \ f{name}必须在[{min_val}, {max_val}]范围内当前值{value}用的时候def calculate(price, quantity, discount): assert_positive(price, price) assert_positive(quantity, quantity) assert_range(discount, 0, 1, discount) return price * quantity * (1 - discount)这样代码更简洁断言信息也更统一。但要注意自定义断言函数本身也是函数调用有额外开销。如果在意性能可以用if __debug__包起来if __debug__: assert_positive(price, price)这样在优化模式下连函数调用都省了。5.2 用断言做契约测试契约测试是验证模块之间接口约定的一种测试方法。断言可以在契约测试里发挥很大作用。假设有两个模块 A 和 BA 调用 B 的接口。契约是B 的接口接收一个字典返回一个列表。可以在 B 的接口里加断言def b_interface(data): assert isinstance(data, dict), f输入必须是字典实际{type(data)} assert key in data, 输入必须包含key字段 result process(data) assert isinstance(result, list), f输出必须是列表实际{type(result)} return result然后在 A 的测试里用各种边界情况调用 B验证契约是否被遵守。这样一旦 B 的接口行为变了契约测试会立刻失败比等到集成测试才发现问题要早得多。5.3 断言在数据管道中的应用数据管道data pipeline里数据质量检查非常重要。断言可以用在管道的各个阶段确保数据符合预期。def clean_data(df): assert not df.empty, 数据框不能为空 assert df[id].is_unique, id列必须唯一 assert df[age].between(0, 150).all(), age列存在非法值 # 清洗逻辑... return df def transform_data(df): assert set(df.columns) {id, name, age}, 缺少必要列 # 转换逻辑... return df这种用法在调试阶段特别有用能快速定位是哪个阶段的数据出了问题。但在生产环境如果数据量很大断言的检查成本可能很高比如is_unique要遍历整列这时候就要考虑用采样检查或者只在关键节点检查。我的经验是数据管道的入口和出口加断言中间环节根据数据量和性能要求决定。入口检查确保输入数据符合预期出口检查确保输出数据没有异常。中间环节如果数据量不大可以多加如果数据量很大就只加关键检查。5.4 断言与类型系统的边界Python 的类型系统越来越强大typing模块提供了很多工具。断言和类型系统怎么配合有一些经验可以分享。对于简单的类型收窄assert isinstance(x, SomeType)就够了。对于更复杂的类型比如TypedDict、Literal、Union断言可能就不太够用了。from typing import Literal, TypedDict class Config(TypedDict): mode: Literal[debug, release] level: int def process_config(config: Config): assert config[mode] in (debug, release), mode值非法 assert isinstance(config[level], int), level必须是整数 # 处理逻辑...这种写法在运行时做了检查但静态检查器可能还是需要额外的类型注解才能完全理解。实际项目中我通常把断言和类型提示结合使用类型提示给静态检查器看断言给运行时兜底。但要注意断言不能替代类型检查。assert isinstance(x, int)在-O模式下会消失而类型错误可能在运行时导致各种奇怪的问题。所以对于关键的类型检查还是用if raise更稳妥。5.5 断言在调试中的实战技巧调试的时候断言是一个很好的工具。可以在怀疑有问题的地方加断言快速定位问题。比如怀疑某个变量在某个时刻应该是特定值def complex_calculation(data): intermediate step1(data) assert intermediate 0, fstep1结果异常{intermediate} result step2(intermediate) assert result 1000, fstep2结果异常{result} return result这样一旦某一步的结果不符合预期立刻就能知道是哪一步出了问题不用一步步打印日志。另一个技巧是用断言做“不可能到达”的标记def process_status(status): if status active: return handle_active() elif status inactive: return handle_inactive() else: assert False, f未知状态{status}这种写法比raise ValueError更明确地表达了“这里不应该被执行到”的意图。当然如果status是用户输入的那还是用raise更合适。还有一个技巧是用断言检查循环不变量def find_max(items): assert len(items) 0, 列表不能为空 max_val items[0] for i in range(1, len(items)): assert max_val max(items[:i]), f循环不变量被破坏i{i} if items[i] max_val: max_val items[i] return max_val这种断言在调试复杂算法时特别有用能帮你验证算法的正确性。当然这种断言的性能开销很大max(items[:i])是 O(n) 的只在调试时用生产环境一定要关掉。6. 断言相关常见问题速查6.1 断言失败时如何获取更多信息默认的AssertionError信息很有限只有你写的那句话。如果想获取更多信息可以在断言信息里包含关键变量值用traceback模块打印调用栈在断言失败时触发调试器import traceback def check(x): try: assert x 0, fx必须为正数当前值{x} except AssertionError: traceback.print_exc() # 或者触发调试器 # import pdb; pdb.post_mortem() raise6.2 断言在多线程环境下的注意事项断言本身是线程安全的就是普通的条件判断但断言检查的条件可能涉及共享状态这时候要注意竞态条件。# 不安全的断言 assert len(shared_list) 0, 列表不能为空 # 在断言和后续操作之间其他线程可能修改了 shared_list item shared_list.pop()这种场景下断言只能作为调试辅助不能作为线程安全的保证。真正的线程安全要靠锁机制。6.3 断言与代码覆盖率的关系断言语句也会被代码覆盖率工具统计。如果断言在测试中没有失败过覆盖率工具会认为断言语句被执行了但不会知道断言条件是否被充分测试。比如assert x 0如果测试里只传了正数覆盖率显示这行被执行了但负数的情况没测到。所以覆盖率不能完全代表测试质量断言的边界情况要单独设计测试用例。6.4 常见问题速查表问题现象可能原因解决方法生产环境断言不生效用了-O参数启动检查启动参数确认是否需要保留断言断言里的函数没执行-O模式下断言被移除把有副作用的操作移到断言外面断言失败但信息不足断言信息写得太简单在信息里包含变量值、类型、上下文断言影响性能热路径里断言条件太复杂用if __debug__包起来或改用if raise断言和异常处理混淆用断言做输入校验输入校验用if raise断言只做内部检查测试里断言不生效用-O模式跑测试跑测试时不要加-O参数断言条件有副作用在断言里调用有副作用的函数先执行函数再断言结果6.5 我踩过的几个坑第一个坑曾经在一个数据处理脚本里用断言检查数据格式本地跑得好好的部署到服务器上因为启动脚本带了-O参数所有检查都失效了脏数据直接进了数据库。后来改成if raise才解决。第二个坑在一个性能敏感的函数里加了一个遍历列表的断言本地测试数据量小没感觉上线后数据量大了断言成了性能瓶颈。后来用if __debug__包起来生产环境自动跳过。第三个坑断言信息写得太简单线上出问题的时候只看到“检查失败”四个字完全不知道是哪个数据出了问题。后来养成习惯断言信息里一定带上关键变量的值。第四个坑在断言里调用了会修改状态的函数结果在-O模式下状态没被修改导致后续逻辑出错。这个坑最隐蔽因为开发环境一切正常只有生产环境才出问题。这些坑总结起来就是一句话断言是开发工具不是运行时机制。用的时候时刻想着“这行代码在优化模式下会消失”就不会出大问题。7. 断言的最佳实践清单7.1 该用断言的场景函数内部的不变量检查比如循环不变量、状态机状态前置条件检查确认调用方传入了符合预期的参数仅限内部函数后置条件检查确认函数返回了符合预期的结果调试阶段类型收窄配合静态类型检查器使用单元测试中的结果验证调试阶段的问题定位7.2 不该用断言的场景用户输入校验权限检查业务规则验证任何在优化模式下消失会导致程序行为错误的检查有副作用的表达式性能敏感的热路径除非用if __debug__包起来7.3 写断言的几个习惯断言信息里带上关键变量的值断言条件尽量简单避免复杂表达式自定义断言函数减少重复定期检查断言的性能开销生产环境根据情况决定是否保留断言7.4 团队协作中的断言规范如果是团队项目建议在代码规范里明确断言的用法什么情况下用assert什么情况下用if raise断言信息的格式要求生产环境是否保留断言断言在代码审查中的检查要点我们团队的做法是在CONTRIBUTING.md里写清楚断言的用法代码审查时重点看有没有把断言当输入校验用、有没有在断言里放副作用、断言信息是否足够详细。这样能避免很多低级错误。断言这个语法点看起来简单但真正用好需要对这些细节有深入理解。我在实际项目里见过太多因为断言用错导致的问题希望这些经验能帮你少走弯路。记住核心原则断言是给开发者自己看的是调试工具不是运行时保护机制。想清楚这一点大部分误用都能避免。