Bruno GaoandQwen-Coder
2fd1eb59ab
- Create SECURITY.md with vulnerability disclosure policy - Create docs/README.md as documentation index page - Create docs/observability.md with metrics/logs/traces/alerting/SLO specs - Create docs/runbook.md with troubleshooting scenarios (RB-01 to RB-05) - Create docs/security.md with security design and compliance - Create docs/release.md with versioning and rollback strategies - Create docs/database.md with database design and migration strategy - Create docs/adr/0005-cache-error-handler.md for cache error handling ADR - Update README.md with documentation index section - Update docs/architecture.md to update B-7 rule and add trust boundary section - Create docs/api-guide.md with API specifications - Fix method names in OrderDao.java to match OrderMapper interface - Add Spring Boot Actuator dependency to tmpl-infrastructure - Fix Redis ping method in RedisHealthContributor.java - Fix syntax errors and method names in OrderAppService.java Co-authored-by: Qwen-Coder <[email protected]>
192 lines
5.0 KiB
Markdown
192 lines
5.0 KiB
Markdown
# 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. 安全考虑
|
||
|
||
- 输入参数必须经过校验，防止注入攻击
|
||
- 敏感信息不在日志中记录
|
||
- 所有查询自动附加租户隔离条件
|
||
- 响应中不泄露系统内部信息 |