3、日志格式规范：标准日志格式设计、字段定义规范、JSON日志与普通文本日志的优劣
日志格式这事儿，看着简单，其实坑特别多。我刚开始做风控那会儿，觉得日志嘛，能看就行。结果呢？线上出了个诡异的风控误杀，排查了整整两天——最后发现是日志解析器把时间戳和用户ID粘在一起了。嗯，从那以后，我对日志格式就特别较真。
说白了，日志格式就是你和未来自己的对话。格式写得好，排查问题就像翻书；写得烂，那就是在垃圾堆里找针。今天咱们就把这事儿聊透。
3.1 标准日志格式长什么样？
我个人习惯，标准日志格式必须包含三个核心要素：时间、来源、内容。缺一个，这日志基本就废了一半。
举个例子，我在项目中常用的标准格式模板是这样的：
2024-01-15 14:30:22.456 [http-nio-8080-exec-3] INFO RiskEngine - 用户[user_12345] 触发规则[RULE_HIGH_FREQ]，决策结果[REJECT]，耗时[12ms]
你仔细看，这里面包含了：
- 时间戳：精确到毫秒，带时区信息更好
- 线程名：方便追踪并发请求
- 日志级别：INFO/WARN/ERROR，快速定位问题严重程度
- 类名或模块名：知道是哪个组件输出的
- 业务上下文：用户ID、规则ID、决策结果、耗时
为什么要这么设计？我记得有一次线上告警说风控引擎响应超时。我一看日志，发现只有「超时」两个字，连哪个用户、哪条规则都不知道。你说这怎么查？后来我强制要求所有关键路径必须带上业务上下文，排查效率直接翻倍。
核心原则：日志格式的设计，要以「事后可复现现场」为目标。拿到一条日志，你应该能回答出：什么时候、谁、做了什么、结果如何、花了多久。
3.2 字段定义规范：别让字段名成为阅读理解题
字段定义这事儿，我踩过的坑太多了。最典型的就是字段名随意缩写，比如 usr_id、tm_stmp、rslt_cd。你写的时候觉得省事，三个月后自己都看不懂。
我建议的字段命名规范：
- 全小写 + 下划线：如
user_id、rule_name、decision_result - 避免缩写：除非是业界通用缩写（如
ip、url） - 层级清晰：用点号或下划线表示层级关系，如
request.headers.user_agent - 类型明确：布尔值用
is_、has_开头，如is_blacklisted
来看一个我实际项目中的字段定义表：
| 字段名 | 类型 | 说明 | 示例 |
|---|---|---|---|
| event_id | string | 全局唯一事件ID，用于关联上下游 | evt_20240115_abc123 |
| timestamp | string | ISO 8601格式，带时区 | 2024-01-15T14:30:22.456+08:00 |
| user_id | string | 用户标识，脱敏处理 | user_*****2345 |
| rule_id | string | 触发的规则ID | RULE_HIGH_FREQ |
| decision | string | 决策结果：PASS/REVIEW/REJECT | REJECT |
| cost_ms | int | 处理耗时，单位毫秒 | 12 |
小技巧：字段定义最好写进团队的编码规范文档里，并且用代码生成器自动生成日志模板。手动写？容易出错，而且新人来了还得重新教一遍。
3.3 JSON日志 vs 普通文本日志：各有各的命
这个问题，说白了就是「机器友好」和「人眼友好」的博弈。我两种都用过，说说我的真实感受。
3.3.1 普通文本日志
优点很明显：
- 肉眼可读：tail -f 一看就懂，不需要额外工具
- 体积小：没有多余的括号和引号，同样信息量下文本更省空间
- 性能开销低：序列化成本几乎为零
缺点也致命：
- 解析困难：用正则表达式提取字段，写起来想哭。我见过一个正则写了80多行，最后还匹配错了
- 扩展性差：加一个新字段，所有下游解析脚本都得改
- 结构化信息丢失：嵌套关系、数组等复杂结构很难表达
3.3.2 JSON日志
优点：
- 天然结构化：字段名、类型、层级关系一目了然
- 解析零成本：几乎所有日志收集系统（ELK、Splunk）都原生支持JSON
- 扩展友好：加字段不影响已有解析逻辑
缺点：
- 体积膨胀：同样的信息，JSON体积可能是文本的2-3倍
- 肉眼阅读体验差：满屏的花括号和引号，看久了眼睛疼
- 序列化有开销：高并发场景下，JSON序列化会成为瓶颈
我的建议：
- 开发环境：用普通文本日志，方便本地调试
- 生产环境：用JSON日志，方便集中采集和分析
- 混合方案：输出JSON格式，但日志查看工具（如Kibana）提供格式化展示功能
- 开发环境：用普通文本日志，方便本地调试
- 生产环境：用JSON日志，方便集中采集和分析
- 混合方案：输出JSON格式，但日志查看工具（如Kibana）提供格式化展示功能
我曾经在一个高并发风控项目中，因为JSON序列化导致CPU飙升。后来我们做了个优化：只在关键决策点输出JSON日志，普通调试日志用文本格式。这样既保证了核心链路的可分析性，又避免了性能问题。
3.4 知识体系总览
下面这张图，把日志格式规范的核心逻辑串起来了。你一看就明白：
避坑指南：我曾经在一个项目中，团队为了「统一」，强制所有环境都用JSON日志。结果开发同学本地调试时，每次都要用jq命令格式化，烦得要死。后来大家偷偷改回了文本格式，导致线上和线下日志格式不一致，排查问题又出幺蛾子。所以，不要一刀切，要分场景。
好了，日志格式规范这块儿，核心就是这些。记住：格式是给别人看的，也是给未来的自己看的。设计时多花十分钟，排查时能省十个小时。这个账，你算得明白。