RESTful API 的请求和响应格式详解
在 RESTful API 中，请求和响应的格式设计直接影响 API 的易用性、一致性和可维护性。优秀的格式规范能让前后端开发者快速理解接口行为，减少沟通成本。
1. 总体原则
- 内容类型统一：几乎全部使用 JSON（application/json）作为请求和响应的数据格式。
- 结构一致：成功响应和错误响应都采用统一的包裹结构，便于客户端统一处理。
- 清晰、可读：字段命名规范，时间格式标准，返回必要元信息。
- 避免裸数据：不要直接返回数组或单个对象，而是用包裹对象提供上下文。
2. 请求格式（Request）
2.1 常见 Content-Type
| HTTP 方法 | 典型 Content-Type | 说明 |
|---|---|---|
| POST / PUT / PATCH | application/json | 最常用，发送 JSON 数据 |
| 文件上传 | multipart/form-data | 上传头像、附件等 |
| 表单提交 | application/x-www-form-urlencoded | 传统表单（较少用） |
2.2 请求体（Body）示例
创建用户（POST /users）
{
"name": "张三",
"email": "zhang@example.com",
"password": "secret123",
"age": 28,
"roles": ["user", "admin"]
}部分更新用户（PATCH /users/123）
{
"name": "张三丰",
"age": 30
}（只包含需要修改的字段）
查询参数（Query Parameters）用于 GET 请求过滤
GET /articles?status=published&tag=rest&sort=-created_at&page=2&limit=202.3 请求头（Headers）常用字段
| Header | 示例值 | 说明 |
|---|---|---|
| Content-Type | application/json | 请求体格式 |
| Accept | application/json | 期望响应格式 |
| Authorization | Bearer eyJhbGciOiJIUzI1NiIs… | JWT 或其他认证令牌 |
| X-API-Key | your-api-key | API Key 认证 |
3. 响应格式（Response）
3.1 成功响应统一结构（推荐）
方案一：通用包裹（最常用）
{
"data": { // 主要数据
"id": 123,
"name": "张三",
"email": "zhang@example.com",
"created_at": "2025-12-25T10:00:00Z"
},
"meta": { // 元信息（可选）
"timestamp": "2025-12-25T10:00:01Z",
"request_id": "abc123-def456"
}
}方案二：集合响应（列表 + 分页）
{
"data": [
{ "id": 1, "title": "REST 教程" },
{ "id": 2, "title": "API 设计" }
],
"meta": {
"pagination": {
"total": 156,
"page": 2,
"limit": 20,
"total_pages": 8
},
"timestamp": "2025-12-25T10:00:01Z"
}
}方案三：无数据内容（如 DELETE 成功）
- 返回 204 No Content（无响应体，最推荐）
- 或返回 200 + 简单结构：
{
"data": null,
"meta": {
"message": "用户删除成功"
}
}3.2 错误响应统一结构（非常重要！）
推荐错误格式（Problem Details – RFC 7807 标准）
{
"error": {
"code": "VALIDATION_ERROR", // 业务错误码（字符串）
"message": "请求参数验证失败", // 给开发者的友好提示
"details": [ // 具体字段错误（可选）
{
"field": "email",
"issue": "already_exists",
"message": "该邮箱已被注册"
},
{
"field": "age",
"issue": "invalid_range",
"message": "年龄必须在 18-100 之间"
}
]
}
}响应头：
- Content-Type: application/json
- HTTP 状态码：400 Bad Request、422 Unprocessable Entity 等
常见错误状态码与 code 对应
| HTTP 状态码 | 推荐 error.code | 场景 |
|---|---|---|
| 400 | BAD_REQUEST | 参数格式错误 |
| 401 | UNAUTHORIZED | 未登录 |
| 403 | FORBIDDEN | 无权限 |
| 404 | NOT_FOUND | 资源不存在 |
| 409 | CONFLICT | 资源冲突（如用户名重复） |
| 422 | VALIDATION_ERROR | 业务校验失败（最常用） |
| 429 | TOO_MANY_REQUESTS | 限流 |
| 500 | INTERNAL_SERVER_ERROR | 服务器异常 |
3.3 字段命名与数据格式规范
| 项目 | 推荐规范 | 示例 |
|---|---|---|
| 字段命名 | snake_case（下划线）或 camelCase | user_id 或 userId（统一即可） |
| 时间格式 | ISO 8601（UTC） | “2025-12-25T10:00:00Z” |
| 布尔值 | true / false | “is_active”: true |
| 空值 | null（避免空字符串） | “description”: null |
| 枚举 | 字符串常量 | “status”: “published” |
4. 完整示例对比
请求
POST /api/v1/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer xyz123...
{
"name": "李四",
"email": "li@example.com",
"password": "123456"
}成功响应（201 Created）
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/456
{
"data": {
"id": 456,
"name": "李四",
"email": "li@example.com",
"created_at": "2025-12-25T10:00:00Z"
},
"meta": {
"timestamp": "2025-12-25T10:00:01Z"
}
}错误响应（422）
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "参数验证失败",
"details": [
{
"field": "email",
"issue": "invalid_format",
"message": "邮箱格式不正确"
}
]
}
}5. 总结口诀
请求简洁 JSON，响应统一包裹，错误结构化提示，状态码要准确
遵循这些格式规范，你的 RESTful API 将更加专业、一致，便于前端统一封装错误处理和数据解析。
如果你想看特定框架（如 Spring Boot、Express、FastAPI）的响应封装代码实现，或者 OpenAPI/Swagger 如何描述这些格式，欢迎继续问！
