架构与系统设计 / 系统课时

定义跨模块 API 与数据契约

定义跨模块 API 与数据契约

跨模块协作最容易失控的地方,不是接口数量,而是输入输出、错误语义和数据所有权没有被明确写下。本节用一个最小订单契约把这些边界固定下来,并给出可执行的校验示例。

学习目标

  • 能为跨模块调用定义稳定的输入、输出与错误语义
  • 能用显式 DTO/事件契约替代共享对象和隐式数据库耦合
  • 能判断字段演进与数据所有权是否破坏模块边界

先把边界写成契约

一个可维护的跨模块契约至少要回答四个问题:调用方可以提交什么、成功时拿到什么、失败时如何判断原因、哪一方拥有并修改这些数据。只要其中一项靠“大家都知道”维持,耦合就已经转移到了口头约定里。

跨模块 API 与数据所有权边界

最危险的反模式是把 ORM 实体、数据库表结构或“公共对象”直接当接口。这样一来,提供方一次字段重命名、表拆分或内部状态调整,就可能同时破坏多个调用方。

用显式 DTO 固定输入与输出

下面的完整 Python 示例模拟一个订单模块边界。调用方只能提交约定字段;模块内部可以自由调整实现,只要返回的数据契约和错误契约保持兼容。

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
    ))

预期输出

text
{"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、只读视图或事件契约,而不是把内部表结构暴露出去。

按兼容规则演进契约

契约演进优先采用向后兼容的增量变化:新增可选字段时提供默认语义;不要复用旧字段表达新的业务含义;删除字段前先经过弃用期,并确认调用方已经迁移。对关键接口,可以把典型请求与响应固化成契约测试,在发布前验证提供方和消费方仍然兼容。

当输入、输出、错误语义和数据所有权都被显式写进契约后,模块内部就获得了真正的实现自由;否则所谓“模块化”只是把耦合藏到了共享对象、共享表和口头约定里。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义跨模块 API 与数据契约

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通