架构与系统设计 / 系统课时
用契约测试保护迁移过程
用契约测试保护迁移过程
边界迁移最危险的回归往往不是接口彻底不可用,而是“还能调用,但字段、状态码或错误语义悄悄变了”。本节把消费者真正依赖的可观察行为写成契约,并让旧实现和新实现接受同一套验证,使切换流量前就能发现不兼容变化。
学习目标
- 把上下游依赖转换为可自动执行的接口契约
- 用同一套契约同时验证旧实现和迁移后的新实现
- 区分需要保护的兼容性与会让测试过度脆弱的实现细节
契约只保护消费者真正依赖的行为
契约测试不是把整个响应快照永久冻结,而是明确消费者已经依赖的边界。对一个查询接口,通常至少要保护成功状态码、必需字段、字段类型与含义,以及资源不存在、参数错误等失败场景的状态码和业务错误码。
如果消费者只读取 id、status 和 totalCents,契约就应围绕这些可观察行为,而不是约束服务内部使用哪张表、调用几个领域对象或日志写成什么格式。这样既能阻止破坏性变化,又给新服务保留重构空间。

让新旧实现执行同一套契约
下面的示例把接口行为抽成一个共享断言 assert_contract,再分别传入旧实现和新实现。示例只使用 Python 标准库,可以直接保存为 contract_test.py 执行;真实项目中可以把两个函数替换为 HTTP 客户端或提供方测试适配器。
import unittest
ORDERS = {
"o-1": {"status": "PAID", "totalCents": 1299},
}
def old_get_order(order_id: str):
order = ORDERS.get(order_id)
if order is None:
return 404, {"code": "ORDER_NOT_FOUND"}
return 200, {"id": order_id, **order}
def new_get_order(order_id: str):
order = ORDERS.get(order_id)
if order is None:
return 404, {"code": "ORDER_NOT_FOUND"}
# 新实现可以完全不同,但对消费者暴露的契约必须一致。
return 200, {
"id": order_id,
"status": order["status"],
"totalCents": order["totalCents"],
}
class OrderContract(unittest.TestCase):
def assert_contract(self, handler):
status, body = handler("o-1")
self.assertEqual(200, status)
self.assertEqual({"id", "status", "totalCents"}, set(body))
self.assertIsInstance(body["totalCents"], int)
# 失败场景也属于契约,不能只验证 2xx 响应。
status, body = handler("missing")
self.assertEqual(404, status)
self.assertEqual({"code": "ORDER_NOT_FOUND"}, body)
def test_old_implementation_matches_contract(self):
self.assert_contract(old_get_order)
def test_new_implementation_matches_contract(self):
self.assert_contract(new_get_order)
if __name__ == "__main__":
unittest.main(verbosity=1)预期输出
..
----------------------------------------------------------------------
Ran 2 tests in <TIME>s
OK其中 <TIME> 是测试运行耗时,实际值可能不同。只要任一实现把 totalCents 改成字符串、删除必需字段,或把“订单不存在”改成不同状态码或错误码,这组测试就会失败,从而在切流前暴露不兼容变化。
把字段和错误语义一起纳入边界
迁移时最容易遗漏的是“成功响应一致,但失败行为不同”。消费者可能根据 404 决定展示“订单不存在”,根据特定业务错误码决定是否重试;如果新服务把所有异常都改成 500,即使成功场景结构完全一致,仍然会破坏调用方。
契约因此应覆盖少量高价值场景:一个代表性的成功响应、关键边界值,以及调用方确实分支处理的失败类型。可选字段如果消费者能够忽略,就不要强行做全响应精确相等;金额单位、时间格式、枚举取值等一旦已经成为调用方逻辑,则应明确测试。
把契约放进迁移流水线
契约测试应成为新服务进入灰度环境之前的门禁,而不是上线后的人工检查。一次迁移通常可以按“消费者更新契约 → 旧实现验证 → 新实现验证 → 集成环境验证 → 灰度切流”的顺序推进。这样契约本身也会证明:新实现至少没有破坏当前消费者已经声明的依赖。
当接口需要故意改变时,不要偷偷修改提供方直到测试重新变绿。应先确认消费者是否能够接受新行为,再通过新版本接口、兼容字段或分阶段消费者升级演进契约。契约测试保护的是协作边界,不是阻止接口永远变化。
避免两种假安全
第一种假安全是只做 JSON Schema 验证。它能发现字段类型变化,却不一定知道“取消订单必须返回哪个业务错误码”这类行为语义。第二种假安全是把完整响应快照逐字比较,导致新增一个消费者可以忽略的字段也让测试失败,最终大家倾向于关闭测试。
更有效的契约应尽量小而关键:只锁定消费者正在依赖的字段、状态和错误语义,同时让旧实现与新实现都持续运行。等两边在同一套契约下稳定通过,再进入灰度切流,迁移过程才有可重复的兼容性证据。