api-patterns

Category: Content & Multimedia | Uploader: MisonL | Downloads: 0 | Version: v1.0（Latest）

API design principles and decision-making（API 设计原则与决策逻辑）。REST vs GraphQL vs tRPC selection（选择）、response formats（响应格式）、versioning（版本控制）、pagination（分页）。

Changelog: Source: GitHub https://github.com/MisonL/Ling

Directory Structure

Current level: .agents/skills/api-patterns/

📁 scripts/
- 📄 api_validator.py 7.4 KB
📄 api-style.md 1.2 KB
📄 auth.md 692 B
📄 documentation.md 494 B
📄 graphql.md 1.1 KB
📄 rate-limiting.md 762 B
📄 response.md 1.0 KB
📄 rest.md 1.4 KB
📄 security-testing.md 2.6 KB
📄 SKILL.md 4.1 KB
📄 trpc.md 844 B
📄 versioning.md 704 B

SKILL.md

---
name: api-patterns
description: API design principles and decision-making（API 设计原则与决策逻辑）。REST vs GraphQL vs tRPC selection（选择）、response formats（响应格式）、versioning（版本控制）、pagination（分页）。
allowed-tools: Read, Write, Edit, Glob, Grep
---

# API Patterns（API 模式）

> API design principles and decision-making for 2025（2025 年 API 设计原则与决策逻辑）。
> **Learn to THINK, not copy fixed patterns（学习如何思考，而非机械复制固定模式）。**

##  选择性阅读规则（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（选择 API 类型时） |
| `rest.md` | Resource naming, HTTP methods, status codes（资源命名/HTTP 方法/状态码） | Designing REST API（设计 REST API 时） |
| `response.md` | Envelope pattern, error format, pagination（信封模式/错误格式/分页） | Response structure（确定响应结构时） |
| `graphql.md` | Schema design, when to use, security（模式设计/使用场景/安全性） | Considering GraphQL（考虑 GraphQL 时） |
| `trpc.md` | TypeScript monorepo, type safety（TS 单仓/类型安全） | TS fullstack projects（TS 全栈项目） |
| `versioning.md` | URI/Header/Query versioning（URI/请求头/查询参数版本控制） | API evolution planning（规划 API 演进） |
| `auth.md` | JWT, OAuth, Passkey, API Keys（认证方案） | Auth pattern selection（选择认证模式） |
| `rate-limiting.md` | Token bucket, sliding window（令牌桶/滑动窗口） | API protection（API 保护机制） |
| `documentation.md` | OpenAPI/Swagger best practices（文档规范） | Documentation（编写 API 文档） |
| `security-testing.md` | OWASP API Top 10, auth/authz testing（认证/授权测试） | Security audits（安全审计） |

---

##  相关技能（Related Skills）

| Need（需求） | Skill（技能） |
| ---- | ------------ |
| API implementation（API 落地实现） | `@[skills/nodejs-best-practices]` |
| Data structure（数据库结构设计） | `@[skills/database-design]` |
| Security details（安全加固细节） | `@[skills/vulnerability-scanner]` |

---

## [OK]  决策检查清单（Decision Checklist）

设计 API 之前（Before designing an API）：

- [ ] **Asked user about API consumers?（是否询问 API 消费者？）**
- [ ] **Chosen API style for THIS context?（是否为当前上下文选择 API 风格？）** (REST/GraphQL/tRPC)
- [ ] **Defined consistent response format?（是否定义统一响应格式？）**
- [ ] **Planned versioning strategy?（是否规划版本控制策略？）**
- [ ] **Considered authentication needs?（是否考虑认证需求？）**
- [ ] **Planned rate limiting?（是否规划频率限制？）**
- [ ] **Documentation approach defined?（是否定义文档方案？）**

---

## [FAIL]  反模式（Anti-Patterns）

**不要（DON'T）：**

- 任何场景都默认 REST（Default to REST for everything）。
- REST 端点使用动词，如 `/getUsers`（Use verbs in REST endpoints）。
- 响应格式不一致（Return inconsistent response formats）。
- 向客户端暴露内部错误（Expose internal errors to clients）。
- 忽略频率限制（Skip rate limiting）。

**推荐做法（DO）：**

- 根据上下文选择 API 风格（Choose API style based on context）。
- 先询问客户端需求（Ask about client requirements）。
- 编写详尽文档（Document thoroughly）。
- 使用合适的 HTTP 状态码（Use appropriate status codes）。

---

## 运行脚本（Script）

| Script（脚本） | Purpose（用途） | Command（命令） |
| ---- | ---- | ---- |
| `scripts/api_validator.py` | API endpoint validation（API 端点校验） | `python scripts/api_validator.py <project_path>`（项目路径） |

---

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

api-patterns

Directory Structure

SKILL.md

Report

Notice