很多开发者对 assert 的理解停留在"写个检查，报错就停"的层面，但它在 Python 里有明确的设计意图和使用边界。搞清楚这些，你才能在调试、测试和文档化代码时真正发挥它的价值，而不是在生产环境里埋雷。
assert 到底做了什么
assert 语句的完整语法是：
assert expression, message
如果 expression 为假，抛出 AssertionError，并把 message 作为错误信息；如果为真，什么都不发生。本质上它等价于：
if __debug__:
if not expression:
raise AssertionError(message)
关键点在于 __debug__。这个内置常量默认为 True，但当 Python 以优化模式运行时（python -O 或 python -OO），__debug__ 变为 False，所有 assert 语句会被编译器完全跳过，连判断都不执行。
这意味着：assert 不是通用的错误处理工具，它是一个可被全局关闭的调试断言。
什么时候该用 assert
内部不变量：验证你的逻辑假设
当你写了一段逻辑，心里有明确的假设——"到这里，列表一定已经排序了"、"这个字典的 key 一定存在"——用 assert 把假设写出来：
def merge_ranges(ranges):
"""合并重叠的区间，要求输入已按起始位置排序。"""
assert all(ranges[i][0] <= ranges[i+1][0] for i in range(len(ranges)-1)), \
"ranges must be sorted by start position"
merged = [ranges[0]]
for start, end in ranges[1:]:
last_start, last_end = merged[-1]
if start <= last_end:
merged[-1] = (last_start, max(last_end, end))
else:
merged.append((start, end))
return merged
这个 assert 的作用不只是检查——它同时充当文档，告诉读者"调用前必须排序"。比写一行注释更可靠，因为注释会过期，assert 会在调试阶段替你报警。
测试中的快速断言
在单元测试里，assert 是最直接的验证手段。即使你用 pytest，底层也是 assert：
def test_parse_config():
config = parse_config("port: 8080\nhost: localhost")
assert config["port"] == 8080
assert config["host"] == "localhost"
assert len(config) == 2
pytest 会重写 assert 语句，让失败信息更详细，但写法不变。这是 Python 测试生态的核心约定。
契约式编程的前置/后置条件
如果你在设计一个模块，想在接口边界处声明"调用方必须满足的条件"和"我保证返回的结果"，assert 是最轻量的实现方式：
def discount(price, rate):
"""计算折扣价。price > 0, 0 < rate <= 1。"""
assert price > 0, f"price must be positive, got {price}"
assert 0 < rate <= 1, f"rate must be in (0, 1], got {rate}"
result = price * rate
assert result < price, "discounted price must be less than original"
return result
前置条件约束调用方，后置条件约束自己。开发阶段这些断言帮你快速定位违约，上线时 -O 一关，零开销。
什么时候不该用 assert
不要用 assert 做数据验证
用户输入、文件内容、API 响应——这些外部数据不可控，验证逻辑不能被优化模式跳过：
# ❌ 错误用法：生产环境 -O 后这行直接消失
assert request.headers.get("Authorization"), "Missing auth header"
# ✅ 正确做法：用显式异常
if not request.headers.get("Authorization"):
raise UnauthorizedError("Missing auth header")
不要用 assert 处理可恢复的错误
assert 夺走的是程序的控制流——它直接抛异常、终止执行。如果错误是业务逻辑的一部分（比如"库存不足，提示用户换商品"），应该用正常的异常或返回值处理，而不是 assert。
不要让 assert 有副作用
因为 -O 模式会跳过整个 assert 语句，如果表达式里包含副作用，优化模式下行为会变：
# ❌ 危险：-O 模式下 write_log 不会被调用
assert write_log("operation completed"), "log write failed"
# ✅ 安全：先执行，再断言结果
result = write_log("operation completed")
assert result, "log write failed"
实战：一个可运行的调试断言模板
下面是一个完整的、可以直接运行的小项目，演示 assert 在开发调试中的几种典型用法：
"""
assert_demo.py — Python assert 使用模式演示
运行方式：python assert_demo.py
优化模式：python -O assert_demo.py（观察断言被跳过的效果）
"""
def validate_batch(batch_id, items):
"""处理一批任务，演示 assert 的三种典型用法。"""
# 1. 前置条件：验证调用方传入的数据结构符合预期
assert isinstance(batch_id, str) and batch_id.startswith("B-"), \
f"batch_id must start with 'B-', got '{batch_id}'"
assert isinstance(items, list) and len(items) > 0, \
f"items must be a non-empty list, got {type(items)} with len={len(items)}"
# 2. 内部不变量：循环中验证中间状态
processed = []
for item in items:
result = process_item(item)
# 每次迭代后确认结果结构正确
assert "status" in result and result["status"] in ("ok", "skip"), \
f"unexpected result structure: {result}"
processed.append(result)
# 3. 后置条件：确认返回值满足承诺
assert len(processed) == len(items), \
f"processed count mismatch: {len(processed)} vs {len(items)}"
return {"batch_id": batch_id, "results": processed}
def process_item(item):
"""模拟单个任务处理。"""
if item.get("priority") == "low":
return {"status": "skip", "reason": "low priority"}
return {"status": "ok", "value": item.get("value", 0) * 2}
if __name__ == "__main__":
# 正常调用——断言全部通过
batch = [
{"priority": "high", "value": 10},
{"priority": "low", "value": 5},
{"priority": "medium", "value": 7},
]
result = validate_batch("B-001", batch)
print(f"✅ 正常流程: {result}")
# 触发前置条件断言——取消注释后运行会报 AssertionError
# validate_batch("X-999", batch) # batch_id 不以 B- 开头
# 触发内部不变量断言——取消注释后运行会报错
# validate_batch("B-002", [{"unknown_key": 1}]) # process_item 返回不含 status
# 对比：用 python -O 运行本文件，上面所有 assert 都不执行
# "X-999" 会静默通过，不再报错——这就是为什么数据验证不能用 assert
运行方式：
# 正常模式，断言生效
python assert_demo.py
# 优化模式，断言被跳过——观察行为差异
python -O assert_demo.py
用 -O 运行时，你会发现所有 assert 行被完全忽略。这正是理解 assert 边界的最佳方式：亲手跑一遍，看断言消失后程序的行为。
使用 assert 的决策清单
每次写 assert 之前，过一遍这四个问题：
| 问题 | 是 → 用 assert | 否 → 用 if + raise |
|---|---|---|
| 检查的是内部逻辑假设，不是外部数据？ | ✅ | ❌ |
| 断言失败意味着程序有 bug，不是业务异常？ | ✅ | ❌ |
| 表达式没有副作用（不修改状态、不做 IO）？ | ✅ | ❌ |
| 生产环境里跳过这个检查是可接受的？ | ✅ | ❌ |
四个全"是"，写 assert；任何一个"否"，换成显式的 if + raise。
assert 的价值不在于它多强大，而在于它精确地做了该做的事：在开发阶段替你守住逻辑假设，在上线时优雅地退场。用对地方，它是代码里最诚实的注释；用错地方，它就是生产环境里最隐蔽的漏洞。