平台服务
Contract 与 Policy
把消费者可见行为和业务规则放在可发现、可验证的权威位置。
API Contract 至少包含
- request、response 和 error schema。
- 认证与授权前置条件。
- 幂等、分页、排序、超时和重试语义。
- version、compatibility window 和 consumers。
Error Contract 要稳定
消费者不应解析自然语言 message 来判断行为。提供稳定 error code，并明确哪些错误可重试、需要用户操作或代表权限拒绝。
Policy 与实现分开
Policy 说明谁允许做什么、数据生命周期、限额或业务约束。实现可以执行 Policy，但不能悄悄成为新的 Policy 定义。
改变消费者行为就是 Contract 变更
即使 TypeScript 类型没有改变，只要默认值、错误语义、权限条件或副作用时机改变，就需要 Contract review 和对应验证。