项目的工具包,以功能分包,功能之间尽量减少相互依赖,每个功能作为最小单元供服务依赖。
Try to reduce mutual dependence between functions and functions. Each function is used as the minimum unit for service dependencies.
具备的能力
- 交互协议封装。具有统一的出参、入参标准
- 规范日志打印格式和分类收集。统一日志打印格式,适配tomcat日志、nginx日志、接口日志、异常日志以及普通日志
- 全局异常捕获处理,同时具备针对特定业务的异常 BusinessException 不打印error日志,只返回接口错误。以及服务级别异常 ServerException 打印error日志,返回接口错误,可配合告警平台做告警通知
- 具备适配 Apollo 功能,可在 Apollo 变更后自动刷新内存,可解决 properties、configurationProperties 导致的 Apollo 不刷新问题
- 具备适配 qconf、mybatis-plus 等能力,均可跟进需要引入各自组件的 pom 文件即可
项目地址: GitHub https://github.com/tf2jaguar/microcosm
参考文尾的 各模块使用建议
讲在前边
- 这个项目只是对
spring-boot
类的项目的一些增强,如果你的项目不是用spring-boot
开发的,那么它对你的用处可能没有那么大 - 本指导用例依据个人开发习惯编写而成,项目结构参考另一个脚手架项目 dust
- 无论在什么情况下,我都会倾听你的意见并对项目做出改进
使用教程
参考: guideline
父版本添加版本控制
<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
配置模块依赖
<dependencies>
<dependency>
<groupId>io.github.tf2jaguar.micro</groupId>
<artifactId>micro-core</artifactId>
</dependency>
</dependencies>
自定义服务异常枚举
你可以通过实现 ExceptionEnums
接口,来定义自己的服务异常枚举,用来适配服务异常、业务异常。两种异常在统一异常捕获模块,会产生不一样的效果哦
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适配的依赖)
配置模块依赖
<dependencies>
<dependency>
<groupId>io.github.tf2jaguar.micro</groupId>
<artifactId>micro-codec</artifactId>
</dependency>
</dependencies>
如果你的服务使用 qconf
而不是 nacos
进行服务发现,那么你还需要添加以下依赖
<dependencies>
<dependency>
<groupId>io.github.tf2jaguar.micro</groupId>
<artifactId>micro-qconf</artifactId>
</dependency>
</dependencies>
main模块添加依赖
这个模块是整个服务的启动模块,是 springboot
项目的启动类所在的模块
这里添加日志处理、apollo配置中心、统一异常捕获的依赖
配置模块依赖
<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
发布日期:2022-06-16
- 调整 logging 模块中追踪方法运行时间的开关以及日志打印级别
1.1.2.RELEASE
发布日期:2021-07-02
- 修复 LogRecordAspect 日志问题
1.1.1.RELEASE
发布日期:2021-07-02
- 修复 revision 重命名问题
1.1.0.RELEASE
发布日期:2021-07-01
- micro-core: 自定义服务异常枚举时实现
ExceptionEnums
如内置的常用异常状态枚举的实现方式public enum ErrorEnums implements ExceptionEnums
;封装了简单的分页请求入参和返回参数,封装了接口交互的出入参数格式类(通过micro-codec
模块完成出入参数自动封装、解封装) - micro-codec: 实现了对
feign
调用的出入参数驼峰转换;实现了对http
调用出入参数驼峰转换,入参数 params 封装,出参数code、data、message
封装;实现了对swagger
展示中入参数、出参数封装 - micro-except: 实现类拦截服务异常
ServerException
,打印error日志,返回接口错误 ;拦截业务异常BusinessException
,不打印error日志,只返回接口错误 ;拦截参数绑定异常BindException
,打印error日志,返回接口错误 ;拦截方法参数异常MethodArgumentNotValidException
,打印error日志,返回接口错误 ;拦截全局异常Exception
,打印error日志,返回接口错误 - 增加mybatis-plus代码生成器模块
1.0.1.RELEASE
发布日期:2021-05-13
- 调整pom依赖和 guideline
1.0.0.RELEASE
发布日期:2021-05-13
- micro-logging: 实现了统计经过
http请求
的出入参数记录,针对每个request
的api日志
用唯一的session_id
进行区分;使用logback记录日志、记录all_log、error_log、api_log、access_log
的日志并按照天做切分 - micro-apollo: 实现了对
apollo
配置变更自动刷新;实现了对apollo
日志级别调整后自动刷新 - micro-qconf: 实现了从
qconf
中获取服务器列表,供给ribbon
远程调用 - micro-distribute: 利用 Twitter 的 Snowflake 算法实现分布式ID
各模块使用建议
micro-logging
使用建议
- 在启动模块中添加
micro-logging
模块的 pom 依赖 - 针对 form表单提交、文件上传/下载等接口,请通过spring-boot配置
micro.logging.api.ignore=
忽略日志打印 - 实现了统计经过
http请求
的出入参数记录,针对每个request
在日志中有唯一的session_id
进行区分 - 使用logback记录日志、记录 all_log、error_log、api_log、access_log 日志并按照天做切分
micro-apollo
使用建议
- 在启动模块中添加
micro-apollo
模块的 pom 依赖 - 实现了对
apollo
配置变更自动刷新 - 实现了对
apollo
日志级别调整后自动刷新
micro-qconf
使用建议
- 在进行
feign
调用的模块中添加micro-qconf
模块的 pom 依赖 - 实现了从
qconf
中获取服务器列表,供给ribbon
远程调用
micro-distribute
使用建议
- 在启动模块中添加
micro-distribute
模块的 pom 依赖 - 服务集群部署,请通过
micro.distribute.machine-list=
指定当前机器集群(单机时无需配置,默认1),用来计算分布式id生成的机器id; - 服务部署在多个数据中心,请通过
micro.distribute.data-center-id=
指定当前数据中心id编号(单机时无需配置,默认1),用来计算分布式id生成的数据中心id
micro-core
使用建议
- 在底层接口模块中添加
micro-core
模块的 pom 依赖 - 自定义服务异常枚举时实现
ExceptionEnums
如内置的常用异常状态枚举的实现方式public enum ErrorEnums implements ExceptionEnums
- 封装了简单的分页请求入参和返回参数
- 封装了接口交互的出入参数格式类(通过
micro-codec
模块完成出入参数自动封装、解封装)
micro-codec
使用建议
- 在启动模块中添加
micro-codec
模块的 pom 依赖 - 实现了对
feign
调用的出入参数驼峰转换 - 实现了对
http
调用出入参数驼峰转换,入参数params
封装,出参数code、data、message
封装 - 实现了对
swagger
展示中入参数、出参数封装
micro-except
使用建议
- 在启动模块中添加
micro-except
模块的 pom 依赖 - 拦截服务异常
ServerException
打印error日志,返回接口错误 - 拦截业务异常
BusinessException
不打印error日志,只返回接口错误 - 拦截参数绑定异常
BindException
打印error日志,返回接口错误 - 拦截方法参数异常
MethodArgumentNotValidException
打印error日志,返回接口错误 - 拦截全局异常
Exception
打印error日志,返回接口错误
micro-mybatis-plus
使用建议
- 使用其生成基础实体类等