with one click
api-design
REST API 设计模式,包括资源命名、状态代码、分页、过滤、错误响应、版本控制和生产 API 的速率限制。
Menu
REST API 设计模式,包括资源命名、状态代码、分页、过滤、错误响应、版本控制和生产 API 的速率限制。
| name | api-design |
| description | REST API 设计模式,包括资源命名、状态代码、分页、过滤、错误响应、版本控制和生产 API 的速率限制。 |
用于设计一致的开发人员友好的 REST API 的约定和最佳实践。
# 资源是名词、复数、小写、kebab-case
GET /api/v1/users
GET /api/v1/users/:id
POST /api/v1/users
PUT /api/v1/users/:id
PATCH /api/v1/users/:id
DELETE /api/v1/users/:id
# 用于关系的子资源
GET /api/v1/users/:id/orders
POST /api/v1/users/:id/orders
# 不映射到 CRUD 的操作(谨慎使用动词)
POST /api/v1/orders/:id/cancel
POST /api/v1/auth/login
POST /api/v1/auth/refresh
# GOOD
/api/v1/team-members # 多词资源使用 kebab-case
/api/v1/orders?status=active # 查询参数用于过滤
/api/v1/users/123/orders # 嵌套资源用于所有权
# BAD
/api/v1/getUsers # URL 中的动词
/api/v1/user # 单数(使用复数)
/api/v1/team_members # URL 中的 snake_case
/api/v1/users/123/getOrders # 嵌套资源中的动词
| 方法 | 幂等 | 安全 | 用于 |
|---|---|---|---|
| GET | 是 | 是 | 检索资源 |
| POST | 否 | 否 | 创建资源,触发操作 |
| PUT | 是 | 否 | 完全替换资源 |
| PATCH | 否* | 否 | 部分更新资源 |
| DELETE | 是 | 否 | 删除资源 |
*PATCH 可以通过正确实现实现幂等
# 成功
200 OK — GET、PUT、PATCH(带有响应体)
201 Created — POST(包括 Location 头)
204 No Content — DELETE、PUT(无响应体)
# 客户端错误
400 Bad Request — 验证失败、格式错误的 JSON
401 Unauthorized — 缺少或无效的身份验证
403 Forbidden — 已认证但未授权
404 Not Found — 资源不存在
409 Conflict — 重复条目、状态冲突
422 Unprocessable Entity — 语义无效(有效 JSON,错误数据)
429 Too Many Requests — 超过速率限制
# 服务器错误
500 Internal Server Error — 意外失败(绝不暴露详细信息)
502 Bad Gateway — 上游服务失败
503 Service Unavailable — 临时过载,包括 Retry-After
# BAD:一切都是 200
{ "status": 200, "success": false, "error": "Not found" }
# GOOD:语义化使用 HTTP 状态代码
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }
# BAD:验证错误返回 500
# GOOD:400 或 422,带字段级详细信息
# BAD:创建资源返回 200
# GOOD:201,带 Location 头
HTTP/1.1 201 Created
Location: /api/v1/users/abc-123
{
"data": {
"id": "abc-123",
"email": "alice@example.com",
"name": "Alice",
"created_at": "2025-01-15T10:30:00Z"
}
}
{
"data": [
{ "id": "abc-123", "name": "Alice" },
{ "id": "def-456", "name": "Bob" }
],
"meta": {
"total": 142,
"page": 1,
"per_page": 20,
"total_pages": 8
},
"links": {
"self": "/api/v1/users?page=1&per_page=20",
"next": "/api/v1/users?page=2&per_page=20",
"last": "/api/v1/users?page=8&per_page=20"
}
}
{
"error": {
"code": "validation_error",
"message": "请求验证失败",
"details": [
{
"field": "email",
"message": "必须是有效的电子邮件地址",
"code": "invalid_format"
},
{
"field": "age",
"message": "必须在 0 到 150 之间",
"code": "out_of_range"
}
]
}
}
// 选项 A:带数据包装器的包装器(推荐用于公共 API)
interface ApiResponse<T> {
data: T;
meta?: PaginationMeta;
links?: PaginationLinks;
}
interface ApiError {
error: {
code: string;
message: string;
details?: FieldError[];
};
}
// 选项 B:平面响应(更简单,内部 API 常见)
// 成功:直接返回资源
// 错误:返回错误对象
// 通过 HTTP 状态代码区分
GET /api/v1/users?page=2&per_page=20
# 实现
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 20;
优点: 易于实现,支持"跳转到第 N 页" 缺点: 在大偏移量上慢(OFFSET 100000),与并发插入不一致
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
# 实现
SELECT * FROM users
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT 21; -- 多获取一个以确定 has_next
{
"data": [...],
"meta": {
"has_next": true,
"next_cursor": "eyJpZCI6MTQzfQ"
}
}
优点: 无论位置如何性能一致,与并发插入稳定 缺点: 无法跳转到任意页面,游标是不透明的
| 用例 | 分页类型 |
|---|---|
| 管理仪表板、小数据集(<10K) | 偏移量 |
| 无限滚动、信息流、大数据集 | 游标 |
| 公共 API | 游标(默认)带偏移量(可选) |
| 搜索结果 | 偏移量(用户期望页码) |
# 简单相等
GET /api/v1/orders?status=active&customer_id=abc-123
# 比较运算符(使用括号表示法)
GET /api/v1/products?price[gte]=10&price[lte]=100
GET /api/v1/orders?created_at[after]=2025-01-01
# 多个值(逗号分隔)
GET /api/v1/products?category=electronics,clothing
# 嵌套字段(点表示法)
GET /api/v1/orders?customer.country=US
# 单字段(前缀 - 表示降序)
GET /api/v1/products?sort=-created_at
# 多字段(逗号分隔)
GET /api/v1/products?sort=-featured,price,-created_at
# 搜索查询参数
GET /api/v1/products?q=wireless+headphones
# 字段特定搜索
GET /api/v1/users?email=alice
# 仅返回指定字段(减少负载)
GET /api/v1/users?fields=id,name,email
GET /api/v1/orders?fields=id,total,status&include=customer.name
# Authorization 头中的不记名令牌
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
# API 密钥(用于服务器到服务器)
GET /api/v1/data
X-API-Key: sk_live_abc123
// 资源级:检查所有权
app.get("/api/v1/orders/:id", async (req, res) => {
const order = await Order.findById(req.params.id);
if (!order) return res.status(404).json({ error: { code: "not_found" } });
if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
return res.json({ data: order });
});
// 基于角色:检查权限
app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
await User.delete(req.params.id);
return res.status(204).send();
});
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
# 超过时
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
"error": {
"code": "rate_limit_exceeded",
"message": "超过速率限制。请在 60 秒后重试。"
}
}
| 层级 | 限制 | 窗口 | 用例 |
|---|---|---|---|
| 匿名 | 30/分钟 | 每 IP | 公共端点 |
| 已认证 | 100/分钟 | 每用户 | 标准 API 访问 |
| 高级 | 1000/分钟 | 每 API 密钥 | 付费 API 计划 |
| 内部 | 10000/分钟 | 每服务 | 服务到服务 |
/api/v1/users
/api/v2/users
优点: 显式、易于路由、可缓存 缺点: 版本之间 URL 更改
GET /api/users
Accept: application/vnd.myapp.v2+json
优点: 干净的 URL 缺点: 难以测试,容易忘记
1. 从 /api/v1/ 开始 — 不需要时不版本控制
2. 最多维护 2 个活动版本(当前 + 前一个)
3. 弃用时间表:
- 宣布弃用(公共 API 6 个月通知)
- 添加 Sunset 头:Sunset: Sat, 01 Jan 2026 00:00:00 GMT
- 在日落日期后返回 410 Gone
4. 非破坏性更改不需要新版本:
- 向响应添加新字段
- 添加新的可选查询参数
- 添加新端点
5. 破坏性更改需要新版本:
- 删除或重命名字段
- 更改字段类型
- 更改 URL 结构
- 更改身份验证方法
import { z } from "zod";
import { NextRequest, NextResponse } from "next/server";
const createUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1).max(100),
});
export async function POST(req: NextRequest) {
const body = await req.json();
const parsed = createUserSchema.safeParse(body);
if (!parsed.success) {
return NextResponse.json({
error: {
code: "validation_error",
"message": "请求验证失败",
details: parsed.error.issues.map(i => ({
field: i.path.join("."),
message: i.message,
code: i.code,
})),
},
}, { status: 422 });
}
const user = await createUser(parsed.data);
return NextResponse.json(
{ data: user },
{
status: 201,
headers: { Location: `/api/v1/users/${user.id}` },
},
);
}
from rest_framework import serializers, viewsets, status
from rest_framework.response import Response
class CreateUserSerializer(serializers.Serializer):
email = serializers.EmailField()
name = serializers.CharField(max_length=100)
class UserSerializer(serializers.ModelSerializer):
class Meta:
model = User
fields = ["id", "email", "name", "created_at"]
class UserViewSet(viewsets.ModelViewSet):
serializer_class = UserSerializer
permission_classes = [IsAuthenticated]
def get_serializer_class(self):
if self.action == "create":
return CreateUserSerializer
return UserSerializer
def create(self, request):
serializer = CreateUserSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
user = UserService.create(**serializer.validated_data)
return Response(
{"data": UserSerializer(user).data},
status=status.HTTP_201_CREATED,
headers={"Location": f"/api/v1/users/{user.id}"},
)
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
var req CreateUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "invalid_json", "无效的请求体")
return
}
if err := req.Validate(); err != nil {
writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
return
}
user, err := h.service.Create(r.Context(), req)
if err != nil {
switch {
case errors.Is(err, domain.ErrEmailTaken):
writeError(w, http.StatusConflict, "email_taken", "电子邮件已注册")
default:
writeError(w, http.StatusInternalServerError, "internal_error", "内部错误")
}
return
}
w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
writeJSON(w, http.StatusCreated, map[string]any{"data": user})
}
在发布新端点之前:
从零开始或通过转换 PowerPoint 文件创建精美的、动画丰富的 HTML 演示文稿。当用户想要构建演示文稿、将 PPT/PPTX 转换为网页或为演讲/路演创建幻灯片时使用。帮助非设计师通过视觉探索而非抽象选择发现他们的审美。
可视化技能、规则和智能体定义是否被真正遵循 — 自动生成 3 个提示严格度级别的场景,运行智能体,分类行为序列,并报告合规率及完整工具调用时间线
使用 tinystruct Java 框架进行开发的专家指南。在 tinystruct 代码库或任何基于 tinystruct 构建的项目上工作时使用 — 包括创建 Application 类、@Action 映射路由、单元测试、ActionRegistry、HTTP/CLI 双模式处理、内置 HTTP 服务器、事件系统、JSON 与 Builder/Builders、使用 AbstractData 的数据库持久化、POJO 生成、Server-Sent Events (SSE)、文件上传和出站 HTTP 网络。
查看、理解、操作视频和音频。查看 — 从本地文件、URL、RTSP/直播流或实时录制桌面进行摄取;返回实时上下文和可播放的流链接。理解 — 提取帧、构建视觉/语义/时间索引,以及带时间戳和自动片段的搜索时刻。操作 — 转码和归一化(编解码器、fps、分辨率、宽高比)、执行时间线编辑(字幕、文本/图像叠加、品牌、音频叠加、配音、翻译)、生成媒体资产(图像、音频、视频),以及为直播流或桌面捕获中的事件创建实时警报。
Remotion 的最佳实践 —— 在 React 中创建视频。涵盖 3D、动画、音频、字幕、图表、转场等 29 条领域特定规则。
AI 原生线索情报和外联流水线。用智能体驱动的信号评分、互惠排名、热路径发现、来源语音建模和跨渠道外联(电子邮件、LinkedIn 和 X)替代 Apollo、Clay 和 ZoomInfo。当用户想要查找、评估和触达高价值联系人时使用。