1、概述
commons-lang3 包含了数十个针对 Java 语言基础库进行扩展的工具类。以下是按照功能模块分类整理的 核心 API 列表全景图 及 常用核心类的详细 API 参数与代码示例。
| 分类模块 | 常用工具类 (Class) | 核心解决问题 |
|---|---|---|
| 字符串处理 | StringUtils, RandomStringUtils, CharSequenceUtils | 空值安全处理、截取、替换、填充、随机数 |
| 对象与空安全 | ObjectUtils, Validate | 防 NPE 操作、默认值赋予、参数校验 |
| 数值与布尔 | NumberUtils, BooleanUtils | 安全类型转换、极值计算、多条件布尔逻辑 |
| 数据结构与容器 | ArrayUtils, Pair, Triple | 数组动态操作、二元/三元组数据封装 |
| 时间与性能 | DateFormatUtils, DateUtils, StopWatch | 日期计算、格式化、代码执行耗时监控 |
| 反射与对象元数据 | FieldUtils, MethodUtils, ReflectionToStringBuilder | 绕过复杂反射代码直接读写属性、自动生成 toString |
| 系统与环境 | SystemUtils, ArchUtils | 获取操作系统类型、JDK 版本、系统目录 |
如需在项目中引用 commons-lang3，只需添加以下依赖：
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.14.0</version>
</dependency>
2、字符串处理
2.1、StringUtils（字符串工具核心）
几乎包含了所有针对 CharSequence / String 的静态操作，最显著的优势是天然防范 NullPointerException。
2.1.1、核心API
- 判空处理
isEmpty(CharSequence cs)/isNotEmpty：判断是否为 null 或长度为 0。isBlank(CharSequence cs)/isNotBlank：判断是否为 null、长度为 0 或全由空白字符（包含空格、制表符等）组成。
- 去除空白与截取
trim(String str)：转为 safe trim（null 返回 null）。strip(String str, String stripChars)：按自定义字符集剥离首尾字符。substringBetween(String str, String open, String close)：高效提取两个标记之间的子串。
- 拼接与分割
join(Iterable<?> iterable, String separator)：将集合/数组按分隔符拼接成字符串。split(String str, String separatorChars)：高性能分割（相比原生 String.split，不用写正则表达式，效率更高）。
- 替换与大小写
capitalize(String str)/uncapitalize：首字母大写/小写。swapCase(String str)：大小写互换（大转小，小转大）。replace(String text, String searchString, String replacement)：无正则的高效替换。
- 填充与对齐
leftPad(String str, int size, String padStr)/rightPad：向左/右补齐长度（常用于生成特定格式单号）。
2.1.2、使用示例
import org.apache.commons.lang3.StringUtils;
public class StringUtilsDemo {
public static void main(String[] args) {
// 1. 判空
System.out.println(StringUtils.isBlank(" \t\n ")); // true
System.out.println(StringUtils.isEmpty(" ")); // false
// 2. 高效安全的提取
String html = "<div>Hello World</div>";
String content = StringUtils.substringBetween(html, "<div>", "</div>");
// content = "Hello World"
// 3. 数组/集合拼接
String[] array = {"Java", "Python", "Go"};
String result = StringUtils.join(array, " - ");
// result = "Java - Python - Go"
// 4. 字符串补齐 (例如补齐6位流水号)
String orderId = StringUtils.leftPad("42", 6, "0");
// orderId = "000042"
// 5. 大小写切换
System.out.println(StringUtils.capitalize("hello")); // "Hello"
System.out.println(StringUtils.swapCase("aBcD")); // "AbCd"
}
}
true
false
Hello
AbCd
2.2、CharUtils（单个字符工具）
专注于 char 和 Character 的转化与判定，提供无装箱/拆箱开销的操作。
2.2.1、核心API
toChar(Character ch, char defaultValue)：将 Character 对象安全转为 char 基础类型。isAscii(char ch)：判断是否为 ASCII 字符。isAsciiNumeric(char ch)：判断是否为 ASCII 数字字符（‘0’-‘9’）。isAsciiAlpha(char ch)：判断是否为 ASCII 字母（a-z, A-Z）。toIntValue(char ch, int defaultValue)：将数字字符直接转为对应的整数值（例如 ‘5’ -> 5）。
2.2.2、使用示例
import org.apache.commons.lang3.CharUtils;
public class CharUtilsDemo {
public static void main(String[] args) {
// 1. 安全转换包装类型，防止 NPE
Character character = null;
char c = CharUtils.toChar(character, 'a'); // 'a'
// 2. 字符类型判断
System.out.println(CharUtils.isAsciiNumeric('8')); // true
System.out.println(CharUtils.isAsciiAlpha('X')); // true
// 3. 字符转整数
int num = CharUtils.toIntValue('9', -1); // 9
}
}
true
true
2.3、RandomStringUtils（随机字符串生成）
非常适合用于生成验证码、随机密码、临时 Token 或测试数据。
2.3.1、核心API
randomNumeric(int count)：生成纯数字随机串。randomAlphabetic(int count)：生成纯字母随机串。randomAlphanumeric(int count)：生成字母+数字组合串。random(int count, String chars)：从给定的字符集限定中随机生成。
2.3.2、使用示例
import org.apache.commons.lang3.RandomStringUtils;
public class RandomStringUtilsDemo {
public static void main(String[] args) {
// 生成 6 位手机短信验证码
String code = RandomStringUtils.randomNumeric(6);
// 例如: "482910"
// 生成 16 位混合随机 Key
String apiKey = RandomStringUtils.randomAlphanumeric(16);
// 例如: "aK9m2P1z0xQ8wN7v"
// 从指定字符集中随机选择 8 位
String custom = RandomStringUtils.random(8, "ABCDEF123456");
// 例如: "B3C1F5A2"
}
}
813598
N20srTPr7JmEf2cK
B4A1312A
2.4、StringEscapeUtils（字符串转义工具）
用于防范 XSS 攻击、生成合法 JSON/HTML/XML/SQL 的转义处理。（注：在 lang3 较新版本中已被标注为废弃，推荐转移使用同组的 commons-text 库，但在旧/常规项目中依然极为常见）。
2.4.1、核心 API
escapeHtml4(String input)/unescapeHtml4：转义/反转义 HTML4 特殊字符。escapeJson(String input)：转义 JSON 中的双引号、换行符等。escapeXml11(String input)：转义 XML 字符。
2.4.2、使用示例
import org.apache.commons.lang3.StringEscapeUtils;
public class EscapeDemo {
public static void main(String[] args) {
// 防范 HTML XSS 攻击
String unsafeHtml = "<script>alert('XSS')</script>";
String safeHtml = StringEscapeUtils.escapeHtml4(unsafeHtml);
// 输出: <script>alert('XSS')</script>
// JSON 转义
String rawJson = "Name: \"John\", Line1\nLine2";
String escapedJson = StringEscapeUtils.escapeJson(rawJson);
// 输出: Name: \"John\", Line1\nLine2
}
}
2.5、RegExUtils（正则表达式简化工具）
简化原生 Pattern 和 Matcher 的繁琐写法，对正则表达式替换进行了更高层的封装。
2.5.1、核心API
removeFirst(CharSequence text, String regex)：移除首个匹配项。removeAll(CharSequence text, String regex)：移除所有匹配项。replaceAll(CharSequence text, String regex, String replacement)：正则表达式替换所有。
2.5.2、使用示例
import org.apache.commons.lang3.RegExUtils;
public class RegExUtilsDemo {
public static void main(String[] args) {
String text = "User phone: 138-0000-1234, ID: 1001";
// 移除所有数字
String noDigits = RegExUtils.removeAll(text, "\\d");
System.out.println(noDigits);
// 输出: "User phone: --, ID: "
// 替换格式 (将手机号中间四位隐藏)
String masked = RegExUtils.replaceAll(text, "(\\d{3})-\\d{4}-(\\d{4})", "$1-****-$2");
System.out.println(masked);
// 输出: "User phone: 138-****-1234, ID: 1001"
}
}
User phone: --, ID:
User phone: 138-****-1234, ID: 1001
3、对象与空安全
在 Java 开发中，NullPointerException（NPE）是最常见的运行时异常之一。commons-lang3 提供了大量强悍且优雅的空安全（Null-Safe）工具类，能够极大减少冗长的 if (obj != null) 判空代码。
在项目中使用 commons-lang3 的空安全工具时，引入以下标准 Maven 依赖即可：
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.14.0</version>
</dependency>
3.1、ObjectUtils（通用对象与空安全核心类）
ObjectUtils 是针对所有 Object 的通用工具类，主要用于安全判空、兜底默认值、多对象安全对比与运算。
3.1.1、核心API
- 空与非空判定
isEmpty(Object object)/isNotEmpty：通用判空。支持 String、数组、Collection、Map、Optional 等多种对象。allNotNull(Object... values)：验证所有传入对象是否全都不为 null。anyNotNull(Object... values)：验证传入对象中是否至少有一个不为 null。
- 默认值与安全获取（防 NPE）
defaultIfNull(T object, T defaultValue)：若对象为 null 则返回默认值。getFirstNonNull(Supplier<T>... suppliers)：按顺序执行表达式，返回第一个非 null 结果（延迟加载，效率高）。
- 安全比较与操作
equals(Object object1, Object object2)：安全比较两对象是否相等（内部已处理 null）。compare(T c1, T c2)/compare(T c1, T c2, boolean nullIsLess)：安全比较实现了 Comparable 的对象大小，可指定 null 算作更大还是更小。mode(T... items)：计算传入对象中出现频率最高的元素（众数）。
3.1.2、使用示例
import org.apache.commons.lang3.ObjectUtils;
import java.util.List;
public class ObjectUtilsDemo {
public static void main(String[] args) {
// 1. 通用判空（支持各种类型）
List<String> list = null;
System.out.println(ObjectUtils.isEmpty(list)); // true
// 2. 多对象非空校验
String a = "hello", b = null, c = "world";
System.out.println(ObjectUtils.allNotNull(a, b, c)); // false
System.out.println(ObjectUtils.anyNotNull(a, b, c)); // true
// 3. 默认值兜底
String name = null;
String finalName = ObjectUtils.defaultIfNull(name, "Guest"); // "Guest"
// 4. 延迟加载取首个非 Null 结果
String result = ObjectUtils.getFirstNonNull(
() -> null,
() -> fetchFromCache(), // 若上面为 null 才执行
() -> "default"
);
// 5. 安全排序比较（null 排在最后/算作最小）
Integer val1 = null, val2 = 10;
int comp = ObjectUtils.compare(val1, val2, true); // true 代表 null 算作小于非 null 值
}
private static String fetchFromCache() { return "Cache Data"; }
}
true
false
true
3.2、Validate（参数校验与前置条件）
用于对方法入参进行强约束断言校验。如果条件不满足，会直接抛出包含定制信息的 IllegalArgumentException 或 NullPointerException，常用于防御性编程。
3.2.1、核心API
notNull(T object, String message, Object... values)：断言对象不能为 null。notEmpty(T chars, String message)：断言字符串/集合/数组不能为 null 且不能为空。notBlank(CharSequence chars, String message)：断言字符串不能为 null、空或全为空格。isTrue(boolean expression, String message)：断言布尔表达式必须为 true。validIndex(T array, int index, String message)：断言数组或集合的索引未越界。
3.2.2、使用示例
import org.apache.commons.lang3.Validate;
public class ValidateDemo {
public void updateUser(String userId, String username, int age) {
// 1. 断言参数非空
Validate.notBlank(userId, "用户ID不能为空");
Validate.notNull(username, "用户名不能为 null");
// 2. 断言业务逻辑表达式
Validate.isTrue(age >= 0 && age <= 150, "年龄格式不合法: %s", age);
// 执行业务逻辑...
}
}
4、数值与布尔
commons-lang3（Apache Commons Lang 3）针对 Java 原生的基本数据类型及对应的包装类提供了大量扩展与补强工具。在涉及数值计算、范围判断、类型安全转换以及布尔逻辑判定时，它们不仅能够完美处理 null 值，还能大幅简化代码。
在项目中直接引入标准的 commons-lang3 坐标即可使用全部工具类：
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.14.0</version>
</dependency>
4.1、NumberUtils（数值工具核心）
NumberUtils 专注于字符串到数值的安全解析与转换、最大/最小值求解以及数值类型判定。
4.1.1、核心API
- 安全转换（防 NumberFormatException 与 NPE）
toInt(String str, int defaultValue)/toLong/toDouble/toBigDecimal：将字符串安全转为对应数值，若输入为 null 或格式非法，不会抛出异常，而是返回设定的默认值（不传默认值时则返回 0 或 0.0）。
- 数值判定
isCreatable(String str)：判断字符串是否可以安全解析为 Java 数值（支持十六进制 0x、科学计数法 1.2e3、八进制及类型后缀 L/F/D 等）。isDigits(String str)：判断字符串是否全由纯数字字符（0-9）组成（不支持负号和小数点）。
- 最值计算（支持数组与多参数）
max(int... array)/min(double... array)：获取一组数值中的最大值/最小值。max(byte a, byte b, byte c)：获取传入参数中的最大值。
- 通用对象解析
createNumber(String str)：将字符串智能解析并自动推导为最合适的 Number 子类对象（如 Integer、Long、Float、BigDecimal 等）。
4.1.2、使用示例
import org.apache.commons.lang3.math.NumberUtils;
import java.math.BigDecimal;
public class NumberUtilsDemo {
public static void main(String[] args) {
// 1. 安全转换字符串为基本数据类型（无需 try-catch）
int age = NumberUtils.toInt("25", 0); // 25
int invalidAge = NumberUtils.toInt("abc", 18); // 格式非法，返回默认值 18
double price = NumberUtils.toDouble(null, 0.0); // null 安全，返回默认值 0.0
// 2. 转换为 BigDecimal
BigDecimal amount = NumberUtils.toBigDecimal("123.456", BigDecimal.ZERO);
// 3. 校验字符串格式
System.out.println(NumberUtils.isCreatable("0x1A")); // true (十六进制)
System.out.println(NumberUtils.isCreatable("-1.5e2"));// true (科学计数法)
System.out.println(NumberUtils.isDigits("12345")); // true
System.out.println(NumberUtils.isDigits("-123")); // false (包含负号)
// 4. 获取最值
int maxVal = NumberUtils.max(10, 50, 30, 90, 20); // 90
double minVal = NumberUtils.min(new double[]{2.5, 1.2, 3.8}); // 1.2
}
}
4.2、BooleanUtils（布尔工具与逻辑运算）
原生的 Boolean 包装类如果是 null，直接隐式拆箱（如 if (flag)）会触发 NullPointerException。BooleanUtils 不仅实现了空安全的布尔运算，还支持丰富的类型转换与逻辑代数。
4.2.1、核心API
- 空安全判定（防 NPE）
isTrue(Boolean bool)/isFalse(Boolean bool)：安全判断 Boolean 对象是否为 true / false（输入 null 安全返回 false）。isNotTrue(Boolean bool)/isNotFalse(Boolean bool)：安全否定判定（null 会被视作非 true）。
- 类型相互转换
toBoolean(int value)：0 转为 false，非 0 转为 true。toBoolean(String str)：将 “true”、“yes”、“y”、“on”、“1”（不区分大小写）安全转换为 true。toInteger(Boolean bool, int trueValue, int falseValue, int nullValue)：根据布尔值状态转换为定制的整型数字。
- 逻辑运算
and(Boolean... array)/or(Boolean... array)/xor(Boolean... array)：对多个可能包含 null 的 Boolean 进行逻辑与、逻辑或、异或（XOR）判定。
4.2.2、使用示例
import org.apache.commons.lang3.BooleanUtils;
public class BooleanUtilsDemo {
public static void main(String[] args) {
Boolean unknownFlag = null;
// 1. 空安全的判断（完全杜绝 NPE）
if (BooleanUtils.isTrue(unknownFlag)) {
// 不会抛出 NPE，且不会触发内部逻辑
}
System.out.println(BooleanUtils.isNotTrue(unknownFlag)); // true
// 2. 多样化的字符串与数字转 boolean
System.out.println(BooleanUtils.toBoolean("yes")); // true
System.out.println(BooleanUtils.toBoolean("ON")); // true
System.out.println(BooleanUtils.toBoolean(1)); // true
System.out.println(BooleanUtils.toBoolean(0)); // false
// 3. 布尔转自定义数字/标识（常用于数据库映射：1-成功，0-失败，-1-未知）
int status = BooleanUtils.toInteger(unknownFlag, 1, 0, -1); // -1
// 4. 多布尔对象的多元逻辑运算
boolean b1 = true;
boolean b2 = false;
boolean b3 = false;
System.out.println(new Boolean[]{b1, b2, b3});
System.out.println(new Boolean[]{b1, b2}); // false
// 5. 异或运算（恰好有一个为 true 时返回 true）
System.out.println(BooleanUtils.xor(new Boolean[]{true, false, false})); // true
}
}
true
true
true
true
false
[Ljava.lang.Boolean;@1d44bcfa
[Ljava.lang.Boolean;@266474c2
true
4.3、Range（数值与区间开闭工具）
Range<N> 用于定义一个不可变的不可为空的区间/范围（例如数字区间、日期区间等），并提供区间交集、包含判断等数学集合操作。
4.3.1、核心API
- 区间构建
between(from, to)：构建闭区间 [from, to]（内部会自动修正顺序，即使传入 between(10, 1)，也会自动识别下界为 1，上界为 10）。is(element)：构建只包含单一元素的单值区间 [element, element]。
- 包含与比较
contains(element)：判断指定元素是否落在该区间内。containsRange(otherRange)：判断当前区间是否完整包含另一个区间。isAfter(element)/isBefore(element)：判断整个区间是否完全在某个元素的上方/下方。
- 区间交集与并集
intersectionWith(otherRange)：求两个区间的交集（无重叠部分时抛出 IllegalArgumentException）。isOverlappedBy(otherRange)：判断两个区间是否有重叠。
4.3.2、使用示例
import org.apache.commons.lang3.Range;
public class RangeDemo {
public static void main(String[] args) {
// 1. 创建区间 [18, 60]（自动容错顺序，18 和 60 颠倒也能正确处理）
Range<Integer> ageRange = Range.between(60, 18);
// 2. 判断元素是否属于区间
System.out.println(ageRange.contains(25)); // true
System.out.println(ageRange.contains(70)); // false
// 3. 判断区间相对位置
System.out.println(ageRange.isAfter(10)); // true (10 小于区间的下界 18)
// 4. 区间重叠与交集计算
Range<Integer> targetRange = Range.between(50, 80);
if (ageRange.isOverlappedBy(targetRange)) {
Range<Integer> intersection = ageRange.intersectionWith(targetRange);
// 交集区间为: [50, 60]
System.out.println("交集: " + intersection);
}
}
}
true
false
true
交集: [50..60]
5、数据结构与容器
commons-lang3 针对 Java 原生集合与容器在数据结构表达上的不足，提供了多个轻量、实用且类型安全的扩展容器与工具。其中最核心的是元组（Tuple）接口族、不可变/可变元组，以及专门针对数组的操作工具 ArrayUtils。
在项目中直接引入标准的 commons-lang3 依赖即可体验上述数据结构与容器支持：
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.14.0</version>
</dependency>
5.1、元组容器：Pair 与 Triple（二元组与三元组）
在业务开发中，我们经常遇到一个方法需要返回 2 个或 3 个关联对象的情况（如：key-value 对、min-max 边界、成功状态-结果数据-错误信息）。原生 Java 必须自定义 DTO 类，而 commons-lang3 提供了优雅的元组方案。
5.1.1、核心API
- Pair<L, R>（二元组）
Pair.of(left, right)：创建不可变二元组。MutablePair.of(left, right)：创建可变二元组（支持通过 setLeft() / setRight() 修改值）。getLeft() / getKey()：获取左侧元素/键。getRight() / getValue()：获取右侧元素/值。
- Triple<L, M, R>（三元组）
Triple.of(left, middle, right)：创建不可变三元组。MutableTriple.of(left, middle, right)：创建可变三元组。getLeft() / getMiddle() / getRight()：获取对应位置的元素。
5.1.2、使用示例
import org.apache.commons.lang3.tuple.Pair;
import org.apache.commons.lang3.tuple.MutablePair;
import org.apache.commons.lang3.tuple.Triple;
public class TupleDemo {
public static void main(String[] args) {
// 1. 不可变二元组 Immutable Pair (只读，线程安全)
Pair<Integer, String> statusPair = Pair.of(200, "OK");
System.out.println("Code: " + statusPair.getLeft()); // 200
System.out.println("Message: " + statusPair.getRight()); // "OK"
// 2. 可变二元组 Mutable Pair (允许更新值)
MutablePair<String, Integer> userScore = MutablePair.of("Alice", 85);
userScore.setRight(95); // 修改分数为 95
System.out.println("New Score: " + userScore.getValue()); // 95
// 3. 不可变三元组 Immutable Triple (适合返回多重维度数据)
Triple<Boolean, String, Integer> result = getExecutionResult();
if (result.getLeft()) { // Success
System.out.println("Data: " + result.getMiddle() + ", Count: " + result.getRight());
}
}
// 模拟多返回值场景
private static Triple<Boolean, String, Integer> getExecutionResult() {
return Triple.of(true, "Process Complete", 42);
}
}
Code: 200
Message: OK
New Score: 95
Data: Process Complete, Count: 42
5.2、ArrayUtils（原生数组操作增强）
Java 原生数组固定长度、缺乏内置工具方法，且直接对 null 数组进行点号操作极易引发 NPE。ArrayUtils 是针对原生数组（包括对象数组和 8 种基本类型数组）功能最全的增强工具。
5.2.1、核心API
- 空安全与转换
isEmpty(Object[] array) / isNotEmpty：安全判断数组是否为 null 或长度为 0。nullToEmpty(T[] array)：若传入 null，安全转换为空数组，防止链式调用报错。toMap(Object[] array)：将二维数组直接安全转换为 Map（如 new String[][]{{“k1”, “v1”}, {“k2”, “v2”}}）。
- 元素动态增删与拼接
add(T[] array, T element) / addAll(T[] array1, T... array2)：追加元素/合并数组（底层会自动处理扩容并返回新数组）。remove(T[] array, int index) / removeAllOccurrences(T[] array, T element)：按索引或按值安全移除元素。
- 查找与翻转
contains(Object[] array, Object objectToFind)：查询数组中是否包含某个元素。indexOf(Object[] array, Object objectToFind)：获取元素的起始索引。reverse(T[] array)：就地翻转数组元素顺序。subarray(T[] array, int startIndexInclusive, int endIndexExclusive)：安全截取子数组（索引越界时会自动容错，不抛异常）。
5.2.2、使用示例
import org.apache.commons.lang3.ArrayUtils;
import java.util.Arrays;
import java.util.Map;
public class ArrayUtilsDemo {
public static void main(String[] args) {
String[] original = {"Java", "Python"};
// 1. 动态添加元素（返回新数组，自动解决原生数组固定长度限制）
String[] updated = ArrayUtils.add(original, "Go");
// ["Java", "Python", "Go"]
// 2. 数组截取与合并 (防越界)
String[] sub = ArrayUtils.subarray(updated, 0, 10); // 不会报 IndexOutOfBoundsException
String[] combined = ArrayUtils.addAll(updated, "C++", "Rust");
// 3. 查找与移除
if (ArrayUtils.contains(combined, "Python")) {
combined = ArrayUtils.removeElement(combined, "Python"); // 移除匹配到的第一个值
}
// 4. 就地翻转数组
ArrayUtils.reverse(combined);
// 5. 二维数组快速转 Map
Object[][] kvArray = {
{"host", "localhost"},
{"port", "8080"}
};
Map<Object, Object> configMap = ArrayUtils.toMap(kvArray);
System.out.println("Host: " + configMap.get("host")); // "localhost"
}
}
Host: localhost
扫一扫
1239
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
