结构化日志需字段统一、语义清晰、机器友好，采用标准json格式，关键字段小写下划线命名，数值型字段保留原始类型，时间戳用iso8601，必含trace_id、span_id、service_name，业务字段通过mdc注入并脱敏，配置须与elk/loki schema对齐。
结构化日志不是“加个 JSON 就完事”，而是让每条日志变成一条可索引、可关联、可计算的记录。核心在于字段统一、语义清晰、机器友好，才能被 Elasticsearch、Loki 或 Flink 等大数据平台高效摄入和深度检索。
用标准 JSON 格式输出，字段命名与类型保持一致
避免自由文本拼接，所有日志必须序列化为合法 JSON，且关键字段名全小写、下划线分隔（如 trace_id、user_id、http_status），便于日志采集器（Filebeat/Fluentd）自动映射为 Elasticsearch 的 keyword 或 long 类型字段。
- 推荐使用 Jackson 或 log4j2 的 JSONLayout，禁用非标准字段（如类名带 $、包路径含特殊字符）
- 数值型字段（金额、耗时、状态码）不转字符串，保留原始类型，支持范围查询和聚合分析
- 时间戳统一用 ISO8601 格式（"@timestamp": "2026-07-28T19:35:22.123Z"），避免时区歧义
嵌入上下文字段，支撑跨服务链路追踪与业务维度下钻
单条日志的价值，取决于它能回答多少问题：是谁触发的？在哪条链路上？发生在哪个业务环节？结构化日志必须携带可扩展的上下文字段，而非仅靠日志内容解析。
- 必含字段：trace_id（全局唯一）、span_id（当前操作）、service_name（服务标识）
- 业务强相关字段：order_id、user_id、payment_channel，按模块约定注入 MDC（SLF4J + Logback）
- 避免敏感字段明文落盘：手机号、身份证号、银行卡号等需在日志框架层脱敏（如 "phone": "138****1234"）
日志模板与 Appender 配置需匹配数据平台 Schema
ELK 或 Loki 不会“猜”你的字段含义。Logback 或 Log4j2 的输出配置，要与后端索引 mapping 或 Loki 的 stream labels 显式对齐。
- Logback 示例（logback-spring.xml）中启用 JSONLayout，并绑定 MDC 字段：
{"app":"my-payment-service"}
- Kafka 输出时，确保每条消息 payload 是单条 JSON，不拼接换行或批量打包，方便 Flink 实时解析
预留扩展能力，支持动态字段与结构演进
业务字段会变，但日志 Schema 不能频繁重建索引。设计时需兼顾灵活性与稳定性。
- 使用 extra 或 context 字段承载非核心、高频变更的业务属性（如促销活动 ID、设备型号），类型设为 object 或 flattened
- 避免在日志中硬编码版本号；通过日志 topic 或 index pattern 区分不同结构版本（如 logs-payment-v1 / logs-payment-v2）
- 上线前用真实流量做字段覆盖率扫描，确认所有关键业务路径都注入了 trace_id 和业务主键
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
