1、契约初识：什么是数据契约？为什么需要数据契约？数据契约在微服务中的角色。

大家好，我是这次课程的主讲。今天咱们聊聊数据契约——这个听起来有点正式、但其实每个做微服务的团队都绕不开的东西。

我记得刚带团队做微服务拆分那会儿，大家各写各的接口，前端调后端、订单调用户、支付调库存……结果联调的时候，三天两头出问题。不是字段名对不上，就是类型不匹配，更离谱的是有人把 userId 改成了 user_id，没人通知下游。嗯，那场面，你想想看，一个接口改了，五个服务跟着崩。

后来我就在想：能不能像签合同一样，让服务之间提前约定好数据格式？这就是数据契约的由来。

1.1 什么是数据契约？

说白了，数据契约就是服务之间对数据交换格式的书面约定。它不只是一份文档，而是一套可执行、可验证的规范。

我习惯把它拆成四个部分：

• 接口定义：路径、方法、请求/响应结构
• 数据模型：字段名、类型、是否必填、默认值
• 约束规则：取值范围、格式校验、业务逻辑
• 版本承诺：兼容性策略、废弃周期

举个例子，一个用户查询的契约可能长这样：

// 数据契约示例：查询用户信息
// 契约版本：v1.2
// 兼容性：向后兼容

GET /api/v1/users/{userId}

请求参数：
  userId: string (必填, UUID格式)

成功响应 (200)：
  {
    "id": "string (UUID)",
    "name": "string (1-50字符)",
    "email": "string (邮箱格式)",
    "phone": "string (可选, 手机号格式)",
    "createdAt": "string (ISO 8601时间戳)"
  }

错误响应 (404)：
  {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在"
  }

你看，这份契约把每个字段的类型、格式、约束都写死了。谁要是改了 email 的类型，或者加了必填字段，契约检查就会报错。

1.2 为什么需要数据契约？

我在项目中遇到过最典型的一个场景：订单服务需要调用支付服务，两边各自维护了一份接口文档。结果支付服务升级时，把 amount 从整数改成了浮点数，文档也更新了，但订单服务没看到。上线后，所有支付金额都变成了科学计数法……

数据契约能解决这类问题，原因有三：

痛点	没有契约	有契约
接口变更	改完通知靠吼，漏了就是事故	契约自动校验，不兼容直接阻断
数据格式	各服务自己解析，对不上就报错	统一模型，类型、格式强制一致
联调效率	前后端、服务间反复沟通确认	契约即文档，Mock 数据自动生成
版本管理	接口版本混乱，不知道哪个在用	版本号+兼容性规则，清晰可追溯

1.3 数据契约在微服务中的角色

微服务架构里，服务之间通过 API 通信。每个服务都是独立的，但数据是流动的。数据契约在这中间扮演了三个关键角色：

1.3.1 契约是服务间的「法律」

没有契约，服务间的依赖就是隐式的。你改了一个字段，下游服务可能直接挂掉。有了契约，每个服务都明确知道自己承诺了什么、依赖了什么。我曾经见过一个团队，因为没契约，两个服务互相改了对方的字段，结果循环依赖，谁都不敢动。

1.3.2 契约是开发的「蓝图」

前后端可以并行开发，只要契约定好了。前端用 Mock 数据先跑起来，后端按契约实现。联调的时候，只要契约没变，基本一次过。我习惯在项目启动时先花半天把契约定下来，后面省下的时间至少是几周。

1.3.3 契约是运维的「监控」

生产环境里，契约还能当监控用。如果某个接口返回的数据不符合契约，说明要么是 Bug，要么是数据异常。我在一个金融项目里，用契约校验拦截过三次数据泄露——因为某个服务不小心把敏感字段暴露了，契约检查直接报警。

下面这张图展示了数据契约在微服务中的核心位置：

1.4 数据契约的核心要素

一个合格的数据契约，至少包含以下要素：

1. 契约标识：唯一 ID、名称、版本号
2. 通信协议：HTTP/gRPC/消息队列等
3. 数据模型：字段定义、类型、约束
4. 交互流程：请求-响应、事件发布-订阅
5. 错误处理：错误码、异常场景
6. 兼容性规则：向后兼容、废弃策略
7. 示例数据：正常场景、边界场景

我个人习惯用 OpenAPI 3.0 或 AsyncAPI 来定义契约，它们有成熟的工具链，能自动生成文档、Mock 服务、客户端代码和测试用例。后面几章我会详细讲怎么落地。