xtools 项目设计文档

开源地址: https://gitee.com/jun-xtools/xtools.git

一、功能和用途

1.1 项目概述

xtools（低调大师工具箱）是一个基于 JDK 25 的 Java 工具库项目，为 Java 应用开发提供通用的工具方法和基础组件支持。

1.2 技术特点

• 采用最新的 JDK 25 版本，充分利用新特性（Record类型、文本块、模式匹配等）
• 基于 JUnit Jupiter 6.0.3 构建单元测试体系
• 使用 Lombok 1.18.44 简化代码编写
• 集成 FastJSON2 2.0.60 实现高性能JSON处理
• 使用 BouncyCastle 1.84 提供国密算法（SM2/SM3/SM4）支持
• 集成 Google ZXing 3.5.4 实现二维码和条形码生成与解析
• 使用 Apache PDFBox 3.0.7 实现PDF文档处理
• 使用 Apache Fesod Sheet 2.0.1-incubating 处理Excel文件
• 集成 mmseg4j-core 1.10.0 实现中文分词
• 支持 AWS S3 SDK 2.42.34 实现对象存储
• 集成 ip2region 3.3.7 实现离线IP地址定位
• 使用 java-jwt 4.5.1 实现JWT令牌生成与验证
• 集成 OSHI 6.11.1 实现系统信息采集
• 使用 Apache Velocity 2.4.1 实现模板引擎功能
• 集成 Jsoup 1.22.1 实现HTML解析和爬虫功能
• 使用 MapStruct 1.6.3 实现对象映射
• 基于 Jakarta Servlet API 6.1.0 提供Web层支持

1.3 核心功能

1.4 功能层次结构

1.5 功能关系图

二、项目结构设计

2.1 整体架构

2.2 模块依赖关系

2.3 模块职责

2.4 包结构设计

xtools
├── xtools-base（基础模块）
│   └── xtools.base
│       ├── exception          # 异常体系
│       │   ├── BaseError      # 错误接口
│       │   ├── BaseErrorModule # 错误模块接口
│       │   ├── CommonException # 通用异常
│       │   └── ExceptionUtils # 异常工具
│       ├── config             # 配置
│       │   └── BaseParams     # 常量接口
│       └── enums              # 枚举
│           ├── ErrorModule    # 错误模块枚举
│           ├── BaseErrorModule # 基础错误模块
│           └── TestError      # 测试错误枚举
│
├── xtools-core（核心工具模块）
│   └── xtools.core
│       ├── encrypt            # 加密工具
│       │   ├── BaseEncryptUtils # 加密基础类
│       │   ├── Base64Utils    # Base64编解码
│       │   ├── Md5Utils       # MD5摘要
│       │   └── Sha1Utils      # SHA1摘要
│       ├── time               # 时间工具
│       │   ├── DateUtils      # Date工具
│       │   ├── LocalDateTimeUtils # LocalDateTime工具
│       │   ├── InstantUtils   # Instant工具
│       │   ├── TimestampUtils # Timestamp工具
│       │   └── CalendarUtils  # Calendar工具
│       ├── sys                # 系统工具
│       │   ├── OsUtils        # 操作系统识别
│       │   ├── BrowserUtils   # 浏览器调用
│       │   ├── CmdUtils       # 命令行执行
│       │   └── SysBaseInfoUtils # 系统信息采集
│       ├── extend             # 扩展工具
│       │   ├── TemplateUtils  # 模板引擎
│       │   ├── PagingUtils    # 分页计算
│       │   ├── UrlUtils       # URL处理
│       │   ├── DistanceUtils  # 距离计算
│       │   ├── RandomUtils    # 随机数生成
│       │   ├── HtmlUtils      # HTML工具
│       │   ├── ExecTimeUtils  # 执行时间统计
│       │   ├── ClassScanner   # 类扫描器
│       │   ├── CheckUtils     # 参数校验
│       │   └── ArithmeticUtils # 数学运算
│       ├── img                # 图像工具
│       │   └── BufferedImageUtils # 图像转换
│       ├── thread             # 线程工具
│       │   ├── ToolThreadFactory # 线程工厂
│       │   └── TimeoutUtils   # 超时控制
│       ├── log                # 日志工具
│       │   └── LogUtils       # 自定义日志
│       ├── sensitive          # 敏感词
│       │   └── SensitiveWordUtils # DFA敏感词过滤
│       ├── dto                # 数据传输对象
│       │   ├── FileInfo       # 文件信息
│       │   ├── RsaDto         # RSA密钥数据
│       │   └── SysBaseInfoDto # 系统信息
│       ├── enums              # 枚举
│       │   ├── CoreError      # 核心错误码
│       │   ├── RegexEnum      # 正则表达式
│       │   ├── TimePattern    # 时间格式
│       │   ├── LogLevel       # 日志级别
│       │   └── OsEnum         # 操作系统枚举
│       ├── ArrUtils           # 数组工具
│       ├── BytesUtils         # 字节数组工具
│       ├── HexUtils           # 十六进制工具
│       ├── CollectionUtils    # 集合工具
│       ├── UuidUtils          # UUID工具
│       └── DtoConversionUtils # DTO转换工具
│
├── xtools-extend（扩展工具模块）
│   └── xtools.extend
│       ├── encrypt            # 国密算法
│       │   ├── Sm2Utils       # SM2非对称加密
│       │   ├── Sm3Utils       # SM3哈希
│       │   ├── Sm4Utils       # SM4对称加密
│       │   └── PkcsUtils      # PKCS填充
│       ├── office             # 文档处理
│       │   ├── PdfUtils       # PDF工具
│       │   ├── WordUtils      # Word工具
│       │   ├── ExcelUtils     # Excel工具
│       │   └── PptUtils       # PPT工具
│       ├── dto                # 数据传输对象
│       │   └── CryptoDto      # 加密数据
│       ├── enums              # 枚举
│       │   └── ExtendError    # 扩展错误码
│       ├── JsonUtils          # JSON工具
│       ├── JwtUtils           # JWT工具
│       ├── CodeUtils          # 二维码/条形码工具
│       ├── AnalyzerUtils      # 中文分词
│       ├── UserAgentUtils     # UserAgent解析
│       └── office             # Office文档工具
│
├── xtools-web（Web工具模块）
│   └── xtools.web
│       ├── xss                # XSS防护
│       │   ├── XssFilter      # XSS过滤器
│       │   ├── XssWrapper     # XSS包装器
│       │   └── XssUtils       # XSS工具
│       ├── enums              # 枚举
│       │   ├── WebError       # Web错误码
│       │   └── HeaderEnum     # HTTP头枚举
│       └── SessionUtils       # Session工具
│
├── xtools-api（API集成模块）
│   └── xtools.api
│       ├── ali                # 阿里云集成
│       │   └── AliEmailUtils  # 邮件发送
│       ├── baidu              # 百度集成
│       │   ├── LocationUtils  # 地理定位
│       │   └── WeatherUtils   # 天气查询
│       ├── dto                # 数据传输对象
│       │   ├── IpAddrDto      # IP地址信息
│       │   ├── LocationDto    # 定位信息
│       │   └── LatAndLngDto   # 经纬度
│       ├── enums              # 枚举
│       │   └── ApiError       # API错误码
│       ├── utils              # 工具
│       │   └── ReqLogUtils    # 请求日志
│       └── config             # 配置
│           └── TestApiConfig  # 测试配置
│
└── xtools-test（测试模块）
    └── xtools.test
        └── BaseTest           # 测试基类

三、项目功能设计

3.1 异常处理体系设计

3.1.1 异常体系架构

3.1.2 异常处理流程

3.1.3 错误码规范

3.2 加密工具设计

3.2.1 加密体系架构

3.2.2 加密工具功能

3.3 时间工具设计

3.4 系统工具设计

3.5 扩展工具设计

3.6 敏感词过滤设计

3.7 XSS防护设计

3.8 文档处理设计

3.9 API集成设计

3.10 测试体系设计

四、编码规范设计

4.1 命名规范

4.1.1 类命名

4.1.2 方法命名

4.1.3 常量命名

4.2 注释规范

4.2.1 类注释格式

/**
 * <p>Title : 类名称</p>
 * <p>Description : 类描述</p>
 * <p>DevelopTools : Idea_x64_v2026.1</p>
 * <p>DevelopSystem : macOS Sequoia 15.7.5</p>
 * <p>Company : org.xujun</p>
 *
 * @author : XuJun
 * @version : 5.0.0
 * @date : 2026/04/16 10:00
 */

4.2.2 方法注释格式

/**
 * 方法描述（中文）
 *
 * @param param 参数说明
 * @return 返回值说明
 */

4.3 代码风格

4.3.1 设计模式

4.3.2 异常处理规范

• 所有checked exception通过CommonException.create()包装为unchecked exception
• 异常消息格式：[module:type-code]formatted message
• 使用{}作为消息模板占位符

4.3.3 序列化规范

• 大多数工具类实现Serializable接口
• 使用@Serial注解标注serialVersionUID

4.3.4 代码结构

• 4空格缩进
• 左大括号同行
• 方法间空行分隔
• 使用implements声明接口实现

4.4 设计规范

4.4.1 分层原则

• xtools-test：零外部依赖，仅依赖JUnit
• xtools-base：基础定义层，不依赖任何业务逻辑
• xtools-core：核心工具层，依赖base
• xtools-extend：扩展工具层，依赖core
• xtools-web：Web专用工具，依赖core
• xtools-api：API集成层，依赖core

4.4.2 单一职责

• 每个Utils类只负责一个功能领域
• 加密工具按算法类型分离（Base64、MD5、SHA1、SM2、SM3、SM4）
• 时间工具按Java时间API类型分离

4.4.3 开闭原则

• BaseEncryptUtils提供protected基础方法，子类可扩展
• BaseError接口定义错误契约，各模块独立实现错误枚举
• ClassScanner支持Predicate<Class<?>>灵活过滤

五、项目依赖设计

5.1 基础依赖

5.2 Apache Commons依赖

5.3 加密与安全依赖

5.4 系统与网络依赖

5.5 文档处理依赖

5.6 媒体与编码依赖

5.7 工具库依赖

5.8 Web依赖

5.9 Maven构建插件

5.10 xtools内部模块依赖

六、技术选型说明

6.1 JDK 25

• 选择原因：使用最新JDK版本，充分利用现代Java特性
• 主要特性：
  • Record类型（用于SensitiveWordUtils.Result等数据载体）
  • 文本块（Text Blocks）简化多行字符串
  • 模式匹配（Pattern Matching）增强类型判断
  • 密封类（Sealed Classes）增强类型安全
  • 虚拟线程（Virtual Threads）提升并发性能
  • 改进的垃圾回收器（ZGC/Shenandoah）

6.2 JUnit Jupiter 6.0.3

• 选择原因：业界标准的Java单元测试框架
• 主要特性：
  • 支持@Test、@DisplayName等注解
  • 支持参数化测试、嵌套测试
  • 强大的断言和假设机制
  • 与BaseTest模板方法模式结合，统一测试输出格式

6.3 BouncyCastle 1.84

• 选择原因：Java平台最全面的加密库，支持国密算法
• 主要特性：
  • 支持SM2（非对称加密）、SM3（哈希）、SM4（对称加密）等国密算法
  • 提供PKCS填充方案
  • 纯Java实现，无本地依赖

6.4 FastJSON2 2.0.60

• 选择原因：高性能JSON处理库
• 主要特性：
  • 高性能序列化/反序列化
  • 支持JSONPath查询
  • 支持JSON模板替换（{{key}}占位符）
  • 支持Base64编码的JSON

6.5 Google ZXing 3.5.4

• 选择原因：业界标准的条码处理库
• 主要特性：
  • 支持QR二维码生成与解析
  • 支持多种条形码格式
  • 支持logo嵌入二维码

6.6 Apache PDFBox 3.0.7

• 选择原因：纯Java的PDF处理库
• 主要特性：
  • PDF转图片（144 DPI）
  • 支持PDF文本提取
  • 无外部依赖

6.7 其他重要依赖版本

文档版本：v1.0
编写日期：2026-04-16
项目版本：5.0.0
父POM版本：xtools-parent:5.0.0
JDK版本：25
维护团队：xujun.org