Java结构化日志需每行一个扁平JSON对象，推荐Logback+Logstash-Encoder或Log4j2+JacksonLayout自动展开MDC/上下文为顶层字段，禁用手动序列化、嵌套字符串及控制台ANSI输出。
在 Java 日志中输出结构化 JSON，关键不是“把 JSON 字符串塞进日志”，而是让每条日志本身是合法、扁平、可解析的 JSON 对象，避免嵌套字符串或换行破坏日志行格式。主流日志收集系统（如 Filebeat + Logstash、Fluentd、Loki、Datadog）都依赖每行一条 JSON，且字段需为顶层键值对。
用支持结构化日志的日志框架（推荐）
Logback + Logstash-Encoder 或 Log4j2 + JacksonLayout 是最稳妥的方式，它们自动将 MDC、上下文、参数转为 JSON 字段，不拼接字符串。
-
Logback 示例（logback-spring.xml）：引入
net.logstash.logback:logstash-logback-encoder，配置 encoder 为LoggingEventCompositeJsonEncoder，它会把 logger、level、message、timestamp、MDC 全部展开为同级 JSON 字段 -
Log4j2 示例：使用
JacksonLayout并设置locationInfo="false"和properties="true"，配合ThreadContext.put("traceId", "abc")，traceId 就会作为顶层字段出现在 JSON 中 - 避免手动调用
new ObjectMapper().writeValueAsString(obj)输出到logger.info()—— 这会导致 JSON 被当作文本内容，变成"message": "{...}"，字段无法被提取
手动构造 JSON 日志时必须扁平化
如果因限制只能用普通 logger（如 slf4j-simple），又需要结构化字段，就需手动构建顶层键值对，而非嵌套对象。
- ✅ 正确：用占位符 + Map 参数（需日志框架支持）：
logger.info("user login", Map.of("userId", 123, "ip", "192.168.1.5", "status", "success"))—— 某些适配器（如 logback-jackson）能识别并展开 - ✅ 可控：拼接 key=value 的 KV 行（类 Nginx 日志格式），例如：
logger.info("method=POST path=/login userId={} ip={} status={}", userId, ip, status)，再用 Filebeat 的dissect或 Grok 解析 - ❌ 错误：直接输出
logger.info("{\"userId\":123,\"event\":\"login\"}")—— 整个字符串被当作文本，JSON 字段不可索引
统一补充上下文字段（MDC / ThreadContext）
请求级元信息（traceId、spanId、userId、env）不应每次写日志都传参，而应通过 MDC（Logback/SLF4J）或 ThreadContext（Log4j2）自动注入到每条日志 JSON 中。
立即学习“Java免费学习笔记（深入）”；
- Web 应用中，在 Filter 或 Interceptor 里调用
MDC.put("traceId", generateTraceId()) - 确保 encoder/layout 配置中启用了 MDC 输出（如 LogstashEncoder 的
includeContext=true） - 注意 MDC 是线程绑定的，异步线程需显式复制（如用
MDC.getCopyOfContextMap()+MDC.setContextMap()）
避免常见陷阱
结构化日志失效往往源于细节疏忽。
- 日志输出到控制台时默认带颜色/ANSI 字符，会污染 JSON 格式 —— 生产环境禁用 console appender 的
%highlight或%coloredLevel - 日志行末尾不能有多余空格、制表符或换行 —— 使用
append=false的 FileAppender，并确认 encoder 不输出额外空白 - 时间戳必须用 ISO8601 格式（如
2024-05-20T14:23:15.123Z），不要用中文或自定义格式，否则解析器无法识别 - 字段名避免点号（
user.id）、空格、特殊符号 —— 使用下划线（user_id）更兼容各类后端系统
