api-and-interface-design

技能简介

本技能用于指导设计稳定、易用且难以误用的 API 与接口。它帮助你在设计 REST/GraphQL 端点、模块边界、组件 props 或前后端契约时，遵循经过验证的设计原则，减少因接口变更或实现细节泄露导致的破坏性问题。

使用场景

• 设计新的 API 端点（REST 或 GraphQL）
• 定义团队间的模块边界或类型契约
• 创建组件 props 接口
• 依据数据库结构设计 API 形状
• 修改现有公共接口时评估影响

使用方法

该技能通常在支持 Claude Skills 的客户端中使用。启用方式：在项目或设置中添加本技能（api-and-interface-design）后，当对话涉及接口设计时，Agent 会自动加载并应用以下原则：

1. 契约先行：先定义接口类型，再实现逻辑。
2. 统一错误语义：所有错误响应使用一致的格式和状态码。
3. 边界校验：只在系统入口（路由处理、表单提交、外部响应解析、环境变量加载）验证数据，内部代码信任已校验的类型。
4. 优先扩展而非修改：新增可选字段，避免删除或修改现有字段类型。
5. 可预测的命名：遵循 REST 复数名词、camelCase 字段、布尔值 is/has/can 前缀、枚举 UPPER_SNAKE 等约定。
6. 尊重 Hyrum's Law：任何可观察行为都会被用户依赖，设计时需明确暴露范围，避免泄露实现细节，并提前规划弃用策略。

你可以直接在编写接口代码或讨论接口设计时要求 Agent 参考该技能，例如：

“请按照 api-and-interface-design 技能帮我设计一个创建任务的 REST API。”

注意事项

• 第三方 API 响应一律视为不可信数据，使用前必须验证其结构和内容。
• 不要混合使用多种错误返回模式（如有的抛异常、有的返回 null），否则消费者无法预判行为。
• 设计废弃策略应在接口创建时就纳入考虑，而不要等到用户依赖后再补救。