代码日志打印规范分享

日志打印往往在一个时间较为紧急的项目中被忽视，而你可能会发现，我们遇到的项目，周期都不怎么松。而且实际上有没有日志，功能照样能实现，还节省了很多时间，正如单元测试的性质一样，它可能会延长项目时间

但是，正所谓，慢就是快，想想，我们的维护时间往往是项目周期的两三倍以上，而维护的对象本质上是什么呢？就是我们写好的代码，若代码中缺少必要的日志打印，或者打印的日志过多过频繁，不仅不好定位问题，还有磁盘存储爆满的问题出现

那么，什么时候需要打印日志呢？

一、什么时候需要打印日志？

简单来说，分为如下几种场景：

• 代码调试
• 问题定位
• 用户行为日志（记录操作日志）
• 根因分析

对于日志的打印，我们有几个基本的规范要求：

二、日志打印的基本要求规范

• 对程序运行情况能够进行记录和监控
• 在必要时可详细了解程序内部的运行状态
• 对系统性能的影响尽量小（代码中打印方式、打印的日志量与日志存储等方面）

三、在哪些场景下需要打日志呢？

• 系统初始化流程
• 编程语言提示异常
• 业务流程预期不符
• 系统核心角色，组件关键动作
• 作为服务提供方（打印入参、出参）
• 作为服务提供方（打印入参）
• 定时任务运行相关记录

四、日志级别

常用的分为以下几种：

1、ERROR

影响到程序正常运行、当前请求正常运行的异常情况。如：

1）打开配置文件失败

2）所有第三方对接的异常(包括第三方返回错误码)

3）所有影响功能使用的异常，包括:SQLException 、空指针异常以及业务异常之外的所有异常

2、WARN

告警日志。不应该出现但是不影响程序、当前请求正常运行的异常情况。。

但是一旦出现了也需要关注，因此一般该级别的日志达到一定的阈值之后，就得提示给用户或者需要关注的人了。如：

1）有容错机制的时候出现的错误情况

2）找不到配置文件，但是系统能自动创建配置文件

3）即将接近临界值的时候，如 cpu 存储已经超过阈值的 80%，就需要打印 warn 级别的日志

3、INFO

记录输入输出、程序关键节点等必要信息。平时无需关注，但出问题时可根据INFO日志诊断出问题

1）Service方法中对于系统/业务状态的变更

2）调用第三方时的调用参数和调用结果（入参和出参）

3）提供方，需要记录入参

4）定时任务的开始执行与结束执行

4、DEBUG

调试信息，对系统每一步的运行状态进行精确的记录。

5、TRACE

特别详细的服务调用流程各个节点信息。业务代码中，除非涉及到多级服务的调用，否则不要使用(除非有特殊用意，否则请使用DEBUG级别替代)

我呢，根据相关资料以及本人在项目中的经验，梳理了其中比较重要的 15 条日志打印规范

五、日志打印规范

1、增删改操作需要打印参数日志（以便定位一些异常业务问题）；

2、条件分支需要打印日志：包括条件值以及重要参数；

3、明确日志打印级别与包含的信息

1）提供方服务，建议以 INFO 级别记录入参，出参可选

2）消费队列消息，务必打印消息内容

3）调用方服务，建议以 INFO 级别记录入参和出参

4）运行环境问题，如网络错误、建议以 WARN 级别记录错误堆栈

5）定时任务，务必打印任务开始时间、结束时间。涉及扫描数据的任务，务必打印扫描范围

4、异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通过关键字throws/throw 往上抛出，由父级方法处理

5、谨慎地记录日志

1）生产环境禁止输出 debug 日志

2）有选择地输出 info 日志

3）如果使用 warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志

6、可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适从

注意日志输出的级别，error 级别只记录系统逻辑出错、异常等重要的错误信息。如非必要，请不要在此场景打出 error 级别。(上述已经说明了 error 与 warn 级别日志的区别)

7、对 trace/debug/info级别的日志输出，必须使用条件输出形式或者使用占位符的方式

说明：

logger.debug("Processing trade with id: " + id + " symbol: " + symbol);

对于上述代码，如果日志级别是 warn，日志不会打印，但是会执行字符串拼接操作，如果 symbol 是对象， 会执行 toString() 方法，浪费了系统资源，执行了上述操作，最终日志却没有打印

正例：（条件）

if (logger.isDebugEnabled()) {
    logger.debug("Processing trade with id: " + id + " symbol: " + symbol);
}

正例：（占位符）

logger.debug("Processing trade with id: {} symbol : {} ", id, symbol);

8、不允许记录日志后又抛出异常，因为这样会多次记录日志，只允许记录一次日志

反例：

if (virtualIpPortCrash) {
            log.error("接入虚拟IP端口冲突");
            throw new BusinessException("接入虚拟IP端口冲突");
        }
        

9、不允许出现System print(包括System.out.println和System.error.println)语句作为日志的打印

10、不允许出现 e.printStackTrace

11、日志性能的考虑。如果代码为核心代码，执行频率非常高，则输出日志建议增加判断，尤其是低级别的输出

12、【强制】应用中不可直接使用日志系统（Log4j、Logback）中的 API，而应依赖使用日志框架 SLF4J 中的 API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一

import lombok.extern.slf4j.Slf4j;
//1-在类上添加注解
@Slf4j 

//2-直接使用log.info()进行日志的打印（还支持error、warn、trace以及debug等级别）
log.info("service update success:{}................",serviceEntity.getName());

13、【强制】日志文件推荐至少保存 15 天，因为有些异常具备以“周”为频次发生的特点

14、【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式： appName_logType_logName.log

logType:日志类型，推荐分类有 stats/desc/monitor/visit 等

logName:日志描述。这种命名的好处：通过文件名就可知 道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。 正例：mppserver 应用中单独监控时区转换异常，如： mppserver_monitor_timeZoneConvert.log

15、【强制】避免重复打印日志，浪费磁盘空间。务必在 log4j.xml 中设置 additivity=false

六、总结

需要注意一点， error 级别和 warn 级别的日志的区别。error 日志表示的是程序因出错，已经无法正常执行业务操作了。而 warn 则表示，并不会影响程序的正常运行，但是也需要适当关注的一些日志信息。

慢就是快，代码中合理地打印日志，将会起到事半功倍的效果。否则呢，不仅会影响维护质量，还可能会引起一些意想不到的问题