commons-patterns
Apache Commons 最佳实践模式。从官方文档提炼,覆盖 Commons Lang3(StringUtils千面判空/isEmpty vs isBlank/Validate抛NullPointerException迁移)、Commons IO(IOUtils.toString大文件陷阱/FileUtils.lineIterator逐行读模式/FilenameUtils.normalize路径规范化)、Commons Collections4(CollectionUtils.union/intersection/subtract集合运算)。 纠正 LLM 误用:混淆 StringUtils.isBlank vs isEmpty、IOUtils.toString 读大文件OOM、不知道 LineIterator 逐行读模式、用 lang 而非 lang3 包名。
How do I install this agent skill?
npx skills add https://github.com/full-stack-skills/java-skills --skill commons-patternsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a documentation and reference guide for using Apache Commons Java libraries (Lang3, IO, Collections4). It contains no malicious code, data exfiltration, or security risks. All external links lead to official, trusted Apache Software Foundation documentation.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Apache Commons 最佳实践模式
Capability Boundaries
✅ Strong Suits
- StringUtils 判空模式 — isEmpty vs isBlank vs defaultString 精确语义选择
- Commons IO 文件操作 — FileUtils 读写复制 / IOUtils 流操作 / LineIterator 逐行
- Commons Collections4 — CollectionUtils/MultiValuedMap/MapUtils
- RandomStringUtils — 生成随机字符串(验证码/Token/临时密码)
- Validate — 参数校验(注意3.0起抛NullPointerException而非IllegalArgumentException)
❌ Out of Scope
- 中文特色(身份证/拼音) → hutool-patterns
- 不可变集合/缓存/EventBus → guava-patterns
- Bean映射/JSON → mapstruct-patterns/jackson-patterns
Commons vs Guava vs Hutool 选择表
| 场景 | Commons | Guava | Hutool | 优先选 |
|---|---|---|---|---|
| 字符串判空/截断/填充 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | 任意(团队约定) |
| 文件复制/删除/读行 | ⭐⭐⭐ | ⭐ | ⭐⭐ | Commons IO |
| 文件名/路径处理 | ⭐⭐⭐ | — | ⭐⭐ | Commons IO |
| 集合运算(交/并/差) | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | 任意 |
| 日期处理(旧Date) | ⭐ | — | ⭐⭐⭐ | Java8 Time |
| 随机字符串 | ⭐⭐⭐ | — | ⭐⭐ | Commons Lang3 |
| HTML/XML转义 | ⭐⭐⭐ | — | ⭐ | Commons Lang3 |
| 数学/统计 | ⭐⭐⭐ | — | ⭐ | Commons Math |
核心模式
模式 1: StringUtils 判空精确语义
// ✅ isEmpty: null 或 "" → true (不含空格)
StringUtils.isEmpty(null); // true
StringUtils.isEmpty(""); // true
StringUtils.isEmpty(" "); // false ← 注意!
StringUtils.isEmpty("abc"); // false
// ✅ isBlank: null 或 空白字符 → true
StringUtils.isBlank(null); // true
StringUtils.isBlank(""); // true
StringUtils.isBlank(" "); // true ← 含空格也true
StringUtils.isBlank("abc"); // false
// ✅ 选择规则: 表单验证用isBlank(不接受空白输入),集合判空用isEmpty
// ✅ defaultString: null安全取值
StringUtils.defaultString(str, ""); // null → ""
StringUtils.defaultIfBlank(str, "N/A"); // null/""/" " → "N/A"
// ✅ 填充与截断
StringUtils.leftPad("1", 3, '0'); // "001"
StringUtils.abbreviate("very long text", 10); // "very lo..."
模式 2: Commons IO 文件模式
// ✅ 读取整个文件(小文件,<10MB)
String content = FileUtils.readFileToString(file, StandardCharsets.UTF_8);
List<String> lines = FileUtils.readLines(file, StandardCharsets.UTF_8);
// ✅ 逐行读(大文件) — LineIterator 模式
LineIterator it = FileUtils.lineIterator(file, "UTF-8");
try { while (it.hasNext()) { String line = it.nextLine(); /* 处理 */ }
} finally { LineIterator.closeQuietly(it); }
// ✅ 流操作(需手动关流)
InputStream in = new URL("https://example.com").openStream();
try { String result = IOUtils.toString(in, StandardCharsets.UTF_8); }
finally { IOUtils.closeQuietly(in); }
// ❌ 反模式: IOUtils.toString() 读 1GB 文件 → 尝试创建1GB String → OOM
// ✅ 写入/复制/删除
FileUtils.writeStringToFile(file, content, StandardCharsets.UTF_8);
FileUtils.copyFile(src, dest);
FileUtils.forceMkdir(dir); // 递归创建目录
FileUtils.deleteDirectory(dir); // 递归删除
// ✅ 文件名处理
FilenameUtils.getExtension("archive.tar.gz"); // "gz" (最后一个.)
FilenameUtils.getBaseName("/path/file.txt"); // "file"
String normalized = FilenameUtils.normalize("C:/a/../b/file.txt"); // "C:/b/file.txt"
模式 3: Commons Lang3 迁移注意事项
// ❌ 旧包名 — 不要用
import org.apache.commons.lang.StringUtils;
// ✅ 新包名(3.0+) — 必须用
import org.apache.commons.lang3.StringUtils;
// Maven坐标
// groupId: commons-lang → org.apache.commons
// artifactId: commons-lang → commons-lang3
模式 4: Validate 的参数校验
// ⚠️ Commons Lang 3.0 变化: Validate 校验 null 抛 NullPointerException
// (对齐JDK标准行为,以前抛 IllegalArgumentException)
Validate.notNull(obj, "参数不能为空: %s", name); // 抛 NPE
Validate.isTrue(age > 0, "年龄必须>0"); // 抛 IllegalArgumentException
// 注意:验证null用Validate.notNull,验证状态用Validate.isTrue
模式 5: RandomStringUtils
// ✅ 随机字母数字(验证码/Token)
RandomStringUtils.randomAlphanumeric(6); // "a3Bx9K"
RandomStringUtils.randomAlphanumeric(32); // 32位Token
// ✅ 随机数字
RandomStringUtils.randomNumeric(6); // "482931"
// ✅ 随机字母
RandomStringUtils.randomAlphabetic(8); // "AbCdEfGh"
模式 6: 集合运算
// ⚠️ 包名: org.apache.commons.collections4 (不是 collections)
CollectionUtils.isEmpty(coll);
CollectionUtils.union(list1, list2); // 并集
CollectionUtils.intersection(list1, list2); // 交集
CollectionUtils.subtract(list1, list2); // 差集(list1 - list2)
MapUtils.getString(map, "key", "default"); // null安全取值
Gotchas
- isEmpty vs isBlank — isEmpty(" ")→true(不含空格),isBlank(" ")→true(含空格)
- IOUtils.toString 加载整个流到内存 — 大文件(>10MB)用 LineIterator 逐行读
- IOUtils.toString 不关流 — 配合 finally { IOUtils.closeQuietly(in) }
- Lang3 DateUtils 与 Java8 LocalDateTime 不兼容 — 用 java.time API,仅旧Date用Commons
- Collections4 包名是 collections4 — 不是 collections(那是3.x)
- Lang3 3.0 起 isAlpha/isNumeric/isAlphanumeric("")→false — 以前版本返回true
- Maven坐标: groupId=org.apache.commons, artifactId=commons-lang3 — 不是 commons-lang
- Validate.notNull 抛 NullPointerException — Validate.isTrue 抛 IllegalArgumentException
Data Privacy
本技能不收集、存储或传输任何用户数据。
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/full-stack-skills/java-skills/commons-patterns">View commons-patterns on skillZs</a>