hutool

name	hutool
license	MIT
description	辅助开发、选择模块、调试和解释 Hutool Java 工具库。只要用户提到 Hutool、cn.hutool、hutool-all、hutool-core、StrUtil、ObjectUtil、Convert、BeanUtil、DateUtil、FileUtil、IoUtil、CollUtil、MapUtil、ReflectUtil、ReUtil、IdUtil、NumberUtil、JSONUtil、HttpRequest/HttpUtil、SecureUtil、JWTUtil、ExcelUtil、Setting、CacheUtil、CronUtil、CaptchaUtil，或需要根据 Hutool 官方开源仓库确认 API、模块依赖、空值行为、编码/日期/Bean/JSON/HTTP/加密/Excel 用法，都必须使用此技能。此技能只记录通用 Hutool 能力，不写入某个业务项目的专属规范。

Hutool 开发技能

你在辅助 Hutool Java 工具库相关开发、API 选择、源码机制解释和问题排查。Hutool 工具类数量很多，且部分 API 有空值、编码、类型转换和版本差异细节，回答和实现必须优先以目标项目依赖版本和官方源码为准。

官方仓库：https://gitee.com/chinabugotech/hutool

首要原则

1. 先判定任务类型：核心工具、字符串/集合/Map、类型转换、Bean 拷贝、日期时间、文件/IO、JSON、HTTP、加密/摘要/JWT、Excel/POI、Setting、缓存、定时任务、验证码、数据库、AOP、脚本或问题排查。
2. 优先查证官方源码：不确定的方法名、参数顺序、空值行为、异常行为、模块归属和依赖，必须读官方仓库或目标项目依赖源码中的实现与测试示例。
3. 按需引入模块：能单独引入模块时不要默认要求 hutool-all；但快速原型或用户明确要全量时可用 hutool-all。
4. 不要臆造 API：Hutool API 很多但命名相近，写代码前确认真实类和方法，尤其是 BeanUtil、JSONUtil、HttpRequest、ExcelUtil。
5. 注意安全边界：涉及 HTTP、文件路径、加密、JWT、反射、脚本执行、Excel 导入时，提醒 SSRF、路径穿越、弱摘要、秘钥泄露、公式注入、反射越权等边界。
6. 保持通用性：本技能只记录 Hutool 通用能力。业务项目专属工具封装、返回体、目录结构、权限规范放到对应项目技能中。

资料入口

按任务读取对应 reference，必要时再读源码文件：

• 仓库结构和模块选择：references/source-map.md
• core 常用工具：references/core-utils.md
• Convert、Bean、Map/集合：references/convert-bean-collection.md
• 日期、文件、IO：references/date-file-io.md
• JSON、HTTP：references/json-http.md
• Crypto、JWT、Excel、Setting 等扩展：references/extension-modules.md
• 排查与安全注意：references/debugging-security.md

如果任务很具体，直接 grep 源码优先于泛读 reference。

工作流

业务代码中使用 Hutool

1. 查当前项目已引入的 Hutool 版本和模块。
2. 若只需要某一能力，优先给单模块依赖；若项目已有 hutool-all，可直接使用。
3. 查对应工具类源码或测试，确认 API 与行为。
4. 给最小代码片段，并说明空值、异常、字符集、时区、资源关闭等关键点。
5. 涉及外部输入时补安全边界：路径、URL、JSON、Excel、加密秘钥等。

源码机制解释

1. 定位工具类和真实实现类，例如 StrUtil 继承 CharSequenceUtil，Convert 走 ConverterRegistry，BeanUtil.copyProperties 走 BeanCopier/CopyOptions。
2. 阅读方法定义和测试示例，不只看 README。
3. 输出：结论 → 源码路径 → 行为细节 → 使用建议/坑点。

问题排查

1. 收集 Hutool 版本、模块依赖、JDK 版本、输入样例、异常堆栈。
2. 对照源码确认：空值返回、默认字符集、日期解析格式、Bean 属性名/大小写、JSONConfig、HTTP 超时/编码、加密算法/Provider。
3. 给最小修复和验证代码。

常用查证命令

# 常用 core 工具
rg "class StrUtil|class BeanUtil|class Convert|class DateUtil|class FileUtil" hutool-core/src/main/java

# JSON/HTTP/Crypto/POI/JWT
rg "class JSONUtil|class HttpRequest|class SecureUtil|class ExcelUtil|class JWTUtil" --glob '*/src/main/java/**'

# 测试示例
find . -path '*/src/test/java/*' -type f | grep -E 'StrUtil|BeanUtil|DateUtil|JSONUtil|HttpRequest|SecureUtil|ExcelUtil|JWTUtil'

输出规范

• 全程中文；Java 类名、方法名、配置键保持原样。
• 涉及源码机制时引用 path:line。
• 不确定时说“源码中未确认”，不要凭 Hutool 旧版本或网上印象补方法。
• 代码示例尽量短，优先使用当前源码中存在的 API。
• 安全相关默认提醒：不要用 MD5/SHA1 存密码，不要拼接不可信路径或 URL，不要把秘钥硬编码到仓库。