架构与系统设计 / 系统课时
设计同步调用的契约边界
设计同步调用的契约边界
同步接口的关键不是把服务内部对象搬到 HTTP 上,而是为调用者暴露一项稳定的业务能力。本篇用报价查询说明如何确定请求与响应字段、约束依赖方向,并避免远程契约随着内部领域模型频繁变化。
学习目标
- 从调用者的业务目的反推同步接口,而不是直接暴露领域对象
- 判断哪些字段应该进入契约,哪些内部状态应留在服务边界之内
- 用明确的请求与响应结构降低服务之间的模型耦合
从业务能力定义接口
设计同步调用时,先写清调用者真正要完成的事情。例如订单服务创建订单前需要商品服务给出“当前可下单价格”,它需要的是一次报价能力,而不是读取商品服务中的 Product、PriceRule、Promotion 等内部对象。
因此接口可以围绕 POST /pricing/quotes 设计。调用者提交形成报价所必需的信息,提供者返回调用者完成后续业务所需的结果。契约描述的是双方共同认可的业务语言,而不是提供者数据库表或聚合根的序列化结果。

只暴露完成调用所需的字段
一个常见错误是直接返回内部对象的全部字段。这样做短期省代码,长期却会让调用者依赖提供者的字段命名、对象层级和状态枚举。内部模型一旦重构,即使业务能力没有变化,也可能迫使多个服务同时修改。
下面的接口定义只传递报价所需的信息。它是接口定义片段,依赖完整 OpenAPI 文档中的服务器地址和公共组件,不能单独启动。
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 时被拒绝。重点不是验证内部使用了哪个领域对象,而是验证对外承诺是否成立。
控制依赖方向
同步调用会天然形成运行时依赖,因此更要避免形成模型依赖。订单服务可以知道“报价”这一公开概念,但不应该导入价格服务的领域类,也不应该根据价格服务内部枚举编写业务分支。
如果调用者必须理解提供者大量内部字段才能正确使用接口,通常说明边界还没有设计好。可以把判断压缩为三个问题:调用者为什么需要这个字段、缺少它是否无法完成自己的业务、它是否属于双方稳定共享的业务语义。无法回答前两个问题的字段通常不应进入契约。
为契约变化预留空间
同步契约不可避免会演进,但应优先采用兼容式变化。例如新增可选请求字段、新增响应字段通常比修改已有字段语义更安全。若一个字段的含义发生根本变化,应考虑引入新的业务概念或新版本,而不是悄悄复用旧字段名。
判断同步接口是否真正形成边界,可以做一次反向测试:假设提供者明天重命名聚合根、拆分数据库表并替换内部规则对象,只要公开的业务能力没有改变,调用者就不应被迫修改。能满足这个条件,契约才是在保护服务自治,而不是把进程内耦合搬到了网络上。