指南
核心(hutool-core)
工具集合(util)

CharsetUtil

CharsetUtil是Hutool中用于处理字符集编码的工具类，提供了常用字符集常量定义、字符集转换、编码探测等功能，简化了Java中字符集相关的操作。

# 功能介绍

常用字符集常量：预定义了US_ASCII、ISO-8859-1、UTF-8、GBK等常用字符集
字符集转换：支持字符串和文件的字符集编码转换
字符集解析：安全地解析字符串为Charset对象，避免编码不支持异常
系统字符集获取：方便获取系统默认字符集和系统字符集
编码探测：支持通过输入流探测文件编码
编码器/解码器创建：提供配置好的字符集编码器和解码器

# 常量定义

常量名	描述	类型
NAME_US_ASCII	US-ASCII字符集名称	String
NAME_ISO_8859_1	ISO-8859-1字符集名称	String
NAME_UTF_8	UTF-8字符集名称	String
NAME_GBK	GBK字符集名称	String
US_ASCII	US-ASCII字符集对象	Charset
ISO_8859_1	ISO-8859-1字符集对象	Charset
UTF_8	UTF-8字符集对象	Charset
GBK	GBK字符集对象	Charset

# 核心方法

# 1. 字符集对象获取

# charset

将字符串转换为Charset对象，为空则返回默认字符集。

Charset charset = CharsetUtil.charset("UTF-8");
// 结果：UTF-8字符集对象

# parse

安全解析字符串编码为Charset对象，解析失败返回默认编码。

Charset charset1 = CharsetUtil.parse("UTF-8");
// 结果：UTF-8字符集对象

Charset charset2 = CharsetUtil.parse("INVALID_CHARSET");
// 结果：系统默认字符集对象

Charset charset3 = CharsetUtil.parse("INVALID_CHARSET", CharsetUtil.UTF_8);
// 结果：UTF-8字符集对象（自定义默认值）

# 2. 字符集转换

# convert(String, String, String)

转换字符串的字符集编码。

String str = "Hello, 你好！";
// 将UTF-8字符串转换为GBK编码
String gbkStr = CharsetUtil.convert(str, "UTF-8", "GBK");

# convert(String, Charset, Charset)

转换字符串的字符集编码，使用Charset对象。

String str = "Hello, 你好！";
// 将UTF-8字符串转换为GBK编码
String gbkStr = CharsetUtil.convert(str, CharsetUtil.UTF_8, CharsetUtil.GBK);

# convert(File, Charset, Charset)

转换文件的字符集编码。

File file = new File("test.txt");
// 将GBK编码文件转换为UTF-8编码
File utf8File = CharsetUtil.convert(file, CharsetUtil.GBK, CharsetUtil.UTF_8);

# 3. 系统字符集获取

# defaultCharsetName

获取系统默认字符集名称。

String charsetName = CharsetUtil.defaultCharsetName();
// 结果：如"UTF-8"或"GBK"等

# defaultCharset

获取系统默认字符集对象。

Charset charset = CharsetUtil.defaultCharset();

# systemCharsetName

获取系统字符集名称（Windows下默认为GBK，其他系统使用默认字符集）。

String charsetName = CharsetUtil.systemCharsetName();

# systemCharset

获取系统字符集对象。

Charset charset = CharsetUtil.systemCharset();

# 4. 编码探测

# detect

探测输入流的编码。

InputStream in = new FileInputStream("test.txt");
// 探测文件编码
Charset charset = CharsetUtil.detect(in);

# detect(int, InputStream, Charset...)

自定义缓存大小探测输入流的编码。

InputStream in = new FileInputStream("test.txt");
// 使用1024字节缓存探测文件编码，指定可能的编码候选
Charset charset = CharsetUtil.detect(1024, in, CharsetUtil.UTF_8, CharsetUtil.GBK);

# 5. 编码器/解码器创建

# newEncoder

创建配置好的CharsetEncoder实例。

// 创建UTF-8编码器，对不合法字符使用替换策略
CharsetEncoder encoder = CharsetUtil.newEncoder(CharsetUtil.UTF_8, CodingErrorAction.REPLACE);

# newDecoder

创建配置好的CharsetDecoder实例。

// 创建UTF-8解码器，对不合法字符使用替换策略
CharsetDecoder decoder = CharsetUtil.newDecoder(CharsetUtil.UTF_8, CodingErrorAction.REPLACE);

# 应用场景

# 1. 解决乱码问题

当读取文件或处理网络数据时遇到乱码，可以使用CharsetUtil进行纠正：

// 假设我们错误地将GBK编码的字符串以UTF-8读取，得到了乱码
String garbledStr = readWithWrongCharset(file, "UTF-8");

// 纠正乱码：先将乱码字符串以UTF-8编码回字节数组，再以GBK解码
String correctStr = CharsetUtil.convert(garbledStr, "UTF-8", "GBK");

# 2. 文件编码转换

批量转换文件编码，例如将项目中的GBK编码文件转换为UTF-8：

// 获取所有Java源文件
List<File> javaFiles = FileUtil.loopFiles("src", file -> file.getName().endsWith(".java"));

// 批量转换为UTF-8编码
for (File file : javaFiles) {
    CharsetUtil.convert(file, CharsetUtil.GBK, CharsetUtil.UTF_8);
}

# 3. 动态编码处理

在Web开发中，根据请求头动态处理字符编码：

// 从HTTP请求头获取字符编码
String charsetName = request.getCharacterEncoding();

// 安全解析编码，避免异常
Charset charset = CharsetUtil.parse(charsetName, CharsetUtil.UTF_8);

// 使用解析后的编码处理请求数据
request.setCharacterEncoding(charset.name());

# 4. 编码探测

在读取未知编码的文件时，使用编码探测功能：

File file = new File("unknown_encoding.txt");

// 探测文件编码
Charset charset = null;
try (InputStream in = new FileInputStream(file)) {
    charset = CharsetUtil.detect(in);
}

// 使用探测到的编码读取文件
String content = FileUtil.readString(file, charset);

# 注意事项

GBK兼容性：在不支持GBK编码的系统中，CharsetUtil.GBK可能为null，使用前请检查
编码转换原理：字符串编码转换的原理是先将字符串按源编码转换为字节数组，再按目标编码转换回字符串
编码探测限制：编码探测不是100%准确的，尤其是对于短文本或特殊编码
性能考虑：频繁的编码转换会影响性能，应尽量避免不必要的转换
安全问题：在处理不可信数据时，应谨慎配置编码错误处理策略，避免安全漏洞

# 总结

CharsetUtil提供了全面的字符集处理功能，简化了Java中字符集相关的操作。无论是解决乱码问题、转换文件编码，还是动态处理编码，都能提供简洁高效的解决方案。通过灵活使用CharsetUtil，可以大大减少字符集相关的错误，提高代码的可靠性和可维护性。

← ByteUtil EnumUtil→