Java DataOutputStream.writeUTF 超过长度限制时怎么办

我在处理 Java 二进制导出时遇到过一个很容易误判的异常：短文本一直能用 DataOutputStream.writeUTF，一旦字段变成长说明、堆栈或用户输入，就突然抛出 UTFDataFormatException。问题通常不在流没有打开，而在 writeUTF 写入的是 modified UTF-8，并且用两个字节记录后续字节数，编码结果超过 65535 字节就不能继续写。

官方 API 说明：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/io/DataOutputStream.html

短字段、内部小协议可以继续用 writeUTF/readUTF；可能超过边界的长文本，应改成“明确长度 + 标准 UTF-8 字节”，并让写入端与读取端一起切换，不能只替换一边。

先看清 writeUTF 的长度字段

writeUTF 不是把 Java 字符串长度直接写进文件。它先写一个两字节的长度值，再按 modified UTF-8 输出字符串内容。这个长度值表示实际写出的字节数，而不是 str.length()；一个字符可能对应多个字节，所以“字符数没有超过 65535”并不能说明写入一定安全。

Oracle 的 DataOutputStream 文档明确说明，modified UTF-8 编码后的内容超过 65535 字节时会抛出 UTFDataFormatException。因此排查时先看异常类型和字段内容，不要先把问题归因于文件系统或字符集名称。

用编码后的字节数提前判断

如果协议已经规定必须使用 writeUTF，可以在真正写流之前计算兼容的字节规模。下面的代码用一个临时的 ByteArrayOutputStream 让 Java 负责执行同一套 modified UTF-8 编码；成功后再把字符串写入正式流。这样做适合做边界判断，不会把临时字节当成最终协议数据。

import java.io.ByteArrayOutputStream;
import java.io.DataOutputStream;
import java.io.IOException;

public final class UtfFieldGuard {
    private UtfFieldGuard() {}

    public static boolean fitsWriteUtf(String value) throws IOException {
        // 临时流只用于复现 writeUTF 的编码和长度判断，不写入业务文件。
        try (ByteArrayOutputStream buffer = new ByteArrayOutputStream();
             DataOutputStream probe = new DataOutputStream(buffer)) {
            probe.writeUTF(value);
            return true;
        } catch (java.io.UTFDataFormatException ex) {
            // 编码后的载荷超过两字节长度字段能表达的范围。
            return false;
        }
    }
}

这个判断不会把多字节字符简单地按“一个字符一个字节”估算，也不会把标准 UTF-8 的结果误当成 modified UTF-8 的结果。真正写入时仍要处理 IOException，并在字段不适合 writeUTF 时进入明确的长文本分支。

短文本继续使用 writeUTF

当字段是协议中的短标识、枚举说明或有限长度的内部名称时，保留 writeUTF 的价值在于读写端简单，而且现有数据格式不需要迁移。关键是把它当成有边界的协议字段，而不是通用文本容器。

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;

public final class ShortTextRecord {
    public static void write(DataOutputStream out, String name) throws IOException {
        // 写入端与 readUTF 配对，字段必须保持在 writeUTF 可表达的范围内。
        out.writeUTF(name);
    }

    public static String read(DataInputStream in) throws IOException {
        // 读取顺序必须与写入顺序一致，不能用 readLine 替代 readUTF。
        return in.readUTF();
    }
}

如果这里的字段来自外部输入，建议在业务层先决定“拒绝、截断还是转成长文本协议”，不要等异常发生后再猜文件已经写了多少内容。对已有协议来说，拒绝并记录字段名通常比静默截断更容易恢复。

长文本的替代协议怎么写

长文本更适合先用标准 UTF-8 得到字节数组，再写入一个足够大的长度字段，最后写字节本身。示例使用四字节有符号整数保存长度，读取端也必须先读同样的四字节长度，再按同一种字符集还原字符串。

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.EOFException;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public final class LongTextRecord {
    private LongTextRecord() {}

    public static void write(DataOutputStream out, String value) throws IOException {
        // 标准 UTF-8 字节数才是协议中要传输和校验的长度。
        byte[] bytes = value.getBytes(StandardCharsets.UTF_8);
        out.writeInt(bytes.length);
        out.write(bytes);
    }

    public static String read(DataInputStream in) throws IOException {
        // 先读长度，再限制读取范围，避免把后续字段误当成长文本内容。
        int length = in.readInt();
        if (length 

这里的重点不是简单把 writeUTF 换成 writeInt，而是同时定义编码、长度字段、字段顺序和读取失败行为。readFully 在流提前结束时会抛出异常，避免返回一个悄悄缺字的字符串。

回滚路径和兼容边界

一旦已有文件或网络协议中使用了 writeUTF，就不要直接让新读取端把所有字段都改成 readInt + UTF-8。旧数据仍然按旧格式读取；新格式可以通过协议版本、记录类型或字段标记区分。

• 只影响短字段：继续使用 writeUTF/readUTF，增加长度预判。
• 新建长文本字段：直接定义长度加 UTF-8 字节，不让它经过 writeUTF。
• 需要兼容旧数据：先识别版本，再选择对应读取方法，保留旧格式回滚能力。
• 写入失败：不要把已经部分写入的流当成完整记录，按文件或消息边界废弃并重试。

我实际会把“字段是否可能超过边界”作为协议设计问题处理，而不是把异常捕获后重新调用一次 writeUTF。重复调用不会改变两字节长度字段的上限，只有改变字段格式或缩短数据才有意义。

常见问题

writeUTF 的 65535 是字符数吗？

不是。限制针对 modified UTF-8 编码后的字节数，字符数量和字节数量不能直接画等号。

能不能改用 writeChars 绕过限制？

writeChars 使用每个字符两个字节的写法，读写双方都要按同一格式处理；它不是把现有 readUTF 协议无缝扩容。是否采用要看协议对字符编码和体积的约束。

长文本方案能不能继续用 readUTF 读取？

不能直接混用。写入端如果写的是四字节长度和标准 UTF-8 字节，读取端必须先读取四字节长度，再读取对应字节并用 UTF-8 解码。

总结一下：writeUTF 的问题不是 Java 字符串突然失效，而是它本来就是带两字节长度字段的受限协议。短字段可以保留并提前判断；长文本则应把“长度 + 编码字节 + 配套读取”作为一个整体设计。