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
全局异常映射	src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java
过滤器测试	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

修改与验证

• 修改异常响应时同时检查 HTTP 状态、ApiResponse 结构、校验错误和安全异常是否仍一致。
• 查询参数类型转换失败映射为 400，Bean Validation 约束失败映射为 422，禁止落入通用 500。
• 修改 Correlation ID 时检查请求头兼容、线程上下文清理和日志链路。
• 从父目录运行 mvn -pl common-web -am test。
• 所有对外 Long/long 值统一序列化为 JSON 字符串，避免 19 位雪花 ID 在浏览器中丢失精度；禁止业务模块重复添加局部转换器。