# 接口统一响应规范
## 通用规范

###  基础信息

| 项目             | 内容                           | 说明                                                         |
| ---------------- | ------------------------------ | ------------------------------------------------------------ |
| **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接口均使用统一的响应格式，结构如下：

```json
{
  "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）

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


##### 成功响应（状态码 201）

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


###  列表数据响应测试


#### 响应示例

##### 成功响应（状态码 200）

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