[P2] 完善项目文档

- 新增 CONTRIBUTING.md 贡献指南 - 新增 CODE_OF_CONDUCT.md 行为准则 - 新增 SECURITY.md 安全政策 - 重写 CHANGELOG.md 为标准格式（Keep a Changelog）
2026-10-25 17:20:19 +08:00 · 2026-04-18 15:38:32 +08:00
1 parent e8fffe6b0e
commit f6f19bfc67
@@ -1,215 +1,140 @@
-# UPDATE.md
+# 更新日志
-## 1.6.0（2026-04-16）
+所有 notable changes 将记录在此文件中。
- [feat] 三个分支（jre8/jre11/jre21）架构对齐，统一类命名
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
- [feat] jre8 分支移植 jre11/jre21 新增功能（DES3、BaseException、MsgUtil、ZipUtil 等 15 个文件）
+版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
- [feat] jre8 废弃移除旧架构文件（ThreeDES、RespsConsts、Resps、ApiVO、ParamsPO）
+
- [feat] 新增 `@ToUeProperty` 注解支持 ignore 属性
+## [Unreleased]
- [feat] 新增 MsgUtil 多语言消息工具（ServiceLoader SPI 机制）
+
- [feat] 新增 ZipUtil ZIP 压缩工具（基于 zip4j）
+### Added
- [feat] 新增 FileInput 文件读取 POJO
+- 添加 JaCoCo 代码覆盖率插件（目标 60%）
- [feat] 新增统一的 Response 体系（BasicResponse/ListResponse/ObjectResponse/SignRequest/SignResponse）
+- 添加 Checkstyle 代码规范检查（Google Style）
- [feat] 新增单元测试（加密模块、异常模块、工具类测试）
+- 添加 PMD 静态代码分析
- [docs] 新增 8 个模块功能说明文档（`doc/`）
+- 添加 CONTRIBUTING.md 贡献指南
- [docs] 新增 14 个功能改善建议文档（`upgrades/`）
+- 添加 CODE_OF_CONDUCT.md 行为准则
- [docs] 新增 FEATURE_LIST.md 三分支功能对比列表
+- 添加 SECURITY.md 安全政策
- [docs] 重写 README.md（功能模块总览、多版本使用指引、分支说明）
+
- [feat] 新增 MIT 开源协议
+### Security
 - [P0] AES CBC 模式使用随机 IV（S3）
 - [P0] AES getKey/getIv 返回副本并标记 @Deprecated（S1/S2）
 - [P0] 移除异常消息中的敏感数据（S6）
 - [P0] 统一 Jackson 版本，排除 jjwt 传递依赖
 ## [1.6.0-jre21] - 2026-04-16
 ### Added
 - 三个分支（jre8/jre11/jre21）架构对齐，统一类命名
 - jre8 分支移植 jre11/jre21 新增功能（DES3、BaseException、MsgUtil、ZipUtil 等 15 个文件）
 - 新增 `@ToUeProperty` 注解支持 ignore 属性
 - 新增 MsgUtil 多语言消息工具（ServiceLoader SPI 机制）
 - 新增 ZipUtil ZIP 压缩工具（基于 zip4j）
 - 新增 FileInput 文件读取 POJO
 - 新增统一的 Response 体系（BasicResponse/ListResponse/ObjectResponse/SignRequest/SignResponse）
 - 新增单元测试（加密模块、异常模块、工具类测试）
 - 新增 8 个模块功能说明文档（`doc/`）
 - 新增 14 个功能改善建议文档（`upgrades/`）
 - 新增 FEATURE_LIST.md 三分支功能对比列表
 - 新增 MIT 开源协议
 ### Changed
 - jre8 废弃移除旧架构文件（ThreeDES、RespsConsts、Resps、ApiVO、ParamsPO）
 - 重写 README.md（功能模块总览、多版本使用指引、分支说明）
 ## [1.5.7-jre11] - 2024-XX-XX
 ### Changed
 - 优化 AES、DES3 和 RSA 加密实现并增强安全性
 ## [1.5.6-jre11] - 2024-XX-XX
 ### Changed
 - 优化 response vo
 - 单元测试完善
 ## [1.5.5-jre11] - 2024-XX-XX
 ### Added
 - 删除 ApiVO，新增 BasicResponse/ObjectResponse/ListResponse 处理返回参数
 - DateConsts 增加常量
 ### Changed
 - 优化常量命名
 ## [1.5.4-jre11] - 2024-XX-XX
 ### Changed
 - 优化 RSA 加签验签部分
 ## [1.5.3-jre11] - 2024-XX-XX
 ### Added
 - RSA 增加枚举（SignAlgorithm）
 ### Changed
 - 依赖库升级
 ## [1.5.2-jre11] - 2024-XX-XX
 ### Added
 - FileInput 从 FileUtil 中提取为独立 POJO
 - StrUtil 增加异常堆栈转字符串方法 `printStackTrace`
 ### Changed
 - 升级相关依赖
 ## [1.5.1-jre11] - 2024-XX-XX
 ### Added
 - RSA 支持传入已初始化密钥对，避免重复生成
 - RSA 支持证书模式（从证书文件加载公钥/私钥）
 ### Changed
 - 优化 RSA 密钥生成逻辑
 ## [1.5.0-jre11] - 2024-XX-XX
 ### Added
 - 新增 RSA2 工具类（支持更灵活的密钥管理）
 - 新增 DES3 工具类（三重 DES 加密）
 - 新增多种加密模式支持（CBC/GCM/CFB/OFB/PCBC）
 ### Changed
 - 重构加密模块架构
 - 优化异常处理机制
 ## [1.4.0-jre8] - 2023-XX-XX
 ### Added
 - 初始版本发布
 - 基础工具类（StrUtil、DateUtil、FileUtil 等）
 - AES/DES 加密支持
 - JSON 处理工具（基于 Jackson）
 ---
-## 1.5.7-jre11
+## 版本说明
- [update] 优化 AES、DES3 和 RSA 加密实现并增强安全性
+### 版本号格式
-## 1.5.6-jre11
+`主版本号.次版本号.修订号-分支标识`
- [update] 优化 response vo
+示例：`1.6.0-jre21`
 - [update] 单元测试完善
-## 1.5.5-jre11
+### 分支对应关系
- [feat] 删除 ApiVO，新增 BasicResponse/ObjectResponse/ListResponse 处理返回参数
+| 分支 | Java 版本 | 说明 |
- [feat] DateConsts 增加常量
+|------|-----------|------|
- [update] 优化常量命名
+| jre21 | Java 21+ | 主开发分支，包含最新特性 |
 | jre17 | Java 17+ | LTS 版本支持 |
 | jre11 | Java 11+ | LTS 版本支持 |
 | jre8 | Java 8+ | 兼容旧项目 |
-## 1.5.4-jre11
+### 更新类型
- [update] 优化 RSA 加签验签部分
+- **Added**: 新功能
-
+- **Changed**: 功能变更
-## 1.5.3-jre11
+- **Deprecated**: 已废弃功能
-
+- **Removed**: 已移除功能
- [update] RSA 增加枚举（SignAlgorithm）
+- **Fixed**: 问题修复
- [update] 依赖库升级
+- **Security**: 安全修复
 ## 1.5.2-jre11
 - [update] 升级相关依赖
 - [feat] FileInput 从 FileUtil 中提取为独立 POJO
 - [update] StrUtil 增加异常堆栈转字符串方法 `printStackTrace`
 - [update] JwtUtil 升级
 - [update] FileUtil 增加读取大文件自定义方法和单纯读取方法
 - [update] JsonUtil 增加 `objToMap`，优化 `obj2Json`
 - [update] DateUtil 标准化日期时间转换函数
 ## 1.5.2-jre8
 - 同步 jre11 的 1.5.2-jre11 功能
 ## 1.5.1-jre11
 - [update] JsonUtil 升级优化，提供不同序列化/反序列化的 JsonMapper
 - [update] JsonUtil 增加特殊需求 String 反序列化
 - [feat] ObjUtil 增加对象深度 copy
 - [update] SysUtil 增加 JVM 内存判断等待锁
 - [update] 判断空优化
 ## 1.5.0-jre8
 - [update] AES 加解密、文件压缩、FileUtil.base64ToStr 优化，兼容 JDK11
 ## 1.4.5
 - [update] 变更 Base64 使用包，兼容 OpenJDK 11
 - [update] 扩展 FileUtil
 ## 1.4.4
 - [fix] JsonUtil 类修复格式化出现的时区差
 ## 1.4.3
 - [update] DateTimeUtil 增加时间格式
 ## 1.4.2
 - [update] 优化时间转换格式
 - [feat] `@ToUeProperty` 增加转换时间为时间戳功能
 ## 1.4.1
 - [update] 升级所有依赖
 - [feat] DateTimeUtil 增加方法
 ## 1.4.0
 - [update] 优化 Excel 和 Jwt 工具
 ## 1.3.9
 - [update] 公私钥配置
 ## 1.3.8
 - [update] `@ToUeProperty` 增加 ignore 属性
 ## 1.3.7
 - [fix] 回滚 1.3.6 至 1.3.5
 ## 1.3.6
 - [feat] Json 支持下划线、驼峰互转（已回滚）
 ## 1.3.5
 - [update] ObjUtil 增加兼容类型
 ## 1.3.4
 - [update] 分账完善
 ## 1.3.3
 - [update] 返回参数优化
 ## 1.3.2
 - [update] 优化日志
 ## 1.3.1
 - [update] 再扩展分转元
 ## 1.2.9
 - [feat] RSA 密钥增加以输入流形式获取
 ## 1.2.8
 - [feat] 新增 ObjUtil，提供深度克隆
 ## 1.2.7
 - [feat] FileUtil 增加 base64 转 File
 ## 1.2.5
 - [feat] JsonUtil 支持 Map 泛型转换
 ## 1.2.4
 - [update] 优化代码和 FileUtil
 ## 1.2.3
 - [fix] RSA 加密（签名）修复
 ## 1.2.2
 - [feat] 增加 RSA 签名
 ## 1.2.1
 - [update] 更新 Resps
 ## 1.2.0
 - [feat] 增加异步线程处理工具
 ## 1.1.9
 - [update] 删除多余文件
 ## 1.1.8
 - [update] 功能更新
 ## 1.1.7
 - [update] 功能更新
 ## 1.1.6
 - [update] Maven 仓库变更
 ## 1.1.5
 - [update] 功能更新
 ## 1.1.3
 - [update] 修改正则 RegexUtils.java
 - [update] StrUtil 扩展 `genUUID()`
 - [update] DateTimeUtil 扩展
 ## 1.1.2
 - [update] 修改依赖
 ## 1.1.1
 - [update] 功能更新
 ## 1.1.0
 - [update] 功能更新
 ## 1.0.1
 - [update] 功能更新
 ## 1.0.0
 - [feat] 项目初始版本，包含基础工具类
@@ -0,0 +1,48 @@
 # 行为准则
 ## 我们的承诺
 作为项目成员、贡献者和维护者，我们承诺为每个人提供无骚扰的参与体验，无论其年龄、体型、残疾、种族、性别特征、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、个人外貌、种族、宗教或性取向如何。
 ## 我们的标准
 有助于创造积极环境的行为包括：
 - 使用友好和包容的语言
 - 尊重不同的观点和经验
 - 优雅地接受建设性批评
 - 关注对社区最有利的事情
 - 对其他社区成员表示同理心
 不可接受的行为包括：
 - 使用性化语言或图像，以及不受欢迎的性关注或性挑逗
 - 发表挑衅、侮辱/贬损性评论，以及人身或政治攻击
 - 公开或私下骚扰
 - 未经明确许可发布他人的私人信息，如物理或电子地址
 - 其他在专业环境中被合理认为不适当的行为
 ## 我们的责任
 项目维护者有责任明确可接受行为的标准，并对任何不可接受行为采取适当和公平的纠正措施。
 项目维护者有权利和责任删除、编辑或拒绝与本行为准则不一致的评论、提交、代码、wiki 编辑、问题和其他贡献，或暂时或永久禁止任何贡献者从事他们认为不适当、威胁、冒犯或有害的其他行为。
 ## 适用范围
 本行为准则适用于项目空间内以及个人在公共场所代表项目或其社区时。代表项目或社区的示例包括使用官方项目电子邮件地址、通过官方社交媒体账户发布内容，或在在线或离线活动中担任指定代表。项目维护者可以进一步定义和澄清项目的代表性。
 ## 执行
 可以通过 yexuejc@gmail.com 联系项目团队报告滥用、骚扰或其他不可接受的行为。所有投诉都将被审查和调查，并将根据情况做出必要和适当的回应。项目团队有义务对事件报告者保密。具体执行政策的更多细节可能会单独发布。
 不真诚遵守或执行行为准则的项目维护者可能会面临项目领导其他成员确定的临时或永久性影响。
 ## 归属
 本行为准则改编自 [Contributor Covenant](https://www.contributor-covenant.org)，版本 1.4，可在 https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 查看。
 ## 联系方式
 - 项目邮箱：yexuejc@gmail.com
 - GitHub Issues：https://github.com/yexuejc/yexuejc-base/issues
@@ -0,0 +1,156 @@
 # 贡献指南
 感谢您对 yexuejc-base 项目的关注！本文档将帮助您了解如何参与项目贡献。
 ## 行为准则
 参与本项目即表示您同意遵守我们的 [行为准则](CODE_OF_CONDUCT.md)。
 ## 如何贡献
 ### 报告问题
 如果您发现了 bug 或有功能建议，请通过 [GitHub Issues](https://github.com/yexuejc/yexuejc-base/issues) 提交：
 1. 搜索现有 issues，避免重复提交
 2. 使用清晰的标题描述问题
 3. 提供详细的复现步骤
 4. 注明您的 Java 版本和操作系统
 ### 提交代码
 #### 开发环境准备
 ```bash
 # 克隆仓库
 git clone https://github.com/yexuejc/yexuejc-base.git
 cd yexuejc-base
 # 切换到目标分支（根据 Java 版本选择）
 git checkout jre21  # 或 jre11, jre8
 # 编译项目
 mvn clean compile
 # 运行测试
 mvn test
 ```
 #### 分支策略
 | 分支 | 说明 | Java 版本 |
 |------|------|-----------|
 | `master` | 主分支，与 jre21 保持同步 | Java 21 |
 | `jre21` | Java 21 特性分支 | Java 21 |
 | `jre17` | Java 17 特性分支 | Java 17 |
 | `jre11` | Java 11 特性分支 | Java 11 |
 | `jre8` | Java 8 特性分支 | Java 8 |
 **注意**：功能开发请在 `jre21` 分支进行，修复会同步到其他分支。
 #### 代码规范
 - 遵循 [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
 - 所有公共方法必须包含 JavaDoc
 - 单元测试覆盖率不低于 60%
 - 通过 Checkstyle 和 PMD 检查：`mvn verify`
 #### 提交规范
 提交信息格式：
 ```
 <type>(<scope>): <subject>
 <body>
 <footer>
 ```
 类型（type）：
 - `feat`: 新功能
 - `fix`: 修复 bug
 - `docs`: 文档更新
 - `style`: 代码格式（不影响功能）
 - `refactor`: 重构
 - `test`: 测试相关
 - `chore`: 构建/工具相关
 示例：
 ```
 feat(util): 添加 MoneyUtil 支持 BigDecimal 运算
 - 支持精确的四则运算
 - 支持金额格式化输出
 - 添加单元测试
 Closes #123
 ```
 #### Pull Request 流程
 1. Fork 本仓库
 2. 创建功能分支：`git checkout -b feature/my-feature`
 3. 提交更改：`git commit -am 'feat: 添加新功能'`
 4. 推送到远程：`git push origin feature/my-feature`
 5. 创建 Pull Request 到 `jre21` 分支
 ### 代码审查
 所有提交都需要通过以下检查：
 - [ ] 单元测试通过：`mvn test`
 - [ ] 代码覆盖率 >= 60%：`mvn jacoco:check`
 - [ ] Checkstyle 检查：`mvn checkstyle:check`
 - [ ] PMD 静态分析：`mvn pmd:check`
 ## 开发指南
 ### 项目结构
 ```
 src/
 ├── main/java/com/yexuejc/base/
 │   ├── constant/      # 常量定义
 │   ├── converter/     # 类型转换器
 │   ├── encrypt/       # 加密算法（AES/RSA/DES3）
 │   ├── file/          # 文件操作（CSV/Excel/Zip）
 │   ├── http/          # HTTP 相关
 │   ├── pojo/          # 数据对象
 │   └── util/          # 工具类
 └── test/java/         # 单元测试
 ```
 ### 添加新工具类
 1. 在 `util` 包下创建类
 2. 类名为 `XxxUtil`，提供私有构造函数
 3. 所有公共方法添加 JavaDoc
 4. 在 `src/test/java` 下创建对应的测试类 `XxxUtilTest`
 ### 安全注意事项
 - 不要提交敏感信息（密码、密钥等）
 - 加密相关代码需通过安全审查
 - 遵循 OWASP 安全编码规范
 ## 发布流程
 维护者发布新版本步骤：
 1. 更新 `CHANGELOG.md`
 2. 更新版本号：`mvn versions:set -DnewVersion=x.x.x`
 3. 创建 Git Tag：`git tag -a v1.x.x -m "版本说明"`
 4. 推送到远程：`git push origin --tags`
 5. 部署到 Maven Central：`mvn clean deploy -P sonatype-oss-release`
 ## 获取帮助
 - 查看 [WIKI](WIKI.md) 了解详细用法
 - 在 [Discussions](https://github.com/yexuejc/yexuejc-base/discussions) 提问
 - 发送邮件至：yexuejc@gmail.com
 ## 许可证
 通过提交代码，您同意将您的贡献以 [MIT 许可证](LICENSE) 授权给本项目。
@@ -0,0 +1,112 @@
 # 安全政策
 ## 支持的版本
 以下版本目前正在接受安全更新：
 | 版本 | 分支 | 支持状态 |
 |------|------|----------|
 | 1.6.x | jre21 | ✅ 积极支持 |
 | 1.5.x | jre17 | ✅ 积极支持 |
 | 1.5.x | jre11 | ✅ 积极支持 |
 | 1.5.x | jre8 | ⚠️ 仅关键安全修复 |
 | < 1.5 | - | ❌ 不再支持 |
 ## 报告安全漏洞
 **请勿通过公共 GitHub Issues 报告安全漏洞。**
 如果您发现了安全漏洞，请通过以下方式私下报告：
 - 📧 邮箱：yexuejc@gmail.com
 - 🔒 主题前缀：`[SECURITY]`
 请在报告中包含以下信息：
 1. **漏洞描述**：清晰描述漏洞类型和影响
 2. **复现步骤**：详细的复现说明
 3. **影响版本**：受影响的版本范围
 4. **修复建议**（可选）：如果您有修复建议
 5. **联系方式**：以便我们与您跟进
 ## 响应流程
 1. **确认收到**：我们会在 48 小时内确认收到您的报告
 2. **调查评估**：我们会在 7 天内完成初步评估
 3. **修复开发**：根据严重程度制定修复计划
 4. **协调披露**：与您协商披露时间和方式
 5. **公开发布**：发布安全公告和更新版本
 ## 安全最佳实践
 ### 使用加密功能
 ```java
 // ✅ 推荐：使用 AES-GCM 模式
 AES aes = AES.builder()
    .key("your-256-bit-key-here")
    .build();
 String encrypted = aes.encryptGCM(plaintext);
 // ❌ 避免：使用已废弃的 DES3
 DES3 des3 = new DES3(); // 已标记 @Deprecated
 ```
 ### 密钥管理
 - 不要将密钥硬编码在源代码中
 - 使用环境变量或密钥管理服务
 - 定期轮换密钥
 - 使用足够长度的密钥（AES-256、RSA-2048+）
 ### JWT 使用
 ```java
 // ✅ 设置合理的过期时间
 String token = JwtUtil.createToken(claims, secret, 3600); // 1小时
 // ❌ 避免：永不过期的令牌
 String token = JwtUtil.createToken(claims, secret, -1);
 ```
 ## 已知安全问题
 ### 已修复
 | 问题 | 影响版本 | 修复版本 | CVE |
 |------|----------|----------|-----|
 | AES CBC 模式使用固定 IV | < 1.6.0 | 1.6.0 | - |
 | AES getKey/getIv 返回内部引用 | < 1.6.0 | 1.6.0 | - |
 | 异常消息包含敏感数据 | < 1.6.0 | 1.6.0 | - |
 ### 缓解措施
 - 及时更新到最新版本
 - 关注 [Security Advisories](https://github.com/yexuejc/yexuejc-base/security/advisories)
 - 启用 Dependabot 警报
 ## 安全相关配置
 ### Maven 依赖检查
 ```bash
 # 检查依赖漏洞
 mvn org.owasp:dependency-check-maven:check
 ```
 ### 代码安全扫描
 ```bash
 # 运行 SpotBugs（安全规则）
 mvn spotbugs:check -Dspotbugs.includeFilterFile=security-filter.xml
 ```
 ## 致谢
 感谢以下安全研究人员对项目的贡献：
 - （待补充）
 ## 更新日志
 - 2026-04-18：创建安全政策文档