Java中级项目统一日志格式的核心是结构化、标准字段与全链路支持，需包含timestamp、level、traceId、spanId、service、thread、class、message八个标准化字段，推荐Logback+LogstashEncoder+MDC方案，按访问日志、业务日志、异常日志、调试日志分场景规范，并通过落地检查清单确保生效。
Java中级项目统一日志格式，核心是结构化 + 标准字段 + 全链路支持，不是简单配个PatternLayout就完事。关键在于让日志可读、可查、可追踪、可聚合，尤其在微服务或模块较多的项目中，日志格式不统一会导致排查效率断崖式下降。
一、必须包含的标准化字段
每条日志至少应携带以下5个基础维度信息，建议以JSON结构输出（便于ELK等工具解析）：
-
timestamp：ISO8601格式（如 2025-05-22T14:23:18.927+0800），避免时区歧义
-
level：大写英文（INFO / WARN / ERROR），不混用debug / Debug
-
traceId：全链路唯一ID（无则填“-”），由网关或第一个服务生成并透传
-
spanId：当前方法/调用段ID（常与traceId组合使用，如 traceId-spanId）
-
service：应用名（如 user-center），取自spring.application.name，非主机名或包名
-
thread：线程名（如 http-nio-8080-exec-3），不简化为“pool-1-thread-1”
-
class：全限定类名（如 com.example.user.service.UserService），不截断
-
message：业务语义清晰的描述，避免“操作成功”这类废话，推荐“create user id=10023, mobile=138****1234”
二、推荐的日志框架组合与配置要点
Spring Boot项目优先采用 Logback + LogstashEncoder + MDC 方案，兼顾性能与扩展性：
- 引入 logstash-logback-encoder 依赖，启用JSON格式输出
- 在 logback-spring.xml 中定义
- 通过 MDC.put("traceId", ...) 注入链路ID（建议封装成Filter或Interceptor自动填充）
- 禁用 console 输出的 pattern layout（开发环境除外），生产环境只走 JSON 文件 + 异步Appender
- ERROR 日志额外触发告警（如写入独立 error.log 并对接钉钉/邮件）
三、不同场景的日志内容规范
不是所有日志都该长一个样，需按用途区分粒度和敏感度：
-
访问日志（Access Log）：单独记录，含 method、uri、status、cost(ms)、ip、ua，建议用 Spring Boot 的
ServerHttpObservationFilter 或自定义 Filter 统一采集
-
业务关键日志（如支付、下单）：必须记录输入参数（脱敏后）、返回结果（脱敏后）、上下游调用耗时，禁止打印明文密码、身份证、银行卡号
-
异常日志：用
logger.error("order process failed", e) 形式，保留完整堆栈；自定义异常需重写 toString
() 提供上下文
-
调试日志（DEBUG）：仅开发/预发开启，禁止在生产代码中留有未注释的 debug 日志，可用
@ConditionalOnProperty 控制开关
四、落地检查清单（上线前必做）
避免“设了格式却没生效”的常见坑：
- 确认项目中没有 log4j.properties 或 commons-logging 冲突依赖
- 验证 MDC 中的 traceId 是否能在异步线程（@Async、线程池）中正确传递（需配合
LogbookMDCFilter 或自定义 ThreadPoolTaskExecutor）
- 抽样检查日志文件，确认 JSON 字段无乱码、无缺失、无嵌套空对象（如
"extra":{} 应为 "extra":null 或删掉）
- 用 Kibana 或 grep 测试能否按 service + traceId 快速聚合一次完整调用链
- 确保日志目录有合理轮转策略（timeBasedFileNamingAndTriggeringPolicy + maxHistory=30）
