spec.md 1.9 KB
ADDED Requirements
Requirement: TraceId 贯穿请求与日志
系统 SHALL 对每个进入基座的 HTTP 请求提取或生成一个 traceId，写入 SLF4J MDC，使 logback 输出的每行日志都带上 [traceId] 字段；响应写回 X-Trace-Id 头；请求结束时清理 MDC。
Scenario: 客户端携带 X-Trace-Id
- WHEN 请求 header 含
X-Trace-Id: abc123 - THEN 日志 pattern 中
%X{traceId}输出为abc123；响应头回写同值
Scenario: 客户端未携带
- WHEN 请求 header 无
X-Trace-Id - THEN 系统生成 32 位无横线 UUID 作为 traceId；写 MDC + 响应头
Scenario: 请求结束清理
- WHEN 请求处理完成（正常或异常）
- THEN MDC 中 traceId 被移除，不会污染下一个线程池复用
Requirement: OpenAPI 文档可控启用
系统 SHALL 通过 application.yml 中 swagger.enable 开关控制 OpenAPI/Swagger UI 是否加载；默认 false；启用后 UI 暴露在 /api/swagger-ui.html（受 server.servlet.context-path 前缀影响）。
Scenario: 开发/测试环境启用
- WHEN 在
application-dev.yml中设置swagger.enable: true - THEN 启动后访问
<host>/api/swagger-ui.html可看到交互式文档 - AND 所有带 Spring MVC 注解（
@RestController等）的 controller 自动列出
Scenario: 生产关闭
- WHEN
swagger.enable为 false 或未配置 - THEN Swagger UI 与
/v3/api-docs均 404；不加载任何 springdoc bean
Requirement: Actuator 健康检查
系统 SHALL 暴露 /actuator/health 与 /actuator/info 两个端点，其他 actuator 端点默认关闭。
Scenario: 健康检查探针
- WHEN 访问
<host>/api/actuator/health - THEN 返回 200 +
{"status":"UP", ...}；包含数据源（若配置）健康子项
Scenario: 敏感端点默认关闭
- WHEN 访问
/actuator/env或/actuator/beans - THEN 返回 404（未暴露）