1. 数据契约基础：什么是数据契约、核心要素与API的关系

各位同学，咱们今天聊一个看似简单、但实际落地时坑特别多的概念——数据契约。

我在过去几年参与过好几个大型API治理项目，发现一个普遍现象：团队里每个人都在谈“契约”，但问到底什么是契约，十个人能给出十一种答案。有人说是接口文档，有人说是Schema定义，还有人觉得就是Swagger文件。嗯，这些都对，但都不全。

咱们先把概念理清楚。

1.1 什么是数据契约

数据契约，说白了就是数据提供方和数据消费方之间的一份正式约定。它规定了数据长什么样、怎么传、什么时候传、出了问题谁负责。

你想想看，这跟现实生活中的合同很像。你去租房，房东和你要签合同——租金多少、租期多久、水电谁付、违约怎么赔。数据契约也是这个道理，只不过签约双方变成了系统和系统。

我记得有一次在项目中，后端团队改了某个字段的类型，从int改成了string，结果前端直接崩溃。为什么？因为没有契约约束。如果有数据契约，这种变更根本不会无声无息地发生。

数据契约有几个关键特征：

• 双向性：契约约束双方，不是单方面的规定
• 可验证性：契约内容可以被自动化工具检查
• 版本化：契约会演进，每个版本都有明确记录
• 可执行：违反契约时，系统能做出明确反应

1.2 数据契约的核心要素

一个完整的数据契约，至少包含以下五个要素。我习惯把它们叫做“契约五要素”，在项目中每次评审都会逐条核对。

要素	说明	常见问题
Schema定义	数据结构、字段类型、必填/可选、枚举值	字段类型不匹配、缺少默认值
语义约束	业务含义、取值范围、关联规则	业务逻辑隐含在代码里，没有显式声明
行为约定	请求方式、响应格式、超时策略、重试机制	超时时间不一致，导致调用方频繁报错
质量承诺	可用性SLA、数据一致性级别、延迟上限	SLA写在文档里，但没人监控
变更策略	版本号规则、废弃流程、兼容性要求	接口说废弃就废弃，消费方措手不及

咱们展开说说每个要素。

Schema定义是最基础的部分。你用JSON Schema、Protobuf、OpenAPI还是GraphQL Schema都行，关键是机器可读。我见过有人把Schema写在Word文档里，然后截图贴到Wiki上——这哪是契约，这是考古材料。

语义约束容易被忽略。举个例子，字段叫status，值是1、2、3。但1代表什么？是“待审核”还是“已通过”？这些语义必须写清楚。我曾经在一个项目中，两个团队对status字段的理解完全相反，数据对账对了一周才发现问题。

行为约定决定了系统怎么交互。是同步还是异步？失败重试几次？幂等怎么保证？这些不写清楚，生产环境一出问题，两边互相甩锅。

质量承诺是契约的“软性”部分，但往往是最容易出问题的。你承诺99.9%的可用性，但实际监控发现只有95%。契约里写了，但没人执行，等于没写。

变更策略是契约的“演进规则”。API一定会变，关键是怎么变。向后兼容的变更可以直接发布，不兼容的变更需要走废弃流程。我建议每个契约都明确声明：major.minor.patch版本号规则，以及每个版本的生命周期。

1.3 数据契约与API的关系

很多人把数据契约和API混为一谈。其实它们的关系是：API是载体，数据契约是灵魂。

API定义了“怎么调用”，数据契约定义了“传什么、传成什么样、传错了怎么办”。

咱们画个图来理解。

从图上可以看得很清楚：API层解决的是通信问题，数据契约层解决的是数据问题。两者相辅相成，缺一不可。

我举个具体例子。假设你有一个GET /users/{id}的API：

• API层面：定义了HTTP方法、路径、认证方式、响应状态码
• 数据契约层面：定义了返回的JSON结构、每个字段的类型和含义、id的格式要求、响应时间的SLA

没有数据契约的API，就像没有施工图纸的毛坯房——能住人，但随时可能出问题。

数据契约和API的关系，还可以从生命周期角度理解：

阶段	API关注点	数据契约关注点
设计	端点设计、RESTful规范	Schema定义、语义约束
开发	路由实现、中间件	数据校验、类型转换
测试	接口连通性、响应时间	数据完整性、边界条件
部署	网关配置、负载均衡	契约版本对齐、兼容性检查
运维	监控告警、日志	数据质量监控、SLA验证

你看，在每个阶段，API和数据契约的关注点都不同，但必须对齐。API改了，数据契约要同步更新；数据契约变了，API要跟着调整。

最后总结一下本章的核心观点：

• 数据契约是提供方和消费方之间的正式约定，不是文档，是可执行规则
• 契约五要素：Schema、语义、行为、质量、变更，缺一不可
• API是载体，数据契约是灵魂，两者在生命周期各阶段都要对齐