API 设计原则

要解决什么问题

新接口上线后，调用方常常卡在资源命名不一致、错误语义模糊、分页与鉴权各写一套，文档和实现慢慢分叉。团队在 REST 与 GraphQL 之间选型时，也容易把「能跑」当成「好用」，缺少在实现前就能对齐的契约与评审口径。

技能如何工作

本技能把 API 设计收成一条可重复的工作流，而不是堆概念清单：

1. 界定边界：先写清调用方、使用场景与约束（性能、兼容、合规等），避免在错误抽象上继续堆端点。
2. 选型与建模：在 REST 或 GraphQL 中选定风格，对资源或类型做一致建模（命名、层级、关联关系）。
3. 横切策略：统一约定错误表示、版本管理、分页 参数形态与鉴权方式，减少「每个接口一种写法」。
4. 用示例验收：用请求/响应示例做一致性评审，在编码前发现歧义与破坏性变更。

详细模式、检查清单与模板见 resources/implementation-playbook.md，适合用来起草规范或在评审会上对齐口径。

适用边界

• 适合：新 API 设计、存量 API 可用性重构、团队设计标准、实现前规范评审、REST ↔ GraphQL 迁移思路、面向移动端或第三方集成的契约优化。
• 不适合：你只缺某个框架的样板代码；工作不涉及对外 API 契约；接口无法做版本管理或不允许调整公共面。