hutool库技能

一、为什么需要这个技能

用过 Hutool 的 Java 开发者都知道它的价值：SecureUtil.md5() 一行顶一段复制粘贴的代码。但 AI 编码智能体在使用 Hutool 时存在三类典型问题：

1. 不用。模型更倾向于手写 SimpleDateFormat、for 循环拼串、UUID.randomUUID().toString().replace("-","") 这类它"训练数据里见过一万遍"的样板代码，而不是 Hutool 的 DateUtil.parse()、StrUtil.format()、IdUtil.simpleUUID()。
2. 用错。Hutool 对第三方库全是可选依赖——Excel 需要 POI、国密需要 BouncyCastle、二维码需要 zxing、邮件需要 javax.mail。AI 常常只写 ExcelUtil.getReader() 却不提醒引入 poi-ooxml，代码一运行就 ClassNotFoundException。
3. 踩坑。DateUtil.month() 返回 0-11、DateTime 默认可变对象、ExcelWriter 不 close 不落盘、IdUtil.createSnowflake() 每次新建导致 ID 重复、QQ 邮箱密码要填授权码、CronUtil 默认不支持秒级表达式……这些坑官方文档里都写着，但 AI 不会主动去翻。

这个技能就是把这些"翻文档"的工作前置固化：让 AI 写代码前先查技能，而不是先写错再返工。

二、技能结构设计

技能采用"渐进式加载"（Progressive Disclosure）结构，主文件常驻上下文、细分参考按需读取，兼顾效果与 token 成本：

hutool/
├── SKILL.md                 # 主文件（236 行）：依赖引入、速查表、代码范式、避坑清单、文档索引
└── references/              # 8 份领域详解，写相关代码时才读
    ├── core.md              # StrUtil/DateUtil/CollUtil/MapUtil/Convert/BeanUtil/ReflectUtil/IdUtil…
    ├── io.md                # FileUtil/IoUtil/ZipUtil/ResourceUtil/系统工具
    ├── data.md              # JSON/XML/CSV/HTML/Base64/Hex 编码
    ├── http.md              # HttpUtil/HttpRequest/UrlBuilder/ServletUtil
    ├── crypto.md            # SecureUtil/DigestUtil/HMac/国密 SM2/SM3/SM4/JWT
    ├── db-cache.md          # Db/Entity/DSFactory/缓存/CronUtil/线程池/日志
    ├── extra.md             # Excel/Mail/二维码/验证码/拼音/Emoji/模板引擎/Spring
    └── ai.md                # hutool-ai：DeepSeek/OpenAI/Grok/豆包 统一调用

三、核心内容一览

1. 依赖引入 + 可选依赖表。给出 Maven/Gradle/BOM 三种引入方式（版本基线 5.8.47，JDK 8+），并用一张表明确"哪些功能必须额外引入什么第三方库"——这是 AI 写 Hutool 代码最高频的翻车点。

2. 任务 → 工具类速查表。主文件的精华，按 20+ 个任务域直接路由：

你要做的事	用它
判空/格式化/脱敏	StrUtil/DesensitizedUtil
日期解析与偏移	DateUtil.parse()自动识别 20+ 种格式
Map ↔ Bean 互转	BeanUtil.toBean()/copyProperties()
HTTP 调用	HttpUtil.get()/HttpRequest链式
摘要与 JWT	SecureUtil.md5()/JWTUtil.createToken()
Excel 读写	ExcelUtil.getReader().readAll()/ExcelWriter
数据库 CRUD	Db.use(dataSource)ActiveRecord 风格

3. 高频代码范式。十余段可直接套用的代码，每段都带正确的包路径，例如 AI 大模型对接：

// hutool-ai：一行调用 DeepSeek
String chat = AIUtil.chat(
    new AIConfigBuilder(ModelName.DEEPSEEK.getValue())
        .setApiKey("your key").build(),
    "写一首赞美我的诗");

4. 避坑清单（16 条）。节选：

• DateUtil.month() 返回 0-11，取 1-12 用 monthEnum().getValue()
• DateTime 默认可变对象，offset() 会修改自身，共享场景先 setMutable(false)
• ExcelWriter 必须 close() 才落盘；大数据量换 BigExcelWriter 或 readBySax 流式读写
• 雪花 ID 用 IdUtil.getSnowflake(1,1) 全局单例，createSnowflake() 每次新建会重复
• CronUtil 默认 5 位表达式，秒级要先 setMatchSecond(true)
• JSONObject 默认忽略 null 值，需要输出时 JSONConfig.setIgnoreNullValue(false)

四、数据来源与可信度

技能内容不是模型"凭记忆"编写的，而是先抓取官方文档站全部约 60 个工具类页面（doc.hutool.cn/pages/<类名>/）与 JavaDoc（plus.hutool.cn/apidocs/，hutool 5.8.47）逐页整理，再按 AI 使用视角重写。SKILL.md 中保留了"单类文档页 URL 模式 + 模块总览 + 源码与 CHANGELOG"入口，未来 Hutool 更新时技能可低成本再生成。

五、安装与使用

将技能目录放入对应 AI 工具的技能目录即可（以 LobsterAI 为例）：

~/Library/Application Support/LobsterAI/SKILLs/hutool/

Claude Code / Cursor 等遵循 SKILL.md 规范的环境放入其技能目录同样可用。无需任何配置，下次让 AI 写 Java 代码（如"写个导出 Excel 的接口"、"调 DeepSeek 生成文案"）时技能会自动触发。

六、适用人群

• 日常用 AI 编码智能体写 Java 后端的开发者
• 团队想统一 AI 生成代码风格、拥抱 Hutool 生态的工程负责人
• 想参考"如何为某个工具库制作 AI 编码技能"的技能作者（本技能的结构可直接套用到其他库）