架构与系统设计 / 系统课时
定义跨模块 API 与数据契约
定义跨模块 API 与数据契约
跨模块协作最容易失控的地方,不是接口数量,而是输入输出、错误语义和数据所有权没有被明确写下。本节用一个最小订单契约把这些边界固定下来,并给出可执行的校验示例。
学习目标
- 能为跨模块调用定义稳定的输入、输出与错误语义
- 能用显式 DTO/事件契约替代共享对象和隐式数据库耦合
- 能判断字段演进与数据所有权是否破坏模块边界
先把边界写成契约
一个可维护的跨模块契约至少要回答四个问题:调用方可以提交什么、成功时拿到什么、失败时如何判断原因、哪一方拥有并修改这些数据。只要其中一项靠“大家都知道”维持,耦合就已经转移到了口头约定里。

最危险的反模式是把 ORM 实体、数据库表结构或“公共对象”直接当接口。这样一来,提供方一次字段重命名、表拆分或内部状态调整,就可能同时破坏多个调用方。
用显式 DTO 固定输入与输出
下面的完整 Python 示例模拟一个订单模块边界。调用方只能提交约定字段;模块内部可以自由调整实现,只要返回的数据契约和错误契约保持兼容。
import json
class ContractError(Exception):
pass
def create_order(payload: dict) -> dict:
allowed = {"customerId", "sku", "quantity"} # 输入字段必须显式声明
unknown = set(payload) - allowed
if unknown:
raise ContractError(f"unsupported fields: {sorted(unknown)}")
quantity = payload.get("quantity")
if not isinstance(quantity, int) or quantity <= 0:
raise ContractError("quantity must be a positive integer")
return { # 持久化与库存校验等实现细节留在模块内部
"data": {
"orderId": "ord-1001",
"status": "CREATED"
},
"error": None
}
def call_api(payload: dict) -> dict:
try:
return create_order(payload)
except ContractError as exc:
return {
"data": None,
"error": {
"code": "INVALID_ARGUMENT",
"message": str(exc)
}
}
if __name__ == "__main__":
print(json.dumps(
call_api({"customerId": "c-7", "sku": "sku-9", "quantity": 2}),
ensure_ascii=False
))
print(json.dumps(
call_api({"customerId": "c-7", "sku": "sku-9", "quantity": 0}),
ensure_ascii=False
))预期输出
{"data": {"orderId": "ord-1001", "status": "CREATED"}, "error": null}
{"data": null, "error": {"code": "INVALID_ARGUMENT", "message": "quantity must be a positive integer"}}真实 HTTP、RPC 或消息接口可以换成其他传输方式,但调用方应该只依赖这些稳定字段,而不依赖订单模块内部的类、表或状态机实现。
让错误语义可编程处理
错误不能只返回一段自然语言。调用方需要稳定的错误码决定是否重试、提示用户还是转入补偿流程;错误消息则主要用于诊断。
| 场景 | 稳定错误码 | 调用方动作 |
|---|---|---|
| 参数不合法 | INVALID_ARGUMENT |
修正请求,不重试 |
| 业务资源不存在 | NOT_FOUND |
终止当前流程或提示用户 |
| 暂时不可用 | TEMPORARILY_UNAVAILABLE |
按退避策略重试 |
不要让调用方通过解析 "库存不足" 这类文本判断业务分支,也不要把数据库异常名直接暴露成公共契约。
明确数据所有权
谁拥有数据,谁就负责定义写入规则、生命周期和一致性约束。订单模块拥有订单数据时,其他模块不应直接更新订单表;它们应通过订单 API 发起命令,或消费订单模块发布的事件。
共享数据库并不等于共享所有权。即使多个模块暂时部署在同一数据库实例,也可以通过独立 schema、最小权限和禁止跨模块写入来维持边界。真正需要共享的信息,应转换成稳定的查询 API、只读视图或事件契约,而不是把内部表结构暴露出去。
按兼容规则演进契约
契约演进优先采用向后兼容的增量变化:新增可选字段时提供默认语义;不要复用旧字段表达新的业务含义;删除字段前先经过弃用期,并确认调用方已经迁移。对关键接口,可以把典型请求与响应固化成契约测试,在发布前验证提供方和消费方仍然兼容。
当输入、输出、错误语义和数据所有权都被显式写进契约后,模块内部就获得了真正的实现自由;否则所谓“模块化”只是把耦合藏到了共享对象、共享表和口头约定里。