# lzh-1.8-prometheus-spring-boot-starter

**Repository Path**: coding_13/lzh-1.8-prometheus-spring-boot-starter

## Basic Information

- **Project Name**: lzh-1.8-prometheus-spring-boot-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 一个异常通知的spring-boot-start框架 lzh-1.8-prometheus-spring-boot-starter

## 前言

对于工程的开发，必然会伴随着各种bug，工程量越大，出现bug的概率也会越高。一般对于代码量较小的工程来说，一个人可能就足够去做开发与维护；但是对于代码量较大的工程往往是需要一个小团队协作开发。当工程基本完成，开始部署测试环境或者生产环境时，这些环境并不能像开发环境一样能快速的调试与维护，线上的工程一旦出现异常时，开发团队就需要主动感知异常并协调处理，当然人不能一天24小时去盯着线上工程，所以就需要一种机制来自动化的对异常进行通知，并精确到谁负责的那块代码。这样会极大地方便后续的运维。因此，本项目上线

## 系统需求

![jdk版本](https://img.shields.io/badge/java-1.8%2B-red.svg?style=for-the-badge&logo=appveyor)
![maven版本](https://img.shields.io/badge/maven-3.2.5%2B-red.svg?style=for-the-badge&logo=appveyor)
![spring boot](https://img.shields.io/badge/spring%20boot-2.0.0.RELEASE%2B-red.svg?style=for-the-badge&logo=appveyor)

## 当前版本

![目前工程版本](https://img.shields.io/badge/version-1.0.0--personal-green.svg?style=for-the-badge&logo=appveyor)

## 最快上手

- 将此工程通过``mvn clean install``打包到本地仓库中。
- 在你的工程中的``pom.xml``中做如下依赖

```xml
<dependency>
    <groupId>com.lzh</groupId>
    <artifactId>lzh-1.8-prometheus-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

- 在``application.properties``或者``application.yml``中做如下的配置：（至于以上的配置说明后面的章节会讲到）

```yaml
prometheus:
  enabled: true
  exceptionnotice:
    enabled: true
    included-trace-package: com.lzh
    enable-async: true
    exclude-exceptions:
    - com.lzh.exceptions.TestException
    include-header-name:
    - tenant-id
    listen-type: web
    strategy:
      enabled: true
      frequency-type: showcount
      notice-show-count: 100
#      notice-time-interval: 2h
  dingding:
    enabled: true
    phone-num:
    - 要@的人的手机号
    access-token: 钉钉通知的所给的url的后面的accessToken的参数的值
    sign-secret: 钉钉的签名秘钥
    enable-signature-check: true
    dingding-text-type: markdown
```

- 至于钉钉的配置请移步：[钉钉机器人](https://open-doc.dingtalk.com/microapp/serverapi2/krgddi "自定义机器人")，这里需要特别说明一下，钉钉在2019年10月份（大概）对于钉钉机器人进行了一次改进,这次改进主要是安全设置变为必选项，原来已经配置过的钉钉机器人且没有配置安全设置的不受影响

![钉钉改进](/src/main/resources/dingdingupgrade.png)

- 以上配置好以后就可以写demo测试啦，首先创建第一个bean：

```java
@Component
@ExceptionListener // 异常通知的监控来自这个注解
public class NoticeComponents {

    public void someMethod(String name) {
        System.out.println("这是一个参数：" + name);
        throw new NullPointerException("第一个异常");
    }

    public void anotherMethod(String name, int age) {
        System.out.println("这又是一个参数" + age);
        throw new IllegalArgumentException(name + ":" + age);
    }
}
```

- 以上都建立好了以后，就可以写单元测试了:

```java
@RunWith(SpringRunner.class)
@SpringBootTest
public class DemoApplicationTests {

    @Autowired
    private NoticeComponents noticeComponents;

    @Test
    public void contextLoads() {
        noticeComponents.someMethod("hello");
    }
}
```

当运行单元测试后，假如钉钉配置没有问题的话，你的钉钉中就会出现如下类似的消息：
![效果](/src/main/resources/simpledingding.png)
假如在你配置的钉钉中出现类似这个信息的话，恭喜你，你成功的产生了一个异常通知。

- 综上，一个最简单的例子就完成了。

## 咋做的

本框架遵循spring boot starter的自动化配置规范而开发的自动化异常通知框架，整体业务流程如下：
![流程](/src/main/resources/new.png)

### 配置

本框架配置主要分为4部分：

1. 全局配置
2. 异常配置
3. 通知配置
4. 外援配置

#### 全局配置

- 全局配置有三项配置

```yaml
prometheus:
  enabled: true
  project-enviroment: develop
  project-name: demo
```
具体说明如下：

|名称|参数类型|说明|必要配置|
|:-:|:-:|:-:|:-:|
|enabled|boolean|用于开启项目配置，属于总控开关|是|
|project-enviroment|enum|工程环境（enum），默认为develop|否|
|project-name|string|一般忽略，以spring.application.name替代|否|

全局配置主要分以上三项，主要用于表明工程的名称、环境与全局开关，工程所处环境分了如下几个：
- dev：开发环境
- test：测试环境
- pre：预部署环境
- release：正式环境
- roll_back:回滚环境
以上5种环境基本够用。

- 异常配置分为两块，分别为异常通知配置与通知频率策略配置，具体如下配置（yml）

```yaml
prometheus:
  exceptionnotice:
    enabled: true
    included-trace-package: com.lzh
    enable-async: true
    exclude-exceptions:
    - com.lzh.exceptions.TestException
    include-header-name:
    - tenant-id
    listen-type: web
    strategy:
      enabled: true
      frequency-type: showcount
      notice-show-count: 100
#      notice-time-interval: 2h
```

|名称|参数类型|说明|必要配置|
|:-:|:-:|:-:|:-:|
|enabled|boolean|基本不用，默认为true，用于开启异常通知配置|否|
|included-trace-package|string|异常追踪的包路径，一般情况下，此配置项就是配置你工程的包路径就可以了|是|
|listen-type|enum|监听类型，有两种：**common/web**，默认为common|是|
|enable-async|boolean|是否开启异步通知，默认为false|否|
|exclude-exceptions|list|排除异常，表示若出现这些异常不需要进行异常通知|否|
|include-header-name|list|异常通知中需要包含的header信息(不写全部返回)|否|
|策略配置|
|enabled|boolean|是否开启通知策略（默认否）|否|
|frequency-type|enum|通知频率策略类型：showcount/timeout|是|
|notice-show-count|int|当策略类型为showcount时，表示距上次通知再出多少次需要再次通知|否|
|notice-time-interval|duration|当策略类型为timeout时，表示距上次通知经过多长时间后再次通知|否|

- 以上通知中**最重要**的当属``exceptionnotice.listen-type``，此配置表示工程的监听方式，目前有两种监听方式：**普通监听（common）**；**web监听（web）**。这两种监听方式各有千秋，普通监听方式主要运用aop的方式对有注解的方法或类进行监听，可以加在任何类与方法上。**web监听只能对controller层进行监听，对其它层无效**，不过异常通知的信息更丰富，不仅仅包括了普通监听的所有信息（不包含参数），还包含了请求中的路径信息（path）、参数信息（param）、请求中的请求体信息（body）和请求体中的头信息（header）。

例如：

```java
@RestController
@RequestMapping("/demo")
public class DemoController {

    @Autowired
    private CustomService customService;

    @PostMapping("/dingding1/{pathParam}")
    @ExceptionListener
    public String dingding1(@PathVariable @ApiParam(value = "来个路径参数", required = true) String pathParam,
            @RequestParam @ApiParam(value = "来个参数", required = true) String param,
            @RequestHeader @ApiParam(value = "来个请求头", required = true) String headParam,
            @RequestBody @ApiParam(value = "来个请求体", required = true) String body) {
        customService.custom();
        return "Keep on going never give up.";
    }
}
```

具体效果如下：
![请求异常通知](/src/main/resources/demo2.png)

- 实际上钉钉机器人提供了很多其他的消息类型，这里适配了**钉钉的markdown**文本输出，只需要配置``exceptionnotice.dingding-text-type=markdown``即可，最终你可以得到以下面类似的效果：
![请求异常通知markdown](/src/main/resources/mvcmarkdown.png)

- 项目中的异常一般分为两大类：第一类为未捕获异常，第二类为业务异常。业务异常一般由用户自己定义，在javaweb项目中，假如用户的请求不满足返回结果的条件，一般是需要主动抛出自定义异常的，所以这类异常并不需要进行通知。排除不需要异常通知的配置如下：

```yaml
prometheus.exceptionnotice.exclude-exceptions=java.lang.IllegalArgumentException,com.yourpackage.YourLogicException
```

- 上一版本的异常通知由于是同步的，由于各种各样的原因，在异常通知失败时，框架本身可能也会产生一些异常，所以增加了异步通知，主要配置为``exceptionnotice.enable-async=true``，开启异步配置需要自行配置一个线程池。

一般而言，一个方法出现异常信息，意味着每当同样的方式调用时都会抛出相同的异常方法，放任不管的话，钉钉异常通知与邮件异常通知会重复的收到同一个异常，所以为了限制发送频率，默认情况下，某个方法出现的异常需要通知，那么这条通知**每天只会出现一次**。当然这样也可能会出现问题，假如邮件或钉钉信息没有收到，很可能会漏掉此通知，所以这里创造了一个通知的策略。

- 通知策略对应的配置类为``ExceptionNoticeFrequencyStrategy``，开启策略需要在``application.properties``中加入如下配置
```properties
exceptionnotice.strategy.enabled=true
```
- 目前一共有两种通知策略
    - 时间策略
    - 出现频次策略

对应的配置为：
```properties
exceptionnotice.strategy.frequency-type=timeout/showcount
```
- 时间策略对应的配置项为``exceptionnotice.strategy.notice-time-interval``，类型为duration，表示的是自上次通知时间起，超过了此配置的时间后，便会再次通知。
- 频次策略对应的配置项为``exceptionnotice.strategy.notice-show-count``，表示的是自上次通知起，出现次数超过了此配置的次数后，便会再次通知

基本上以上策略足够使用，假如还有更好的配置策略可以联系我

#### 通知配置

- 通知配置一共三总类型：
  1. 钉钉通知
  2. 邮件通知
  3. 自定义通知

- 钉钉通知配置：

```yaml
prometheus：
  dingding:
    enabled: true
    phone-num:
    - 钉钉通知人的手机号
    access-token: 钉钉机器人的手机号
    sign-secret: 钉钉机器人秘钥
    enable-signature-check: true
    dingding-text-type: markdown
```

|名称|参数类型|说明|必要配置|
|:-:|:-:|:-:|:-:|
|enabled|boolean|开启钉钉通知，默认为否|是|
|phone-num|list|通知人的手机号（可以多个）|是|
|access-token|string|钉钉机器人需要的accesstoken|是|
|enable-signature-check|boolean|是否开启验签验证|否|
|sign-secret|string|验签秘钥，开启验签验证后必填|否|
|dingding-text-type|enum|钉钉通知的文本类型：text/markdown，默认为text|否|

开启签名验证时，需要在钉钉机器人的安全设置中选中*加签*设置：
![钉钉加签](/src/main/resources/dingdingsign.png)

- 邮件通知同样也延续了原来的邮件配置，同样依赖``spring-boot-starter-mail``及其配置

```yaml
spring:
  mail:
    host: smtp.xxx.com
    port: 25
    username: 开启smtp权限的邮箱用户名
    password: 密码
prometheus:
  email:
    enabled: true