111

snailmall-shipping-service/src/main/resources/logback.xml

@@ -1,33 +1,73 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!-- 整个 logback 配置的根元素，所有的日志配置都在此元素内进行定义，遵循 logback 的 XML 配置规范 -->
 <configuration>
+    <!-- 定义一个名为 LOG_HOME 的属性，其值为 "/logs/shipping/"，这个属性可以在后续配置中被引用，
+         通常用于指定日志文件的存储路径等相关设置，方便统一管理日志文件的存放位置，若后续需要修改日志文件存储位置，
+         只需更改此处属性值即可，无需在多处配置中逐个修改 -->
     <property name="LOG_HOME" value="/logs/shipping/" />
 
+    <!-- 配置名为 "Console" 的日志输出组件（Appender），类型是 ch.qos.logback.core.ConsoleAppender，
+         作用是将日志信息输出到控制台，常用于开发阶段方便查看实时日志，便于调试代码 -->
     <appender name="Console" class="ch.qos.logback.core.ConsoleAppender">
+        <!-- 编码器（Encoder）配置，用于定义日志输出到控制台的格式 -->
         <encoder>
+            <!-- 具体的日志格式定义，各部分含义如下：
+                 %d{H:mm}：表示输出日期时间，精确到小时和分钟；
+                 %-5level：输出日志级别，占 5 个字符宽度且左对齐；
+                 [%logger{16}]：输出日志记录器的名称，最长显示 16 个字符；
+                 %msg：输出日志消息的具体内容；
+                 %n：换行符，用于使每条日志信息换行显示，提高可读性 -->
             <pattern>%d{H:mm} %-5level [%logger{16}] %msg%n</pattern>
         </encoder>
     </appender>
 
+    <!-- 配置名为 "normalLog" 的日志输出组件，类型为 ch.qos.logback.core.rolling.RollingFileAppender，
+         它用于将日志输出到文件，并支持按照一定规则对日志文件进行滚动管理（如按时间、大小等进行切割、备份等操作） -->
     <appender name="normalLog"
               class="ch.qos.logback.core.rolling.RollingFileAppender">
+        <!-- 滚动策略配置，这里采用基于时间的滚动策略（TimeBasedRollingPolicy），
+             按照日期来对日志文件进行切割和管理，方便按天、月等时间周期查看不同时间段的日志记录 -->
         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+            <!-- 定义日志文件的命名模式，会在 LOG_HOME 所指定的路径下生成类似 web.normal.2024-12-17.log 这样的文件（以实际日期为准），
+                 每天都会生成一个新的日志文件，便于对日志进行分类存储和查看 -->
             <FileNamePattern>${LOG_HOME}/web.normal.%d{yyyy-MM-dd}.log
             </FileNamePattern>
+            <!-- 设置保留的历史日志文件数量，这里规定最多保留 30 天的日志文件，超过这个数量的旧日志文件会被自动删除，
+                 避免日志文件过多占用大量磁盘空间 -->
             <MaxHistory>30</MaxHistory>
         </rollingPolicy>
+        <!-- 触发滚动的策略配置，这里采用基于文件大小的触发策略（SizeBasedTriggeringPolicy），
+             当单个日志文件大小达到 10MB 时，就会触发滚动操作，比如进行日志文件的切割、备份等处理，
+             结合前面的时间滚动策略，从时间和文件大小两个维度来合理管理日志文件 -->
         <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
             <maxFileSize>10MB</maxFileSize>
         </triggeringPolicy>
+        <!-- 日志布局（Layout）配置，用于定义日志在文件中的具体输出格式 -->
         <layout class="ch.qos.logback.classic.PatternLayout">
+            <!-- 具体的日志格式，各部分含义如下：
+                 %d{HH:mm:ss.SSS}：输出日期时间，精确到小时、分钟、秒以及毫秒；
+                 [%thread]：输出产生该日志的线程名称；
+                 %-5level：输出日志级别，占 5 个字符宽度且左对齐；
+                 %logger{16}：输出日志记录器的名称，最长显示 16 个字符；
+                 -：一个连接符，用于分隔日志记录器名称和日志消息内容；
+                 %msg：输出日志消息的具体内容；
+                 %n：换行符，使每条日志信息换行显示 -->
             <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{16} - %msg%n
             </pattern>
         </layout>
+        <!-- 配置一个过滤器（LevelFilter），用于根据日志级别来决定是否允许该日志输出到这个 Appender 对应的日志文件中 -->
         <filter class="ch.qos.logback.classic.filter.LevelFilter">
+            <!-- 指定要过滤的日志级别为 ERROR -->
             <level>ERROR</level>
+            <!-- 如果日志级别匹配（即当前日志是 ERROR 级别），则拒绝该日志输出，也就是不会将 ERROR 级别的日志记录到这个 normalLog 对应的日志文件中 -->
             <onMatch>DENY</onMatch>
+            <!-- 如果日志级别不匹配（即不是 ERROR 级别），则接受该日志输出，允许非 ERROR 级别的日志正常记录到该日志文件中 -->
             <onMismatch>ACCEPT</onMismatch>
         </filter>
     </appender>
+
+    <!-- 配置名为 "errorLog" 的日志输出组件，同样是基于滚动文件的方式将日志输出到文件，结构和前面的 "normalLog" 类似，
+         但在日志级别过滤方面有所不同，主要用于专门记录 ERROR 级别的日志 -->
     <appender name="errorLog"
               class="ch.qos.logback.core.rolling.RollingFileAppender">
         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
@@ -44,18 +84,23 @@
         </layout>
         <filter class="ch.qos.logback.classic.filter.LevelFilter">
             <level>ERROR</level>
+            <!-- 对于 ERROR 级别的日志，这里设置为接受输出，即只有 ERROR 级别的日志会被记录到这个 errorLog 对应的日志文件中 -->
             <onMatch>ACCEPT</onMatch>
             <onMismatch>DENY</onMismatch>
         </filter>
     </appender>
 
-
+    <!-- 配置一个名为 "com.oursnail" 的日志记录器（Logger），指定其日志级别为 debug，
+         意味着这个记录器会记录 DEBUG 及以上级别的日志信息，并且将这些日志输出到 "normalLog" 和 "errorLog" 这两个 Appender 对应的日志文件中，
+         通过这种方式可以针对特定的包（这里是 com.oursnail 包及其子包下的代码）进行日志的分级管理和分类输出 -->
     <logger name="com.oursnail" level="debug" >
         <appender-ref ref="normalLog" />
         <appender-ref ref="errorLog" />
     </logger>
 
-
+    <!-- 配置根日志记录器（Root Logger），它是所有日志记录器的默认父级，这里设置其日志级别为 info，
+         也就是会记录 INFO 及以上级别的日志信息，并且将这些日志输出到 "Console" 这个 Appender 对应的控制台中，
+         对整个应用的日志输出做了一个基础的级别和输出目标的配置 -->
     <root level="info">
         <appender-ref ref="Console" />
     </root>