Java HexFormat 怎么在字节数组和十六进制文本间转换

Java 17 及以上不必再手写字符表或循环拼接十六进制字符串。java.util.HexFormat 已经提供完整的双向接口：formatHex(byte[]) 把字节数组变成文本，parseHex(CharSequence) 再把文本还原为新的 byte[]。

最小写法是复用 HexFormat.of()。需要冒号、空格、前缀或大写输出时，先创建带参数的 HexFormat，再用同一个实例负责格式化和解析。

官方 API 文档：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/HexFormat.html

默认格式就能完成双向转换

HexFormat.of() 使用小写字母，不添加分隔符、前缀和后缀。每个字节固定对应两个十六进制字符，因此字节的正负号表现不会影响输出宽度。

import java.util.Arrays;
import java.util.HexFormat;

public class HexRoundTrip {
    private static final HexFormat HEX = HexFormat.of();

    public static void main(String[] args) {
        byte[] source = {0x00, 0x2A, 0x7F, (byte) 0xA5, (byte) 0xFF};

        // 默认输出无分隔符的小写十六进制文本。
        String text = HEX.formatHex(source);

        // 使用同一格式实例把文本还原成新的字节数组。
        byte[] restored = HEX.parseHex(text);

        System.out.println(text);
        System.out.println(Arrays.equals(source, restored));
    }
}

上面得到的文本是 002a7fa5ff，比较结果为 true。0xA5 和 0xFF 在 Java 的 byte 中是负数，但 formatHex 仍按 8 位原始值生成 a5 和 ff。

冒号分隔和大写输出怎么配置

指纹、摘要和网络标识经常使用冒号分隔的大写形式。可以从 ofDelimiter(":") 开始，再调用 withUpperCase()：

import java.util.HexFormat;

public class FingerprintFormat {
    private static final HexFormat FINGERPRINT =
            HexFormat.ofDelimiter(":").withUpperCase();

    public static void main(String[] args) {
        byte[] digest = {0x01, 0x23, 0x45, 0x67, (byte) 0x89, (byte) 0xAB};

        // 输出形如 01:23:45:67:89:AB。
        String text = FINGERPRINT.formatHex(digest);

        // parseHex 会按冒号结构解析，十六进制字母本身不区分大小写。
        byte[] bytes = FINGERPRINT.parseHex(text.toLowerCase());

        System.out.println(text);
        System.out.println(bytes.length);
    }
}

withUpperCase() 控制输出风格，不会要求解析输入必须大写。parseHex 同时识别 0-9、a-f 和 A-F；真正必须一致的是冒号的位置。

前缀、后缀和分隔符必须匹配

withPrefix 与 withSuffix 作用于每一个字节值，而不是整段字符串。例如下面的格式会生成 0x00h 0x7Fh 0xA5h：

import java.util.HexFormat;

public class MarkedHex {
    private static final HexFormat MARKED = HexFormat.ofDelimiter(" ")
            .withPrefix("0x")
            .withSuffix("h")
            .withUpperCase();

    public static void main(String[] args) {
        byte[] source = {0x00, 0x7F, (byte) 0xA5};

        // 每个字节都会带上 0x 前缀和 h 后缀。
        String text = MARKED.formatHex(source);

        // 解析时同样要求每个字节都有对应前后缀。
        byte[] restored = MARKED.parseHex(text);

        System.out.println(text);
        System.out.println(restored.length);
    }
}

如果用 HexFormat.of() 去解析带冒号的文本，或者用带 0x 前缀的实例解析纯数字文本，都会抛出 IllegalArgumentException。因此格式定义最好与协议、文件格式或字段类型放在同一个类中，避免编码端和解码端各写一套。

只转换数组区间或直接写入 Appendable

formatHex 既能处理完整数组，也能处理左闭右开的索引区间。对于已有 StringBuilder、PrintStream 或其他 Appendable 的场景，还可以直接追加，避免先生成完整中间字符串。

import java.util.HexFormat;

public class HexSlice {
    private static final HexFormat HEX = HexFormat.ofDelimiter("-");

    public static void main(String[] args) {
        byte[] packet = {0x10, 0x20, 0x30, 0x40, 0x50};

        // 索引 1 包含，索引 4 不包含，结果对应 20-30-40。
        String middle = HEX.formatHex(packet, 1, 4);

        StringBuilder out = new StringBuilder("payload=");
        // 直接把选定区间追加到现有缓冲区。
        HEX.formatHex(out, packet, 1, 4);

        System.out.println(middle);
        System.out.println(out);
    }
}

区间越界会抛出 IndexOutOfBoundsException。如果目标 Appendable 在写入时发生 I/O 错误，API 会以 UncheckedIOException 抛出，因此面向流式输出的代码仍要保留异常边界。

解析失败通常是这三类结构问题

不要对未知输入直接执行全局 replace 删除标点，因为这会把“格式错误”悄悄改成另一组合法字节。对外部输入应先限制长度，再捕获解析异常并返回清楚的业务错误。

import java.util.HexFormat;

public final class HexInput {
    private static final int MAX_TEXT_LENGTH = 8192;
    private static final HexFormat COLON_HEX = HexFormat.ofDelimiter(":");

    public static byte[] parse(String text) {
        // 先限制外部输入，避免为超大文本分配过多数组空间。
        if (text == null || text.length() > MAX_TEXT_LENGTH) {
            throw new IllegalArgumentException("十六进制文本为空或过长");
        }

        try {
            // 保留严格格式检查，不静默删除错误字符。
            return COLON_HEX.parseHex(text);
        } catch (IllegalArgumentException ex) {
            throw new IllegalArgumentException("十六进制文本格式不正确", ex);
        }
    }

    private HexInput() {
        // 工具类不需要实例化。
    }
}

Java 版本和实例复用边界

HexFormat 从 Java 17 开始提供。若库代码还要运行在 Java 8 或 Java 11，直接引用该类会导致编译或运行兼容问题，应保留旧实现或提高最低运行版本，而不是在低版本环境中假设该 API 存在。

官方文档把 HexFormat 定义为不可变且线程安全的类。withDelimiter、withPrefix、withSuffix、withUpperCase 和 withLowerCase 都返回新的配置副本，所以可以把常用格式保存为 static final 并跨线程复用。它还是 value-based class，不应把实例用于身份敏感操作、同步锁或 == 比较；需要比较配置时使用 equals。

另一个容易混淆的点是 toHexDigits(int)。它用于固定宽度的原始类型转换，只考虑大小写参数，不使用 delimiter、prefix 和 suffix。字节数组的结构化输出应继续使用 formatHex。

import java.util.HexFormat;

public class MethodBoundary {
    public static void main(String[] args) {
        HexFormat format = HexFormat.ofDelimiter(":").withPrefix("0x");

        // 数组格式化会应用前缀和分隔符。
        String bytesText = format.formatHex(new byte[]{0x0A, 0x0B});

        // 原始 int 转换只使用大小写，固定返回八位十六进制数字。
        String intText = format.toHexDigits(255);

        System.out.println(bytesText);
        System.out.println(intText);
    }
}

常见问题

parseHex 能解析大小写混合的文本吗？

可以。十六进制字符解析不区分大小写，但分隔符、前缀和后缀仍必须与当前 HexFormat 配置匹配。

为什么 FF 解析后得到的 byte 是 -1？

Java 的 byte 是有符号 8 位类型，位模式 11111111 对应数值 -1。这不表示解析错误；再次格式化仍会得到 ff 或 FF。

HexFormat 能直接解析带空白的任意文本吗？

不能把它当作宽松清洗器。若格式使用空格分隔，应创建 HexFormat.ofDelimiter(" ")；若格式规定无分隔符，额外空白会被视为非法结构。

HexFormat 和 Integer.toHexString 有什么区别？

HexFormat 重点覆盖字节数组、格式参数和双向解析；Integer.toHexString 面向单个整数的无符号十六进制表示。处理协议载荷、摘要或二进制字段时，formatHex 与 parseHex 更直接。

实际项目中可以先为每种外部格式定义一个 static final HexFormat，再让编码与解析共用它。这样大小写只是展示选择，而分隔符、前缀和后缀则成为明确、可复查的格式契约。