如何利用String.codePoints()方法准确获取并处理包含复杂Unicode字符的字符串码点流？

本文共计933个文字，预计阅读时间需要4分钟。

`String.codePoints()` 是 Java 8 引入的一个用于正确处理 Unicode 字符（尤其是补充字符，即码点大于 `0xFFFF` 的字符）的关键方法。它返回一个 `IntStream`，其中每个元素是一个完整的 Unicode 码点（`int` 类型），而不是 `char` 类型（仅能表示 BMP 中的字符）。这样可以避免将代理对（surrogate pair）错误地成两个无效的 `char` 值。

为什么不能只用 charAt() 或 toCharArray()？

Java 的 char 是 16 位无符号整数，只能表示基本多文种平面（BMP，U+0000–U+FFFF）中的字符。超出该范围的字符（如大多数 emoji、古文字、部分数学符号）在 UTF-16 中以**代理对**（两个连续的 char：高代理 + 低代理）形式存储。例如：

• "?‍?"（程序员 emoji）实际由 4 个 char 组成：0xD83D 0xDC68 0x200D 0xD83D 0xDCBB（注意：中间有 ZWJ 连接符，共 5 个码点，但底层是多个代理对）
• "?"（U+20BB7，一个汉字）在字符串中占两个 char：0xD842 0xDFB7

若用 charAt(i) 遍历，会把代理对拆开，得到无意义的高位或低位代理值，导致乱码或 Character.isSurrogate() 判定异常。

使用 codePoints() 获取完整码点流

调用 str.codePoints() 返回 IntStream，每个 int 是一个合法 Unicode 码点（0x0000–0x10FFFF），自动合并代理对，跳过孤立代理。常用方式：

• 遍历所有码点：str.codePoints().forEach(cp -> System.out.printf("U+%04X%n", cp));
• 转为码点数组：int[] cps = str.codePoints().toArray();
• 过滤/映射处理：str.codePoints().filter(Character::isLetter).mapToObj(Character::toString).collect(Collectors.joining())
• 统计真实字符数（非 char 数）：long count = str.codePoints().count();（比 length() 更准确）

对比：codePoints() vs chars() vs getChars()

chars() 也返回 IntStream，但它只是将每个 char 强转为 int，不处理代理对——遇到增补字符仍会输出两个分离的代理值（如 0xD842 和 0xDFB7），不可用于语义化文本处理。
getChars() 和 toCharArray() 返回 char[]，同样暴露底层 UTF-16 编码细节，需手动检测代理对并组合，极易出错。

只有 codePoints() 在 API 层面屏蔽了编码细节，提供面向 Unicode 字符（grapheme cluster 的基础单元）的抽象。

注意：codePoints() 不处理组合字符或 emoji 序列

codePoints() 解决的是**单个 Unicode 字符（scalar value）** 的正确提取，但它不识别更高级的视觉单位，例如：

• "é" 可能是单个预组字符（U+00E9），也可能是 "e" + U+0301（组合用重音符）——codePoints() 会正确返回 1 或 2 个码点，但不会自动归一化
• "?‍❤️‍?‍?"（女同性恋亲吻 emoji）由多个码点 + ZWJ 连接符组成，codePoints() 会返回全部独立码点，但不将其视为一个“逻辑字符”

如需按用户感知的“字形”（grapheme cluster）切分，需借助 ICU4J 或 Java 9+ 的 java.text.BreakIterator（类型 GRAPHEME_CLUSTER），而非仅依赖 codePoints()。