版本号规则

三位版本号 x.y.z，分别是主版本号、次版本号、修订版本号。例如 1.2.3。

  • 主版本号：主版本号内的所有版本必须相互兼容；与其它主版本号不一定完全兼容，尽量向下兼容。

  • 次版本号：代表新特性增强。版本号越大特性越丰富。

  • 修订版本号：代表BugFix版本。只做bug修复使用，版本号越大越稳定。

Shoulder 版本分布

Shoulder 版本 Spring Boot 版本 JDK 版本 推荐度

0.8.1

3.2.6

17+

🔥推荐

0.7.1

2.7.6

1.8 ~ 11

🔥推荐

0.6.x

2.7.6

1.8

❌停止维护

更早版本

2.x

❌停止维护

1.0（规划中）

  • api-doc

    • 提供开箱即用的接口说明

  • web

    • cors 一键开关

    • 现在会自动引入 shoulder-api-doc

    • 提供操作日志查询

    • 配置开启发送邮件，支持模板

  • crypto

    • 支持关闭公钥查询接口

    • 支持修改公钥查询接口地址

  • batch

    • batch_record_detail 表字段 index 名称改为 index_no

  • ext-ai

    • 提供AI 工程里额外能力，如意图识别，输出内容管控、会话历史、会话分析等

  • ext-config

    • 提供动态配置管理功能

  • ext-moments

    • 提供社交功能模块

    • 动态、文章、评论、点赞、朋友圈、通知等

0.8.1（2024-6-17）

升级内容速览

小版本：依赖版本升级、少量优化和错误修复

  • shoulder-dependencies 升级依赖

    • spring-boot 3.2.4 → 3.2.6

    • mybatis-plus 3.5.5 → 3.5.6

    • commons-io 2.16.0 → 2.16.1

    • shoulder-maven-plugin 1.2.1 → 1.2.2

  • shoulder-core

    • 修复单测报错

  • autoconfiguration

    • 添加提示项

  • shoulder-archetype-simple 优化

    • 去除不需要的 import

    • readme.md 介绍文件内容优化

    • 去除多余的配置文件内容

    • 源码目录添加 model

  • shoulder-starter-web 默认引入操作日志模块 shoulder-operation-log

0.8 （2024-4-24）【升级 spring boot3.2, JDK 17】

升级内容速览

升级并支持 spring-boot3（并将相关生态升级，如 jdk、spring-cloud、spring security6、swaggerv3/OPEN-APIv2等）

  • core

    • 升级 jdk17

    • concurrent 引入双buffer缓存通用工具类 DoubleBufferCache，便于更简单的实现该高性能算法。

    • 提供增强的 ConversionService，支持集合、更多的类转换，比如日期解析时支持多种格式，Jdk8的各类时间互转

    • Translator 增加支持默认message方法

    • 新增字典定义

    • 新增日志配置，提供默认 logger

    • 基础错误码新增

    • 多线程工具优化，能力增强

    • fix 修正错误的拼写

  • db

    • 扩展的 bizId、version、逻辑删除等 模板Entity进入可用状态，现在可以继承这些模板类减少bizId 相关DB操作代码的编写了（0.6 引入并开始孵化）

  • operation-log

    • detailKey 改为 detailI18nKey，db 中 detail_key 改为 detail_i18n_key

    • detailItems 改为 detailI18nItems，db 中 detail_item 改为 detail_i18n_values

  • web

    • 模板类进入可用状态（0.6 引入并开始孵化）

    • 提供开箱即用可扩展的字典、标签能力（0.6 引入并开始孵化），并添加配套支持（HTTP-API、相关工具类、ConversionService、JPA、Mybatis-plus、MongoDb…​）

    • filter 提供可配置的 traceId、user、tenantId 默认填充过滤器，方便后续使用 AppContext 上下文。

    • BaseResultAdvance 优化：若返回值是 Collection，则改用 ListResult 包装

    • 提供 xss 过滤器，保障内容安全

    • 兼容 spring boot spring/security 6.x 新方法

  • autoconfiguration（forTest）

    • 支持内嵌 redis 启动，方便测试

    • traceId、userId、tenantId mock

    • 新增配置开关，将带@sensitive 注解的字段在自动打印日志中脱敏/不打印

  • crypto

    • fix spring6 RestTemplate 底层方法不兼容变更bug

  • batch

    • 批处理模块进入可用状态（0.6 引入并开始孵化）

0.7.1（2023-10-2）【较大更新】

升级内容速览

大版本：较多依赖版本升级；大量功能优化，OAuth2 Server暂时不支持

  • shoulder 不再为除spring boot外的三方jar定制能力（如mybatis-plus）以减少三分jar定制功能学习成本， 也不考虑没有spring上下文的情况，本框架强依赖Spring，定位为Spring的能力扩展。

  • 升级到了 SpringBoot 2.7.x, 关于springfox升级注意事项[spring boot2.x升级到2.6](https://springfox.github.io/springfox/docs/snapshot/#migrating-from-existing-2-x-version)

  • 升级2.7注意： https://spring.io/blog/2022/05/19/spring-boot-2-7-0-available-now

  • META-INF/spring.factories - META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

  • DB

    • 自动判断是否存在分布式事务问题，默认仅开发时生效

    • TransactionSynchronizationManager.isActualTransactionActive() 判断是否有 @Transactional

    • 且该方法是写的（C/U/D）支持扩展这里

    • 拿到数据源

    • 判断是否是同一个事务管理器（不是则可能有分布式事务问题）

    • !null && 正在事务 && TransactionSynchronizationManager.getResource(dataSource) == null || isTransactionActive=false

  • core

    • 调整部分内置错误码定义

    • json 日期格式按照统一设置

    • 增加了部分高性能的数据结构，以适用于企业级流量染色场景

  • autoconfiguration

    • 兼容性优化：调整功能自动激活逻辑，增加部分功能关闭开关

    • 集群模式下不需要手动注入 instanceId，由依赖手动注入改为 默认配置 + WARN 日志提醒

  • 操作日志

    • 优化扩展，支持自定义解析逻辑，以支持在记录操作日志时，同时记录其他信息:OperationLoggerInterceptor

  • batch

    • 批处理模块支持导出导出，进度条等基本逻辑，上升至无依赖任务批处理

    • 新增支持并发 process，允许单独使用，见 [spider 项目](https://gitee.com/ChinaLym/learn-spider)

  • log

    • Logger 分割，定义更明确，以满足更多的日志文件划分方式，以应对大业务量的场景

    • 新增 缓存(redis) 访问日志输出，默认只对慢查询、大数据做一定记录

    • 新增统计日志（stat-log），REST 分钟级访问统计

    • 异常日志新增链路上下文打印

    • 追踪日志更详细：digest、stat

  • 安全与加密-脱敏

    • 敏感词过滤

    • 字段名-脱敏 shielder 算法id-脱敏算法实现

    • 注解形式，输出时自动脱敏#

AuthServer 因 Spring Security OAuth 项目废弃，暂时废弃，将在下一版本待 spring-auth-server 稳定后一起回归

  • redis 连接池事件监听聚合接口

  • LettuceEventConsumer

  • monitor 部分能力增强

  • 稳定性提升：bugfix、compile warning

  • 依赖升级

Example 1. 依赖升级

springboot 2.4.5 → 2.7.16
spring-cloud 2020.0.2 → 2021.0.1
swagger2 1.6.2 → 1.6.11（默认不引入）
swagger3 2.1.9 → 2.2.16（默认不引入）
nimbus-jose-jwt 8.21 → 9.35
hutool 5.8.22 → 5.8.22
xstream 1.4.17 → 1.4.20
guava 30.1.1-jre → 31.2-jre
alibaba.transmittable 2.12.1 → 2.14.3
bcprov.jdk15on 1.68 → 1.70
bcpkix.jdk15on 1.68 → 1.70
caffeine 2.8.5 → 3.0.5（默认不引入）
tika-core 1.24.1 → 2.9.0
opencsv 4.1 → 5.6
h2 1.4.200 → 2.2.224
redisson → 3.23.5
mybatis-plus 3.4.2 → 3.5.3.2
p6spy 3.3.2 → 3.9.1
knife4j 3.0.2 → 3.0.3
jna 5.8 → 5.13
javassist 3.27.0-GA → 3.29.2-GA
lombok 1.18.30
druid 1.2.4 → 1.2.8
mysql-connector-j → 8.1.0 mysql artifactId 变更
---
maven-compiler-plugin 3.8.1 → 3.11.0
maven-gpg-plugin 3.0.1 → 3.1.0
maven-source-plugin 3.2.1 → 3.3.0
maven-javadoc-plugin 3.2.0 → 3.6.0
maven-jar-plugin 3.2.0 → 3.3.0
maven-surefire-plugin 2.22.2 → 3.1.2
license-maven-plugin 2.0.0 → 2.2.0
sonar-maven-plugin 3.7.0.1746 → 3.10.0.2594
versions-maven-plugin 2.7 → 2.16.1
git-commit-id-plugin 2.1.5 → 6.0.0（groupId变化）
errcode-maven-plugin -→ shoulder-maven-plugin
maven-resources-plugin 3.0.2 → 3.3.1
maven-archetype-plugin 3.2.0 → 3.2.1
archetype-packaging 3.2.0 → 3.2.1

0.6 （2021-5-21）

0.6 版本主要致力于基本能力的完善，也是标志着基本使用方式确定，具体的实现可能有部分调整，方向不再大幅变动。

上下文工具类很早就提交了，但一直未支持使用，但模块中又依赖上下文，因此上下文进行重构，准备落地使用

操作日志在 0.1 添加了，0.5 对其进行了调整，0.6 中将结合实际使用情况，进行调整，并添加基本实现，重构定义部分接口，如operationLogger接口，使其更符合整体的设计，提升扩展性和易用性。

加解密部分代码规范性重构：密钥协商可以定制协商 / 加密算法、允许增删支持的算法；优化api更易于使用；符合http规范；

  • 依赖升级

    • spring boot: 升级到 2.4.5

    • spring cloud: 升级到 2020.0.2

    • 其他依赖小版本升级

  • 接口文档选型

    • 注解同时支持 swagger3（主）/swagger2

    • 注释支持 smartDoc

    • 可视化界面默认使用 knife4j

  • core:

    • 错误码，默认日志级别调整为 ERROR

    • 使用 AppContext 作为变量共享中心，且支持自动跨线程

    • 新增 instanceId 获取，并添加两种可选的方式（配置 / from redis），集群模式自动切换

    • DelayTask 现在默认自动开启

    • 新增线程池增强器接口，可以在这里定义全局线程增强

    • 响应中增加错误上下文（在 ext 扩展字段中）

    • 错误码

      • 目前不推荐错误码与 log 级别 / HTTP 响应码绑定

      • 新增错误码插件，在编译时，自动根据注释生成错误码文档，供项目使用

    • i18n

      • 消除启动时因个性化设置后且 baseFilePath 中包含 '*' 且文件不存在时的堆栈打印提醒

      • 结合世界国际化组织标准增加跨地域上下文以增强多语言、全球化能力

    • 增加日期转换器格式

    • JsonUtil 反序列化日期支持格式增加，允许复用 core 中的枚举解析器反序列化枚举

    • 新增 guid 标准接口，自动注入 guid 生成器

  • 操作日志框架重构

    • 日志上下文增加语法糖方法

    • 包结构重构

    • DTO添加更多常用字段，记录更详细，如用户端特征UA

    • logger 增加 bufferedLogger，优化以 HTTP / MQ / Jdbc 形式记录日志的频繁写入性能

    • 当 @OperationLog 所在方法抛出异常时，若为 ErrorCode 及其子类，则自动记录错误码

      • 更换跨线程增强方式，使用 shoulder-core 中定义的扩展点，提高 shoulder 框架内聚

  • db

    • 模板类重构

      • 包路径变更 org.shoulder.data.mybatis.base → org.shoulder.data.mybatis.template

      • 泛型要求调整

    • 确定依赖 mybatis-plus（其新分页插件存在5个月无法使用的bug修复）

    • 增加 mybatis-plus 扩展方法，如针对 bizId 的（实验性功能）

  • web

    • 默认的 RestController 全局异常处理仅对 json 格式响应支持

    • 引入 字典、标签 通用功能暂时放置于 web（实验性功能）

    • 引入依赖于 db 的通用 controller 实现快速开接口（实验性功能）

  • validate

    • 通用错误码提供枚举类

    • 首次引入动态校验规则

  • crypto

    • 对称加解密较大重构（最后一个参数为 明文/密文），使用接口，而非静态工具类

    • 统一参数位置，统一使用方法的最后一个参数作为待处理的明文/密文

    • 密钥协商

      • 完善协商协议，不再是固定使用最高银行加密级别 AES256 CBC，而是根据协商双发都支持的算法随机选择（可自行替换成安全性更低地以获得更高的性能）

      • 修改协商请求头前缀为 "X-S-"

  • 扩展模块

    • 引入扩展模块

    • 后台配置：ext-config 开箱即用的轻量级配置管理模块（实验性功能）

      • 后续引入动态表单：动态字段展示样式（实验性功能）

  • starters

    • 完善一些自动配置的提示

    • 引入 shoulder-starter-mysql 快速对接 mysql

    • 允许监听 redis 重连、集群变更等事件

0.5 （2020-12-6）

更新内容较多：拓展新功能，维护已有模块的设计，对接错误码等规范，修复多个缺陷。

亮点：

  • 分布式id生成器性能提升（魔改雪花算法吊打各家实现）

  • 基于SpringSecurity 安全的认证，该版本已经稳定，且实现了部分默认配置。目前支持 session / common token / jwt / jwk。

  • 分布式锁（兼容jdk接口：可重入的redis实现，兼顾嵌套事务的数据库实现）

  • 快速接入批量业务

  • 操作日志框架支持嵌套调用（参考了 Spring 的事务传播）

主要改动

  • 批量业务抽象支持

    • csv / excel 解析

    • 批量校验、查询进度、导入、查询进度、查询导入历史、导入详情

    • 导出

  • 全局id生成器

    • 性能提升

    • 增加透支消费上限配置、智能阻塞

    • 超高压力下识别缓存buffer过度消费（只在单节点亿级/s以上的压测中才可能出现）

  • web

    • 全局异常拦截：现在会对 JSR303 校验框架抛出的异常做详细日志记录以及返回值封装

    • 日志记录：支持记录 MultiPartFile 类型参数信息

  • 校验框架

    • 参数相关错误码移动至 validate

    • 提供默认翻译项（通过插件生成）

    • @MimeType 改为 @FileType 并增加更多校验能力

      • 文件类型检查从 mime 类型，改为后缀名 allowList → allowSuffix

      • 增加对文件头的检查

      • 增加对文件大小的检查

        • 增加对文件名称格式限制检查（支持正则，包含允许字符检查、禁止字符检查）

        • 增加对批量文件上传校验支持

  • 日志框架

    • 为 debug、info、warn 级别增加类似 errorWitErrorCode 的方法，支持更低级别打印错误码

    • core 中提供 LogHelper 用于生成方法栈目标栈的跳转链接（从 http 的 HttpLogHelper 迁移）

  • 优化基础包中的非必选强依赖

    • 如 spring，降低最小使用依赖成本

  • 默认使用 Undertow 而非 Tomcat

    • 取消各个模块对 tomcat 的依赖

    • 注意 undertow 不支持 jsp

    • 废弃该需求，不实现：默认 tomcat、若希望使用 undertow 使用者自行排除即可

  • 分布式锁

    • 提供锁的概念、接口定义

    • 默认实现

      • JDK 适配（非分布式）

      • 基于内存（伪分布式，默认）

      • 基于数据库（依赖了数据库则默认使用该方式）

      • 基于 Redis

  • 加解密

    • 修复本地存储加解密中-文件存储-未配置存储路径时未能正确新建

    • 本地存储加解密中-文件存储-支持多个工程同时启动且共享一个文件

    • 本地存储加解密中-文件存储-内容为空（如手动清空，但不删除该文件）导致的加载失败

    • 修复密钥交换流程错误bug

    • 密钥交换流程增加额外处理：服务器缓存意外失效后，客户端自动清理无效缓存并重新发起协商（如 redis 宕机重启，且恰好服务端密钥交换缓存丢失，而客户端密钥交换缓存还在）

    • 删除加解密门面接口，因为可能未使用所有加密方式

    • 默认项目启动后，异步初始化本地加解密，以提升第一次调用性能

  • 安全与认证

    • 提供 Token 认证方式默认实现和装配

    • 完善 session 认证中条件装配

    • 添加基于 Session 认证 Demo

    • 添加基于 Token 认证 Demo

  • 验证码框架

    • 支持一个 url 需要校验多种验证码

  • 操作日志框架

    • 支持加了该注解的方法 A 中调用 加了该注解的方法 B 时

    • 支持自定义业务传播行为（日志上下文创建策略），接口：OperationContextStrategy

    • 调整日志上下文的包名、创建器类名 OperationLogBuilder → OperationLogFactory

0.4 （2020-11-2）

  • 提供 starters

    • mysql

  • 全局唯一标识生成器（分布式全局id）

    • 高性能可配置的全局递增唯一 id 生成器（单节点持续高压场景为 twitter 雪花算法两百万倍+、JDK UUID的百倍+！、百度开源算法的 60 倍！）。

    • 优雅处理时钟回拨，支持突发峰值、持续高压，支持扩展

    • todo 多实例小场景、分布式默认装配

  • operation-log 模块

  • 完善安全认证实现

    • 重构安全认证模块

    • 支持自签 Oauth2 JWT Token 授权

    • session 支持集群模式

    • security 的全局异常处理器

    • successHandler 同时支持 session、token（TokenAuthenticationSuccessHandler）

  • 接口响应自动包装支持配置排除路径

  • 框架异常整理

    • 供使用者直接使用的工具

    • 抛出带错误码的 RuntimeException

  • 翻译支持spring原生用法、增加识别jar内多语言资源文件夹

  • 增加 maven archetype，便于快速创建工程

0.3 （2020-9-25）

  • 数据库功能增强：分页、自动补充创建者、修改者、创建时间、修改时间

  • 更简单的服务间安全传输(基于 ECDH，jdk15中才加的功能，shoulder已经在jdk8中实现，且为Spring Boot 提供了开箱即用的能力)

  • 增加 ColorStringBuilder，方便构建彩色输出

  • 优化新增自动日志与美化（自动区分本地和生产环境）

    • HTTP 接口自动记录日志支持单行格式

    • 自动记录 RestTemplate 接口调用，默认支持彩色和单行两种

    • 重构日志自动记录类关系，便于二次扩展，自定义日志规则（如某些用户记录、特定请求记录等）与格式

  • 完善安全认证实现，browser 可用

  • 完善验证码框架，可用

  • 增加监控模块（线程池监控、错误码、异常监控），基于 micrometer，可使用 Prometheus 等对接

  • 升级依赖 Spring Boot→ 2.3.4, Cloud→ H.S8，修复 RFD 漏洞

  • 废弃 trace、minio、aopx 三个模块，移动至 shoulder-platform 中，Spring 高级特性使用保留原生用法

0.2 （2020-9-10）

  • 数据库功能支撑

    • 连接池选型为 beeCP，近似 spring boot 默认连接池两倍性能

    • 引入 mybatis-plus 增强 mybatis

    • 数据源动态切换

  • 更舒服的控制台日志（针对开发阶段、基于色彩学，DEBUG=淡灰色；INFO=控制台默认色；Warn=蓝色；异常/Error=粗体、红色；行号：蓝色；线程名称/线程id/时间=跟随日志级别）

  • JSON 工具支持自动扩展

  • 新增http接口自动记录日志 Controller日志

    • 开发阶段更好的调试体验

    • 支持IDE点击打印日志，自动跳转代码位置

  • 可监控、动态调整的线程池

    • 可实现负载告警、动态扩容、资源释放、执行统计

  • 将 spring-web 日志级别提高为INFO，防止无用日志过多

  • 添加监控对接技术方案

  • 已知问题

    • 版本号不正确（snapshot）

    • 签名异常

0.1 （2020-8-5）

首次发布，将大多数基本功能测试并发布

这些内容均可在开源仓库可见