mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-12 04:33:29 +08:00
docs(zh-CN): translate code block(plain text) (#753)
Co-authored-by: neo <neo.dowithless@gmail.com>
This commit is contained in:
zdoc.app
@@ -22,7 +22,7 @@ origin: ECC
|
||||
### URL 结构
|
||||
|
||||
```
|
||||
# Resources are nouns, plural, lowercase, kebab-case
|
||||
# 资源使用名词、复数、小写、短横线连接
|
||||
GET /api/v1/users
|
||||
GET /api/v1/users/:id
|
||||
POST /api/v1/users
|
||||
@@ -30,11 +30,11 @@ PUT /api/v1/users/:id
|
||||
PATCH /api/v1/users/:id
|
||||
DELETE /api/v1/users/:id
|
||||
|
||||
# Sub-resources for relationships
|
||||
# 用于关系的子资源
|
||||
GET /api/v1/users/:id/orders
|
||||
POST /api/v1/users/:id/orders
|
||||
|
||||
# Actions that don't map to CRUD (use verbs sparingly)
|
||||
# 非 CRUD 映射的操作（谨慎使用动词）
|
||||
POST /api/v1/orders/:id/cancel
|
||||
POST /api/v1/auth/login
|
||||
POST /api/v1/auth/refresh
|
||||
@@ -43,16 +43,16 @@ POST /api/v1/auth/refresh
|
||||
### 命名规则
|
||||
|
||||
```
|
||||
# GOOD
|
||||
/api/v1/team-members # kebab-case for multi-word resources
|
||||
/api/v1/orders?status=active # query params for filtering
|
||||
/api/v1/users/123/orders # nested resources for ownership
|
||||
# 良好
|
||||
/api/v1/team-members # 多单词资源使用 kebab-case
|
||||
/api/v1/orders?status=active # 查询参数用于过滤
|
||||
/api/v1/users/123/orders # 嵌套资源表示所有权关系
|
||||
|
||||
# BAD
|
||||
/api/v1/getUsers # verb in URL
|
||||
/api/v1/user # singular (use plural)
|
||||
/api/v1/team_members # snake_case in URLs
|
||||
/api/v1/users/123/getOrders # verb in nested resource
|
||||
# 不良
|
||||
/api/v1/getUsers # URL 中包含动词
|
||||
/api/v1/user # 使用单数形式（应使用复数）
|
||||
/api/v1/team_members # URL 中使用 snake_case
|
||||
/api/v1/users/123/getOrders # 嵌套资源路径中包含动词
|
||||
```
|
||||
|
||||
## HTTP 方法和状态码
|
||||
@@ -72,41 +72,41 @@ POST /api/v1/auth/refresh
|
||||
### 状态码参考
|
||||
|
||||
```
|
||||
# Success
|
||||
200 OK — GET, PUT, PATCH (with response body)
|
||||
201 Created — POST (include Location header)
|
||||
204 No Content — DELETE, PUT (no response body)
|
||||
# 成功
|
||||
200 OK — GET、PUT、PATCH（包含响应体）
|
||||
201 Created — POST（包含 Location 头部）
|
||||
204 No Content — DELETE、PUT（无响应体）
|
||||
|
||||
# Client Errors
|
||||
400 Bad Request — Validation failure, malformed JSON
|
||||
401 Unauthorized — Missing or invalid authentication
|
||||
403 Forbidden — Authenticated but not authorized
|
||||
404 Not Found — Resource doesn't exist
|
||||
409 Conflict — Duplicate entry, state conflict
|
||||
422 Unprocessable Entity — Semantically invalid (valid JSON, bad data)
|
||||
429 Too Many Requests — Rate limit exceeded
|
||||
# 客户端错误
|
||||
400 Bad Request — 验证失败、JSON 格式错误
|
||||
401 Unauthorized — 缺少或无效的身份验证
|
||||
403 Forbidden — 已认证但未授权
|
||||
404 Not Found — 资源不存在
|
||||
409 Conflict — 重复条目、状态冲突
|
||||
422 Unprocessable Entity — 语义无效（JSON 格式正确但数据错误）
|
||||
429 Too Many Requests — 超出速率限制
|
||||
|
||||
# Server Errors
|
||||
500 Internal Server Error — Unexpected failure (never expose details)
|
||||
502 Bad Gateway — Upstream service failed
|
||||
503 Service Unavailable — Temporary overload, include Retry-After
|
||||
# 服务器错误
|
||||
500 Internal Server Error — 意外故障（切勿暴露细节）
|
||||
502 Bad Gateway — 上游服务失败
|
||||
503 Service Unavailable — 临时过载，需包含 Retry-After 头部
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
```
|
||||
# BAD: 200 for everything
|
||||
# 错误：对所有请求都返回 200
|
||||
{ "status": 200, "success": false, "error": "Not found" }
|
||||
|
||||
# GOOD: Use HTTP status codes semantically
|
||||
# 正确：按语义使用 HTTP 状态码
|
||||
HTTP/1.1 404 Not Found
|
||||
{ "error": { "code": "not_found", "message": "User not found" } }
|
||||
|
||||
# BAD: 500 for validation errors
|
||||
# GOOD: 400 or 422 with field-level details
|
||||
# 错误：验证错误返回 500
|
||||
# 正确：返回 400 或 422 并包含字段级详情
|
||||
|
||||
# BAD: 200 for created resources
|
||||
# GOOD: 201 with Location header
|
||||
# 错误：创建资源返回 200
|
||||
# 正确：返回 201 并包含 Location 标头
|
||||
HTTP/1.1 201 Created
|
||||
Location: /api/v1/users/abc-123
|
||||
```
|
||||
@@ -202,7 +202,7 @@ interface ApiError {
|
||||
```
|
||||
GET /api/v1/users?page=2&per_page=20
|
||||
|
||||
# Implementation
|
||||
# 实现
|
||||
SELECT * FROM users
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 20 OFFSET 20;
|
||||
@@ -216,11 +216,11 @@ LIMIT 20 OFFSET 20;
|
||||
```
|
||||
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
|
||||
|
||||
# Implementation
|
||||
# 实现
|
||||
SELECT * FROM users
|
||||
WHERE id > :cursor_id
|
||||
ORDER BY id ASC
|
||||
LIMIT 21; -- fetch one extra to determine has_next
|
||||
LIMIT 21; -- 多取一条以判断是否有下一页
|
||||
```
|
||||
|
||||
```json
|
||||
@@ -250,44 +250,44 @@ LIMIT 21; -- fetch one extra to determine has_next
|
||||
### 过滤
|
||||
|
||||
```
|
||||
# Simple equality
|
||||
# 简单相等
|
||||
GET /api/v1/orders?status=active&customer_id=abc-123
|
||||
|
||||
# Comparison operators (use bracket notation)
|
||||
# 比较运算符（使用括号表示法）
|
||||
GET /api/v1/products?price[gte]=10&price[lte]=100
|
||||
GET /api/v1/orders?created_at[after]=2025-01-01
|
||||
|
||||
# Multiple values (comma-separated)
|
||||
# 多个值（逗号分隔）
|
||||
GET /api/v1/products?category=electronics,clothing
|
||||
|
||||
# Nested fields (dot notation)
|
||||
# 嵌套字段（点表示法）
|
||||
GET /api/v1/orders?customer.country=US
|
||||
```
|
||||
|
||||
### 排序
|
||||
|
||||
```
|
||||
# Single field (prefix - for descending)
|
||||
# 单字段排序（前缀 - 表示降序）
|
||||
GET /api/v1/products?sort=-created_at
|
||||
|
||||
# Multiple fields (comma-separated)
|
||||
# 多字段排序（逗号分隔）
|
||||
GET /api/v1/products?sort=-featured,price,-created_at
|
||||
```
|
||||
|
||||
### 全文搜索
|
||||
|
||||
```
|
||||
# Search query parameter
|
||||
# 搜索查询参数
|
||||
GET /api/v1/products?q=wireless+headphones
|
||||
|
||||
# Field-specific search
|
||||
# 字段特定搜索
|
||||
GET /api/v1/users?email=alice
|
||||
```
|
||||
|
||||
### 稀疏字段集
|
||||
|
||||
```
|
||||
# Return only specified fields (reduces payload)
|
||||
# 仅返回指定字段（减少负载）
|
||||
GET /api/v1/users?fields=id,name,email
|
||||
GET /api/v1/orders?fields=id,total,status&include=customer.name
|
||||
```
|
||||
@@ -334,7 +334,7 @@ X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
X-RateLimit-Reset: 1640000000
|
||||
|
||||
# When exceeded
|
||||
# 超出限制时
|
||||
HTTP/1.1 429 Too Many Requests
|
||||
Retry-After: 60
|
||||
{
|
||||
@@ -379,21 +379,21 @@ Accept: application/vnd.myapp.v2+json
|
||||
### 版本控制策略
|
||||
|
||||
```
|
||||
1. Start with /api/v1/ — don't version until you need to
|
||||
2. Maintain at most 2 active versions (current + previous)
|
||||
3. Deprecation timeline:
|
||||
- Announce deprecation (6 months notice for public APIs)
|
||||
- Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
|
||||
- Return 410 Gone after sunset date
|
||||
4. Non-breaking changes don't need a new version:
|
||||
- Adding new fields to responses
|
||||
- Adding new optional query parameters
|
||||
- Adding new endpoints
|
||||
5. Breaking changes require a new version:
|
||||
- Removing or renaming fields
|
||||
- Changing field types
|
||||
- Changing URL structure
|
||||
- Changing authentication method
|
||||
1. 从 /api/v1/ 开始 —— 除非必要，否则不要急于版本化
|
||||
2. 最多同时维护 2 个活跃版本（当前版本 + 前一个版本）
|
||||
3. 弃用时间线：
|
||||
- 宣布弃用（公共 API 需提前 6 个月通知）
|
||||
- 添加 Sunset 响应头：Sunset: Sat, 01 Jan 2026 00:00:00 GMT
|
||||
- 在弃用日期后返回 410 Gone 状态
|
||||
4. 非破坏性变更无需创建新版本：
|
||||
- 向响应中添加新字段
|
||||
- 添加新的可选查询参数
|
||||
- 添加新的端点
|
||||
5. 破坏性变更需要创建新版本：
|
||||
- 移除或重命名字段
|
||||
- 更改字段类型
|
||||
- 更改 URL 结构
|
||||
- 更改身份验证方法
|
||||
```
|
||||
|
||||
## 实现模式
|
||||
|
||||
Reference in New Issue
Block a user