doc 0.8

.drone.yml

@@ -30,7 +30,7 @@ steps:
       #
       # ========== deploy script ==========
       - bash scripts/prepareRelease.sh
-      - mvn clean deploy -P release -Dmaven.test.skip=true -B -V -T 1.5C -rf :shoulder-archetype-simple
+      - mvn clean deploy -P release -Dmaven.test.skip=true -B -V -T 1.5C
       # ========== deploy script end ==========
       - echo '========FINISHED CICD=========='
 #

CONTRIBUTING.MD

@@ -1,22 +1,23 @@
 # 如何贡献我的源代码
 
- 目前使用 Git 来控制程序版本，如果你想为 `Shoulder Framework` 贡献源代码，请先大致了解 Git 的使用方法。我们目前把项目托管在 `Gitee` 上，任何 Gitee 用户都可以向我们贡献代码。
-
- 参与的方式很简单，
- - `fork` 一份 `Shoulder Framework` 的代码到你的仓库中
- - 修改后提交，并向我们发起`pull request`申请
- - 我们会及时对代码进行审查并处理你的申请并。审查通过后，你的代码将被 `merge` 进我们的仓库中，这样你就会自动出现在贡献者名单里了。
-
- 我们希望你贡献的代码遵循常见的编码规范（如符合阿里巴巴Java编码规范，IDEA中可以选中特定包右键`Reformat Code`），最好附带单元测试代码~
+`Shoulder` 欢迎各类型代码提交，不限于`优化代码格式`、`优化注释/JavaDoc`、`修复 BUG`、`新增功能`
 
- 
-# 导航 
+# 导航
+- [分支管理](#基础知识)
 - [分支管理](#分支管理)
 - [发布流程](#发布流程)
+- [IED实用设置](#IED实用设置)
+
+## 基础知识
 
-这些部分均借鉴了 spring 的策略，并结合其他流行的方式。
+ 目前使用 `Git` 来控制程序版本，如果你想为 `Shoulder Framework` 贡献源代码，请先大致了解 Git 的使用方法。我们目前把项目托管在 `Gitee` 上，任何 Gitee 用户都可以向我们贡献代码。
 
+ 参与的方式很简单，
+ - `fork` 一份 `Shoulder Framework` 的代码到你的仓库中
+ - 修改后提交，并向我们发起`pull request`申请
+ - 我们会及时对代码进行审查并处理你的申请并。审查通过后，你的代码将被 `merge` 进我们的仓库中，这样你就会自动出现在贡献者名单里了。
 
+ 我们希望你贡献的代码遵循常见的编码规范（如符合`阿里巴巴Java编码规范`，IDEA中可以选中特定包右键`Reformat Code`），最好附带单元测试代码~
 
 ## 分支管理
 
@@ -27,18 +28,18 @@
 - 开发分支（开发完毕合并至预发布分支 或 维护分支）
     - 新功能分支命名：
     feature-{issue编号}
-    
+
     - 缺陷修复分支命名：
     bug-{issue编号}
-    
+
     - 重构分支命名：
     refactor-{issue编号}
-    
+
     - 改进分支命名：
     improvement-{issue编号}
 
 - 预发布分支（单人开发时，开发分支与预发布分支为同一分支）
-v{x.y.0}    
+v{x.y.0}
 
 - 发布分支（同 tag）：
 release-v{x.y.z}
@@ -97,7 +98,7 @@ v{x.y.z}.RELEASE
 
 ----
 
-## IED 实用设置
+## IED实用设置
 
 #### 部分代码跳过格式化（spring security dsl）
 IDEA：settings - Editor - Code Style - enable formatter marks in comments
@@ -109,4 +110,4 @@ IDEA 可以为我们自动转化：
 - 勾选 `Transparent native-to-ascii conversion`
 
 gpg 发布错误
-https://blog.csdn.net/u011781521/article/details/130454386
+https://blog.csdn.net/u011781521/article/details/130454386

ROADMAP.MD

@@ -1,5 +1,13 @@
 # Road Map 发展规划
 
+> **shoulder** 复用/优化当前业界成熟的解决方案（站在巨人的肩膀上），将 `开源社区` 中优秀的实现带给使用者，给使用者一个肩膀！
+> 为减少使用者的上手成本，在用法上借鉴了 `Spring Boot`，使用 `Shoulder` 就像使用 `Spring Boot` 的 `starter` 一样简单（开箱即用）！
+
+- 实现上参照了 **[软件优雅设计与开发最佳实践](https://spec.itlym.cn)** 中提到的内容，但没与它完全绑定，仅将该实践方案作为默认实现，实际中可替换、可二次开发。
+- 可制定自己团队/项目的规范，在 **Shoulder** 基础上增加自己个性化部分，即可快速实现自定义规范并获得常用的功能实现。
+
+## 诞生背景
+
 14年spring boot 发布，15年逐渐流行，16年先锋队跟上，后续逐渐普及，2021 年，spring boot 已经成为 web 标配，spring cloud 也逐渐成熟稳定
 
 但 spring boot 是面向所有场景的，实际开发中还有许多需要完善，shoulder 在此之外对 web 开发做了一些简化代码编写，利于工程维护，
@@ -17,6 +25,12 @@ Google 等互联网顶尖公司已经探索 `ServiceMesh` 许久，虽然当前
 
 ----
 
+##  **[软件优雅设计与开发最佳实践](https://spec.itlym.cn)**  是什么
+
+一千开发手里有一千种实践之路，这一千条路中，`平坦的`（开发维护成本低）、`坎坷的`（开发维护成本高） 差别很大，使用业界有成熟的解决方案往往会**事半功倍**！
+为保证 `代码性能` ，降低 `维护成本`、`开发成本`。**Shoulder** 还提供了`技术选型指导`和一定的`开发规范`，带你轻松踏上最佳实践之路！[点击这里可以查看 Shoulder Framework 推荐的开发规约](https://doc.itlym.cn)
+
+
 ## 展望未来
 
 未来提供基础 docker 镜像，只需要依赖很轻的一层用于对接容器 sideCar 约定API 的 jar，中间件/依赖升级通过镜像方式分发。
@@ -29,10 +43,23 @@ Google 等互联网顶尖公司已经探索 `ServiceMesh` 许久，虽然当前
 - 服务治理：服务注册、动态配置、发现、负载均衡、重试、熔断、限流、降级、故障注入、健康检查、实时监控、日志采集、链路追踪、统一应急接入、压测、同城/异地容灾
 ----
 
-计划
+## 计划
 - 生产/压测隔离【DONE】
 - redis6已经发布，有客户端缓存相关涉及，lettuce6.x已经支持，但spring boot 中暂未支持，预计 spring boot 2.5+ 支持【DONE】
 - 启动速度（CRaC，spring boot 3.2 2023.11才支持）、启动预热 https://docs.spring.io/spring-framework/reference/integration/checkpoint-restore.html
 - 默认容器由 alpaquita 替换 alpine，以获得更好的内存管理支持（musl-perf，JDK16后兼容）、支持 Graavl VN
 - redis Lettuce 6.3 修复了redis宕机会导致15分钟不可用（客户端无主动探活，问题链接未释放），netty-transport-native-epoll:4.1.65.Final:linux-x86_64，在 EPOLL 可用时；https://xie.infoq.cn/article/8d5ecb7b1bc9c84a35de43674
 - JDK 21 https://www.oracle.com/java/technologies/downloads/#jdk21-windows
+
+---
+## 技术选型
+
+喜欢引入新的优秀技术，但不盲目追捧，当且仅当有完整的实践方案
+
+- 业界标准或绝对主流
+- 技术先进、可用于生产环境，且容易从原有的主流技术迁移
+
+## 发行版本号说明
+
+采用 [主版本号.次版本号.修订号](https://semver.org/lang/zh-CN)（[MAJOR.MINOR.PATCH](https://semver.org)） 的形式
+

doc/ability-intro.md

@@ -0,0 +1,88 @@
+# 功能介绍
+
+- `Spring Boot`一致的风格和使用体验
+    - maven 工程模块命名为 `Spring Boot` 官方唯一指定风格
+    - 一处配置，处处默认：如字符集、语言、日期格式等，无需 `session.store.cluster=true crypto.store.cluster=true token.store.cluster=true` ，仅需统一指定 `application.cluster=true`，一配置切换至集群模式，无状态化
+    - 约定大于配置，配置生效优先级：`显式模块级配置 > 显式全局级配置 > 模块默认值 > 环境变量 > 系统默认值 > 未设置`）
+    - 体验同`Spring Boot`，就像`Shoulder`不存在一样，只有 `starter` 和几个配置，但节省了巨大工作量。
+-
+- 错误码（契约精神）
+    - 错误可通过错误码溯源，提供表意、传递、追踪机制
+    - 与日志记录、链路追踪、接口契约、消息传递打通，有全局自动化兜底处理机制
+
+- 日志、异常（周到全面的异常设计）
+    - 基于业界标准的日志标准（base on `Slf4j`），无兼容问题，最小化配置、开箱即用，优化内部并发机制，并结合shoulder技术栈提供增强能力
+    - `日志`、`异常`、`错误码` 打通、改造了 `lombok` 源码，提供简化开发注解，极大减少代码量
+    - 统一错误码格式（也支持配置）、规范代码中的错误
+    - 提供错误码实践方案，让 `错误码规范` 不在头疼
+    - 提供全局`异常`、`错误码`处理
+
+- 操作/审计日志（周到全面的溯源审核设计）
+    - 基于注解的使用：一个注解简单上手
+    - 可扩展的输出格式：便于统一日志规范、提供默认推荐格式
+    - 可扩展的目标源：无论是打印日志、保存至数据库、发送至Kafka，ELK等
+    - 可扩展的记录流程：灵活编排记录步骤、动态填充
+    - 日志策略上下文：自定义日志上下文传递方案，借鉴 Spring 的事务传播机制
+    - 自动跨线程支持：异步业务场景，也不需要担心如何将一些变量跨线程传递
+    - 异步与缓存：支持高并发场景异步与批量记录，提高系统的吞吐量
+
+- 国际化与多语言翻译
+    - 丝滑的翻译封装：在 Spring MessageSource 之上，添加了动态获取当前语言的方法
+    - 完善的多语言支持：支持多种多语言文件存放规则，除spring/jdk默认的、以及基于语言标识目录名
+
+- 完备的 session 管理
+    - 包含存储、分析
+
+- 先进完备的加密与安全
+    - 不像其他第三方 jar ，仅提供只提供 `AES\RSA\ECC\SHA\MD5` 等公开算法的实现。`Shoulder`
+      还在这之上提供了`安全` `可靠` `可生产落地` 的方案与实现，如 `多级密钥管理`
+      、`加密算法平滑升级`
+        - 安全本地存储加解密：LocalCrypto，仅本应用/服务可以解密
+        - 可配置的非对称密钥端点：无论是 `RSA`、`ECC` 还是国产化的 `SM2`，通过配置即刻实现切换；设置为集群时，自动将密钥存储转移至redis
+        - 数字摘要算法（哈希算法）、抗抵赖的签名算法
+        - 简化使用的统一接口：不仅仅 byte[] ，也可以 String、Input/OutputStream 的加密
+        - 大数据并行加解密：充分利用计算资源，提升加解密性能
+        - 便于快速上手的门面工具类：只需要知道几个静态方法即可使用
+        - 基于 `ECC`（可替换） 的密钥协商实现，提供了完整的密钥协商逻辑并在 spring boot 中自动激活
+        - 安全传输方案（基于 `注解` ，无感知密钥协商，极简使用）
+
+- 通用业务代码封装
+    - 数据库封装，如枚举与字段转换
+    - 基本业务封装，增删改查系列
+
+- 校验框架
+    - 基于 `JSR` 规范，实现更多常用校验规则
+    - 与异常、错误码、多语言打通，简化开发难度
+    - 包含文件、熟悉、DTO
+
+- WEB 认证 & 安全
+    - 常见 `WEB` 攻击的防御器：CSRF、XSS、SQL Inject
+    - Oauth2 授权
+        - 认证服务器、资源服务器等（扩展 `Spring Security` ）
+    - 充分灵活的认证框架（扩展 `Spring Security` 迁移自 [learn-spring-security](https://gitee.com/ChinaLym/learn-spring-security)）
+    - 灵活可配置的验证码框架：只需一行配置，即可在任意接口增加验证码校验，极大提高代码复用度
+    - 快速实现认证中心：`OAuth2`、`JWT Token` 发放、鉴权、认证、JWK端点、自定义的认证方式、支持 `SSO` 单点登录
+    - 灵活的认证方式切换：一行配置在 Session、集群 Session、Token、JWT Token
+
+- 依赖管理 & 开箱即用
+    - 与 `Spring Boot` 类似，无需再思考引入哪个版本，会不会冲突，`Shoulder` 管理了常用依赖的版本号，如 `spring-boot`、`spring-cloud`、`spring-cloud-alibaba`
+    - 自动依赖，当你引入 `shoulder-starter-web` 不需要再引入 `spring-boot-starter-web` 也不需要担心还要依赖什么
+    - 最小化配置，提供了默认的配置项，自带建议配置。
+    - 配置项支持 `IDE` 的自动提示
+
+- 更多
+    - **Java中性能最高**、灵活配置的**分布式、全局递增、唯一标识生成器（单节点持续高压场景为 twitter 雪花算法**200w倍+**、JDK UUID的 **120倍！**、百度开源算法的近 **60 倍！**）。
+      巧妙处理时钟回拨，突发峰值、持续高压，并支持配置与扩展。
+    - 可扩展的生产级分布式锁：优雅处理持锁宕机、并发加锁、可重入；默认支持数据库（巧妙处理事务可见性）、内存（提供模拟器）、Redis、zookeeper...
+    - 可扩展的延迟任务
+    - 几乎去SQL开发的设计
+    - 类型转换（枚举 - int - String - json 自动互转、各类时间格式互转）
+    - 可动态调节，具备监控能力的线程池
+    - 灵活的多环境配置
+    - 标准可扩展的链路追踪（`Open Tracing`）
+    - 认证、注册、权限管理
+    - 分布式的任务调度
+    - 与 Spring Boot 天衣无缝的自动集成能力
+    - 能力保证可扩展、可监控、可回滚（单独屏蔽下线）
+    - 提供使用demo、部分单元测试：提供优秀的应用案例，懒人可以直接复制代码即可。
+    - **等你探索...**

doc/faq.md

@@ -0,0 +1,20 @@
+# 🔍FAQ & 问题排查指南
+
+## 👀1.确认问题
+**首先** 要确定该能力是否是 `Shoulder` 提供的，不然方向错了，就白忙活啦~ （注：可以通过包路径、类路径来判断~）
+
+`Shoulder` 提供的能力可以参见[功能介绍.md](ability-intro.md)
+
+## 🔥 2.非 Shoulder 问题（主要）
+
+`Shoulder` 自动引入并管理了 `Spring Boot` 的版本，但未屏蔽或改变 `Spring Boot` 用法，一些功能并不是 Shoulder 提供的，Shoulder仅仅是帮你引入咯~
+如 `Spring Boot`、`Spring Cloud` 等优秀第三方库为我们提供了大量能力（致敬），使用这些时可以去看他们官方的一手教程，或到搜索引擎搜索对应关键词。如
+
+- shoulder Web 工程中如何使用添加自己的过滤器、拦截器
+    - 过滤器、拦截器等的基本功能是 `Spring Boot` 提供的，应该搜索 `Spring Boot 自定义过滤器` 而不是 ~~`Shoulder 自定义过滤器`~~
+- shoulder Web 工程中如何访问静态资源文件
+    - web 的基础功能是由`Spring Boot` 提供哒，所以这么搜索会更合适哟~ `Spring Boot 如何访问静态资源文件`
+
+## 🤝 3.Shoulder 自身问题
+
+这类问题比较少，若您发现，请自豪得在 `ISSUE` 或 [向 cn_lym@foxmai.com 发送邮件](mailto:cn_lym@foxmai.com) 告诉我们你发现了一个，我们将收集 & 记录 & 确认问题，若需要解决则会尽快修复问题，感谢您的贡献！

doc/module-intro.md

@@ -0,0 +1,19 @@
+# 源码目录指南 & 模块划分
+
+> 与 spring、spring-boot 的包模块划分、包命名策略相似（简化使用者学习成本）
+
+最外层的 shoulder-build 管理了 shoulder 的构建，包含了三个部分
+
+- **shoulder-dependencies** 负责依赖版本管理
+
+- **shoulder-parent** 是 shoulder 所有功能模块的直接父类，负责管理他们的公共依赖、插件配置等，**使用者也可以直接继承该模块**。
+
+- **shoulder-build** 包含 shoulder 的代码，其下面又按照用途分为两个模块。
+
+    - **shoulder-base**: 基础定义与功能模块，真正实现功能代码，但使用者一般不会直接引入。
+        - **shoulder-xxx**: xxx模块代码（开发时可以把一个模块当作一个工程）。
+        - ...
+
+    - **shoulder-starters**: 带 `Spring Boot` 自动配置的开箱即用模块，并提供 `Shoulder` 功能的默认实现，简化使用者上手难度。
+      - **shoulder-starter-xxx**: xxx模块的自动配置，供使用者直接引入。
+      - ...

pom.xml

@@ -5,7 +5,7 @@
 
     <groupId>cn.itlym</groupId>
     <artifactId>shoulder-framework</artifactId>
-    <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+    <version>0.8</version><!-- shoulder-version -->
 
     <modelVersion>4.0.0</modelVersion>
     <packaging>pom</packaging>

shoulder-archetype-simple/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-framework</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../pom.xml</relativePath>
     </parent>
 

shoulder-archetype-simple/src/main/resources/archetype-resources/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
     </parent>
 
     <groupId>${groupId}</groupId>
@@ -19,7 +19,7 @@
 
     <properties>
         <java.version>17</java.version>
-        <shoulder.version>0.8-SNAPSHOT</shoulder.version><!-- shoulder-version -->
+        <shoulder.version>0.8</shoulder.version><!-- shoulder-version -->
 
         <errorCodePrefix>0x000b</errorCodePrefix>
     </properties>

shoulder-build/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-framework</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../pom.xml</relativePath>
     </parent>
 

shoulder-build/shoulder-base/pom.xml

@@ -6,12 +6,12 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-build</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../pom.xml</relativePath>
     </parent>
 
     <artifactId>shoulder-base</artifactId>
-    <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+    <version>0.8</version><!-- shoulder-version -->
     <packaging>pom</packaging>
 
     <modules>

shoulder-build/shoulder-base/shoulder-api-doc/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../../../shoulder-parent/pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

shoulder-build/shoulder-base/shoulder-batch/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../../../shoulder-parent/pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

shoulder-build/shoulder-base/shoulder-cluster/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../../../shoulder-parent/pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

shoulder-build/shoulder-base/shoulder-core/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../../../shoulder-parent/pom.xml</relativePath>
     </parent>
 

shoulder-build/shoulder-base/shoulder-crypto-negotiation/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../../../shoulder-parent/pom.xml</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

shoulder-build/shoulder-base/shoulder-crypto/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>cn.itlym</groupId>
         <artifactId>shoulder-parent</artifactId>
-        <version>0.8-SNAPSHOT</version><!-- shoulder-version -->
+        <version>0.8</version><!-- shoulder-version -->
         <relativePath>../../../shoulder-parent/pom.xml</relativePath>
     </parent>