用途
本技能用于指导稳定、文档完善的 API 与接口设计，目标是让正确的用法变得容易、错误的用法变得困难。它适用于 REST API、GraphQL schema、模块边界、组件 props，以及任何一段代码与另一段代码交互的界面。
适用场景包括：设计新的 API 端点；定义模块边界或团队之间的契约；创建组件 prop 接口；建立影响 API 形态的数据库 schema；变更现有的公共接口。
核心原则
海勒姆定律（Hyrum's Law）：当 API 拥有足够多的用户时，系统的所有可观察行为都会被某些人依赖，无论契约中承诺了什么。这意味着每个公共行为——包括未文档化的怪癖、错误消息文本、时序和顺序——一旦被用户依赖，就成为事实上的契约。设计启示：对暴露什么要有意识；不要泄露实现细节；在设计阶段就规划弃用；测试并不足够。
单一版本规则：避免迫使消费者在同一依赖或 API 的多个版本之间做选择。为同一时间只存在一个版本的世界而设计——扩展而非分叉。
主要能力
契约优先：先定义接口再实现，契约即规范。示例中定义了 TaskAPI 接口，包含 createTask、listTasks、getTask、updateTask、deleteTask 等方法及其输入输出类型。
一致的错误语义：选定一种错误策略并处处使用。REST 使用 HTTP 状态码加结构化错误体，错误体统一为 { error: { code, message, details? } } 形状。状态码映射：400 客户端数据无效、401 未认证、403 已认证但未授权、404 资源未找到、409 冲突、422 校验失败、500 服务器错误（绝不暴露内部细节）。不要混用模式。
在边界处校验：信任内部代码，只在外部输入进入的系统边缘校验。校验位置包括 API 路由处理器、表单提交处理器、外部服务响应解析（第三方数据始终视为不可信）、环境变量加载。校验不属于内部共享类型契约的函数之间、已被校验代码调用的工具函数、刚来自自己数据库的数据。
优先扩展而非修改：通过添加可选字段扩展接口，不破坏现有消费者。避免更改现有字段类型或删除字段。
可预测命名：REST 端点用复数名词、无动词；查询参数用 camelCase；响应字段用 camelCase；布尔字段用 is/has/can 前缀；枚举值用 UPPER_SNAKE。
幂等键的正确实现：接受 Idempotency-Key 是契约，兑现它才是实现。键必须从意图而非尝试派生，在一次意图的重试间保持稳定、在不同意图间保持不同。原子地声明键（用唯一约束而非先查后插，避免 TOCTOU 竞态）。用请求体哈希守卫载荷，同键不同体必须显式失败。决定进行中的重复请求如何处理（拒绝 409、等待、或返回 202）。每次调用有三种结果：成功、失败、未知。保留窗口应基于最长重试链而非磁盘成本。
使用方式
技能以原则加代码示例的形式呈现，可直接作为设计评审清单和编码参考。设计完成后按验证清单逐项检查：每个端点有类型化输入输出 schema；错误响应格式统一；校验只在系统边界；列表端点支持分页；新字段为附加且可选；命名一致；API 文档或类型与实现一同提交；状态变更端点要么兑现幂等键要么标注为不可安全重试；键以单次原子操作声明并由唯一约束守卫；同键不同载荷显式失败；进行中重复的响应是刻意选择；键保留期长于最长重试路径（含死信重放）。
REST API 模式
资源设计采用 GET/POST/GET:id/PATCH/DELETE 的标准映射，子资源如 /api/tasks/:id/comments。列表端点必须分页，响应包含 data 与 pagination（page、pageSize、totalItems、totalPages）。过滤使用查询参数。PATCH 接受部分对象，只更新提供的字段。
TypeScript 接口模式
使用可辨识联合表示变体（如 TaskStatus 的 pending/in_progress/completed/cancelled），消费者可获得类型收窄。输入与输出分离：CreateTaskInput 是调用方提供的，Task 包含服务器生成字段。使用品牌类型区分 ID（TaskId、UserId），防止误传。
限制
资料未提供该技能的具体安装命令、运行环境、收费方式或平台支持信息。技能本身为设计指导性内容，不包含可执行工具或自动化检查脚本。