java21-template/docs/api-guide.md

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 成功响应

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

3.2 分页响应

{
  "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 创建响应

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

3.4 空响应

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

---

4. 错误响应

4.1 标准错误格式

{
  "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：

{
  "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. 安全考虑

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