# API 指南 (API Guide)

本文档定义 tmpl-api 服务的 REST API 规范，包括端点、请求/响应格式、错误码、认证授权等。

---

## 1. API 端点规范

### 1.1 命名约定

| 资源 | 列表 | 详情 | 创建 | 更新 | 删除 |
|------|------|------|------|------|------|
| 订单 | `GET /api/v1/orders` | `GET /api/v1/orders/{id}` | `POST /api/v1/orders` | `PATCH /api/v1/orders/{id}/status` | `DELETE /api/v1/orders/{id}` |

### 1.2 版本控制

API 版本通过 URL 路径控制：`/api/v{version}/{resource}`。当前版本为 `v1`。

### 1.3 HTTP 方法语义

- `GET`：安全、幂等，用于查询资源
- `POST`：非幂等，用于创建资源或触发操作
- `PUT`：幂等，用于完全替换资源（当前未使用，使用 PATCH）
- `PATCH`：幂等，用于部分更新资源
- `DELETE`：幂等，用于删除资源

---

## 2. 请求格式

### 2.1 内容类型

| 方法 | Content-Type | Accept |
|------|--------------|--------|
| GET | (无) | `application/json` |
| POST | `application/json;charset=UTF-8` | `application/json` |
| PATCH | `application/json;charset=UTF-8` | `application/json` |
| DELETE | (无) | `application/json` |

### 2.2 多租户 Header（必需）

所有请求必须携带以下 Header：

| Header | 类型 | 说明 |
|--------|------|------|
| `X-Tenant-Id` | String | 租户标识，长度 ≤ 64 字符 |
| `X-Dept-Id` | String | 部门标识，长度 ≤ 64 字符，"0" 表示跨部门 |
| `X-User-Id` | Long | 操作人 ID，必须为合法数字 |

> **重要**：这些 Header 由 API Gateway 从 JWT Token 中提取并注入，服务不信任客户端直接传入的值。

---

## 3. 响应格式

### 3.1 成功响应

```json
{
  "code": 200,
  "message": "Success",
  "data": {
    // 具体业务数据
  },
  "timestamp": "2026-02-12T10:00:00.123Z",
  "traceId": "abc123def456"
}
```

### 3.2 分页响应

```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100,
    "pageNum": 1,
    "pageSize": 20,
    "pages": 5
  },
  "timestamp": "2026-02-12T10:00:00.123Z",
  "traceId": "abc123def456"
}
```

### 3.3 创建响应

```json
{
  "code": 201,
  "message": "Created",
  "data": {
    // 新创建的资源数据
  },
  "timestamp": "2026-02-12T10:00:00.123Z",
  "traceId": "abc123def456"
}
```

### 3.4 空响应

DELETE 操作成功时返回 204 No Content，无响应体。

---

## 4. 错误响应

### 4.1 标准错误格式

```json
{
  "code": 400,
  "errorCode": "COMMON_INVALID_PARAM",
  "message": "参数校验失败",
  "details": "orderNo 不能为空", // 仅非生产环境返回
  "timestamp": "2026-02-12T10:00:00.123Z",
  "traceId": "abc123def456"
}
```

### 4.2 通用错误码

| HTTP 状态码 | errorCode | message | 说明 |
|-------------|-----------|---------|------|
| 400 | `COMMON_INVALID_PARAM` | 参数校验失败 | 请求参数不符合约束 |
| 400 | `AUTH_MISSING_TENANT` | 缺少租户标识 | 缺少 X-Tenant-Id Header |
| 400 | `AUTH_MISSING_DEPT` | 缺少部门标识 | 缺少 X-Dept-Id Header |
| 400 | `AUTH_INVALID_USER_ID` | 用户标识格式不合法 | X-User-Id 非合法数字 |
| 400 | `AUTH_HEADER_CONFLICT` | 请求头信息冲突 | 新旧 Header 值不一致 |
| 403 | `AUTH_ACCESS_DENIED` | 无权限 | 认证失败或权限不足 |
| 403 | `AUTH_FORBIDDEN_SCOPE` | 部门范围越权 | deptId=0 但无 SCOPE_ALL_DEPT 权限 |
| 404 | `COMMON_NOT_FOUND` | 资源不存在 | 请求的资源不存在 |
| 409 | `COMMON_OPTIMISTIC_LOCK` | 数据已被修改，请刷新重试 | 乐观锁冲突 |
| 422 | `ORDER_AMOUNT_INVALID` | 订单金额不合法 | 订单金额相关业务校验失败 |
| 500 | `COMMON_INTERNAL_ERROR` | 系统内部错误 | 服务器内部错误 |

---

## 5. 认证

### 当前状态

模板当前未启用认证（`SecurityConfig` 配置为 `permitAll()`），适用于开发和演示环境。

### 生产要求

在生产部署中，所有 `/api/**` 请求必须经过认证。推荐方案为 JWT Bearer Token
（`spring-boot-starter-oauth2-resource-server`）。

### X-Tenant-Id Header

所有 API 请求必须携带 `X-Tenant-Id` Header。

**重要**：在生产环境中，此 Header 的值必须由 API Gateway / 认证层从已验证的
JWT Token 中提取并注入，不得信任客户端直接传入的值。tmpl-api 假设上游已完成校验。

缺失该 Header 时，服务返回 `400 Bad Request`：

```json
{
  "code": 400,
  "message": "Missing X-Tenant-Id header",
  "data": null
}
```

---

## 6. 限流与熔断

当前未实现限流与熔断机制，计划在后续迭代中引入 Resilience4j。

---

## 7. 监控指标

API 调用通过 Micrometer 自动记录以下指标：

- `http.server.requests`：请求计数、延迟、状态码分布
- `http.client.requests`：下游服务调用指标（如有）
- 业务自定义指标（如 `order.created.total`）

---

## 8. 安全考虑

- 输入参数必须经过校验，防止注入攻击
- 敏感信息不在日志中记录
- 所有查询自动附加租户隔离条件
- 响应中不泄露系统内部信息