# EZ-API Response Envelope 规范

本文档定义响应信封结构及业务码表。HTTP 状态码保留用于传输层语义。

## Envelope 结构

```json
{
  "code": 0,
  "message": "success",
  "data": { "user_id": 123, "name": "example" },
  "trace_id": "req_abc123"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `code` | number | ✅ | 业务码，0=成功，非0=错误 |
| `message` | string | ✅ | 成功时 `"success"`，错误时具体描述 |
| `data` | object/array/null | ✅ | 成功时返回业务数据，错误时为 `null` |
| `trace_id` | string | ✅ | 请求追踪 ID，复用 `X-Request-ID` 或自动生成 |
| `details` | object/null | ❌ | 可选，错误时的补充信息（如字段级校验错误） |

## 业务码表

### 码段划分

| 范围 | 类别 | 说明 |
|------|------|------|
| 0 | 成功 | 请求成功 |
| 1000-1999 | 通用错误 | 参数错误、认证失败等通用场景 |
| 4000-4999 | 客户端错误 | 业务级客户端错误 |
| 5000-5999 | 服务端错误 | 服务端内部错误 |

### 通用错误 (1xxx)

| Code | 名称 | HTTP Status | 说明 |
|------|------|-------------|------|
| 1001 | invalid_param | 400 | 参数校验失败 |
| 1002 | unauthorized | 401 | 未认证或认证失效 |
| 1003 | forbidden | 403 | 无权限访问 |
| 1004 | rate_limited | 429 | 请求频率超限 |

### 客户端错误 (4xxx)

| Code | 名称 | HTTP Status | 说明 |
|------|------|-------------|------|
| 4001 | resource_not_found | 404 | 资源不存在 |
| 4002 | resource_conflict | 409 | 资源冲突（如重复创建） |
| 4003 | invalid_state | 400 | 资源状态不允许此操作 |

### 服务端错误 (5xxx)

| Code | 名称 | HTTP Status | 说明 |
|------|------|-------------|------|
| 5001 | internal_error | 500 | 服务器内部错误 |
| 5002 | service_unavailable | 503 | 服务暂不可用 |
| 5003 | timeout | 504 | 请求超时 |

## 示例

### 成功响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "example"
  },
  "trace_id": "req_abc123"
}
```

### 错误响应（简单）

```json
{
  "code": 4001,
  "message": "master not found",
  "data": null,
  "trace_id": "req_abc123"
}
```

### 错误响应（带 details）

```json
{
  "code": 1001,
  "message": "参数校验失败",
  "data": null,
  "details": {
    "user_id": "必填",
    "email": "格式错误"
  },
  "trace_id": "req_abc123"
}
```

## 客户端处理指南

1. **判断成功/失败**：检查 `code === 0`
2. **获取业务数据**：成功时从 `data` 读取
3. **展示错误信息**：使用 `message` 字段
4. **排查问题**：记录/上报 `trace_id`
5. **字段级错误**：检查 `details` 是否存在

## 不包装的端点

以下端点不使用 envelope 包装：
- Swagger UI (`/swagger/*`)
- 健康检查 (`/health`)
- Metrics (`/debug/vars`, `/internal/metrics`)
- CORS preflight