接口断言分层：把"200+非空"升级为契约/值/不变式三层，并给弱断言定一个可追踪占比

一、现象与背景：全绿的套件，拦不住一次 0.01 元的差

先摆数字。我做了 5 年测试开发，现在维护一条 B 端 SaaS 核心计费链路，接口自动化是 pytest + httpx 共 1200 条用例，跑在共享 staging，CI 常年全绿。但过去一年线上出了 3 次 P2，复盘下来没有一次是"接口挂了"，全是断言太弱漏掉的：

• 一次是金额比较把 >= 写成 >，少收 0.01 元，断言只写了 assert data["amount"] is not None，根本没比对数值；
• 一次是退款状态机漏判一个 != REFUNDED 分支，接口照样返回 200，断言只验了 200；
• 一次是枚举值从 SUCCESS 悄悄变成了 SUCCEEDED，弱断言没挂任何白名单，自然也就过了。

我抽样统计过：1200 条里有 560 条（约 38%）是"200 + 字段非空"型弱断言，逐字段精确断言只占 9%。弱断言占比越高，"全绿"就越不可信。

二、根因：弱断言校验的是"存在性"，不是"语义正确性"

把三次 P2 归因后，机制很清楚：

1. 断言强度 = 可检测的缺陷空间 / 真实缺陷空间。is not None 的可检测空间极小——字段一存在就过，等于把"接口没崩"当成了"接口正确"。
2. 弱断言抓不住三类高频缺陷：逻辑取反（>= vs >）、边界差一、枚举/分支静默变更。它们共同点是接口不抛异常、返回结构不变，只有"值"变了。
3. 缺一个可追踪的指标。团队都知道"断言要写强"，但没有量化标准，靠人肉 review，铺不动、也守不住。

核心结论：断言要分层，且每一层都有明确、可机检的判据，把"断言有效性"从玄学变成一个可追踪的占比数字。

三、具体做法：契约 / 值 / 不变式 三层断言模型

L1 契约层：用 pydantic 一次校验整个响应结构

不再逐字段 is not None，把接口响应声明成 pydantic v2 模型，一次校验类型 + 必填 + 枚举：

from pydantic import BaseModel, Field
from enum import Enum

class RefundStatus(str, Enum):
    PENDING = "PENDING"
    SUCCESS = "SUCCESS"   # 枚举白名单，SUCCEEDED 会直接 ValidationError

class RefundResp(BaseModel):
    refund_no: str
    status: RefundStatus
    amount: int                       # 单位：分，int 精确
    amount_cents: int = Field(gt=0)   # 值域约束

用例里一行代替 N 行非空断言：

RefundResp.model_validate(resp.json())   # 类型/必填/枚举/值域一次全校验

L2 值层：逐字段精确值 + 精度统一

金额类断言用精确相等，且统一把金额存为 int（分）避免浮点坑：

body = resp.json()
assert body["amount"] == 12345, f"期望 12345 分，实际 {body['amount']}"  # 精确到分
assert body["status"] == RefundStatus.SUCCESS

L3 不变式层：跨字段 / 跨调用的业务规则

这是弱断言最漏的一层：

# 计费不变式：明细之和 == 总额
assert sum(line["amount"] for line in body["lines"]) == body["total"]
# 幂等不变式：同一幂等键重放，结果一致
assert body["refund_no"] == replay["refund_no"]

给"弱断言占比"定一个可追踪指标

在 CI 里扫一遍用例，统计"纯 200 + is not None / 无非空型断言"占比，写进报告并设门禁：

weak_ratio = weak_assertions / total_assertions
assert weak_ratio < 0.20   # 门禁：弱断言占比 < 20%

我们的目标是把弱断言占比从 38% 压到 20% 以下，强断言占比从 9% 提到 60% 以上。

四、踩过的坑 / 反直觉之处

1. 契约层铺开后"假失败"先涨了一波。pydantic 对多余字段敏感，后端返回的冗余空数组 / 调试字段直接 ValidationError。最后和后端约定"契约即接口"，多余字段要么删、要么在模型里显式声明——弱断言没变强，反而先多了噪音，契约层的前提是先和后端对齐契约。
2. 浮点金额用 == 必挂。早期 amount 是 float，断言里反复炸。后来统一后端以"分"为 int 下发，断言全改 int 相等，一整类 flaky 直接消失。
3. 全量改造不现实。1200 条一次性铺到 L3 排期做不完，我们按风险分级：计费 / 退款 / 扣款这 300 条核心用例先做到 L3，4 周落地；其余先做到 L1+L2。先强核心，再铺长尾。

五、结论与可复用清单

弱断言的本质是把"接口没崩"当成"接口正确"。治理不是一次多写几条断言，而是分层 + 定指标 + 按风险铺开。可复用清单：

• 用 pydantic / JSON Schema 建 L1 契约层，一次校验结构，替代 N 行 is not None；
• 金额统一 int（分），L2 值层用精确相等 + 枚举白名单；
• L3 不变式层写跨字段（明细和 == 总额）与跨调用（幂等重放一致）断言；
• CI 里加一个"弱断言占比"门禁（如 <20%），让断言有效性可追踪；
• 按风险分级铺开：核心链路先做到 L3，长尾先做到 L1+L2；
• 契约层落地前，先和后端对齐"契约即接口"，避免假失败。

一句话：断言强度是可以被度量、被治理、被门禁的工程指标，而不是一句"断言写强点"。