microcosm-SpringBoot工具包

发表于 更新于 分类于 阅读次数： 本文字数： 7k 阅读时长 ≈ 6 分钟

项目的工具包，以功能分包，功能之间尽量减少相互依赖，每个功能作为最小单元供服务依赖。
Try to reduce mutual dependence between functions and functions. Each function is used as the minimum unit for service dependencies.

具备的能力

  1. 交互协议封装。具有统一的出参、入参标准
  2. 规范日志打印格式和分类收集。统一日志打印格式，适配tomcat日志、nginx日志、接口日志、异常日志以及普通日志
  3. 全局异常捕获处理，同时具备针对特定业务的异常 BusinessException 不打印error日志，只返回接口错误。以及服务级别异常 ServerException 打印error日志，返回接口错误，可配合告警平台做告警通知
  4. 具备适配 Apollo 功能，可在 Apollo 变更后自动刷新内存，可解决 properties、configurationProperties 导致的 Apollo 不刷新问题
  5. 具备适配 qconf、mybatis-plus 等能力，均可跟进需要引入各自组件的 pom 文件即可

参考文尾的 各模块使用建议

讲在前边

  1. 这个项目只是对 spring-boot 类的项目的一些增强，如果你的项目不是用 spring-boot 开发的，那么它对你的用处可能没有那么大
  2. 本指导用例依据个人开发习惯编写而成，项目结构参考另一个脚手架项目 dust
  3. 无论在什么情况下，我都会倾听你的意见并对项目做出改进

使用教程

参考: guideline

父版本添加版本控制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<properties>
    <last-vision>最新版本(参考本文的发版历史)</last-vision>
</properties>

<dependencyManagement>
    <dependencies>
      <!-- microcosm start -->
      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-logging</artifactId>
        <version>${revision}</version>
      </dependency>

      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-apollo</artifactId>
        <version>${revision}</version>
      </dependency>

      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-qconf</artifactId>
        <version>${revision}</version>
      </dependency>

      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-distribute</artifactId>
        <version>${revision}</version>
      </dependency>
      
      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-core</artifactId>
        <version>${revision}</version>
      </dependency>

      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-codec</artifactId>
        <version>${revision}</version>
      </dependency>

      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-except</artifactId>
        <version>${revision}</version>
      </dependency>
      
      <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-micro-mybatis-plus</artifactId>
        <version>${revision}</version>
      </dependency>
      <!-- microcosm end -->
    </dependencies>
</dependencyManagement>

api模块增加依赖

这里主要增加一些核心类库，包括但不限于出入参数封装 InputMessage, OutputMessage,
服务异常 ServerException,
业务异常 BusinessException，
核心异常枚举 ErrorEnums

配置模块依赖

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-core</artifactId>
    </dependency>
</dependencies>

自定义服务异常枚举

你可以通过实现 ExceptionEnums 接口，来定义自己的服务异常枚举，用来适配服务异常、业务异常。两种异常在统一异常捕获模块，会产生不一样的效果哦

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
public enum GmmpErrorCodes implements ExceptionEnums {
    // 异常
    INTERNAL_EXCEPT(10000, "系统内部异常"),
    INVALID_SIGN(10001, "请求加密协议错误"),
    INVALID_IP(10002, "请求IP地址异常"),
    INVALID_DATA(10003, "数据错误"),
    INVALID_PARAMS(10004, "参数错误"),
    INVALID_CITY_ID(10005, "无效的城市编号"),
    INVALID_ENTERPRISE_ID(10006, "无效的企业编号"),
    // …… 省略部分
    ;
    private int code;
    private String message;
    public static final int MODULE = 200;
    GmmpErrorCodes(int code, String message) {
        this.code = code;
        this.message = message;
    }
    @Override
    public int code() {
        return this.code;
    }
    @Override
    public String message() {
        return this.message;
    }
}

common模块增加依赖

这个模块主要是通用能力的封装，包括但不限于调用第三方服务、通用工具类处理

此处增加 出入参数封装依赖（qconf适配的依赖）

配置模块依赖

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-codec</artifactId>
    </dependency>
</dependencies>

如果你的服务使用 qconf 而不是 nacos 进行服务发现，那么你还需要添加以下依赖

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-qconf</artifactId>
    </dependency>
</dependencies>

main模块添加依赖

这个模块是整个服务的启动模块，是 springboot 项目的启动类所在的模块

这里添加日志处理、apollo配置中心、统一异常捕获的依赖

配置模块依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<dependencies>
    <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-logging</artifactId>
    </dependency>

    <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-apollo</artifactId>
    </dependency>

    <dependency>
        <groupId>io.github.tf2jaguar.micro</groupId>
        <artifactId>micro-except</artifactId>
    </dependency>
</dependencies>

发版日历

最新发版及调整参考: version

最新版本

1.1.3.RELEASE

更新日历

1.1.3.RELEASE

发布日期：2022-06-16

  1. 调整 logging 模块中追踪方法运行时间的开关以及日志打印级别

1.1.2.RELEASE

发布日期：2021-07-02

  1. 修复 LogRecordAspect 日志问题

1.1.1.RELEASE

发布日期：2021-07-02

  1. 修复 revision 重命名问题

1.1.0.RELEASE

发布日期：2021-07-01

  1. micro-core： 自定义服务异常枚举时实现 ExceptionEnums 如内置的常用异常状态枚举的实现方式 public enum ErrorEnums implements ExceptionEnums；封装了简单的分页请求入参和返回参数，封装了接口交互的出入参数格式类（通过 micro-codec 模块完成出入参数自动封装、解封装）
  2. micro-codec： 实现了对 feign 调用的出入参数驼峰转换；实现了对 http 调用出入参数驼峰转换，入参数 params 封装，出参数 code、data、message 封装；实现了对 swagger 展示中入参数、出参数封装
  3. micro-except： 实现类拦截服务异常 ServerException，打印error日志，返回接口错误 ；拦截业务异常 BusinessException，不打印error日志，只返回接口错误 ；拦截参数绑定异常 BindException，打印error日志，返回接口错误 ；拦截方法参数异常 MethodArgumentNotValidException，打印error日志，返回接口错误 ；拦截全局异常 Exception，打印error日志，返回接口错误
  4. 增加mybatis-plus代码生成器模块

1.0.1.RELEASE

发布日期：2021-05-13

  1. 调整pom依赖和 guideline

1.0.0.RELEASE

发布日期：2021-05-13

  1. micro-logging： 实现了统计经过 http请求 的出入参数记录，针对每个 request 的 api日志 用唯一的 session_id 进行区分；使用logback记录日志、记录 all_log、error_log、api_log、access_log 的日志并按照天做切分
  2. micro-apollo： 实现了对 apollo 配置变更自动刷新；实现了对 apollo 日志级别调整后自动刷新
  3. micro-qconf： 实现了从 qconf 中获取服务器列表，供给 ribbon 远程调用
  4. micro-distribute： 利用 Twitter 的 Snowflake 算法实现分布式ID

各模块使用建议

micro-logging

使用建议

  1. 在启动模块中添加 micro-logging 模块的 pom 依赖
  2. 针对 form表单提交、文件上传/下载等接口，请通过spring-boot配置 micro.logging.api.ignore= 忽略日志打印
  3. 实现了统计经过 http请求 的出入参数记录，针对每个 request 在日志中有唯一的 session_id 进行区分
  4. 使用logback记录日志、记录 all_log、error_log、api_log、access_log 日志并按照天做切分

micro-apollo

使用建议

  1. 在启动模块中添加 micro-apollo 模块的 pom 依赖
  2. 实现了对 apollo 配置变更自动刷新
  3. 实现了对 apollo 日志级别调整后自动刷新

micro-qconf

使用建议

  1. 在进行 feign 调用的模块中添加 micro-qconf 模块的 pom 依赖
  2. 实现了从 qconf 中获取服务器列表，供给 ribbon 远程调用

micro-distribute

使用建议

  1. 在启动模块中添加 micro-distribute 模块的 pom 依赖
  2. 服务集群部署，请通过 micro.distribute.machine-list= 指定当前机器集群（单机时无需配置，默认1），用来计算分布式id生成的机器id；
  3. 服务部署在多个数据中心，请通过 micro.distribute.data-center-id= 指定当前数据中心id编号（单机时无需配置，默认1），用来计算分布式id生成的数据中心id

micro-core

使用建议

  1. 在底层接口模块中添加 micro-core 模块的 pom 依赖
  2. 自定义服务异常枚举时实现 ExceptionEnums 如内置的常用异常状态枚举的实现方式 public enum ErrorEnums implements ExceptionEnums
  3. 封装了简单的分页请求入参和返回参数
  4. 封装了接口交互的出入参数格式类（通过 micro-codec 模块完成出入参数自动封装、解封装）

micro-codec

使用建议

  1. 在启动模块中添加 micro-codec 模块的 pom 依赖
  2. 实现了对 feign 调用的出入参数驼峰转换
  3. 实现了对 http 调用出入参数驼峰转换，入参数 params 封装，出参数 code、data、message 封装
  4. 实现了对 swagger 展示中入参数、出参数封装

micro-except

使用建议

  1. 在启动模块中添加 micro-except 模块的 pom 依赖
  2. 拦截服务异常 ServerException 打印error日志，返回接口错误
  3. 拦截业务异常 BusinessException 不打印error日志，只返回接口错误
  4. 拦截参数绑定异常 BindException 打印error日志，返回接口错误
  5. 拦截方法参数异常 MethodArgumentNotValidException 打印error日志，返回接口错误
  6. 拦截全局异常 Exception 打印error日志，返回接口错误

micro-mybatis-plus

使用建议

  1. 使用其生成基础实体类等