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 如何描述这些格式，欢迎继续问！
