myblog/rule/后端api接口文档/接口统一响应文档.md

接口统一响应规范

通用规范

基础信息

项目	内容	说明
Base URL	http://localhost:8080/api/	接口基础路径
Content-Type	application/json	统一采用 JSON 格式传输数据
字符编码	UTF-8	确保多语言字符兼容
时间格式	ISO 8601	示例：2025-01-09T10:30:00Z（UTC 时间）、2025-01-09T18:30:00+08:00（带时区）
请求方法	遵循 RESTful 规范	GET（查询）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除）

统一响应格式

所有API接口均使用统一的响应格式，结构如下：

{
  "code": 200,           // 业务状态码
  "message": "操作成功",   // 响应描述信息
  "data": { ... },       // 响应数据（成功时为业务数据，失败时可为null或错误详情）
  "timestamp": "2025-08-11T00:30:00+08:00"  // 服务器响应时间戳（ISO 8601格式）
}

状态码定义

状态码	含义	适用场景	前端处理建议
200	成功	请求处理完成且结果正常	解析 data 展示业务数据
201	创建成功	资源（如用户、订单）创建完成	可跳转至详情页或提示创建结果
400	请求错误	参数格式错误、缺失必填项等	展示具体参数错误信息（如data.errors）
401	未授权	未登录、token 过期或无效	跳转至登录页
403	禁止访问	登录状态下无操作权限	提示 "无权限"，可跳转至首页
404	资源不存在	请求的 URL 或资源 ID 不存在	提示 "资源不存在"
409	资源冲突	资源已存在（如用户名重复）	提示冲突原因（如 "用户名已被注册"）
423	账户锁定	账户因安全原因被临时锁定	提示锁定原因及解锁方式
500	服务器错误	后端逻辑异常、数据库错误等	提示 "系统繁忙，请稍后重试"，不展示技术细节

通用响应示例

成功响应（状态码 200）

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "status": "UP",
    "message": "应用正常运行中"
  },
  "timestamp": "2025-08-11T00:11:02.52634"
}

成功响应（状态码 201）

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 100,
    "username": "newUser",
    "password": "password123",
    "email": "new@example.com"
  },
  "timestamp": "2025-08-11T00:30:00+08:00"
}

列表数据响应测试

响应示例

成功响应（状态码 200）

{
  "code": 200,
  "message": "操作成功",
  "data": ["项目1", "项目2", "项目3"],
  "timestamp": "2025-08-11T00:11:48.321178"
}