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

设计同步调用的契约边界

设计同步调用的契约边界

同步接口的关键不是把服务内部对象搬到 HTTP 上,而是为调用者暴露一项稳定的业务能力。本篇用报价查询说明如何确定请求与响应字段、约束依赖方向,并避免远程契约随着内部领域模型频繁变化。

学习目标

  • 从调用者的业务目的反推同步接口,而不是直接暴露领域对象
  • 判断哪些字段应该进入契约,哪些内部状态应留在服务边界之内
  • 用明确的请求与响应结构降低服务之间的模型耦合

从业务能力定义接口

设计同步调用时,先写清调用者真正要完成的事情。例如订单服务创建订单前需要商品服务给出“当前可下单价格”,它需要的是一次报价能力,而不是读取商品服务中的 Product、PriceRule、Promotion 等内部对象。

因此接口可以围绕 POST /pricing/quotes 设计。调用者提交形成报价所必需的信息,提供者返回调用者完成后续业务所需的结果。契约描述的是双方共同认可的业务语言,而不是提供者数据库表或聚合根的序列化结果。

同步调用契约边界与依赖方向

只暴露完成调用所需的字段

一个常见错误是直接返回内部对象的全部字段。这样做短期省代码,长期却会让调用者依赖提供者的字段命名、对象层级和状态枚举。内部模型一旦重构,即使业务能力没有变化,也可能迫使多个服务同时修改。

下面的接口定义只传递报价所需的信息。它是接口定义片段,依赖完整 OpenAPI 文档中的服务器地址和公共组件,不能单独启动。

yaml
paths:
  /pricing/quotes:
    post:
      summary: Create a price quote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customerId, sku, quantity]
              properties:
                customerId:
                  type: string
                sku:
                  type: string
                quantity:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: Quote created
          content:
            application/json:
              schema:
                type: object
                required: [quoteId, unitPrice, currency]
                properties:
                  quoteId:
                    type: string
                  unitPrice:
                    type: number
                  currency:
                    type: string

这里没有暴露价格规则 ID、促销对象、成本价、数据库主键或规则计算中间状态。调用者只依赖 quoteId、成交单价和币种,即使价格服务以后更换规则引擎或调整领域对象,契约也可以保持稳定。

验证这份定义时,可以用 OpenAPI 校验器检查语法,并用契约测试确认合法请求能得到包含必需字段的响应、quantity 小于 1 时被拒绝。重点不是验证内部使用了哪个领域对象,而是验证对外承诺是否成立。

控制依赖方向

同步调用会天然形成运行时依赖,因此更要避免形成模型依赖。订单服务可以知道“报价”这一公开概念,但不应该导入价格服务的领域类,也不应该根据价格服务内部枚举编写业务分支。

如果调用者必须理解提供者大量内部字段才能正确使用接口,通常说明边界还没有设计好。可以把判断压缩为三个问题:调用者为什么需要这个字段、缺少它是否无法完成自己的业务、它是否属于双方稳定共享的业务语义。无法回答前两个问题的字段通常不应进入契约。

为契约变化预留空间

同步契约不可避免会演进,但应优先采用兼容式变化。例如新增可选请求字段、新增响应字段通常比修改已有字段语义更安全。若一个字段的含义发生根本变化,应考虑引入新的业务概念或新版本,而不是悄悄复用旧字段名。

判断同步接口是否真正形成边界,可以做一次反向测试:假设提供者明天重命名聚合根、拆分数据库表并替换内部规则对象,只要公开的业务能力没有改变,调用者就不应被迫修改。能满足这个条件,契约才是在保护服务自治,而不是把进程内耦合搬到了网络上。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计同步调用的契约边界

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

登录哪都通