api-design

Name: api-design
Author: virgo777

311stars25forks

How to install api-design?

virgo777/buddyme/api-design

$npx -y skills add virgo777/buddyme --skill api-design

Installs into the current project.

Summary

生产级 API 的 REST API 设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和速率限制。

Files · 1

View on GitHub

SKILL.md

1	# API 设计模式 (API Design Patterns)
2
3	设计一致且开发者友好的 REST API 的规范与最佳实践。
4
5	## 何时启用
6
7	- 设计新的 API 端点 (Endpoints)
8	- 审查现有的 API 合约 (Contracts)
9	- 添加分页、过滤或排序功能
10	- 为 API 实现错误处理
11	- 规划 API 版本控制策略
12	- 构建公开或面向合作伙伴的 API
13
14	## 资源设计 (Resource Design)
15
16	### URL 结构
17
18	```
19	# 资源是名词、复数、小写、短横线命名 (kebab-case)
20	GET /api/v1/users
21	GET /api/v1/users/:id
22	POST /api/v1/users
23	PUT /api/v1/users/:id
24	PATCH /api/v1/users/:id
25	DELETE /api/v1/users/:id
26
27	# 关系子资源
28	GET /api/v1/users/:id/orders
29	POST /api/v1/users/:id/orders
30
31	# 不属于 CRUD 的操作（谨慎使用动词）
32	POST /api/v1/orders/:id/cancel
33	POST /api/v1/auth/login
34	POST /api/v1/auth/refresh
35	```
36
37	### 命名规则
38
39	```
40	# 正确示例 (GOOD)
41	/api/v1/team-members # 多单词资源使用 kebab-case
42	/api/v1/orders?status=active # 使用查询参数进行过滤
43	/api/v1/users/123/orders # 嵌套资源表示所属关系
44
45	# 错误示例 (BAD)
46	/api/v1/getUsers # URL 中包含动词
47	/api/v1/user # 使用单数（应使用复数）
48	/api/v1/team_members # URL 中使用 snake_case
49	/api/v1/users/123/getOrders # 嵌套资源中包含动词
50	```
51
52	## HTTP 方法与状态码
53
54	### 方法语义 (Method Semantics)
55
56	\| 方法 (Method) \| 幂等 (Idempotent) \| 安全 (Safe) \| 用途 \|
57	\|--------\|-----------\|------\|---------\|
58	\| GET \| 是 \| 是 \| 获取资源 \|
59	\| POST \| 否 \| 否 \| 创建资源，触发操作 \|
60	\| PUT \| 是 \| 否 \| 完整替换资源 \|
61	\| PATCH \| 否* \| 否 \| 部分更新资源 \|
62	\| DELETE \| 是 \| 否 \| 删除资源 \|
63
64	*如果实现得当，PATCH 也可以实现为幂等的。
65
66	### 状态码参考
67
68	```
69	# 成功 (Success)
70	200 OK — GET, PUT, PATCH（包含响应正文）
71	201 Created — POST（需包含 Location 标头）
72	204 No Content — DELETE, PUT（无响应正文）
73
74	# 客户端错误 (Client Errors)
75	400 Bad Request — 验证失败、JSON 格式错误
76	401 Unauthorized — 缺失或无效的身份验证
77	403 Forbidden — 已身份验证但无权访问
78	404 Not Found — 资源不存在
79	409 Conflict — 重复条目、状态冲突
80	422 Unprocessable Entity — 语义无效（JSON 合法，但数据有误）
81	429 Too Many Requests — 超出速率限制
82
83	# 服务器错误 (Server Errors)
84	500 Internal Server Error — 意外故障（绝不要暴露详细信息）
85	502 Bad Gateway — 上游服务故障
86	503 Service Unavailable — 临时过载，包含 Retry-After 标头
87	```
88
89	### 常见错误
90
91	```
92	# 错误：所有响应都返回 200
93	{ "status": 200, "success": false, "error": "Not found" }
94
95	# 正确：语义化使用 HTTP 状态码
96	HTTP/1.1 404 Not Found
97	{ "error": { "code": "not_found", "message": "User not found" } }
98
99	# 错误：验证错误返回 500
100	# 正确：返回 400 或 422，并附带字段级详细信息
101
102	# 错误：创建资源返回 200
103	# 正确：返回 201 并在 Location 标头中包含路径
104	HTTP/1.1 201 Created
105	Location: /api/v1/users/abc-123
106	```
107
108	## 响应格式 (Response Format)
109
110	### 成功响应
111
112	```json
113	{
114	"data": {
115	"id": "abc-123",
116	"email": "alice@example.com",
117	"name": "Alice",
118	"created_at": "2025-01-15T10:30:00Z"
119	}
120	}
121	```
122
123	### 集合响应（带分页）
124
125	```json
126	{
127	"data": [
128	{ "id": "abc-123", "name": "Alice" },
129	{ "id": "def-456", "name": "Bob" }
130	],
131	"meta": {
132	"total": 142,
133	"page": 1,
134	"per_page": 20,
135	"total_pages": 8
136	},
137	"links": {
138	"self": "/api/v1/users?page=1&per_page=20",
139	"next": "/api/v1/users?page=2&per_page=20",
140	"last": "/api/v1/users?page=8&per_page=20"
141	}
142	}
143	```
144
145	### 错误响应
146
147	```json
148	{
149	"error": {
150	"code": "validation_error",
151	"message": "Request validation failed",
152	"details": [
153	{
154	"field": "email",
155	"message": "Must be a valid email address",
156	"code": "invalid_format"
157	},
158	{
159	"field": "age",
160	"message": "Must be between 0 and 150",
161	"code": "out_of_range"
162	}
163	]
164	}
165	}
166	```
167
168	### 响应封装变体
169
170	```typescript
171	// 选项 A：带数据包装器的封装（推荐用于公开 API）
172	interface ApiResponse<T> {
173	data: T;
174	meta?: PaginationMeta;
175	links?: PaginationLinks;
176	}
177
178	interface ApiError {
179	error: {
180	code: string;
181	message: string;
182	details?: FieldError[];
183	};
184	}
185
186	// 选项 B：扁平化响应（较简单，常用于内部 API）
187	// 成功：直接返回资源
188	// 错误：返回错误对象
189	// 通过 HTTP 状态码进行区分
190	```
191
192	## 分页 (Pagination)
193
194	### 基于偏移量 (Offset-Based) - 简单
195
196	```
197	GET /api/v1/users?page=2&per_page=20
198
199	# 实现
200	SELECT * FROM users
201	ORDER BY created_at DESC
202	LIMIT 20 OFFSET 20;
203	```
204
205	优点：易于实现，支持“跳转到第 N 页”。
206	缺点：偏移量较大时性能较差 (OFFSET 100000)，且在并发插入时可能出现不一致。
207
208	### 基于游标 (Cursor-Based) - 可扩展
209
210	```
211	GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
212
213	# 实现
214	SELECT * FROM users
215	WHERE id > :cursor_id
216	ORDER BY id ASC
217	LIMIT 21; -- 多获取一个以确定是否有下一页 (has_next)
218	```
219
220	```json
221	{
222	"data": [...],
223	"meta": {
224	"has_next": true,
225	"next_cursor": "eyJpZCI6MTQzfQ"
226	}
227	}
228	```
229
230	优点：无论位置如何，性能保持一致；并发插入时稳定。
231	缺点：无法跳转到任意页码，游标是不透明的。
232
233	### 何时使用哪种方式
234
235	\| 使用场景 \| 分页类型 \|
236	\|----------\|----------------\|
237	\| 管理后台、小型数据集 (<10K) \| 偏移量 (Offset) \|
238	\| 无限滚动、Feed 流、大型数据集 \| 游标 (Cursor) \|
239	\| 公开 API \| 默认使用游标 (Cursor)，可选偏移量 (Offset) \|
240	\| 搜索结果 \| 偏移量 (Offset)（用户通常期望看到页码） \|
241
242	## 过滤、排序与搜索 (Filtering, Sorting, and Search)
243
244	### 过滤 (Filtering)
245
246	```
247	# 简单等值匹配
248	GET /api/v1/orders?status=active&customer_id=abc-123
249
250	# 比较运算符（使用方括号标记）
251	GET /api/v1/products?price[gte]=10&price[lte]=100
252	GET /api/v1/orders?created_at[after]=2025-01-01
253
254	# 多个值（逗号分隔）
255	GET /api/v1/products?category=electronics,clothing
256
257	# 嵌套字段（点标记法）
258	GET /api/v1/orders?customer.country=US
259	```
260
261	### 排序 (Sorting)
262
263	```
264	# 单个字段（前缀 - 表示降序）
265	GET /api/v1/products?sort=-created_at
266
267	# 多个字段（逗号分隔）
268	GET /api/v1/products?sort=-featured,price,-created_at
269	```
270
271	### 全文搜

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

api-design

311stars25forks

View on GitHub

How to install api-design?

virgo777/buddyme/api-design

$npx -y skills add virgo777/buddyme --skill api-design

Installs into the current project.

Summary

生产级 API 的 REST API 设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和速率限制。

Files · 1

View on GitHub

SKILL.md

1	# API 设计模式 (API Design Patterns)
2
3	设计一致且开发者友好的 REST API 的规范与最佳实践。
4
5	## 何时启用
6
7	- 设计新的 API 端点 (Endpoints)
8	- 审查现有的 API 合约 (Contracts)
9	- 添加分页、过滤或排序功能
10	- 为 API 实现错误处理
11	- 规划 API 版本控制策略
12	- 构建公开或面向合作伙伴的 API
13
14	## 资源设计 (Resource Design)
15
16	### URL 结构
17
18	```
19	# 资源是名词、复数、小写、短横线命名 (kebab-case)
20	GET /api/v1/users
21	GET /api/v1/users/:id
22	POST /api/v1/users
23	PUT /api/v1/users/:id
24	PATCH /api/v1/users/:id
25	DELETE /api/v1/users/:id
26
27	# 关系子资源
28	GET /api/v1/users/:id/orders
29	POST /api/v1/users/:id/orders
30
31	# 不属于 CRUD 的操作（谨慎使用动词）
32	POST /api/v1/orders/:id/cancel
33	POST /api/v1/auth/login
34	POST /api/v1/auth/refresh
35	```
36
37	### 命名规则
38
39	```
40	# 正确示例 (GOOD)
41	/api/v1/team-members # 多单词资源使用 kebab-case
42	/api/v1/orders?status=active # 使用查询参数进行过滤
43	/api/v1/users/123/orders # 嵌套资源表示所属关系
44
45	# 错误示例 (BAD)
46	/api/v1/getUsers # URL 中包含动词
47	/api/v1/user # 使用单数（应使用复数）
48	/api/v1/team_members # URL 中使用 snake_case
49	/api/v1/users/123/getOrders # 嵌套资源中包含动词
50	```
51
52	## HTTP 方法与状态码
53
54	### 方法语义 (Method Semantics)
55
56	\| 方法 (Method) \| 幂等 (Idempotent) \| 安全 (Safe) \| 用途 \|
57	\|--------\|-----------\|------\|---------\|
58	\| GET \| 是 \| 是 \| 获取资源 \|
59	\| POST \| 否 \| 否 \| 创建资源，触发操作 \|
60	\| PUT \| 是 \| 否 \| 完整替换资源 \|
61	\| PATCH \| 否* \| 否 \| 部分更新资源 \|
62	\| DELETE \| 是 \| 否 \| 删除资源 \|
63
64	*如果实现得当，PATCH 也可以实现为幂等的。
65
66	### 状态码参考
67
68	```
69	# 成功 (Success)
70	200 OK — GET, PUT, PATCH（包含响应正文）
71	201 Created — POST（需包含 Location 标头）
72	204 No Content — DELETE, PUT（无响应正文）
73
74	# 客户端错误 (Client Errors)
75	400 Bad Request — 验证失败、JSON 格式错误
76	401 Unauthorized — 缺失或无效的身份验证
77	403 Forbidden — 已身份验证但无权访问
78	404 Not Found — 资源不存在
79	409 Conflict — 重复条目、状态冲突
80	422 Unprocessable Entity — 语义无效（JSON 合法，但数据有误）
81	429 Too Many Requests — 超出速率限制
82
83	# 服务器错误 (Server Errors)
84	500 Internal Server Error — 意外故障（绝不要暴露详细信息）
85	502 Bad Gateway — 上游服务故障
86	503 Service Unavailable — 临时过载，包含 Retry-After 标头
87	```
88
89	### 常见错误
90
91	```
92	# 错误：所有响应都返回 200
93	{ "status": 200, "success": false, "error": "Not found" }
94
95	# 正确：语义化使用 HTTP 状态码
96	HTTP/1.1 404 Not Found
97	{ "error": { "code": "not_found", "message": "User not found" } }
98
99	# 错误：验证错误返回 500
100	# 正确：返回 400 或 422，并附带字段级详细信息
101
102	# 错误：创建资源返回 200
103	# 正确：返回 201 并在 Location 标头中包含路径
104	HTTP/1.1 201 Created
105	Location: /api/v1/users/abc-123
106	```
107
108	## 响应格式 (Response Format)
109
110	### 成功响应
111
112	```json
113	{
114	"data": {
115	"id": "abc-123",
116	"email": "alice@example.com",
117	"name": "Alice",
118	"created_at": "2025-01-15T10:30:00Z"
119	}
120	}
121	```
122
123	### 集合响应（带分页）
124
125	```json
126	{
127	"data": [
128	{ "id": "abc-123", "name": "Alice" },
129	{ "id": "def-456", "name": "Bob" }
130	],
131	"meta": {
132	"total": 142,
133	"page": 1,
134	"per_page": 20,
135	"total_pages": 8
136	},
137	"links": {
138	"self": "/api/v1/users?page=1&per_page=20",
139	"next": "/api/v1/users?page=2&per_page=20",
140	"last": "/api/v1/users?page=8&per_page=20"
141	}
142	}
143	```
144
145	### 错误响应
146
147	```json
148	{
149	"error": {
150	"code": "validation_error",
151	"message": "Request validation failed",
152	"details": [
153	{
154	"field": "email",
155	"message": "Must be a valid email address",
156	"code": "invalid_format"
157	},
158	{
159	"field": "age",
160	"message": "Must be between 0 and 150",
161	"code": "out_of_range"
162	}
163	]
164	}
165	}
166	```
167
168	### 响应封装变体
169
170	```typescript
171	// 选项 A：带数据包装器的封装（推荐用于公开 API）
172	interface ApiResponse<T> {
173	data: T;
174	meta?: PaginationMeta;
175	links?: PaginationLinks;
176	}
177
178	interface ApiError {
179	error: {
180	code: string;
181	message: string;
182	details?: FieldError[];
183	};
184	}
185
186	// 选项 B：扁平化响应（较简单，常用于内部 API）
187	// 成功：直接返回资源
188	// 错误：返回错误对象
189	// 通过 HTTP 状态码进行区分
190	```
191
192	## 分页 (Pagination)
193
194	### 基于偏移量 (Offset-Based) - 简单
195
196	```
197	GET /api/v1/users?page=2&per_page=20
198
199	# 实现
200	SELECT * FROM users
201	ORDER BY created_at DESC
202	LIMIT 20 OFFSET 20;
203	```
204
205	优点：易于实现，支持“跳转到第 N 页”。
206	缺点：偏移量较大时性能较差 (OFFSET 100000)，且在并发插入时可能出现不一致。
207
208	### 基于游标 (Cursor-Based) - 可扩展
209
210	```
211	GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
212
213	# 实现
214	SELECT * FROM users
215	WHERE id > :cursor_id
216	ORDER BY id ASC
217	LIMIT 21; -- 多获取一个以确定是否有下一页 (has_next)
218	```
219
220	```json
221	{
222	"data": [...],
223	"meta": {
224	"has_next": true,
225	"next_cursor": "eyJpZCI6MTQzfQ"
226	}
227	}
228	```
229
230	优点：无论位置如何，性能保持一致；并发插入时稳定。
231	缺点：无法跳转到任意页码，游标是不透明的。
232
233	### 何时使用哪种方式
234
235	\| 使用场景 \| 分页类型 \|
236	\|----------\|----------------\|
237	\| 管理后台、小型数据集 (<10K) \| 偏移量 (Offset) \|
238	\| 无限滚动、Feed 流、大型数据集 \| 游标 (Cursor) \|
239	\| 公开 API \| 默认使用游标 (Cursor)，可选偏移量 (Offset) \|
240	\| 搜索结果 \| 偏移量 (Offset)（用户通常期望看到页码） \|
241
242	## 过滤、排序与搜索 (Filtering, Sorting, and Search)
243
244	### 过滤 (Filtering)
245
246	```
247	# 简单等值匹配
248	GET /api/v1/orders?status=active&customer_id=abc-123
249
250	# 比较运算符（使用方括号标记）
251	GET /api/v1/products?price[gte]=10&price[lte]=100
252	GET /api/v1/orders?created_at[after]=2025-01-01
253
254	# 多个值（逗号分隔）
255	GET /api/v1/products?category=electronics,clothing
256
257	# 嵌套字段（点标记法）
258	GET /api/v1/orders?customer.country=US
259	```
260
261	### 排序 (Sorting)
262
263	```
264	# 单个字段（前缀 - 表示降序）
265	GET /api/v1/products?sort=-created_at
266
267	# 多个字段（逗号分隔）
268	GET /api/v1/products?sort=-featured,price,-created_at
269	```
270
271	### 全文搜

People who liked this also viewed

6 picks

Type