《游戏服务端架构·核心系统与契约》附录 B 系统契约模板

为什么需要一份模板

卷二反复出现同一类争论：这个字段谁能写、重复回调怎么办、下游挂了谁负责、数据保留多久。争论本身不可怕，可怕的是每次都要从头吵一遍，最后靠会议纪要里的模糊句子收场。

契约模板的作用，是把这些争论变成固定栏目。填不满的栏目，就是尚未想清楚的地方；填出来互相矛盾的栏目，就是评审要先解决的问题。

模板不追求覆盖所有系统。它只要求每个核心系统在接入其他系统之前，至少能回答下面这些问题。

一、契约卡的最小字段

一张契约卡通常一页到两页。超过两页，说明边界没有切干净。

二、填写顺序

建议按下面的顺序填，因为后面的栏目依赖前面的结论。

第一步：先定数据所有权

列出本系统拥有的实体和关键字段，逐项确认“唯一写入者”。如果一个字段需要两个系统写，先决定谁拥有，另一个改为通过接口或事件请求。

判据：能否用一个唯一约束或写入接口把“第二个写入者”挡住。挡不住，所有权就只是文档上的声明。

第二步：再定读写路径

• 外部系统只能通过接口或事件读取，不允许直连数据库；
• 读取方需要的是原始数据还是聚合结果，决定提供查询接口还是订阅事件；
• 跨系统查询要明确一致性窗口，不要假设“刚写完就能读到”。

第三步：定义写操作的幂等语义

每个写操作回答三个问题：

1. 幂等键是什么，由调用方还是服务方生成；
2. 重复请求返回什么：原结果、冲突错误还是静默成功；
3. 幂等记录保留多久，过期后重复请求会怎样。

第四步：写失败语义

至少覆盖五类失败：

“结果未知”最容易被忽略。调用方超时后既不能当成功，也不能当失败，必须有一个查询或幂等机制让它确认。

第五步：定 SLA 与降级

SLA 要分接口、分场景，不要给整个系统一个笼统数字。降级要写清楚：

• 依赖不可用时，本系统返回缓存、默认值还是错误；
• 降级期间哪些写操作被拒绝，恢复后如何补偿；
• 谁有权触发降级，多久复审一次。

三、四个填写示例

3.1 账号服务

关键点：账号状态只有一个写入者。游戏服可以缓存昵称和等级，但不能改账号的封禁、注销与绑定关系。

3.2 结算服务

关键点：先落结算单，再发奖。顺序反过来，一旦发奖后崩溃，就无法判断是否已发。

3.3 支付服务

关键点：支付状态与发货状态分开。已支付未发货是合法中间态，必须有补偿任务，而不是靠人工发现。

3.4 平台能力

关键点：SLA 按能力定义。账号可用性 99.95% 和推荐服务可用性 99.9% 不是同一件事，混在一个数字里无法追责。

四、评审时的十个问题

拿到一张契约卡，按顺序问：

1. 这份数据如果出现两个写入者，哪一个约束会挡住第二个？
2. 读取方是走接口还是直连库？直连的什么时候迁走？
3. 幂等键由谁生成？重复请求返回什么？
4. 超时后调用方如何确认结果？
5. 部分成功时，已成功的部分如何回滚或补偿？
6. 最终一致的窗口多大？窗口内读到旧值会怎样？
7. SLA 是按接口还是按系统？故障时如何统计？
8. 删除请求如何传导到缓存、日志和备份？
9. 依赖不可用时，降级返回什么？谁有权触发？
10. 上一次契约变更是什么时候？旧版本还支持多久？

十个问题里有两个答不上来，契约就不应该签字。

五、常见错误

六、一页纸模板

系统：____            负责人/值班：____
拥有的数据：____
唯一写入者：____      其他写入者及理由：____
读取方与方式：____
幂等键：____          重复请求返回：____
一致性：强一致 ____ / 最终一致 ____（窗口 ____）
失败语义：参数 ____ / 越权 ____ / 冲突 ____ / 不可用 ____ / 结果未知 ____
SLA：接口 ____ P99 ____；可用性 ____；恢复时间 ____
保留期：____          删除传导：____
降级：触发条件 ____；返回 ____；授权人 ____；复审 ____
版本：____            上次复审：____

模板本身不解决问题，它只是让“没想清楚”无处可藏。真正有价值的契约，是两个人分别填写后能得到同一份答案；如果填出来不一样，说明边界还需要再谈一次。

契约卡填完之后，建议和附录 C 的故障模式清单一起过一遍：每个失败语义，是否都有对应的可探测信号和兜底动作。两页纸对不上，系统就还没有准备好接入别人。