# pan-common **Repository Path**: apanlh/pan-common ## Basic Information - **Project Name**: pan-common - **Description**: pan-common是Java Spring Web企业级组件库，通过声明式注解消灭样板代码，内置强大基础工具类底座，配套轻量 HTTP 客户端、JSON 自动适配(Fastjson2/Jackson/Fastjson1)、数据脱敏、国密SM2/SM3/SM4、链式计算及Redis键管理，Java工具集，Spring Boot 2.x / 3.x 兼容，JDK8~21+兼容 - **Primary Language**: Java - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: https://gitee.com/apanlh/pan-common - **GVP Project**: No ## Statistics - **Stars**: 67 - **Forks**: 3 - **Created**: 2023-08-31 - **Last Updated**: 2026-05-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: 工具类, HttpClient, java工具类, 快速开发, Java ## README

### pan-common

**跟 Spring Web 穿一条裤子，企业开发效率拉满** [![Maven](https://badges.mvnrepository.com/badge/com.gitee.apanlh/apanlh-common/badge.svg?label=Maven&selector=2.)](https://mvnrepository.com/artifact/com.gitee.apanlh/apanlh-common) [![License](https://img.shields.io/badge/License-MulanPSL2-blue)](LICENSE) [![JDK](https://img.shields.io/badge/JDK-8→21+-blue)](https://openjdk.org/) [![Gitee Stars](https://gitee.com/apanlh/pan-common/badge/star.svg?theme=dark)](https://gitee.com/apanlh/pan-common/stargazers)

**[📖 打开 Wiki 文档](https://gitee.com/apanlh/pan-common/wikis/%E9%A6%96%E9%A1%B5) · [🚀 快速开始](#-快速开始) · [📚 文档目录](#-文档目录) · [🐛 反馈问题](https://gitee.com/apanlh/pan-common/issues)**

--- ## 📦 这是什么 `pan-common` 是专为 Spring Web 企业项目设计的**注解化组件库** 它不是 Spring 生态全家桶——分布式锁、服务发现、消息队列这些，而是聚焦在请求解析、Redis 键管理、JSON 序列化等等功能，每天都要写的高频场景上消灭样板代码，同时也在往请求/响应加解密、字段级解密这些方向扩展，慢慢把注解驱动这件事做透跟通用工具库的本质区别在于：那些库是你主动调方法干活，它是你加个注解，样板代码直接消失 ```java // 声明式 Redis 键管理——静态常量直接操作，不用手动拼 Key @RegisterRedisKey public class CacheKeys { public static final RedisString PHONE_CODE = RedisKeyBuilder.builder().withKeys("sms", "code").buildString(); } // 业务代码一行完事，RedisTemplate 自动注入 CacheKeys.PHONE_CODE.setForSeconds("13800138000", "123456", 180); ``` ```java // 用户实体一个注解完成手机号脱敏 public class UserVO { @Desensitize(type = DesensitizeType.PHONE) private String phone; } // Controller 直接返回，138****1234 自动输出 @GetMapping("/user") public ResultVO getUser() { return ResultVO.success(userService.getById(1L)); } // 调用脱敏工具类，一行搞定 @GetMapping("/user") public ResultVO getUser() { User user = userService.getById(1L); UserVO userVO = CopyUtils.copy(User, UserVO.class); DesensitizeUtils.desensitize(userVO); // phone 被自动替换为 138****1234 return ResultVO.success(user); } ``` ```java // 链式计算，自动生成表达式 Num.of(1).add(2).mul(3); // 表达式: 1 + 2 * 3, 结果: 9 Num.of(200).percent(15); // 200 的 15% = 30 // 聚合统计——均值、方差、偏度、峰度一把出 NumCollector.of(1, 2, 3, 4, 5).avg(); // 平均值 3 NumCollector.of(1, 2, 3, 4, 5).median(); // 中位数 3 NumCollector.of(1, 2, 3, 4, 5).stdDev(true); // 总体标准差 ``` **相比传统工具库，它更注重与 Spring 生态融合和对复杂业务场景的深度抽象** 例如：声明式注解驱动的 Redis 键管理、统一请求参数封装（支持路径导航）、数据脱敏注解、树结构构建，以及高性能反射缓存（经 JMH 验证，实际场景提升明显），这些设计旨在让开发者写更少、更清晰、更易维护的代码，把精力真正投入到核心业务逻辑中当然，字符串、集合、IO、日期这些基础工具它也有，但那些只是底座项目目前维护 **2.x**（Spring Boot 2.x + javax.servlet）和 **3.x**（Spring Boot 3.x + jakarta.servlet）两个版本，核心功能两边通用，升级只换版本号就行 --- ## ⚡ 与传统工具库核心区别 - **注解驱动，不只有工具方法**：数据脱敏、树结构构建、字段解密、Redis 键管理……声明式注解搞定很多事情，减少大量样板代码 - **深度 Spring 融合**：不只是提供工具方法，而是直接集成到 Spring 生态，例如声明式 Redis 键管理、统一请求参数封装（支持简单路径导航获取）、Redis 序列化器零配置 - **JSON 适配灵活**：自动适配 Fastjson2 / Jackson / Fastjson1，项目用了哪个库它就自动用哪个，Redis 序列化也一样，零配置切换，不强制绑定 - **性能优化**：反射缓存机制经 JMH 验证，比传统反射调用快一个数量级；字符串、集合等高频工具方法也经过针对性重写，实测性能显著提升 - **轻量级 HTTP/FTP 客户端**：基于 `HttpURLConnection` / `JDK11HttpClient` 实现，支持链式构建、 SPI 扩展、 JDK 版本自适应、拦截器链和多种认证，不依赖第三方库 HttpClient 或 OkHttp，体积小巧，FTP 客户端一并提供 - **本地缓存多种策略**：LRU、LFU、FIFO、LIFO、Weak 引用等多种淘汰策略，无外部依赖，简单实现的轻量方案 --- ## ✨ 你能用它干什么 | 场景 | 怎么干 | 省多少事 | |-----------|-------------------------------------------------------------------|---------------------------------| | 数据脱敏 | `@Desensitize` 注解 + `DesensitizeUtils.desensitize()`，手机/身份证/邮箱等脱敏 | 不用再写脱敏工具类 | | Redis 键管理 | `@RegisterRedisKey` 声明键，静态常量直接 set/get | 告别手动拼 Key 和获取 RedisTemplate | | 树结构构建 | `@TreeId`/`@TreeParentId` 注解 + TreeUtils | 不用手写递归 | | 统一请求/响应 | `@RequestVo` 注解 + RequestVO 路径导航 | Controller 参数处理零样板代码 | | HTTP 客户端 | HttpClientBuilder 链式构建，支持拦截器链和多种认证 | 不用引入 Apache HttpClient 或 OkHttp | | FTP 客户端 | Ftp 工具直接操作上传下载 | 不用找第三方 FTP 库 | | 国密算法 | SM2/SM3/SM4 开箱即用，国密合规 | 不用翻 bc 库文档拼参数 | | 本地缓存 | LRU/LFU/FIFO/LIFO/Weak 引用，选策略直接用 | 不用引入 Guava/Caffeine | | JSON 自动适配 | 项目用 Fastjson2/Jackson/Fastjson1，它自动检测切换 | 零配置，不用改代码 | | 反射高性能调用 | 反射缓存优化，JMH 验证提升显著 | 高频场景性能有保障 | | 数值统计计算 | Num / NumCollector 流式计算，均值/方差/偏度/峰度 | 复杂统计代码不用手写 | --- ## 📚 文档目录 - **[Wiki 文档首页](https://gitee.com/apanlh/pan-common/wikis)** - **[Javadoc API](https://apidoc.gitee.com/apanlh/pan-common)** | 分类 | 模块 | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 🍃 Spring 集成 | [Redis 缓存（声明式键管理）](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631403&doc_id=4748393) · [上下文工具](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631404&doc_id=4748393) | | 🌍 Web 工具 | [Servlet 工具](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631406&doc_id=4748393) · [RequestVO](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631408&doc_id=4748393) · [ResultVO](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631407&doc_id=4748393) | | 🔐 加密与算法 | [对称加密](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631411&doc_id=4748393) · [非对称加密](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631415&doc_id=4748393) · [摘要算法](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631412&doc_id=4748393) · [EC 密钥](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631413&doc_id=4748393) · [通用密钥](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631414&doc_id=4748393) | | 🕶️ 脱敏 | [脱敏工具](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631458&doc_id=4748393) | | 🌲 树结构 | [树结构工具](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631512&doc_id=4748393) | | 🌐 网络 | [HTTP 客户端](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631496&doc_id=4748393) · [FTP 客户端](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631494&doc_id=4748393) · [HTTP 参数工具](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631495&doc_id=4748393) | | 💾 缓存 | [本地缓存（LRU/LFU/FIFO/LIFO/Weak）](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631446&doc_id=4748393) | | 🧰 基础工具 | [StringUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631423&doc_id=4748393) · [CollUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631419&doc_id=4748393) · [MapUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631418&doc_id=4748393) · [ArrayUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631417&doc_id=4748393) · [DateUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631454&doc_id=4748393) · [FileUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631482&doc_id=4748393) · [IOUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631487&doc_id=4748393) · [ReflectionUtils](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631501&doc_id=4748393) · [更多...](https://gitee.com/apanlh/pan-common/wikis/首页) | | 📦 数据格式 | [JSON（自动适配三引擎）](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631451&doc_id=4748393) · [XML](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631452&doc_id=4748393) | | 🧮 数值计算 | [Num](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631449&doc_id=4748393) · [NumCollector](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631448&doc_id=4748393) | | 其他 | [ID 生成](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631485&doc_id=4748393) · [随机数](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631498&doc_id=4748393) · [身份证校验](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631520&doc_id=4748393) · [计时器](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631492&doc_id=4748393) · [字节可读性](https://gitee.com/apanlh/pan-common/wikis/pages?sort_id=17631514&doc_id=4748393) · [完整目录](https://gitee.com/apanlh/pan-common/wikis/首页) | --- ## 📋 最近更新 **v2.0.5 / v3.0.5 — 2026-05-14** - **RequestVO 优化**：去掉 fastjson2 内部类直接依赖，新增 `getHeader()`、`getBoolean()`、`getLong()`、`getStrArray()` 等方法，路径导航取值更干净 - **Redis 序列化模块优化**：引入适配器模式，自动检测 Fastjson2/Jackson/Fastjson1 三种引擎切换，支持动态白名单注入 - **JsonUtils 优化**：基于 Provider 模式，不再绑定单一 JSON 库，统一方法命名 `parseObject` / `parseArray` / `parseToMap` - **DateParserUtils 优化**：双层解析（自定义格式 → 内置格式），自动识别 20+ 种常见日期格式 - **[查看完整更新日志 →](https://gitee.com/apanlh/pan-common/blob/master/changelog.md)** - **[查看路线图 →](https://gitee.com/apanlh/pan-common/blob/master/%E9%A1%B9%E7%9B%AE%E8%B7%AF%E7%BA%BF%E5%9B%BE.md)** --- ## 📦 添加依赖 **Maven** ```xml com.gitee.apanlh apanlh-common 2.0.5 com.gitee.apanlh apanlh-common 3.0.5 ``` --- **Gradle** ```gradle // 2.x implementation 'com.gitee.apanlh:apanlh-common:2.0.5' // 3.x implementation 'com.gitee.apanlh:apanlh-common:3.0.5' ``` --- ## ⚠️ 版本兼容性说明 | 版本分支 | Spring Boot 适配 | Servlet 包 | 状态 | |:--------|:-----------------|:------------------|:-------| | **2.x** | Spring Boot 2.x | `javax.servlet` | ✅ 长期维护 | | **3.x** | Spring Boot 3.x+ | `jakarta.servlet` | ✅ 长期维护 | > 核心功能两边通用，升级只换版本号就行 --- ## 🤝 贡献指南欢迎通过以下方式参与项目，一起把这东西磨得更顺手详见([贡献指南.md](贡献指南.md)) - 🐞 **反馈Bug**：在 [Issues](https://gitee.com/apanlh/pan-common/issues) 中提交详细的问题描述 - 💡 **功能建议**：在 [Issues](https://gitee.com/apanlh/pan-common/issues) 中提出你的想法 - 🔧 **提交代码**： Fork 项目 → 创建特性分支 → 提交 Pull Request - 📖 **完善文档**：修正文档错误、补充示例代码 - ⭐ **推荐项目**：点击右上角 Star 支持我 --- ## 👤 联系作者 | 方式 | 信息 | |-----------|------------------------------------------------------| | **作者** | Pan | | **邮箱** | [582084583@qq.com](mailto:582084583@qq.com) | | **Gitee** | [https://gitee.com/apanlh](https://gitee.com/apanlh) | --- ## ⚖️ 开源协议本项目基于 **MulanPSL2** 开源协议，您可以自由使用、修改和分发详见：[LICENSE](LICENSE) --- ## 💖 支持项目如果觉得对您有帮助： - ⭐ 点击右上角 **Star** 关注项目更新 - 🔄 **Fork** 项目参与代码贡献 - 📢 **分享** 给你的同事和朋友 - 🐞 提交 **Issue** 反馈使用中遇到的问题您的支持是我持续迭代的动力！ ---

返回顶部

Made with ❤️ by Pan