手写UTF-8编解码器：从编码规则到边界测试的完整实现

UTF-8编码这块，说实话是个典型的“看着简单、写起来全是坑”的活儿。网上能搜到一大堆实现，真到自己动手，要处理非法序列、边界码点、代理区的时候，才知道水有多深。我这次在某个内部项目里需要处理一批用户昵称数据，要求不引入 iconv 之类的第三方库，全部手写，顺带把一批常用工具函数也自己撸了一遍。这篇文章就完整记录下这个 Day 3·3 的实现过程，从编码规则、代码实现到边界测试，尽量讲透。

1. 项目背景与设计目标

1.1 一个真实的痛点

事情的起因不复杂。我负责的内部系统需要接收一批旧版本客户端上传的字符串数据，然后做统一的清洗、落库和前端展示。旧系统一直用的是本地编码，转成 UTF-8 之后出了很多幺蛾子：有的字符串中间混了非法字节序列，有的码点直接落在代理区里，还有的统计字符数的时候数错，导致截断后出现半个汉字的情况。

现有的依赖解析库是有的，但项目部署环境为了瘦身，要求尽量去掉动态依赖。我看了下现有代码，其实核心逻辑并不多，正好好好梳理一遍，手写一个最小化的 UTF-8 编解码模块，配合几个高频工具函数，彻底解决这些问题。

1.2 设计目标与边界

在动手之前，我给自己定的目标很明确：

• 纯 C 语言实现，不引入任何第三方库，只依赖标准头文件。
• 支持 UTF-8 编码和解码，覆盖 1 到 4 字节格式。
• 对非法序列能给出明确错误标识，绝不明目张胆地把垃圾字节放行。
• 附带一批工具函数：字符数统计、按字符索引截断、字节转十六进制等。
• 模块尽量独立，接口简单，方便以后直接移植到其他项目。

我不打算做那种把所有非法情况都自动纠错的“智能”实现，因为在脏数据场景里，静默纠错往往比直接报错更可怕——你以为数据没问题了，其实是被悄悄替换了。我的策略是：能解析就解析，不能解析就返回错误码，由调用方决定怎么处理。

2. UTF-8 编码规则，先把它彻底讲透

2.1 设计动机与变长编码

UTF-8 是一种变长编码方案，把 Unicode 码点编码成 1 到 4 个字节。设计上最大的优点就是兼容 ASCII：0 到 127 的码点直接用单字节表示，和英文字母、数字、标点的 ASCII 编码完全一致。这也是为什么 UTF-8 能成为互联网传输的主流编码——任何老旧系统都不用改协议，就能无缝接收纯英文文本。

变长编码的代价也很明显：处理时不能简单用字节数判断字符数，必须从头逐个解析，要么就得额外维护字节数到字符数的索引。很多做字符串展示、截断、搜索的功能，都必须围绕这个特性重新设计。

2.2 四类格式与码点分段

UTF-8 的编码规则可以用一张表说清楚：

先说格式里的关键点。每个多字节字符的首字节，高位里连续几个 1 表示总共几个字节，然后是 1 个 0，再接有效数据位。后续的每个字节都以 10 开头，是专门给解码器定位用的“续字节标记”。这种设计有一个好处：从任意位置开始向后读，只要读到非 10 开头的字节，就能知道这是一个新字符的开头，不容易错位。

举个例子，“中”这个字的码点是 U+4E2D，二进制是 100111000101101，落在 3 字节区间。套进 1110xxxx 10xxxxxx 10xxxxxx 的格式，拆成三组：0100、111000、101101，对应十六进制就是 E4 B8 AD。很多人看到 UTF-8 编码结果里有 E4、B8 这种看起来很“随机”的字节，其实就是拆位再拼上模板前缀的结果。

理解这里的核心，其实是理解一个映射关系：码点的高位有效数据 -> 被拆分成若干组 6 位或 5 位的子串 -> 依次填进格式模板。编码器做的是这个拼装动作，解码器就是反过来拆。

3. 编码器实现：码点转字节序列

3.1 字符数统计函数（UTF-8 strlen）

先写最基础的字符数统计函数。C 标准库的 strlen 返回的是字节数，遇到中文会得到 3 倍的字面长度。我在这个项目里需要知道用户昵称到底有几个“字”，所以得自己实现一个按字符数统计的函数。

基本思路：遍历字节序列，遇到首字节就把该字符的完整字节数跳过，统计值加一。如果首字节是非法前缀，比如开头的字节是 10xxxxxx，说明字节流已经错位，这种场景需要按错误处理，避免死循环。

size_t utf8_strlen(const unsigned char *s, size_t len) { size_t count = 0; size_t i = 0; while (i < len) { unsigned char c = s[i]; size_t seq_len = 0; if (c < 0x80) { seq_len = 1; } else if ((c & 0xE0) == 0xC0) { seq_len = 2; } else if ((c & 0xF0) == 0xE0) { seq_len = 3; } else if ((c & 0xF8) == 0xF0) { seq_len = 4; } else { // 非法首字节：按一个“无效字符”处理，跳过 count++; i++; continue; } if (i + seq_len <= len) { count++; i += seq_len; } else { // 序列不完整，按无效字符处理 count++; break; } } return count; }

这个实现最需要注意的是i + seq_len <= len的边界判断。字符串如果在中途被截断，可能出现首字节说“我需要 3 个字节”，但实际只剩 1 个字节的情况。这时候不能盲目往后跳，否则会越界读取内存。

3.2 UTF-8 编码函数

编码函数的核心，就是把一个码点拆位，再填模板。我需要一个基础函数，输入是 Unicode 码点（uint32_t），输出是编码后的字节数组和长度。如果码点本身不合法，返回错误码。

int utf8_encode(uint32_t codepoint, unsigned char *out, size_t *out_len) { if (codepoint <= 0x7F) { out[0] = (unsigned char)codepoint; *out_len = 1; } else if (codepoint <= 0x7FF) { out[0] = (unsigned char)(0xC0 | (codepoint >> 6)); out[1] = (unsigned char)(0x80 | (codepoint & 0x3F)); *out_len = 2; } else if (codepoint <= 0xFFFF) { // 代理区码点不合法，单独校验 if (codepoint >= 0xD800 && codepoint <= 0xDFFF) { return -1; } out[0] = (unsigned char)(0xE0 | (codepoint >> 12)); out[1] = (unsigned char)(0x80 | ((codepoint >> 6) & 0x3F)); out[2] = (unsigned char)(0x80 | (codepoint & 0x3F)); *out_len = 3; } else if (codepoint <= 0x10FFFF) { out[0] = (unsigned char)(0xF0 | (codepoint >> 18)); out[1] = (unsigned char)(0x80 | ((codepoint >> 12) & 0x3F)); out[2] = (unsigned char)(0x80 | ((codepoint >> 6) & 0x3F)); out[3] = (unsigned char)(0x80 | (codepoint & 0x3F)); *out_len = 4; } else { return -1; } return 0; }

这里有几个关键判断，必须提一下。

• 为什么要特殊校验 0xD800 到 0xDFFF 区间？这是 UTF-16 的代理区，是为编码 Unicode 辅助平面字符预留的，在 Unicode 标准里本身就不是合法码点。直接把代理码点编成 UTF-8，会导致解码端得到不可识别的字符，我在实际数据里遇到过有人把 UTF-16 的代理字节直接丢进 UTF-8 流的情况，乱码很彻底。
• 最高合法码点是 0x10FFFF。这是 Unicode 标准定义的码点上限，超过这个值，5 字节、6 字节的所谓 UTF-8 扩展都是非标准的，必须拒绝。

边界情况：对于 0x10000 到 0x10FFFF 这个区间的码点，很多新手会误算移位。4 字节模板里第一个字节有效位是 3 位（11110xxx），实际只需要码点的第 18 到 20 位，所以是codepoint >> 18，然后逐次取低 6 位。这个位移我建议写完了用边界值逐个验证，别只看逻辑对就觉得稳了。

3.3 配套字节工具函数

除了编解码，我还顺手实现了几个工具函数。这些函数在调试 UTF-8 数据时特别有用，特别是在打印未知二进制内容时，能把每个字节的十六进制完整展示出来。

void bytes_to_hex(const unsigned char *data, size_t len, char *out) { static const char hex_digits[] = "0123456789ABCDEF"; size_t i; for (i = 0; i < len; i++) { out[i * 2] = hex_digits[data[i] >> 4]; out[i * 2 + 1] = hex_digits[data[i] & 0x0F]; } out[len * 2] = '\0'; }

另一个工具函数是把十六进制字符转成字节值，用于排查日志里打印出来的编码序列是否合法。这类函数代码量不大，但很能提升调试效率。我调试非法数据时，经常直接把一段字节打出来，跟正常数据的十六进制做对比，很快就能看出不是缺了 80 开头的前缀，就是多了一个非法字节。

4. 解码器实现：字节序列还原码点

4.1 基础解析函数

解码是编码的逆过程，难点不在拆位，在校验。我写了一个单字符解析函数，输入字节流指针和剩余长度，输出解析到的码点和实际消耗的字节数。

int utf8_decode(const unsigned char *buf, size_t len, uint32_t *codepoint, size_t *consumed) { if (len == 0) { return -1; } unsigned char c = buf[0]; if (c < 0x80) { *codepoint = c; *consumed = 1; return 0; } // 判断序列长度 size_t seq_len = 0; uint32_t cp = 0; if ((c & 0xE0) == 0xC0) { seq_len = 2; cp = c & 0x1F; } else if ((c & 0xF0) == 0xE0) { seq_len = 3; cp = c & 0x0F; } else if ((c & 0xF8) == 0xF0) { seq_len = 4; cp = c & 0x07; } else { return -1; } if (len < seq_len) { return -1; } // 逐个校验连续字节 for (size_t i = 1; i < seq_len; i++) { unsigned char cc = buf[i]; if ((cc & 0xC0) != 0x80) { return -1; } cp = (cp << 6) | (cc & 0x3F); } // 校验码点合法性 if (cp > 0x10FFFF) { return -1; } if (cp >= 0xD800 && cp <= 0xDFFF) { return -1; } // 校验 overlong（过长编码） if (seq_len == 2 && cp < 0x80) { return -1; } if (seq_len == 3 && cp < 0x800) { return -1; } if (seq_len == 4 && cp < 0x10000) { return -1; } *codepoint = cp; *consumed = seq_len; return 0; }

4.2 校验逻辑：坑在哪里

解码器的核心价值，全在校验逻辑上。我逐条说下这些校验在做什么，以及为什么不校验会出大事。

• 连续字节必须是 10 开头。这是最基本的校验，防止把任意字节拼进来。
• 码点不能超出 0x10FFFF。这个之前讲过了，是标准上限。
• 代理区必须拒绝。这个在生产环境特别容易踩坑，有些系统为了兼容 UTF-16，会在内部使用代理对表示辅助平面字符，转换时如果不做映射，直接把代理码点拼进 UTF-8，解码端拿到就是非法字符。
• 对应字节数太少却能解析出小码点，就是 overlong 编码。例如用 2 字节序列编码一个 ASCII 字符0xC1 0x81，逻辑上也能解析出码点 1，但是这种编码方式是冗余的，绝大多数标准实现要求拒绝。这里面有个安全考量：如果解码器接受 overlong，攻击者可能利用它绕过安全过滤，比如把/编码成 2 字节形式，有些粗心的文本处理逻辑就会识别不出路径分隔符。

顺便说一句，上面utf8_decode里的 overlong 检查逻辑比较朴素，属于“够用就好”的水平。更严格的做法是在解析头部时就检查范围上限，比如两个字节的序列，头部c & 0x1F的值至少应为 1，保证码点不小于 0x80。我这里的做法是用解析后的码点反查，逻辑更直观，也好懂。

4.3 安全截断函数

截断字符串是用户昵称、文章摘要场景的高频操作。核心难点在于不能按字节硬切，否则会截出半个汉字。我的实现思路：从字节流开头逐个解析字符，累计到目标字符数后，返回该位置的字节偏移，调用方直接按这个偏移做截断。

size_t utf8_safe_truncate_index(const unsigned char *s, size_t len, size_t char_limit) { size_t count = 0; size_t i = 0; while (i < len && count < char_limit) { unsigned char c = s[i]; size_t seq_len = 0; if (c < 0x80) { seq_len = 1; } else if ((c & 0xE0) == 0xC0) { seq_len = 2; } else if ((c & 0xF0) == 0xE0) { seq_len = 3; } else if ((c & 0xF8) == 0xF0) { seq_len = 4; } else { // 非法字节直接跳过，不计入字符数 i++; continue; } if (i + seq_len > len) break; i += seq_len; count++; } return i; }

这个函数有几个细节值得注意。第一，遇到非法首字节，我选择跳过而不是终止。这样能尽量从脏数据中恢复出有效文本。第二，返回的是字节偏移，不是字符数。调用方拿到这个偏移量后，可以直接用于memcpy截断。第三，循环退出条件里有count < char_limit，意味着最后一个字符如果刚好是完整字符，偏移量会停留在它的末尾，保证截断后的字符串是完整字符边界。

5. 完整测试：边界值、非法序列与性能

5.1 边界值测试

代码写完只是开始，真正的魔鬼都在测试里。我构造了一组边界码点，把编码、解码、再编码的往返都测了一遍，确保不丢数据。

边界值最容易出错的地方是 0x800 这个位置。0x7FF 编码是 2 字节，0x800 起就必须是 3 字节，而且三字节模板会自动生成开头字节 E0。这里注意 E0 后面跟随的字节有个范围要求：如果码点是 0x800，第二字节的合法值会是 A0 而不是 80。原因是需要避免 overlong，有些新手编码器在这个位置会输出 E0 80 80，这就是典型的错误编码。

5.2 非法序列测试

非法序列测试是我的重点，因为脏数据场景里这些都是实打实会出现的。我总结了一套常见非法输入，大家可以抄走直接当测试用例：

这里特别说一下 ED A0 80，它表面看是三字节格式，头部 ED 落在 1110 模板范围内，解码结果却是 0xD800。有些老的传输层代码会在中间层做 UTF-16 转换，如果不小心把 UTF-16 代理字节直接追加到 UTF-8 流里，就会出现这种数据。拒绝它不仅是标准要求，更是防止脏数据污染下游存储的防线。

5.3 工具函数验证

工具函数测试主要是确认字符统计和截断在混合文本场景下正确。我拿了一段混合数据做验证：一个中文字符（3 字节）、一个英文字母（1 字节）、一个 emoji（4 字节）、一个生僻汉字（4 字节），总共 4 个字符、12 个字节。utf8_strlen应当返回 4，utf8_safe_truncate_index设置字符数上限为 3 时，应当返回前 8 个字节的偏移量，这样截断后刚好是完整的“中文 + 英文字母 + emoji”，不会出现半个字符。

性能方面我做了个简单压测，准备了一段约 1MB 的文本，包含中英文混合，循环解码了一遍。手写解码器在不做复杂分支预测优化的情况下，耗时大概是每 100 字节 2 microsecond 左右，完全够用。当然这是在我自己的测试环境里跑的，具体数值参考即可，重点是没有明显瓶颈，说明逐字节解析的性能没有差到需要优化的程度。

6. 踩坑记录与个人体会

6.1 三个容易被忽略的坑

第一个坑：C 语言的char类型到底有没有符号。在实际测试中我一开始用了char*直接取字节，结果在高位字节上出了问题——某些编译器默认char是有符号的，取buf[0]后再用& 0xF0做比对，符号扩展会把整个掩码计算带偏。解决方法是统一使用unsigned char，或者在函数入口处做一次显式转换。这个坑坑过不少初学者，我自己也在这个地方耽误过一晚上。

第二个坑：边界长度判断一定要用len < seq_len而不是len <= seq_len。两次看似差不多，实际上如果剩余长度恰好等于序列长度，应该是合法输入，用<=就把最后一个完整的字符误杀了。我在测试用例里专门放了一个“恰好剩 3 字节、且是合法 3 字节序列”的用例，防止自己写出这种隐蔽错误。

第三个坑：静态缓冲区溢出。编码到缓冲区时，很多人图省事会直接声明char buf[4]，但 4 字节编码需要 4 个输出字节，如果某个函数的输出编码还会附带前缀或终结符，4 字节就不够用。我的建议是编码函数对外暴露size_t *out_len，让调用方自己确认输出缓冲区大小。要真图省事，宏定义#define UTF8_MAX_SEQ_LEN 4用起来也足够直观。

6.2 后续扩展方向

这套工具函数目前够用，但有三个方向是后续需要考虑的。

• 错误处理策略升级：现在解码遇到非法字节是返回错误码，由调用方决定。后续可以提供一个“替换模式”，遇到非法字节自动替换成 U+FFFD（替换字符），保证下游流程不会中断。
• 带状态增量解析：网络流式数据经常把一个字符拆在两个 TCP 包里传输，需要做一个带状态机的解析器，把上次解析到一半的字节序列暂存在内存里，等剩余字节到达后再拼接。
• 编解码单元测试自动化：建议用脚本生成一组随机的边界码点和非法序列，批量跑测试函数，避免依赖手写测试用例导致覆盖不全。我在这个项目中把用例固化成了一个测试文件，以后改代码直接回归测试，成本很低。

最后说点个人体会。手写 UTF-8 编解码，最大的收获不是“我不用第三方库了”，而是真正理解了 Unicode 和字节流之间的关系。以前用现成库的时候，看到乱码只会直觉地怀疑“是不是编码没转对”，做完这个模块后，我能直接看出来是 missing continuation byte 还是 overlong 编码。这种能力在排查线上数据问题时特别有用，别人还在翻日志，你已经能凭十六进制输出判断个八九不离十了。