程序接口设计

解决的问题

接口一旦暴露，错误形状、错误语义和未文档化行为都会变成事实契约。团队里常见问题包括：REST 端点在不同条件下返回不同结构，GraphQL、模块边界或组件 props 缺少清晰契约，PATCH / PUT 选择混乱，第三方响应未校验就进入业务逻辑。此技能把这些问题整理成可执行的设计框架。

技能如何工作

它围绕“让正确操作容易，让错误操作困难”组织检查点：

• 契约优先：先定义输入、输出、类型和错误格式，再开始实现。
• 统一错误语义：避免有的接口 throw、有的返回 null、有的返回 { error }。
• 边界校验：在 API handler、表单提交、环境变量和第三方响应处校验；内部共享类型契约时不要重复校验。
• 向后兼容扩展：优先新增可选字段、discriminated unions、branded IDs，避免破坏现有消费端。
• 命名与 REST 约定：使用 GET /api/tasks、camelCase 查询参数、isComplete 布尔字段、UPPER_SNAKE 枚举值。

最后用 checklist 验证：typed schemas、一致错误、分页、PATCH 支持与命名一致性。

适用边界

适合新 API 端点、跨团队契约、组件 props、数据库 schema 影响接口形状等场景。它不替代安全扫描、权限模型或分布式系统设计。注意 Hyrum's Law：可观察行为就是承诺，deprecation 要提前计划。