《游戏服务端架构·核心系统与契约》附录 A 平台接口速查

这份速查表怎么用

卷二各章分别给出了系统契约。到了接入阶段，团队真正需要的是另一张表：平台对游戏开放了哪些接口、调用时要注意什么、出错时怎么处理。

这份附录按能力列出接口清单。它不是完整的 API 文档，不包含字段级定义和示例报文；它只回答集成时最容易出错的那几件事：

• 这个接口是不是幂等的，幂等键由谁生成；
• 数据是强一致还是最终一致，窗口大概多大；
• 超时、重复、越权分别返回什么；
• 平台不可用时，游戏侧应该降级还是报错。

接口名使用能力语义命名，不绑定具体协议。RPC、HTTP 或消息都可以实现同一份契约。

一、统一约定

1.1 租户上下文

所有平台接口都必须携带租户上下文：

game_id      游戏标识，平台据此做配额、数据隔离与审计
env          prod / staging / dev，禁止跨环境访问
channel      可选，渠道标识，用于账号与支付归因
request_id   调用方生成的唯一请求 ID，用于链路追踪

缺少 game_id 的请求一律拒绝。不要把租户信息放在 URL 路径里让调用方自由拼接，平台应该在网关层强制注入并校验。

1.2 幂等约定

写接口统一接受 idempotency_key。规则：

1. 键由调用方生成，平台不替调用方编造；
2. 同一租户、同一能力、同一键，只执行一次；
3. 重复请求返回第一次的结果，不返回“已存在”错误；
4. 幂等记录保留时间不短于业务重试窗口，通常 24 小时起步。

查询接口不需要幂等键，但必须接受 request_id 以便排查。

1.3 错误分类

平台错误统一归为五类，游戏侧按类别决定是否重试：

UNKNOWN_RESULT 必须单独存在。把超时当成失败，会导致调用方重复执行；把超时当成成功，会导致数据缺失。

二、账号与身份

关键约束：

• 一个外部身份在同一游戏内只能指向一个内部账号；
• 解绑前必须确认还有其他可用登录方式；
• 注销是异步流程，平台返回受理结果，不返回“已删完”。

三、登录与会话

票据与会话令牌的职责不同：票据一次性、短命，用于证明“刚刚完成了身份验证”；会话令牌可续期，用于后续请求。不要用会话令牌替代登录票据，也不要把票据当成长连接凭证。

四、匹配与房间

匹配与房间是两段式契约：匹配只负责“找到人”，房间负责“落在哪”。匹配成功后房间创建失败，必须有补偿或重新入队策略，不能把玩家留在中间态。

五、结算与发奖

顺序必须是“先落结算单，再发奖”。发奖失败时结算单保持待发状态，由补偿任务重试；不要在发奖成功后再补结算单。

六、经济与交易

余额查询与扣减必须走同一账本。游戏服可以缓存展示余额，但任何扣减都必须由经济服务裁决。

七、社交、公会与聊天

关系链允许最终一致，但必须保证“黑名单优先生效”；公会权限变更要立即失效，不能等缓存过期。

八、榜单、邮件与奖励

榜单允许延迟可见，但必须说明延迟窗口；邮件与附件不允许丢失，也不允许重复领取。

九、支付与合规

支付状态与发货状态分开；合规判定与游戏执行分开。平台给出“允许/限制/拒绝”，游戏侧负责执行与提示。

十、数据与审计

事件总线通常保证至少一次，不保证顺序。消费方必须用事件 ID 去重，并在需要顺序时按业务键分区。

十一、平台与游戏的职责边界

边界的原则是：平台提供机制，游戏决定策略。 平台不应内置某款游戏的玩法规则，游戏也不应绕过平台直接改账号、余额或订单。

十二、常见误用

十三、一页纸速查

调用任何写接口前：
  1. 带 game_id / env / request_id
  2. 生成幂等键，并确保重试复用同一个键
  3. 明确超时后的动作：查询，而不是盲目重试

判断错误：
  INVALID_ARGUMENT / UNAUTHENTICATED / PERMISSION_DENIED → 不重试
  ALREADY_EXISTS / VERSION_CONFLICT → 先读状态
  UNAVAILABLE / DEADLINE_EXCEEDED → 退避重试
  UNKNOWN_RESULT → 用幂等键或查询接口确认

设计降级：
  账号/登录不可用 → 已登录会话可短时续命，禁止新登录
  匹配/榜单不可用 → 功能降级，不阻塞主流程
  经济/支付不可用 → 停止相关写操作，保留待处理单

速查表到这里结束。它不能替代接口文档，但可以在评审时快速检查：每个跨系统调用，是否都回答了幂等、一致性、失败语义和降级这四个问题。