Java StringBuilder appendCodePoint 怎样追加 Unicode 码点

如果文本里出现火箭、音乐符号或部分历史文字，直接把它们当成一个 char 处理很容易误判长度。Java 的 StringBuilder 应该使用 appendCodePoint(int)：把合法 Unicode 码点传进去，API 会按 UTF-16 规则追加对应字符。对大于 U+FFFF 的补充平面字符，length() 可能增加 2，但它仍然只代表 1 个 Unicode 码点。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/lang/StringBuilder.html

下面用一个很小的“状态标签拼接器”把写法、长度统计和输入边界一次串起来。

先做一个最小 Unicode 标签拼接器

核心写法只有一行：builder.appendCodePoint(codePoint)。码点用 int 表达，例如 0x1F680 是火箭符号；普通的前后缀仍然可以继续使用 append(String)。

public class CodePointLabel {
    public static void main(String[] args) {
        // 用 int 保存完整 Unicode 码点，而不是强转成单个 char
        int rocket = 0x1F680;
        StringBuilder builder = new StringBuilder("状态: ");

        // appendCodePoint 会按 UTF-16 规则追加这个码点
        builder.appendCodePoint(rocket);
        // 普通文本仍然用 append 追加
        builder.append(" ready");

        String text = builder.toString();
        System.out.println(text);
        // length 统计 UTF-16 char 单元，不等同于码点数量
        System.out.println("char length = " + text.length());
        // codePointCount 统计指定范围内的 Unicode 码点
        System.out.println("code point count = "
                + text.codePointCount(0, text.length()));
    }
}

这里不要把 0x1F680 先强制转换为 char。char 只有 16 位，无法独立容纳这个补充平面码点；appendCodePoint 才能根据码点生成需要的 UTF-16 表示。

理解 char 长度和码点数量为何不同

Java 的字符串和字符序列采用 UTF-16。基本多文种平面里的字符通常占一个 char，补充平面字符则由高代理项和低代理项组成一对 char。因此示例中“状态: 🚀 ready”的 length() 会把火箭的两个 UTF-16 单元算进去。

如果业务关心的是码点数量，应使用 codePointCount(0, text.length())；如果业务要计算数组容量、索引位置或截取范围，仍然必须先确认自己处理的是 char 索引还是码点索引。两者不能用一个数字互相替代。

把非法输入和补充平面边界写清楚

合法码点范围是 U+0000 到 U+10FFFF，但代理项区间不能作为独立 Unicode 标量值使用。调用前可以用 Character.isValidCodePoint 做输入保护；传入非法值时，appendCodePoint 会抛出 IllegalArgumentException，不要把它当成普通字符继续拼接。

static void appendChecked(StringBuilder builder, int codePoint) {
    // 先拒绝超出 Unicode 合法范围的外部输入
    if (!Character.isValidCodePoint(codePoint)) {
        throw new IllegalArgumentException("invalid Unicode code point");
    }
    // 合法码点可能需要一个或两个 UTF-16 char
    builder.appendCodePoint(codePoint);
}

还要注意，codePointCount 解决的是码点统计，不等于用户看到的“字素簇”数量。例如一个基础字母和组合音标可能包含多个码点。如果需求是光标移动、截断或按用户感知字符分割，就不能只靠 appendCodePoint 和 codePointCount 完成。

用编译命令完成最小验收

把上面的类保存为 CodePointLabel.java 后，可以用下面的命令编译。命令只负责验证示例的 Java 语法，正文中的输出是读者运行后应关注的统计关系，不把它当作本机截图证据。

# 查看当前 JDK，确认 java 与 javac 来自同一套环境
java -version

# 编译示例类；源文件名要与 public class 名称一致
javac CodePointLabel.java

# 运行后重点比较 char length 与 code point count
java CodePointLabel

验收时只看两点：火箭被完整追加，没有出现孤立代理项；包含火箭的文本中，length() 比码点数量多 1。若输入来自接口或文件，先做 isValidCodePoint 判断，再决定是拒绝、替换还是记录错误。

几个容易混淆的问题

直接 append 一个字符串不行吗？

已经有完整字符串时当然可以直接 append(String)。选择 appendCodePoint 的场景是：程序手里只有整数码点，或者需要明确表达“这里追加一个 Unicode 码点”，避免手工拼接代理项。

为什么 length 和用户看到的字符数经常不一样？

length() 是 UTF-16 单元数量，codePointCount 是码点数量，而用户感知字符还可能由多个码点组成。先确认业务要统计哪一层，再选对应 API。