baiyue-firstleg/common-web/AGENTS.md

Common Web 模块指引

职责边界

• 提供 Servlet Web 通用能力：请求链路标识、上下文和统一异常响应。
• 不放具体业务 Controller、路由或领域异常编排；业务错误通过 common-core 的契约表达。

快速索引

功能	入口
链路上下文	src/main/java/com/baiyue/common/web/CorrelationContext.java
请求 ID 过滤器	src/main/java/com/baiyue/common/web/CorrelationIdFilter.java
W3C Trace Context	src/main/java/com/baiyue/common/web/TraceParent.java；严格接收 version 00，响应 traceparent、X-Trace-Id 与 MDC traceId 使用同一 trace ID
Feign Trace 传播	FeignTraceRequestInterceptor.java、FeignTracePropagationAutoConfiguration.java；仅 Feign 存在时装配，optional 依赖不向无 Feign 服务传递
RestClient Trace 传播	RestClientTraceInterceptor.java、RestClientTracePropagationAutoConfiguration.java；Spring 管理的 Builder 自动装配，原始 Builder 可显式复用拦截器
自动配置入口	src/main/java/com/baiyue/common/web/CommonWebAutoConfiguration.java；为只扫描自身包的服务注册异常处理器和 Correlation 过滤器
全局异常映射与业务失败指标	src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java；指标 baiyue.api.business.failures 按有限 code 标记
过滤器测试	src/test/java/com/baiyue/common/web/CorrelationIdFilterTest.java
异常响应测试	src/test/java/com/baiyue/common/web/GlobalExceptionHandlerTest.java
长整型 JSON 字符串序列化	src/main/java/com/baiyue/common/web/LongIdJacksonConfiguration.java

修改与验证

• 普通 BizException、参数校验和兜底系统异常统一返回 HTTP 200 + 非 "200" body code；查询参数/消息解析失败使用 A0400，Bean Validation 使用 A0422，不要再按 HTTP 400/422 判断业务失败。
• 网关/Servlet Security 的真实 401/403、协议或基础设施错误、Warehouse readiness 503、Audit 202 与 Event Bridge 内部鉴权仍保留真实 HTTP 状态；完整边界见 ../docs/统一响应约定改造方案-HTTP200.md。
• 修改自动配置时必须验证 audit-service、event-bridge-service 等只扫描自身包的应用仍能加载 GlobalExceptionHandler 和 CorrelationIdFilter。
• 修改 Correlation ID 时同步检查当前请求头契约、线程上下文清理和日志链路。
• 入站 Trace 优先级固定为：合法单值 traceparent > 完全缺失 traceparent 时的 32 位非零十六进制 X-Trace-Id > 新 trace。只要 traceparent 已出现但重复、超长、格式非法或含全零 ID，就必须生成新 trace，不得回退信任 X-Trace-Id；请求 ID 独立按 X-Request-Id 校验或生成。
• 同步 Feign 出站固定先移除调用模板中的 X-Request-Id、X-Trace-Id、traceparent，再仅从当前 MDC 的合法请求 ID 和 trace ID 重建；traceparent 沿用当前 trace ID、每次调用生成新非零 span ID、flags 固定 01。不得从业务参数、远端返回头或无效 MDC 建立上下文；本能力不处理 Reactor、异步线程、重试、超时或 fallback。
• 同步 RestClient 出站统一覆盖 X-Request-Id、X-Trace-Id、traceparent，从当前 MDC 生成 child span；MDC 缺失或非法时安全新建 trace。不得从业务参数或远端响应头建立上下文，生产代码应使用 Spring 管理的 RestClient.Builder，原始 Builder 必须显式安装同一拦截器。
• 从父目录运行 mvn -pl common-web -am test。
• 所有对外 Long/long 值统一序列化为 JSON 字符串，避免 19 位雪花 ID 在浏览器中丢失精度；禁止业务模块重复添加局部转换器。