SpringBoot3中的属性绑定注解和YMAL配置文件、日志

悠悠 2023-10-13 08:02 42阅读 0赞

### 1. 常用注解 ###

> SpringBoot摒弃XML配置方式，改为**全注解驱动**

#### 1. 组件注册 ####

`@Configuration`、`@SpringBootConfiguration`  
`@Bean`、`@Scope`  
`@Controller`、`@Service`、`@Repository`、`@Component`  
`@Import`  
`@ComponentScan`

**步骤：**

**1、@Configuration 编写一个配置类**  
**2、在配置类中，自定义方法给容器中注册组件。配合@Bean**  
**3、或使用@Import 导入第三方的组件**

#### 2. 条件注解 ####

> 如果注解指定的**条件成立**，则触发指定行为

`@ConditionalOnXxx`  
`@ConditionalOnClass`：如果类路径中存在这个类，则触发指定行为  
`@ConditionalOnMissingClass`：如果类路径中不存在这个类，则触发指定行为  
`@ConditionalOnBean`：如果容器中存在这个Bean（组件），则触发指定行为  
`@ConditionalOnMissingBean`：如果容器中不存在这个Bean（组件），则触发指定行为

例如：`@ConditionalOnBean（value=组件类型，name=组件名字）`：判断容器中是否有这个类型的组件，并且名字是指定的值

`@ConditionalOnRepositoryType` (org.springframework.boot.autoconfigure.data)  
`@ConditionalOnDefaultWebSecurity` (org.springframework.boot.autoconfigure.security)  
`@ConditionalOnSingleCandidate` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnWebApplication` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnWarDeployment` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnJndi` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnResource` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnExpression` (org.springframework.boot.autoconfigure.condition)  
**@ConditionalOnClass** (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnEnabledResourceChain` (org.springframework.boot.autoconfigure.web)  
**@ConditionalOnMissingClass** (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnNotWebApplication` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnProperty` (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnCloudPlatform` (org.springframework.boot.autoconfigure.condition)  
**@ConditionalOnBean** (org.springframework.boot.autoconfigure.condition)  
**@ConditionalOnMissingBean** (org.springframework.boot.autoconfigure.condition)  
`@ConditionalOnMissingFilterBean` (org.springframework.boot.autoconfigure.web.servlet)  
`@Profile` (org.springframework.context.annotation)  
`@ConditionalOnInitializedRestarter` (org.springframework.boot.devtools.restart)  
`@ConditionalOnGraphQlSchema` (org.springframework.boot.autoconfigure.graphql)  
`@ConditionalOnJava` (org.springframework.boot.autoconfigure.condition)

#### 3. 属性绑定 ####

*  `@ConfigurationProperties`： 声明组件的属性和配置文件哪些前缀开始项进行绑定
 *  `@EnableConfigurationProperties`：**快速注册注解**：
    
     *  **使用场景**：SpringBoot默认只扫描自己主程序所在的包。如果导入第三方包，即使组件上标注了 `@Component`、`@ConfigurationProperties` 注解，也没用。因为组件都扫描不进来，此时使用这个注解就可以快速进行属性绑定并把组件注册进容器

> 将容器中任意**组件（Bean）的属性值**和**配置文件**的配置项的值**进行绑定**
> 
>  *  1、给容器中注册组件（`@Component`、`@Bean`）
>  *  2、使用`@ConfigurationProperties` 声明组件和配置文件的哪些配置项进行绑定

### 2. YAML配置文件 ###

解决痛点：SpringBoot 集中化管理配置，`application.properties`。配置多以后难阅读和修改，**层级结构辨识度不高**

特点：

>  *  设计目标，就是**方便人类读写**
>  *  **层次分明**，更适合做配置文件
>  *  使用`.yaml`或 `.yml`作为文件后缀

#### 1. 基本语法 ####

*  **大小写敏感**
 *  使用**缩进表示层级关系，k: v，使用空格分割k,v**
 *  缩进时不允许使用Tab键，只允许**使用空格**。换行
 *  缩进的空格数目不重要，只要**相同层级**的元素**左侧对齐**即可
 *  **\# 表示注释**，从这个字符一直到行尾，都会被解析器忽略。

**支持的写法：**

*  **对象**：**键值对**的集合，如：映射（map）/ 哈希（hash） / 字典（dictionary）
 *  **数组**：一组按次序排列的值，如：序列（sequence） / 列表（list）
 *  **纯量**：单个的、不可再分的值，如：字符串、数字、bool、日期

#### 2. 示例 ####

@Component
    @ConfigurationProperties(prefix = "person") //和配置文件person前缀的所有配置进行绑定
    @Data //自动生成JavaBean属性的getter/setter
    //@NoArgsConstructor //自动生成无参构造器
    //@AllArgsConstructor //自动生成全参构造器
    public class Person {
        
        private String name;
        private Integer age;
        private Date birthDay;
        private Boolean like;
        private Child child; //嵌套对象
        private List<Dog> dogs; //数组（里面是对象）
        private Map<String,Cat> cats; //表示Map
    }
    
    @Data
    public class Dog {
        
        private String name;
        private Integer age;
    }
    
    @Data
    public class Child {
        
        private String name;
        private Integer age;
        private Date birthDay;
        private List<String> text; //数组
    }
    
    @Data
    public class Cat {
        
        private String name;
        private Integer age;
    }

properties表示法

person.name=张三
    person.age=18
    person.birthDay=2010/10/12 12:12:12
    person.like=true
    person.child.name=李四
    person.child.age=12
    person.child.birthDay=2018/10/12
    person.child.text[0]=abc
    person.child.text[1]=def
    person.dogs[0].name=小黑
    person.dogs[0].age=3
    person.dogs[1].name=小白
    person.dogs[1].age=2
    person.cats.c1.name=小蓝
    person.cats.c1.age=3
    person.cats.c2.name=小灰
    person.cats.c2.age=2

yaml表示法

person:
      name: 张三
      age: 18
      birthDay: 2010/10/10 12:12:12
      like: true
      child:
        name: 李四
        age: 20
        birthDay: 2018/10/10
        text: ["abc","def"]
      dogs:
        - name: 小黑
          age: 3
        - name: 小白
          age: 2
      cats:
        c1:
          name: 小蓝
          age: 3
        c2: {
        name: 小绿,age: 2} #对象也可用{}表示

#### 3. 细节 ####

*  birthDay 推荐写为 birth-day，用`-`来表示驼峰命名
 *  **文本**：
    
     *  **单引号**不会转义【\\n 则为普通字符串显示】
     *  **双引号**会转义【\\n会显示为**换行符**】
 *  **大文本**
    
     *  `|`开头，大文本写在下层，**保留文本格式，换行符正确显示**
     *  `>`开头，大文本写在下层，折叠换行符
 *  **多文档合并**
    
     *  使用`---`可以把多个yaml文档合并在一个文档中，每个文档区依然认为内容独立
     *  **多配置文件**：文件名可以是`application-{profile}.properties/yml`，用来指定多个不同的环境版本；默认使用`application`主配置文件，通过`spring.profiles.active=dev`激活指定的配置文件

#### 4. 小技巧：lombok ####

> 简化JavaBean 开发。自动生成构造器、getter/setter、自动生成Builder模式等

<dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        
        <scope>compile</scope>
    </dependency>

### 3. 日志配置 ###

#### 1. 简介 ####

1.  Spring使用`commons-logging`作为内部日志，但底层日志实现是开放的。可对接其他日志框架。
2.  支持 `jul`，`log4j2`,`logback`。SpringBoot 提供了默认的控制台输出配置，也可以配置输出为文件。
3.  `logback`是默认使用的。
4.  虽然**日志框架很多**，但是不用慌，使用 SpringBoot 的**默认配置就能工作的很好**。

**SpringBoot怎么把日志默认配置好的：**

*  1、每个starter场景，都会导入一个核心场景`spring-boot-starter`
 *  2、核心场景引入了日志的所用功能`spring-boot-starter-logging`
 *  3、默认使用了`logback` \+ `slf4j` 组合作为默认底层日志
 *  4、日志是系统一启动就要用，`xxxAutoConfiguration`是系统启动好了以后放好的组件，后来用的。
 *  5、日志是利用监听器机制配置好的。`ApplicationListener`。
 *  6、日志所有的配置都可以通过修改配置文件实现。以`logging`开始的所有配置。

#### 2. 日志格式 ####

2023-06-07T22:18:12.568+08:00  INFO 7700 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
    2023-06-07T22:18:12.569+08:00  INFO 7700 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed initialization in 1 ms

**默认输出格式：**

*  时间和日期：毫秒级精度
 *  日志级别：`ERROR`, `WARN`, `INFO`, `DEBUG`, or `TRACE`.
 *  进程 ID
 *  —： 消息分割符
 *  线程名： 使用\[\]包含
 *  Logger 名： 通常是产生日志的**类名**
 *  消息： 日志记录的内容

注意： logback 没有`FATAL`级别，对应的是`ERROR`

默认值：参照：spring-boot包`additional-spring-configuration-metadata.json`文件  
默认输出格式值：`"defaultValue": "%clr(%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd'T'HH:mm:ss.SSSXXX}}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"`

以上配置使用的SpringBoot版本是：3.0.5

#### 3. 记录日志 ####

Logger logger = LoggerFactory.getLogger(getClass());
    
    #或者使用Lombok的@Slf4j注解

#### 4. 日志级别 ####

*  由低到高：`ALL`<`TRACE`<`DEBUG`< `INFO`< `WARN`< `ERROR`<`FATAL`<`OFF`；
    
     *  **只会打印指定级别及以上级别的日志**
     *  `ALL`：打印所有日志
     *  `TRACE`：追踪框架详细流程日志，一般不使用
     *  `DEBUG`：开发调试细节日志
     *  `INFO`：关键、感兴趣信息日志
     *  `WARN`：警告但不是错误的信息日志，比如：版本过时
     *  `ERROR`：业务错误日志，比如出现各种异常
     *  `FATAL`：致命错误日志，比如jvm系统崩溃
     *  `OFF`：关闭所有日志记录
 *  不指定级别的所有类，都使用root指定的级别作为默认级别
 *  SpringBoot日志**默认级别**是 **INFO**

1.  在`application.properties/yaml`中配置`logging.level.<logger-name>=<level>`指定日志级别
2.  `level`可取值范围：`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` or `OFF`，定义在 LogLevel类中
3.  root 的`logger-name`叫`root`，可以配置`logging.level.root=warn`，代表所有未指定日志级别都使用 root 的`warn` 级别

#### 5. 日志分组 ####

比较有用的技巧是：

将相关的`logger`分组在一起，统一配置。SpringBoot 也支持。比如：Tomcat 相关的日志统一设置

logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat
    logging.level.tomcat=trace

SpringBoot 预定义的两个组：

<table> 
 <thead> 
  <tr> 
   <th>Name</th> 
   <th>Loggers</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>web</td> 
   <td><code>org.springframework.core.codec, org.springframework.http</code>, <code>org.springframework.web, org.springframework.boot.actuate.endpoint.web</code>, <code>org.springframework.boot.web.servlet.ServletContextInitializerBeans</code></td> 
  </tr> 
  <tr> 
   <td>sql</td> 
   <td><code>org.springframework.jdbc.core, org.hibernate.SQL, org.jooq.tools.LoggerListener</code></td> 
  </tr> 
 </tbody> 
</table>

#### 6. 文件输出 ####

SpringBoot 默认只把日志写在控制台，如果想额外记录到文件，可以在`application.properties`中添加`logging.file.name` or `logging.file.path`配置项。也可以直接在日志配置文件中直接指定

常用的`logback-spring.xml`模板：

<?xml version="1.0" encoding="UTF-8"?>
    <configuration debug="false" scan="true" scanPeriod="1000 seconds">
        <springProperty scope="context" name="spring.application.name" source="spring.application.name" defaultValue="app"/>
        <timestamp key="date" datePattern="yyyyMMdd"/>
        <property name="colorfulPattern"
                  value="%blue(%d{MM-dd HH:mm:ss}) [%boldYellow(%thread)] | %highlight(%-5level) | %boldGreen(%logger) %X{clientIp} %X{operateId} - %highlight(%msg) %n"/>
        <property name="defaultPattern"
                  value="%d{MM-dd HH:mm:ss} [%thread] | %-5level | %logger %X{clientIp} %X{operateId} - %msg %n"/>
        <property name="log.base_path" value="E:\data\logs"/>
        
        <property name="log.max.size" value="100MB"/>
    
        
        <appender name="stdout" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>${colorfulPattern}</pattern>
                
            </encoder>
        </appender>
    
        <appender name="trace.appender" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>${log.base_path}/${spring.application.name}/trace.${spring.application.name}.log</file>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>
                    ${log.base_path}/archive/${spring.application.name}/trace.${spring.application.name}.%d{yyyyMMdd}.%i.log.zip
                </fileNamePattern>
                <timeBasedFileNamingAndTriggeringPolicy
                        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                    <maxFileSize>${log.max.size}</maxFileSize>
                </timeBasedFileNamingAndTriggeringPolicy>
            </rollingPolicy>
            <layout class="ch.qos.logback.classic.PatternLayout">
                <pattern>${defaultPattern}</pattern>
            </layout>
            <filter class="ch.qos.logback.classic.filter.LevelFilter">
                <level>TRACE</level>
                <onMatch>ACCEPT</onMatch>
                <onMismatch>DENY</onMismatch>
            </filter>
        </appender>
    
        <appender name="info.appender" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>${log.base_path}/${spring.application.name}/info.${spring.application.name}.log</file>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>
                    ${log.base_path}/archive/${spring.application.name}/info.${spring.application.name}.%d{yyyyMMdd}.%i.log.zip
                </fileNamePattern>
                <timeBasedFileNamingAndTriggeringPolicy
                        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                    <maxFileSize>${log.max.size}</maxFileSize>
                </timeBasedFileNamingAndTriggeringPolicy>
            </rollingPolicy>
            <layout class="ch.qos.logback.classic.PatternLayout">
                <pattern>${defaultPattern}</pattern>
            </layout>
            <filter class="ch.qos.logback.classic.filter.LevelFilter">
                <level>INFO</level>
                <onMatch>ACCEPT</onMatch>
                <onMismatch>DENY</onMismatch>
            </filter>
        </appender>
    
        <appender name="debug.appender" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>${log.base_path}/${spring.application.name}/debug.${spring.application.name}.log</file>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>
                    ${log.base_path}/archive/${spring.application.name}/debug.${spring.application.name}.%d{yyyyMMdd}.%i.log.zip
                </fileNamePattern>
                <timeBasedFileNamingAndTriggeringPolicy
                        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                    <maxFileSize>${log.max.size}</maxFileSize>
                </timeBasedFileNamingAndTriggeringPolicy>
            </rollingPolicy>
            <layout class="ch.qos.logback.classic.PatternLayout">
                <pattern>${defaultPattern}</pattern>
            </layout>
            <filter class="ch.qos.logback.classic.filter.LevelFilter">
                <level>DEBUG</level>
                <onMatch>ACCEPT</onMatch>
                <onMismatch>DENY</onMismatch>
            </filter>
        </appender>
    
        <appender name="error.appender" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>${log.base_path}/${spring.application.name}/error.${spring.application.name}.log</file>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>
                    ${log.base_path}/archive/${spring.application.name}/error.${spring.application.name}.%d{yyyyMMdd}.%i.log.zip
                </fileNamePattern>
                <timeBasedFileNamingAndTriggeringPolicy
                        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                    <maxFileSize>${log.max.size}</maxFileSize>
                </timeBasedFileNamingAndTriggeringPolicy>
            </rollingPolicy>
            <layout class="ch.qos.logback.classic.PatternLayout">
                <pattern>${defaultPattern}</pattern>
            </layout>
            
            <filter class="ch.qos.logback.classic.filter.LevelFilter">
                <level>ERROR</level>
                <onMatch>ACCEPT</onMatch>
                <onMismatch>DENY</onMismatch>
            </filter>
        </appender>
        
        
        
        <appender name="trace.async" class="ch.qos.logback.classic.AsyncAppender">
            <discardingThreshold>0</discardingThreshold>
            <queueSize>256</queueSize>
            <includeCallerData>true</includeCallerData>
            <appender-ref ref="trace.appender"/>
        </appender>
        
        <logger name="cn.felord.common.http.RestBodyAdvice" level="TRACE"/>
        <logger name="cn.felord.app.mapper" level="DEBUG"/>
        
        <springProfile name="dev">
            <logger name="org.springframework.security" level="TRACE" additivity="false" >
                <appender-ref ref="stdout"/>
            </logger>
            <logger name="org.springframework.security.oauth2" level="DEBUG" additivity="false" >
                <appender-ref ref="stdout"/>
            </logger>
            <logger name="org.springframework.web" level="TRACE" additivity="false" >
                <appender-ref ref="stdout"/>
            </logger>
        </springProfile>
    
        <root level="info">
            <appender-ref ref="stdout"/>
            <appender-ref ref="info.appender"/>
            <appender-ref ref="debug.appender"/>
            <appender-ref ref="error.appender"/>
            <appender-ref ref="trace.async"/>
        </root>
    </configuration>

#### 7. 文件归档与滚动切割 ####

> 归档：每天的日志单独存到一个文档中。  
> 切割：每个文件10MB，超过大小切割成另外一个文件。

1.  每天的日志应该独立分割出来存档。如果使用`logback`（SpringBoot 默认整合），可以通过`application.properties/yaml`文件指定日志滚动规则。
2.  如果是其他日志系统，需要自行配置（添加`log4j2.xml`或`log4j2-spring.xml`）
3.  支持的滚动规则设置如下

<table> 
 <thead> 
  <tr> 
   <th>配置项</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>logging.logback.rollingpolicy.file-name-pattern</code></td> 
   <td>日志存档的文件名格式（默认值：<code>${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz</code>）</td> 
  </tr> 
  <tr> 
   <td><code>logging.logback.rollingpolicy.clean-history-on-start</code></td> 
   <td>应用启动时是否清除以前存档（默认值：<code>false</code>）</td> 
  </tr> 
  <tr> 
   <td><code>logging.logback.rollingpolicy.max-file-size</code></td> 
   <td>存档前，每个日志文件的最大大小（默认值：<code>10MB</code>）</td> 
  </tr> 
  <tr> 
   <td><code>logging.logback.rollingpolicy.total-size-cap</code></td> 
   <td>日志文件被删除之前，可以容纳的最大大小（默认值：<code>0B</code>）。设置1GB则磁盘存储超过 <code>1GB</code> 日志后就会删除旧日志文件</td> 
  </tr> 
  <tr> 
   <td><code>logging.logback.rollingpolicy.max-history</code></td> 
   <td>日志文件保存的最大天数(默认值：<code>7</code>)</td> 
  </tr> 
 </tbody> 
</table>

#### 8. 自定义配置 ####

通常配置 `application.properties` 就够了。当然也可以自定义。比如：

<table> 
 <thead> 
  <tr> 
   <th>日志系统</th> 
   <th>日志系统 自定义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Logback</td> 
   <td><code>logback-spring.xml</code>, <code>logback-spring.groovy</code>, <code>logback.xml</code>, or <code>logback.groovy</code></td> 
  </tr> 
  <tr> 
   <td>Log4j2</td> 
   <td><code>log4j2-spring.xml</code> or <code>log4j2.xml</code></td> 
  </tr> 
  <tr> 
   <td>JDK (Java Util Logging)</td> 
   <td><code>logging.properties</code></td> 
  </tr> 
 </tbody> 
</table>

**最佳工作实践**：自己要写日志配置文件，配置文件名加上 `xx-spring.xml`

#### 9. 切换日志组合 ####

<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
        <exclusions>
            <exclusion>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-log4j2</artifactId>
    </dependency>

log4j2支持XML、JSON、YAML和properties四种配置文件格式

#### 10. 工作实践 ####

1.  导入任何第三方框架，先排除它的日志包，因为SpringBoot底层控制好了日志
2.  修改 `application.properties` 配置文件，就可以调整日志的所有行为。如果不够，可以编写日志框架自己的配置文件放在类路径下就行，比如`logback-spring.xml`，`log4j2-spring.xml`
3.  如需对接**专业日志系统**，也只需要把 logback 记录的**日志**灌倒 `kafka`之类的中间件，这和SpringBoot没关系，都是日志框架自己的配置，**修改配置文件即可**
4.  业务中使用`slf4j-api`记录日志。不要再 `System.out.println()` 了