SpringBoot项目端点配置

一时失言乱红尘 2022-11-12 04:16 335阅读 0赞

## 端点配置 ##

### 开启端点 ###

在SpringBoot中开启应用监控非常容易，只需要添加spring-boot-starter-actuator依赖即可，actuator（执行器）是制造业术语，  
指一个用于移动或控制机械装置的工具，一个很小的变化就能让执行器产生大量的运动。依赖如下：

<dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-actuator</artifactId>
            </dependency>
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <optional>true</optional>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
        </dependencies>

开发者可以使用执行器中的端点（EndPoints）对应用进行监控或者与应用进行交互，SpringBoot默认包含许多端点，如下表：

<table> 
 <thead> 
  <tr> 
   <th>端点</th> 
   <th>端点描述</th> 
   <th>是否开启</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>auditevents</td> 
   <td>展示当前应用程序的审计信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>beans</td> 
   <td>展示所有SpringBeans信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>conditions</td> 
   <td>展示一个自动配置类的使用报告，该报告展示所有自动配置类及他们被使用或未使用的原因</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>configprops</td> 
   <td>展示所有@configurationProperties的列表</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>env</td> 
   <td>展示系统运行信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>flyway</td> 
   <td>展示数据库迁移路径</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>health</td> 
   <td>展示应用程序的健康信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>httptrace</td> 
   <td>展示trace信息，（默认为最新的100条HTTP请求）</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>info</td> 
   <td>展示应用的定制信息，这些定制信息以info开头</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>loggers</td> 
   <td>展示并修改应用的日志配置</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>liquibase</td> 
   <td>展示任何Liquibase数据库迁移路径</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>metrice</td> 
   <td>展示应用程序度量信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>mappings</td> 
   <td>展示所有@RequestMapping路径的集合列表</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>scheduledtasks</td> 
   <td>展示应用的所有定时任务</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>shutdown</td> 
   <td>远程关闭应用接口</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>sessions</td> 
   <td>展示并操作spring session回话</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>threaddump</td> 
   <td>展示线程活动的快照</td> 
   <td>Yes</td> 
  </tr> 
 </tbody> 
</table>

如果是个Web应用，还会有下面的端点：

<table> 
 <thead> 
  <tr> 
   <th>端点</th> 
   <th>端点描述</th> 
   <th>是否开启</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>headdump</td> 
   <td>返回一个GZip压缩的hprof堆转储文件</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>jolokia</td> 
   <td>展示通过HTTP暴露的JMX beans</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>logfile</td> 
   <td>返回日志文件的内容</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>prometheus</td> 
   <td>展示一个可以被Promentheus服务器抓取的metrics数据</td> 
   <td>Yes</td> 
  </tr> 
 </tbody> 
</table>

这些端点大部分都是默认开启的，只有shutdown端点默认为开启，如果需要开启，可以在application.yml中通过如下配置开启：

management:
      endpoint:
        shutdown:
          enabled: true

如果开发者不想暴露这么多端点，那么可以关闭默认配置，然后手动指定需要开启那些端点，如下配置表示关闭所有端点，只开启info端点：

management:
      endpoint:
        info:
          enabled: true
      endpoints:
        enabled-by-default: false

### 暴露端点 ###

由于有的端点包含铭感信息，端点启用和暴露是两码事。下表展示了端点的默认暴露情况。

<table> 
 <thead> 
  <tr> 
   <th>端点</th> 
   <th>JMX</th> 
   <th>Web</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>auditevents</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>beans</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>conditions</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>configprops</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>env</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>flyway</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>health</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>httptrace</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>info</td> 
   <td>Yes</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>loggers</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>liquibase</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>metrics</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>mapping</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>scheduledtasks</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>shutdown</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>sessions</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>threaddump</td> 
   <td>Yes</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>headdump</td> 
   <td>N/Y</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>jolokia</td> 
   <td>N/Y</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>logfile</td> 
   <td>N/Y</td> 
   <td>NO</td> 
  </tr> 
  <tr> 
   <td>prometheus</td> 
   <td>N/Y</td> 
   <td>NO</td> 
  </tr> 
 </tbody> 
</table>

在Web应用中，默认只有health和info两个端点暴露，即当开发者在SpringBoot项目中加入spring-boot-starter-actuator依赖并启动SpringBoot项目后，  
默认只有这两个端口课访问。

开发者可以在配置文件中自定义需要暴露那些端点，例如要暴露mapping和metrics端点，添加如下配置即可：

management:
      endpoints:
        web:
          exposure:
            include: mapping,metrics

要暴露所有端点，添加如下配置即可：

management:
      endpoints:
        web:
          exposure:
            include: *

### 端点保护 ###

如果这些端点需要对外提供服务，那么最好能够讲这些端点保护起来，若classpath中存在SpringSecurity，则默认使用SpringSecurity保护，  
使用SpringSecurity保护的步骤很简单，首先添加SpringSecurity依赖：

<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>

然后添加SpringSecurity配置，代码如下：

@Configuration
    public class ActuatorSecurity extends WebSecurityConfigurerAdapter { 
        @Override
        protected void configure(HttpSecurity http) throws Exception { 
            http.requestMatcher(EndpointRequest.toAnyEndpoint())
                    .authorizeRequests()
                    .anyRequest().hasRole("ADMIN")
                    .and()
                    .httpBasic();
        }
    }

在HttpSecurity中配置所有的Endpoint多需要具有ADMIN角色才能访问，同时开启httpBasic认证。注意，EndpointRequest.toAnyEndpoint()表示匹配所有的Endpoint，  
例如shutdown、mappings、health等，但不包括开发者通过@RequestMapping注解定义的接口。

为了方便演示，直接配置一个用户。

spring:
      security:
        user:
          name: yulu
          password: 123
          roles: ADMIN

定义完成后，再去访问health端点，需要登录后才可以访问。

### 端点响应缓存 ###

对于不带参数的端点请求，会自动进行缓存，开发者可通过如下方式配置缓存时间：

management:
      endpoint:
        beans:
          cache:
            time-to-live: 100s

这个配置表示beans端点的缓存时间为100s，如果要配置其他的端点，只需将beans修改为其他的端点名即可。

注意：如果端点添加了SpringSecurity保护，此时Principal会被视为端点的输入，因此端点响应将不被缓存。

### 路径映射 ###

默认情况下，所有的端点都暴露在“/actuator”路径下，例如health端点的访问路径是“/actuator/health”，如果开发者需要对端点路径进行定制，可通过如下配置进行：

management:
      endpoints:
        web:
          base-path: /
          path-mapping: 
            health: healthcheck

修改后health端点的访问路径由“/actuator/health”变为“/healthcheck”。

### CORS支持 ###

所有端点默认都没有开启跨域，开发者可以通过如下配置，快速开启CORS支持，进而实现跨域：

management:
      endpoints:
        web:
          cors:
            allowed-origins: http://localhost:8080
            allowed-methods: GET,POST

### 健康信息 ###

#### 1. 展示健康信息详情 ####

开发者可以通过查看健康信息来获取应用的运行数据，进而提早发现应用问题，提早解决，避免造成损失。默认情况下，开阿发这只能获取到status信息，这是因为detail信息默认不显示，  
开发者可以通过management.endpoint.health.show-detail属性来配置detail信息的显示策略，该属性的取值有三种：

*  never 即不显示detail信息，默认即此
 *  when-authorized detail信息只展示给认证用户，即用户登录后可查看detail信息，未登录则不可查看，另外可以通过management.endpoint.health.roles属性配置要求的角色，  
    如果不配置，那么通过认证的用户都可以查看detail信息，如果配置了，例如management.endpoint.health.roles=ADMIN表示认证的用户必须具有ADMIN角色才能查看detail信息。
 *  always 将detail信息展示给所有用户。

例如：在pom.xml文件中加入SpringSecurity依赖后，在application.yml文件中增加如下配置:

management:
      endpoint:
        health:
          show-details: when_authorized
          roles: ADMIN
      endpoints:
        web:
          exposure:
            include: "*"
    spring:
      security:
        user:
          name: yulu
          password: 123
          roles: ADMIN

这里首先暴露所有端点，配置health的detail信息只展示给认证用户，并且认证用户还要具有ADMIN角色，然后配置一个默认用户，用户名是yulu 密码是123，  
用户角色是ADMIN.

配置完成后，启动SpringBoot项目，在Postman中访问health端点，如下图所示：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1bHUzMg_size_16_color_FFFFFF_t_70_pic_center]

#### 2. 健康指示器 ####

SpringBoot会根据classpath中依赖的添加情况来自动配置一些HealthIndicators，如下表所示：

<table> 
 <thead> 
  <tr> 
   <th>名字</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>CassandraHealthIndicator</td> 
   <td>检查Cassandra数据库状况</td> 
  </tr> 
  <tr> 
   <td>DiskSpaceHealthIndicator</td> 
   <td>低磁盘空间检查</td> 
  </tr> 
  <tr> 
   <td>DataSourceHealthIndicator</td> 
   <td>检查是否可以从DataSource获取一个Connection</td> 
  </tr> 
  <tr> 
   <td>ElasticsearchHealthIndicator</td> 
   <td>检查Elasticsearch集群状况</td> 
  </tr> 
  <tr> 
   <td>InfluxDbHealthIndicator</td> 
   <td>检查InfluxDB状况</td> 
  </tr> 
  <tr> 
   <td>JmsHealthIndicator</td> 
   <td>检查JMS消息代理状况</td> 
  </tr> 
  <tr> 
   <td>MailHealthIndicator</td> 
   <td>检查邮件服务器状况</td> 
  </tr> 
  <tr> 
   <td>MongoHealthIndicator</td> 
   <td>检查MongoDB数据库状况</td> 
  </tr> 
  <tr> 
   <td>Neo4jHealthIndicator</td> 
   <td>检查Neo4j服务器状况</td> 
  </tr> 
  <tr> 
   <td>RabbitHealthIndicator</td> 
   <td>检查Rabbit服务器状况</td> 
  </tr> 
  <tr> 
   <td>RedisHealthIndicator</td> 
   <td>检查Redis服务器状况</td> 
  </tr> 
  <tr> 
   <td>SolrHealthIndicator</td> 
   <td>检查Solr服务器状况</td> 
  </tr> 
 </tbody> 
</table>

如果项目中存在相关的依赖，那么列表中对应的HealthIndicators将会被自动配置。

若开发者不需要这么多的HealthIndicators，则可以通过如下配置关闭所有的HealthIndicators自动化配置：

management:
      health:
        defaults:
          enabled: false

#### 3. 自定义HealthInfo ####

除了SpringBoot自动收集的这些HealthInfo之外，开发者也可以自定义HealthInfo，只需要实现HealthIndicator接口即可：

@Component
    public class MyHealth implements HealthIndicator { 
        @Override
        public Health health() { 
            if (checkNetWork()){ 
                return Health.up().withDetail("msg","网络连接正常。。。").build();
            }
            return Health.up().withDetail("msg","网络断开。。。").build();
        }
    
        private static boolean checkNetWork(){ 
            return true;
        }
    }

代码解释：

*  开发者自定义类实现HealthIndicator接口，并实现接口中的health方法，在health方法中，checkNetWork是一个网络连接检查的方法，  
    Health中的up的down方法分别对应两种常见的响应状态，即“up”和“down”。
 *  默认的响应状态一共有4种，定义在OrderedHealthAggregator类中，分别是DOWN、OUT\_OF\_SERVICE、UP、UNKNOWN，如果想增加响应状态，  
    可以自定义了继承自OrderedHealthAggregator，或者在application.yml中通过management.health.status.order属性进行配置。

如果开发者想要增加响应状态FATAL，在application.yml中增加如下配置即可：

management:
      health:
        status:
          order: FATAL,DOWN,OUT_OF_SERVICE,UP,UNKNOWN

配置完成后，就可以在health方法中返回自定义的响应状态了，修改MyHealth的health方法如下：

@Component
    public class MyHealth implements HealthIndicator { 
        @Override
        public Health health() { 
            return Health.status("FATAL").withDetail("msg","网络断开。。。").build();
        }
    
    }

### 应用信息 ###

应用信息就是通过/actuator/info接口获取到的信息，主要包含三大类：自定义信息、Git信息以及项目构建信息。

#### 1. 自定义信息 ####

自定义信息可以在配置文件中添加，也可以在Java代码中添加。

在配置文件中添加是指在application.yml中手动定义info信息，这些信息将在info端点中显示出来，例如在application.yml中配置如下信息：

info: 
      app: 
        encoding: @project.build.sourceEncoding@
        java: 
          source: @java.version@
          target: @java.version@
      author: 
        name: yulu
        email: aaa@163.com

注意@…@表示引用Maven中的定义

添加这些配置信息之后，重启SPringBoot项目，访问/actuator/info端点，结果如下图所示：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1bHUzMg_size_16_color_FFFFFF_t_70_pic_center 1]

通过Java代码自定义信息只需要自定义类继承自InfoContributor，然后实现该类中的contribute方法即可，代码如下：

@Component
    public class MyInfo implements InfoContributor { 
        @Override
        public void contribute(Info.Builder builder) { 
            Map<String,Object> info = new HashMap<>();
            info.put("name","yulu1");
            info.put("email","bbb@123.com");
            builder.withDetail("author",info);
        }
    }

此时访问info端点，结果如下图所示：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1bHUzMg_size_16_color_FFFFFF_t_70_pic_center 2]

#### 2. 项目构建信息 ####

如果classpath下存在META-INF/build-info.properties文件，SpringBoot项目将自动构建BuildPropertiesBean，  
然后info端点会发布build-info.properties文件中的信息。build-info.properties文件可以通过插件自动生成，具体操作步骤如下：

首先在pom.xml文件中添加插件：

<plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <executions>
            <execution>
                <goals>
                    <goal>build-info</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <excludes>
                <exclude>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
                </exclude>
            </excludes>
        </configuration>
    </plugin>

然后在IdEA中单击MavenProject，找到该插件，单击spring-boot：build-info按钮，生成构建信息。如下图所示：  
\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-i1PmCIZy-![在这里插入图片描述][20210322193540856.png_pic_center]

构建信息生成成功后，在项目目录下的target/classes/META-INF目录下生成了一个build-info.properties文件，内容如下图所示：

build.artifact=chapter14-1
    build.group=com.demo
    build.name=chapter14-1
    build.time=2021-03-22T11\:19\:23.967Z
    build.version=0.0.1-SNAPSHOT

此时启动SpringBoot项目，访问info端点，构建信息将被自动发布。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1bHUzMg_size_16_color_FFFFFF_t_70_pic_center]: /images/20221022/e2817661a5434ca981dc7f8f1fbd60b2.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1bHUzMg_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221022/e318a6a66dd14f7c92e2ae43ba62b769.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1bHUzMg_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221022/7e52b686be8e498bb2698cf3b4e485f3.png
[20210322193540856.png_pic_center]: /images/20221022/33f9fa90a4fd4b7db6bbed3b3ad64069.png