commons-patterns

Apache Commons 最佳实践模式

来源：Commons Home | Lang3 User Guide | IO Description

能力边界

✅ 擅长领域

1. StringUtils 判空模式 — 精确选择 isEmpty 与 isBlank、defaultString 的语义
2. Commons IO 文件操作 — FileUtils 读写复制 / IOUtils 流操作 / LineIterator 逐行读取
3. Commons Collections4 — CollectionUtils/MultiValuedMap/MapUtils
4. RandomStringUtils — 生成随机字符串（验证码/Token/临时密码）
5. Validate — 参数校验（注意：从 3.0 起抛出 NullPointerException，而非 IllegalArgumentException）

❌ 不在适用范围内

1. 中文特色（身份证/拼音）→ hutool-patterns
2. 不可变集合/缓存/EventBus → guava-patterns
3. Bean 映射/JSON → mapstruct-patterns/jackson-patterns

Commons、Guava 与 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安全取值

注意事项

1. isEmpty 与 isBlank — isEmpty(" ")→true（不含空格），isBlank(" ")→true（含空格）
2. IOUtils.toString 会将整个流加载到内存中 — 大文件（>10MB）使用 LineIterator 逐行读取
3. IOUtils.toString 不会关闭流 — 搭配 finally { IOUtils.closeQuietly(in) } 使用
4. Lang3 DateUtils 与 Java8 LocalDateTime 不兼容 — 使用 java.time API，仅对旧 Date 使用 Commons
5. Collections4 的包名是 collections4 — 不是 collections（后者属于 3.x）
6. 从 Lang3 3.0 起，isAlpha/isNumeric/isAlphanumeric("")→false — 旧版本返回 true
7. Maven 坐标：groupId=org.apache.commons，artifactId=commons-lang3 — 不是 commons-lang
8. Validate.notNull 抛出 NullPointerException — Validate.isTrue 抛出 IllegalArgumentException

数据隐私

本技能不收集、存储或传输任何用户数据。