📦 类型转换工具-ConvertUtil

ConvertUtil 是 Hutool 类型转换模块的核心工具类，提供了丰富的类型转换方法，支持几乎所有 Java 类型之间的转换。

🔧 核心方法

1. 基本类型转换

转换为字符串

// 转换为字符串，转换失败返回默认值
String str1 = ConvertUtil.toStr(123, "0"); // "123"

// 转换为字符串，转换失败返回null
String str2 = ConvertUtil.toStr(null); // null

// 转换为字符串，null返回"null"字符串
String str3 = ConvertUtil.toStrOrNullStr(null); // "null"

转换为数值类型

// 转换为int，转换失败返回默认值
Integer int1 = ConvertUtil.toInt("123", 0); // 123

// 转换为int，转换失败返回null
Integer int2 = ConvertUtil.toInt("abc"); // null

// 转换为long
Long long1 = ConvertUtil.toLong("123"); // 123L

// 转换为double
Double double1 = ConvertUtil.toDouble("123.45"); // 123.45

// 转换为BigDecimal
BigDecimal bigDecimal = ConvertUtil.toBigDecimal("123.45"); // new BigDecimal("123.45")

转换为布尔值

// 转换为boolean，支持true/false/yes/no/1/0等
Boolean bool1 = ConvertUtil.toBoolean("true"); // true
Boolean bool2 = ConvertUtil.toBoolean("yes"); // true
Boolean bool3 = ConvertUtil.toBoolean("1"); // true
Boolean bool4 = ConvertUtil.toBoolean("0"); // false

2. 数组转换

// 转换为字符串数组
String[] strArray = ConvertUtil.toStrArray("1,2,3"); // ["1", "2", "3"]

// 转换为int数组
Integer[] intArray = ConvertUtil.toIntArray("1,2,3"); // [1, 2, 3]

// 转换为原始类型byte数组
byte[] byteArray = ConvertUtil.toPrimitiveByteArray("1,2,3"); // [1, 2, 3]

3. 日期时间转换

// 转换为Date
Date date1 = ConvertUtil.toDate("2023-01-01");

// 转换为LocalDateTime
LocalDateTime localDateTime = ConvertUtil.toLocalDateTime("2023-01-01 12:00:00");

// 转换为Instant
Date instant = ConvertUtil.toInstant(1672531200000L);

4. 枚举转换

enum Status {
    SUCCESS, FAILURE
}

// 转换为枚举
Status status1 = ConvertUtil.toEnum(Status.class, "SUCCESS"); // Status.SUCCESS
Status status2 = ConvertUtil.toEnum(Status.class, 0); // Status.SUCCESS（按索引转换）

5. 集合转换

// 转换为List
List<?> list1 = ConvertUtil.toList("1,2,3"); // ["1", "2", "3"]

// 指定元素类型转换为List
List<Integer> list2 = ConvertUtil.toList(Integer.class, "1,2,3"); // [1, 2, 3]

// 转换为Set
Set<Integer> set = ConvertUtil.toSet(Integer.class, "1,2,3,1"); // [1, 2, 3]

6. Map转换

// 转换为Map
Map<?, ?> map1 = ConvertUtil.toMap(String.class, Integer.class, "a:1,b:2"); // {a=1, b=2}

// 指定Map类型转换
HashMap<String, Integer> map2 = ConvertUtil.toMap(HashMap.class, String.class, Integer.class, "a:1,b:2");

7. 泛型转换

// 使用TypeReference转换泛型类型
List<Map<String, Object>> list = new ArrayList<>();
Map<String, Object> map = new HashMap<>();
map.put("name", "test");
list.add(map);

// 转换为指定泛型类型
String json = "[{\"name\":\"test\"}]";
List<Map<String, Object>> result = ConvertUtil.convert(new TypeReference<List<Map<String, Object>>>() {}, json);

8. 编码转换

// 转换字符编码
String utf8Str = ConvertUtil.convertCharset("中文", "GBK", "UTF-8");

9. 全角半角转换

// 半角转全角
String sbcStr = ConvertUtil.toSBC("abc123"); // "ａｂｃ１２３"

// 全角转半角
String dbcStr = ConvertUtil.toDBC("ａｂｃ１２３"); // "abc123"

10. 数字格式转换

// 阿拉伯数字转英文
String english = ConvertUtil.numberToWord(123); // "one hundred twenty-three"

// 阿拉伯数字转中文
String chinese = ConvertUtil.numberToChinese(123.45, false); // "一百二十三点四五"

// 阿拉伯数字转中文大写金额
String money = ConvertUtil.digitToChinese(123.45); // "壹佰贰拾叁元肆角伍分"

// 中文金额转数字
BigDecimal number = ConvertUtil.chineseMoneyToNumber("壹佰贰拾叁元肆角伍分"); // new BigDecimal("123.45")

// 数字转精简表示
String simple = ConvertUtil.numberToSimple(1200); // "1.2k"

11. 时间单位转换

// 转换时间单位（1小时转换为分钟）
long minutes = ConvertUtil.convertTime(1, TimeUnit.HOURS, TimeUnit.MINUTES); // 60

12. 原始类型与包装类型转换

// 原始类型转包装类型
Class<?> wrapClass = ConvertUtil.wrap(int.class); // Integer.class

// 包装类型转原始类型
Class<?> unWrapClass = ConvertUtil.unWrap(Integer.class); // int.class

🎯 转换规则

ConvertUtil 遵循以下转换规则：

1. 基本类型优先：基本类型与包装类型之间自动转换
2. 字符串智能解析：支持多种格式的字符串解析，如日期、数值等
3. 集合自动拆分：字符串通过分隔符自动拆分为集合
4. Map自动解析：字符串通过键值对格式自动解析为Map
5. 枚举灵活转换：支持通过名称、索引等方式转换枚举
6. 空值安全处理：对null值进行安全处理，返回合理默认值

🚀 高级用法

静默转换

ConvertUtil 提供了静默转换方法，转换失败时返回默认值，无需处理异常：

// 静默转换，转换失败返回默认值
String str = ConvertUtil.convertQuietly(String.class, null, "default"); // "default"

// 泛型静默转换
List<String> list = ConvertUtil.convertQuietly(new TypeReference<List<String>>() {}, "invalid", new ArrayList<>());

强制转换

对于需要强制转换的场景，可以使用 convert 方法，转换失败时抛出异常：

// 强制转换，转换失败抛出ConvertException
Integer intVal = ConvertUtil.convert(Integer.class, "abc"); // 抛出ConvertException

📋 方法列表

方法签名	功能描述
toStr(Object value, String defaultValue)	转换为字符串，转换失败返回默认值
toInt(Object value, Integer defaultValue)	转换为int，转换失败返回默认值
toLong(Object value, Long defaultValue)	转换为long，转换失败返回默认值
toDouble(Object value, Double defaultValue)	转换为double，转换失败返回默认值
toBoolean(Object value, Boolean defaultValue)	转换为boolean，转换失败返回默认值
toDate(Object value, Date defaultValue)	转换为Date，转换失败返回默认值
toLocalDateTime(Object value, LocalDateTime defaultValue)	转换为LocalDateTime，转换失败返回默认值
toEnum(Class<E> clazz, Object value, E defaultValue)	转换为枚举，转换失败返回默认值
toList(Class<T> elementType, Object value)	转换为指定元素类型的List
toSet(Class<T> elementType, Object value)	转换为指定元素类型的Set
toMap(Class<K> keyType, Class<V> valueType, Object value)	转换为Map
convert(Class<T> type, Object value)	转换为指定类型，转换失败抛出异常
convertQuietly(Type type, Object value, T defaultValue)	静默转换为指定类型，转换失败返回默认值
toSBC(String input)	半角转全角
toDBC(String input)	全角转半角
numberToChinese(double number, boolean isUseTraditional)	阿拉伯数字转中文
chineseToNumber(String number)	中文数字转阿拉伯数字

💡 注意事项

1. 转换性能：对于频繁转换的场景，建议缓存转换结果，避免重复转换
2. 转换精度：浮点数转换为整数时会丢失小数部分，需注意精度问题
3. 日期格式：字符串转日期时，支持多种常见格式，如"yyyy-MM-dd"、"yyyy/MM/dd"等
4. 集合分隔符：默认使用逗号作为集合元素分隔符，可通过自定义转换器修改
5. Map键值分隔：默认使用冒号作为键值分隔符，逗号作为键值对分隔符

通过 ConvertUtil，可以大幅简化Java开发中的类型转换代码，提高开发效率和代码可读性。