Appearance
API and Interface Design 解决的是 AI 先写实现、后补接口导致契约混乱的问题。它强调 contract first：先定输入、输出、错误语义、分页、权限和兼容策略，再写具体实现。
AI 设计接口怎么先定契约：API and Interface Design 怎么用
下载 api-and-interface-design 中文版 Skill ZIP
前端已经接上 /api/tasks 的时候，你再想把字段 title 改成 name，事情就没那么轻了。
字段名、错误码、排序方式、分页语义，甚至某个看似偶然的返回顺序，都可能被调用方依赖。
api-and-interface-design 这个技能的重点是：先定契约，再写实现。
接口不只是后端 API
这里的 interface 不只指 REST API。
它也包括：
- 前后端请求响应结构。
- TypeScript 公共类型。
- 组件 props。
- SDK 方法签名。
- 模块之间的边界。
- 数据库字段暴露到外部的形状。
只要一处代码要被另一处代码依赖，它就是契约。
先写请求和响应
让 AI 写接口前，可以先让它输出契约：
md
先不要实现接口。
请先定义：
- endpoint 和 HTTP method。
- 请求参数和 body。
- 成功响应结构。
- 错误响应结构。
- 权限规则。
- 分页和排序规则。
- 哪些字段以后可以新增，哪些不能改。契约清楚以后，实现反而更简单。
错误语义要统一
AI 很容易让不同接口返回不同错误：有的抛异常，有的返回 null，有的返回 { message }，有的返回字符串。
调用方会很痛苦。
一个项目最好统一错误结构：
- 400：请求格式不对。
- 401：未登录。
- 403：登录了但无权访问。
- 404：资源不存在。
- 409：冲突。
- 422：业务校验失败。
- 500：服务端内部错误，不暴露细节。
错误结构越稳定，前端处理越简单。
列表接口默认分页
AI 写列表接口时，常见问题是一次返回全部数据。
开发阶段看不出问题，数据一多就炸。
列表接口最好一开始就定义分页、排序和过滤：
- page / pageSize。
- sortBy / sortOrder。
- filter 参数。
- total 或 hasMore。
- 默认 pageSize 上限。
这不是过度设计，而是避免把不受控数据量暴露给调用方。
兼容比你想象得重要
接口变更最危险的是修改已有字段。
更安全的策略是新增可选字段，而不是改变字段含义；新增 endpoint，而不是让旧 endpoint 语义漂移。
如果必须破坏兼容，就要写迁移计划，并明确谁会受影响。
AI 设计接口时，要让它说明：这次变更是否破坏兼容，老调用方会不会受影响。
给 AI 的接口设计 Prompt
md
请按 contract first 方式设计这个接口。
先输出契约，不要直接写实现。
需要包含：请求、响应、错误结构、权限、分页或过滤、兼容性影响。
如果会破坏现有调用方，请明确指出并给出迁移方案。你可能还需要
同类技能：
接口是长期契约，不要让 AI 先写完再说。