API Patterns

API 模式

API design principles and decision-making for 2025. Learn to THINK, not copy fixed patterns.

2025年API设计原则与决策制定指南。 学会思考，而非照搬固定模式。

🎯 Selective Reading Rule

🎯 选择性阅读规则

Read ONLY files relevant to the request! Check the content map, find what you need.

只阅读与需求相关的文件！ 查看内容目录，找到你需要的部分。

📑 Content Map

📑 内容目录

File	Description	When to Read
`api-style.md`	REST vs GraphQL vs tRPC decision tree	Choosing API type
`rest.md`	Resource naming, HTTP methods, status codes	Designing REST API
`response.md`	Envelope pattern, error format, pagination	Response structure
`graphql.md`	Schema design, when to use, security	Considering GraphQL
`trpc.md`	TypeScript monorepo, type safety	TS fullstack projects
`versioning.md`	URI/Header/Query versioning	API evolution planning
`auth.md`	JWT, OAuth, Passkey, API Keys	Auth pattern selection
`rate-limiting.md`	Token bucket, sliding window	API protection
`documentation.md`	OpenAPI/Swagger best practices	Documentation
`security-testing.md`	OWASP API Top 10, auth/authz testing	Security audits

文件	描述	阅读时机
`api-style.md`	REST、GraphQL与tRPC的决策树	选择API类型时
`rest.md`	资源命名、HTTP方法、状态码	设计REST API时
`response.md`	信封模式、错误格式、分页	设计响应结构时
`graphql.md`	模式设计、适用场景、安全	考虑使用GraphQL时
`trpc.md`	TypeScript monorepo、类型安全	开发TS全栈项目时
`versioning.md`	URI/Header/Query版本控制	规划API演进时
`auth.md`	JWT、OAuth、Passkey、API密钥	选择认证模式时
`rate-limiting.md`	令牌桶、滑动窗口	保护API时
`documentation.md`	OpenAPI/Swagger最佳实践	编写文档时
`security-testing.md`	OWASP API Top 10、认证/授权测试	安全审计时

🔗 Related Skills

🔗 相关技能

Need	Skill
API implementation	`@[skills/backend-development]`
Data structure	`@[skills/database-design]`
Security details	`@[skills/security-hardening]`

需求	技能
API实现	`@[skills/backend-development]`
数据结构	`@[skills/database-design]`
安全细节	`@[skills/security-hardening]`

✅ Decision Checklist

✅ 决策检查清单

Before designing an API:

Asked user about API consumers?
Chosen API style for THIS context? (REST/GraphQL/tRPC)
Defined consistent response format?
Planned versioning strategy?
Considered authentication needs?
Planned rate limiting?
Documentation approach defined?

在设计API前：

询问过用户关于API消费者的情况？
针对当前场景选择了合适的API风格？（REST/GraphQL/tRPC）
定义了统一的响应格式？
规划了版本控制策略？
考虑了认证需求？
规划了速率限制？
确定了文档编写方案？

❌ Anti-Patterns

❌ 反模式

DON'T:

Default to REST for everything
Use verbs in REST endpoints (/getUsers)
Return inconsistent response formats
Expose internal errors to clients
Skip rate limiting

DO:

Choose API style based on context
Ask about client requirements
Document thoroughly
Use appropriate status codes

不要：

所有场景默认使用REST
在REST端点中使用动词（如/getUsers）
返回不一致的响应格式
向客户端暴露内部错误
跳过速率限制

应该：

根据场景选择API风格
询问客户端需求
全面编写文档
使用合适的状态码

Script

脚本

Script	Purpose	Command
`scripts/api_validator.py`	API endpoint validation	`python scripts/api_validator.py <project_path>`

脚本	用途	命令
`scripts/api_validator.py`	API端点验证	`python scripts/api_validator.py <project_path>`

api-patterns

Original

Translation

API Patterns

API 模式

🎯 Selective Reading Rule

🎯 选择性阅读规则

📑 Content Map

📑 内容目录

🔗 Related Skills

🔗 相关技能

✅ Decision Checklist

✅ 决策检查清单

❌ Anti-Patterns

❌ 反模式

Script

脚本