1. Header到底重要在哪增量文件的起点先说一个我自己的经历。早几年我给某个内部系统做版本升级方案为了省带宽研究了一圈增量更新工具最后选定Xdelta3。当时项目模型很简单旧版本1.2MB新版本1.4MB直接全量下发要跑1.4MB用Xdelta3生成增量后只有200KB左右。线上效果很理想直到有一天运维反馈说下载的解压失败报告VCDIFF头不合法我才被迫把目光从效率指标挪到文件本身开始一行一行啃Xdelta3的头部解析代码。为什么Header值得单独拿出来看因为增量文件虽然整体结构复杂但解码器的第一个动作就是读Header。这一块读对了后面的delta窗口、指令表、地址缓存才能正常衔接读错了哪怕文件其他部分再标准解码器也是直接拒绝。换句话说Header是解码器的第一道关卡也是格式自描述信息的集中地。对于看源码的同学Xdelta3的Header处理集中在两个函数里解码端xd3_decode_hdr、编码端xd3_encode_hdr。它们对应的数据模型就是xd3_hdr结构体。这篇文章就围绕这三个点展开从结构体定义、字段含义、解码流程、编码流程到实战验证把整个Header部分拆清楚。2. xd3_hdr结构体拆解16字节的信息密度2.1 从VCDIFF格式说起Xdelta3生成的增量文件遵循VCDIFF格式这是一套面向二进制差异的通用格式规范。VCDIFF文件最开头不是直接进delta数据而是有一段固定格式的文件头用来告诉解码器这个文件是不是VCDIFF、版本是多少、有没有二级压缩器、有没有应用自定义头。Xdelta3源码里用xd3_hdr来承载这些内容typedef struct _xd3_hdr { uint8_t vcd_magic[4]; uint8_t hdr_ven; uint8_t hdr_flags; uint8_t sec_type; uint16_t sec_id; const uint8_t *appheader; usize_t appheader_size; } xd3_hdr;一眼看过去前四个字段加一起才七字节加上两个可选字段通常不过十几字节。但整个增量的解码路径全部依赖这几个字节的取值。所以理解xd3_hdr本质是理解这份文件头的信息布局。2.2 魔数与版本号为什么靠它们做二次校验vcd_magic[4]存的是VCD\0四个字节其中最后一个字节是0x00。这是VCDIFF格式的签名解码器在DEC_HDRMAGIC阶段就会做比较。有人可能会问文件扩展名不就已经说明格式了吗为什么还要魔数因为扩展名可以随便改网络传输也可能把文件内容覆盖了。魔数是解码器在字节流层面做的第一道可信校验任何自称VCDIFF的文件开头必须能对上这四个字节。版本号hdr_ven在Xdelta3里固定是0。当前VCDIFF规范只有这一个版本值源码里也直接做了判断不是0就返回错误。这个设计其实很务实格式演进时版本号可以平滑升级旧解码器遇到新版本会明确报错而不是瞎猜。我在实际项目里遇到过一种情况某个上游工具生成的文件版本号字段被填了1结果下游解码器全部拒绝排查半天才发现是对方实现的magic问题。这提醒我们魔数版本号的组合校验是格式兼容性最基本的保障。2.3 三个标志位一字节塞下所有开关hdr_flags是一个字节Xdelta3定义了三个位标志位值含义VCD_DECOMPRESS0x01增量数据经过次级压缩器压缩VCD_CODETABLE0x02Header中包含次级压缩器类型与编号VCD_APPHEADER0x04Header中包含应用自定义数据注意一个细节VCD_DECOMPRESS表示的是增量数据段被压缩过而VCD_CODETABLE表示的是文件头里带了压缩器标识。这两个标志经常一起出现但逻辑上并不等价。文件头带压缩器ID说明作者认为解码端需要知道用什么算法去解增量段但理论上也可以约定好默认算法不写这个字段。Xdelta3的编码端会把它们同步设置解码端却要分开判断。读源码时第一反应可能是为什么不合并成一个标志真正实现过才知道合并标志会牺牲自描述性因为解码器必须同时知道有没有压缩和用什么压缩两件事拆开反而干净。2.4 sec_type与sec_id只有在需要时才出现的次级压缩器信息sec_type占一字节sec_id占两字节大端序。它俩表示的是次级压缩器的类型和编号只在hdr_flags置了VCD_CODETABLE时才写入文件。这里有一个工程上的讲究Header结构体里这两个字段始终存在但实际写入文件时是条件字段解码端必须根据标志位决定是否读取。这种结构体字段固定、文件字段可选的设计在解析类代码里特别常见。好处是内存模型稳定坏处是码农容易在写编解码代码时漏掉条件判断我后面会专门讲这个坑。sec_type为0时表示自定义的次级压缩器非0时对应内置类型。sec_id是16位由各个实现自行约定。对大多数使用场景来说Xdelta3默认不使用次级压缩器这两个字段不会出现在文件里所以很多人跑完整个流程都没见过它们。想深挖的同学可以直接给编码端传XD3_SECONDARY标志强制把次级压缩器信息写进Header。2.5 appheader应用私有元数据的存放点appheader指针指向的是文件内部的一段数据appheader_size记录它的字节数。它相当于VCDIFF留给应用的便利贴可以放源文件哈希、版本号、平台信息、签名等任何元数据。它在文件中的位置紧跟在Header的固定字段之后、第一个Window之前。解码端读到这里时只是把指针指向stream-next_in位置并把大小记录下来并不复制内容。之后应用层可以决定要不要校验这段数据。我实际做版本升级时会把旧包SHA-256的前16字节塞进appheader。这样客户端解压增量前可以先校验源文件是否匹配不匹配就直接放弃解压避免解到一半才发现数据错乱。这个做法成本非常低但能省掉很多脏数据引发的排查时间。3. 解码端源码逐行看xd3_decode_hdr的状态机3.1 为什么用状态机而不是直接读很多同学第一次看xd3_decode_hdr会被状态机绕晕。它没有一次性把N个字节读进来而是定义一个dec_state每处理完一个字段就转移一次状态。原因很简单解码器的输入不保证一次性给全。比如网络流场景可能一次只到了3个字节而Header需要12字节。如果按全部读完再处理的写法就得频繁处理差几个字节、等下一批的边界逻辑。状态机则把这个问题化解为当前进度和下次从哪个状态继续配合Xdelta3的输入流循环每个片段到达后都能从上次位置接着走不需要大块缓冲区等待。这也是解压缩库常见的写法宁可多switch几次状态也不要假设输入一定够。3.2 从DEC_HDRMAGIC到DEC_HDRFLAGS下面是比较常见的一版解码主循环骨架static int xd3_decode_hdr(xd3_stream *stream) { const uint8_t *inp stream-next_in; int err; for (;;) { switch (stream-dec_state) { case DEC_HDRMAGIC: if (stream-avail_in 4) { ... } // 等待更多输入 if (memcmp(inp, VCD, 3) ! 0) return XD3_INVALID_INPUT; inp 4; stream-dec_state DEC_HDRVER; break; case DEC_HDRVER: if (stream-avail_in 1) { ... } stream-hdr_ven *inp; if (stream-hdr_ven ! 0) return XD3_INVALID_INPUT; stream-dec_state DEC_HDRFLAGS; break; case DEC_HDRFLAGS: if (stream-avail_in 1) { ... } stream-hdr_flags *inp; if (stream-hdr_flags VCD_CODETABLE) stream-dec_state DEC_SECONDARY; else stream-dec_state DEC_APPHEADER; break; // ... } } }关键点有几个。首先第一个DEC_HDRMAGIC比对不是memcmp(inp, VCD\0, 4)而是先比对VCD三个字符、再跳过第四个字节。这个差异看起来无关紧要其实是为了兼容部分历史实现有些工具生成的增量文件第四个字节并不是严格的0x00但前三个字符一定是VCD。源码选择只校验前三个字符等于在严格性和兼容性之间取了中间值。其次HDRFLAGS做完立即分叉。如果VCD_CODETABLE置位就进入次级压缩器字段读取否则直接跳到appheader处理。这里没有对VCD_DECOMPRESS单独分支因为解码端只有在见到VCD_CODETABLE时才需要读sec_type和sec_id而VCD_DECOMPRESS更多是留给后续窗口解码阶段用的标记。3.3 读取sec_type与sec_id的边界处理case DEC_SECONDARY: if (stream-avail_in 1) { ... } stream-sec_type *inp; stream-dec_state DEC_SECONDARY_ID; break; case DEC_SECONDARY_ID: if (stream-avail_in 2) { ... } stream-sec_id (*inp 8) | *(inp 1); inp 2; stream-dec_state DEC_APPHEADER; break;两字节大端序对多数习惯了小端的工程师来说要稍微转个弯。Xdelta3在设计时没有跟随主机字节序而是统一用大端序写入文件为的是跨平台一致性。假如这里用了本机字节序在某主机上生成的增量文件另一个平台解码时就乱套了。所以凡是涉及文件格式的整数字段统一字节序是基本素养。这里还必须注意dec_state DEC_SECONDARY_ID这个转移。如果缓冲区只有1字节第一段读完第二段进入等待状态等下一个输入切片到达直接从DEC_SECONDARY_ID开始而不是重新回到DEC_SECONDARY。否则sec_type会被重复读取sec_id却永远凑不齐两个字节。3.4 appheader的变长读取与缓冲区限制case DEC_APPHEADER: if (stream-hdr_flags VCD_APPHEADER) { if (stream-avail_in 1) { ... } stream-appheader_size *inp; if (stream-appheader_size XD3_MAX_APPHEADER) return XD3_INVALID_INPUT; if (stream-avail_in stream-appheader_size) { ... } stream-appheader inp; inp stream-appheader_size; } stream-dec_state DEC_WININD; return 0;这里用的是单字节长度所以appheader最多255字节。对存哈希或版本号来说通常够用但不适合塞大段元数据。源码里还有一个XD3_MAX_APPHEADER上限强制校验即便长度值本身合法超过上限也会拒绝。这属于典型的防呆设计数据再合理也得卡一道硬边界。读到appheader之后状态变成DEC_WININDHeader阶段结束。后面就是Window区包括源窗口长度、目标窗口长度、delta指令、地址缓存等那是另一篇文章的内容了。3.5 解码端源码的经验小结把xd3_decode_hdr整体看下来我提炼出几个通用经验VCDIFF头不是必须一次性读齐的状态机设计让它可以应对任意分片到达所有跨平台整数字段都按大端序存储解析时小心字节序标志位决定有没有、字段值决定是什么两者分工明确每个跳转状态都必须对应一个明确的读取量漏一个状态就会导致整个流错位。4. 编码端看回去xd3_encode_hdr如何把结构写进文件4.1 编码端与解码端必须严格对称看完了解码再回头看编码会轻松很多因为逻辑完全是镜像的。static int xd3_encode_hdr(xd3_stream *stream, xd3_output *head) { xd3_output *out; /* 先分配、再按顺序写入 */ if (stream-hdr_flags VCD_APPHEADER) { // 写入 appheader_size appheader 数据 } if (stream-hdr_flags VCD_CODETABLE) { // 写入 sec_type(1字节) sec_id(2字节) } // 最后写入 magic、version、flags }有人可能疑惑为什么编码端先把可选的appheader、sec_id写进输出最后才写magic和flags这不破坏文件顺序吗关键在于输出缓冲区的组织方式和内存布局。Xdelta3的编码器先把所有数据片段都append到输出链表里最后再整体按逻辑顺序写出。由于可选字段的长度是动态的appheader长度不固定编码器选择先把它们算好、填好再通过一次收尾操作把固定字段安排在最终缓冲区的头部。这样既避免反复移动大块内存又保证了解码端读取顺序的正确性。从解码端视角看解码时总是先读magic、再读version、再读flags然后根据flags决定读不读sec字段。因此编码端必须把固定字段安排在最前面可选字段紧跟其后。这个先写可选、后写固定的实现技巧本质上只是为了减少内存拷贝而不是改变文件布局。4.2 标志位组合逻辑别漏写VCD_DECOMPRESS编码端设置hdr_flags的过程通常分散在配置阶段。比较典型的场景是调用方通过xd3_set_appheader设置应用数据于是编码器置上VCD_APPHEADER调用方通过xd3_set_secondary_compressor设置次级压缩器于是编码器置上VCD_CODETABLE同时标记VCD_DECOMPRESS。我在实际项目里踩过一个很典型的坑自己写了个封装函数把次级压缩器的sec_type和sec_id写好了但忘了置VCD_CODETABLE标志。结果解码端看到flags没有VCD_CODETABLE就不会去读sec字段文件里后面那些字节全被当成Window数据解析直接崩。这个问题在编码端往往不容易发现因为生成时自己知道结构只有放到解码器里跑一遍才暴露出写与读不同步的问题。经验是凡是手动构造Header字段唯一可靠的验证方式就是用独立的解码器去解析。自己写的编码器配合自己写的解码器经常会因为同一个bug而相互掩盖。4.3 写入顺序与输出链表结构Xdelta3的xd3_output是一个简单的输出链表每个节点都指向前一个节点是为了方便头部插入。编码时每个字段的写入都通过xd3_emit_byte、xd3_emit_bytes这类接口完成。它们不关心最终文件里字段的绝对偏移只负责把数据追加到对应节点。整个过程结束后编码器会把整条链表按逻辑顺序串起来生成最终增量文件。如果你自己在调试时打印head链表会发现appheader的节点可能在magic节点之前被创建但最终输出顺序由编码器统一调整不会影响格式正确性。5. 其他值得留意的细节5.1 Header解析的容错策略与安静失败Xdelta3在Header解析阶段遇到错误时几乎一律返回XD3_INVALID_INPUT不会打印日志也不会尝试修复输入。这个策略初看有点粗暴细想却很合理Header数据量极小一旦有字节错误后续内容基本不可信与其半推半就地解析造成更大的数据损坏风险不如直接拒绝。讲两个影响判断的细节vcd_version ! 0时返回错误。这个错误本身无可厚非但如果文件只是追加了新的扩展字段旧解码器直接拒绝就破坏了向后兼容。VCDIFF选用了版本号为0的定义等于把演进空间封死了。实践中的应对是要么保持版本号不变把新信息塞进appheader要么换用新的文件扩展名避免旧解码器误判。sec_type非0时表示内置压缩器但Xdelta3内置几类压缩器的支持是编译期决定的。如果你的解码库没有编译进该压缩器的支持Header解析能通过后面解Window时才会报错。这个错存在延迟性排查时要双向确认文件Header里写了什么库是否支持。5.2 为什么建议把源文件校验信息放在appheader前面提到我会把源文件哈希塞进appheader。展开看一下实现逻辑增量解码前客户端需要先拿到源文件如果源文件跟生成增量时用的源文件不一致解码结果必然错误。与其解到一半报地址越界不如一开始就检查appheader里的哈希。这里有一个微妙点appheader是应用层数据Xdelta3不会自动校验它。也就是说放哈希只是约定了我们自己做的校验格式层面并不强制。好处是灵活坏处是如果解码端没有实现这套校验放了也是白放。团队内部约定好协议即可。5.3 Header字节流验证方法最后分享一个最实用的验证手段。不管你是复用现成工具生成增量文件还是自己写了编码器拿到文件后第一时间用十六进制编辑器看前16字节56 43 44 00 00 00 ...对照规则偏移字节含义0-356 43 44 00VCD\0魔数400版本号500flags无特殊标记6...后续Window数据如果flags是0x04说明有appheader那么第6字节是appheader长度第7字节起是应用数据。如果flags是0x02说明有次级压缩器信息第6字节是sec_type第7-8字节是sec_id。这个手工校验法在排错时特别管用大概三分钟就能确定Header写得对不对。6. 从Header看增量格式设计的通用思路分析完Xdelta3的Header值得退一步总结一下这种二进制格式的通用设计逻辑。第一固定字段在前、可选字段在后。magic、version、flags是每个VCDIFF必有的所以放在最前面sec_type、sec_id、appheader是可选字段由flags决定是否出现。这种布局让解码器可以先读少量字节确定后续结构再决定要不要继续读非常节省解析成本。第二自描述信息要冗余但不过度。魔数是冗余的确保不是其他格式version也是冗余的确保解码器知道如何解释后面的内容flags则是索引告诉解码器哪些字段出现、哪些字段缺席。三者的冗余层次不同缺一不可。第三应用数据与格式数据分离。appheader是留给应用的自留地Xdelta3核心只保存和透传不理解和校验。这样既保证了格式的通用性又给了业务方扩展空间。很多格式设计者喜欢把业务字段揉进核心结构体里Xdelta3的做法更干净。第四状态机是解析器最好的朋友。InputStream不保证一次给全状态机天然适合接着上次继续读的场景。以后自己写解析器别再用一次性读满的假设状态机虽然在代码量上略多但健壮性提升是实打实的。 
长河君 · 2026/10/22 16:29:44 · 阅读 1.2k Xdelta3 Header源码拆解：VCDIFF增量文件头格式与解码实现
1. Header到底重要在哪增量文件的起点先说一个我自己的经历。早几年我给某个内部系统做版本升级方案为了省带宽研究了一圈增量更新工具最后选定Xdelta3。当时项目模型很简单旧版本1.2MB新版本1.4MB直接全量下发要跑1.4MB用Xdelta3生成增量后只有200KB左右。线上效果很理想直到有一天运维反馈说下载的解压失败报告VCDIFF头不合法我才被迫把目光从效率指标挪到文件本身开始一行一行啃Xdelta3的头部解析代码。为什么Header值得单独拿出来看因为增量文件虽然整体结构复杂但解码器的第一个动作就是读Header。这一块读对了后面的delta窗口、指令表、地址缓存才能正常衔接读错了哪怕文件其他部分再标准解码器也是直接拒绝。换句话说Header是解码器的第一道关卡也是格式自描述信息的集中地。对于看源码的同学Xdelta3的Header处理集中在两个函数里解码端xd3_decode_hdr、编码端xd3_encode_hdr。它们对应的数据模型就是xd3_hdr结构体。这篇文章就围绕这三个点展开从结构体定义、字段含义、解码流程、编码流程到实战验证把整个Header部分拆清楚。2. xd3_hdr结构体拆解16字节的信息密度2.1 从VCDIFF格式说起Xdelta3生成的增量文件遵循VCDIFF格式这是一套面向二进制差异的通用格式规范。VCDIFF文件最开头不是直接进delta数据而是有一段固定格式的文件头用来告诉解码器这个文件是不是VCDIFF、版本是多少、有没有二级压缩器、有没有应用自定义头。Xdelta3源码里用xd3_hdr来承载这些内容typedef struct _xd3_hdr { uint8_t vcd_magic[4]; uint8_t hdr_ven; uint8_t hdr_flags; uint8_t sec_type; uint16_t sec_id; const uint8_t *appheader; usize_t appheader_size; } xd3_hdr;一眼看过去前四个字段加一起才七字节加上两个可选字段通常不过十几字节。但整个增量的解码路径全部依赖这几个字节的取值。所以理解xd3_hdr本质是理解这份文件头的信息布局。2.2 魔数与版本号为什么靠它们做二次校验vcd_magic[4]存的是VCD\0四个字节其中最后一个字节是0x00。这是VCDIFF格式的签名解码器在DEC_HDRMAGIC阶段就会做比较。有人可能会问文件扩展名不就已经说明格式了吗为什么还要魔数因为扩展名可以随便改网络传输也可能把文件内容覆盖了。魔数是解码器在字节流层面做的第一道可信校验任何自称VCDIFF的文件开头必须能对上这四个字节。版本号hdr_ven在Xdelta3里固定是0。当前VCDIFF规范只有这一个版本值源码里也直接做了判断不是0就返回错误。这个设计其实很务实格式演进时版本号可以平滑升级旧解码器遇到新版本会明确报错而不是瞎猜。我在实际项目里遇到过一种情况某个上游工具生成的文件版本号字段被填了1结果下游解码器全部拒绝排查半天才发现是对方实现的magic问题。这提醒我们魔数版本号的组合校验是格式兼容性最基本的保障。2.3 三个标志位一字节塞下所有开关hdr_flags是一个字节Xdelta3定义了三个位标志位值含义VCD_DECOMPRESS0x01增量数据经过次级压缩器压缩VCD_CODETABLE0x02Header中包含次级压缩器类型与编号VCD_APPHEADER0x04Header中包含应用自定义数据注意一个细节VCD_DECOMPRESS表示的是增量数据段被压缩过而VCD_CODETABLE表示的是文件头里带了压缩器标识。这两个标志经常一起出现但逻辑上并不等价。文件头带压缩器ID说明作者认为解码端需要知道用什么算法去解增量段但理论上也可以约定好默认算法不写这个字段。Xdelta3的编码端会把它们同步设置解码端却要分开判断。读源码时第一反应可能是为什么不合并成一个标志真正实现过才知道合并标志会牺牲自描述性因为解码器必须同时知道有没有压缩和用什么压缩两件事拆开反而干净。2.4 sec_type与sec_id只有在需要时才出现的次级压缩器信息sec_type占一字节sec_id占两字节大端序。它俩表示的是次级压缩器的类型和编号只在hdr_flags置了VCD_CODETABLE时才写入文件。这里有一个工程上的讲究Header结构体里这两个字段始终存在但实际写入文件时是条件字段解码端必须根据标志位决定是否读取。这种结构体字段固定、文件字段可选的设计在解析类代码里特别常见。好处是内存模型稳定坏处是码农容易在写编解码代码时漏掉条件判断我后面会专门讲这个坑。sec_type为0时表示自定义的次级压缩器非0时对应内置类型。sec_id是16位由各个实现自行约定。对大多数使用场景来说Xdelta3默认不使用次级压缩器这两个字段不会出现在文件里所以很多人跑完整个流程都没见过它们。想深挖的同学可以直接给编码端传XD3_SECONDARY标志强制把次级压缩器信息写进Header。2.5 appheader应用私有元数据的存放点appheader指针指向的是文件内部的一段数据appheader_size记录它的字节数。它相当于VCDIFF留给应用的便利贴可以放源文件哈希、版本号、平台信息、签名等任何元数据。它在文件中的位置紧跟在Header的固定字段之后、第一个Window之前。解码端读到这里时只是把指针指向stream-next_in位置并把大小记录下来并不复制内容。之后应用层可以决定要不要校验这段数据。我实际做版本升级时会把旧包SHA-256的前16字节塞进appheader。这样客户端解压增量前可以先校验源文件是否匹配不匹配就直接放弃解压避免解到一半才发现数据错乱。这个做法成本非常低但能省掉很多脏数据引发的排查时间。3. 解码端源码逐行看xd3_decode_hdr的状态机3.1 为什么用状态机而不是直接读很多同学第一次看xd3_decode_hdr会被状态机绕晕。它没有一次性把N个字节读进来而是定义一个dec_state每处理完一个字段就转移一次状态。原因很简单解码器的输入不保证一次性给全。比如网络流场景可能一次只到了3个字节而Header需要12字节。如果按全部读完再处理的写法就得频繁处理差几个字节、等下一批的边界逻辑。状态机则把这个问题化解为当前进度和下次从哪个状态继续配合Xdelta3的输入流循环每个片段到达后都能从上次位置接着走不需要大块缓冲区等待。这也是解压缩库常见的写法宁可多switch几次状态也不要假设输入一定够。3.2 从DEC_HDRMAGIC到DEC_HDRFLAGS下面是比较常见的一版解码主循环骨架static int xd3_decode_hdr(xd3_stream *stream) { const uint8_t *inp stream-next_in; int err; for (;;) { switch (stream-dec_state) { case DEC_HDRMAGIC: if (stream-avail_in 4) { ... } // 等待更多输入 if (memcmp(inp, VCD, 3) ! 0) return XD3_INVALID_INPUT; inp 4; stream-dec_state DEC_HDRVER; break; case DEC_HDRVER: if (stream-avail_in 1) { ... } stream-hdr_ven *inp; if (stream-hdr_ven ! 0) return XD3_INVALID_INPUT; stream-dec_state DEC_HDRFLAGS; break; case DEC_HDRFLAGS: if (stream-avail_in 1) { ... } stream-hdr_flags *inp; if (stream-hdr_flags VCD_CODETABLE) stream-dec_state DEC_SECONDARY; else stream-dec_state DEC_APPHEADER; break; // ... } } }关键点有几个。首先第一个DEC_HDRMAGIC比对不是memcmp(inp, VCD\0, 4)而是先比对VCD三个字符、再跳过第四个字节。这个差异看起来无关紧要其实是为了兼容部分历史实现有些工具生成的增量文件第四个字节并不是严格的0x00但前三个字符一定是VCD。源码选择只校验前三个字符等于在严格性和兼容性之间取了中间值。其次HDRFLAGS做完立即分叉。如果VCD_CODETABLE置位就进入次级压缩器字段读取否则直接跳到appheader处理。这里没有对VCD_DECOMPRESS单独分支因为解码端只有在见到VCD_CODETABLE时才需要读sec_type和sec_id而VCD_DECOMPRESS更多是留给后续窗口解码阶段用的标记。3.3 读取sec_type与sec_id的边界处理case DEC_SECONDARY: if (stream-avail_in 1) { ... } stream-sec_type *inp; stream-dec_state DEC_SECONDARY_ID; break; case DEC_SECONDARY_ID: if (stream-avail_in 2) { ... } stream-sec_id (*inp 8) | *(inp 1); inp 2; stream-dec_state DEC_APPHEADER; break;两字节大端序对多数习惯了小端的工程师来说要稍微转个弯。Xdelta3在设计时没有跟随主机字节序而是统一用大端序写入文件为的是跨平台一致性。假如这里用了本机字节序在某主机上生成的增量文件另一个平台解码时就乱套了。所以凡是涉及文件格式的整数字段统一字节序是基本素养。这里还必须注意dec_state DEC_SECONDARY_ID这个转移。如果缓冲区只有1字节第一段读完第二段进入等待状态等下一个输入切片到达直接从DEC_SECONDARY_ID开始而不是重新回到DEC_SECONDARY。否则sec_type会被重复读取sec_id却永远凑不齐两个字节。3.4 appheader的变长读取与缓冲区限制case DEC_APPHEADER: if (stream-hdr_flags VCD_APPHEADER) { if (stream-avail_in 1) { ... } stream-appheader_size *inp; if (stream-appheader_size XD3_MAX_APPHEADER) return XD3_INVALID_INPUT; if (stream-avail_in stream-appheader_size) { ... } stream-appheader inp; inp stream-appheader_size; } stream-dec_state DEC_WININD; return 0;这里用的是单字节长度所以appheader最多255字节。对存哈希或版本号来说通常够用但不适合塞大段元数据。源码里还有一个XD3_MAX_APPHEADER上限强制校验即便长度值本身合法超过上限也会拒绝。这属于典型的防呆设计数据再合理也得卡一道硬边界。读到appheader之后状态变成DEC_WININDHeader阶段结束。后面就是Window区包括源窗口长度、目标窗口长度、delta指令、地址缓存等那是另一篇文章的内容了。3.5 解码端源码的经验小结把xd3_decode_hdr整体看下来我提炼出几个通用经验VCDIFF头不是必须一次性读齐的状态机设计让它可以应对任意分片到达所有跨平台整数字段都按大端序存储解析时小心字节序标志位决定有没有、字段值决定是什么两者分工明确每个跳转状态都必须对应一个明确的读取量漏一个状态就会导致整个流错位。4. 编码端看回去xd3_encode_hdr如何把结构写进文件4.1 编码端与解码端必须严格对称看完了解码再回头看编码会轻松很多因为逻辑完全是镜像的。static int xd3_encode_hdr(xd3_stream *stream, xd3_output *head) { xd3_output *out; /* 先分配、再按顺序写入 */ if (stream-hdr_flags VCD_APPHEADER) { // 写入 appheader_size appheader 数据 } if (stream-hdr_flags VCD_CODETABLE) { // 写入 sec_type(1字节) sec_id(2字节) } // 最后写入 magic、version、flags }有人可能疑惑为什么编码端先把可选的appheader、sec_id写进输出最后才写magic和flags这不破坏文件顺序吗关键在于输出缓冲区的组织方式和内存布局。Xdelta3的编码器先把所有数据片段都append到输出链表里最后再整体按逻辑顺序写出。由于可选字段的长度是动态的appheader长度不固定编码器选择先把它们算好、填好再通过一次收尾操作把固定字段安排在最终缓冲区的头部。这样既避免反复移动大块内存又保证了解码端读取顺序的正确性。从解码端视角看解码时总是先读magic、再读version、再读flags然后根据flags决定读不读sec字段。因此编码端必须把固定字段安排在最前面可选字段紧跟其后。这个先写可选、后写固定的实现技巧本质上只是为了减少内存拷贝而不是改变文件布局。4.2 标志位组合逻辑别漏写VCD_DECOMPRESS编码端设置hdr_flags的过程通常分散在配置阶段。比较典型的场景是调用方通过xd3_set_appheader设置应用数据于是编码器置上VCD_APPHEADER调用方通过xd3_set_secondary_compressor设置次级压缩器于是编码器置上VCD_CODETABLE同时标记VCD_DECOMPRESS。我在实际项目里踩过一个很典型的坑自己写了个封装函数把次级压缩器的sec_type和sec_id写好了但忘了置VCD_CODETABLE标志。结果解码端看到flags没有VCD_CODETABLE就不会去读sec字段文件里后面那些字节全被当成Window数据解析直接崩。这个问题在编码端往往不容易发现因为生成时自己知道结构只有放到解码器里跑一遍才暴露出写与读不同步的问题。经验是凡是手动构造Header字段唯一可靠的验证方式就是用独立的解码器去解析。自己写的编码器配合自己写的解码器经常会因为同一个bug而相互掩盖。4.3 写入顺序与输出链表结构Xdelta3的xd3_output是一个简单的输出链表每个节点都指向前一个节点是为了方便头部插入。编码时每个字段的写入都通过xd3_emit_byte、xd3_emit_bytes这类接口完成。它们不关心最终文件里字段的绝对偏移只负责把数据追加到对应节点。整个过程结束后编码器会把整条链表按逻辑顺序串起来生成最终增量文件。如果你自己在调试时打印head链表会发现appheader的节点可能在magic节点之前被创建但最终输出顺序由编码器统一调整不会影响格式正确性。5. 其他值得留意的细节5.1 Header解析的容错策略与安静失败Xdelta3在Header解析阶段遇到错误时几乎一律返回XD3_INVALID_INPUT不会打印日志也不会尝试修复输入。这个策略初看有点粗暴细想却很合理Header数据量极小一旦有字节错误后续内容基本不可信与其半推半就地解析造成更大的数据损坏风险不如直接拒绝。讲两个影响判断的细节vcd_version ! 0时返回错误。这个错误本身无可厚非但如果文件只是追加了新的扩展字段旧解码器直接拒绝就破坏了向后兼容。VCDIFF选用了版本号为0的定义等于把演进空间封死了。实践中的应对是要么保持版本号不变把新信息塞进appheader要么换用新的文件扩展名避免旧解码器误判。sec_type非0时表示内置压缩器但Xdelta3内置几类压缩器的支持是编译期决定的。如果你的解码库没有编译进该压缩器的支持Header解析能通过后面解Window时才会报错。这个错存在延迟性排查时要双向确认文件Header里写了什么库是否支持。5.2 为什么建议把源文件校验信息放在appheader前面提到我会把源文件哈希塞进appheader。展开看一下实现逻辑增量解码前客户端需要先拿到源文件如果源文件跟生成增量时用的源文件不一致解码结果必然错误。与其解到一半报地址越界不如一开始就检查appheader里的哈希。这里有一个微妙点appheader是应用层数据Xdelta3不会自动校验它。也就是说放哈希只是约定了我们自己做的校验格式层面并不强制。好处是灵活坏处是如果解码端没有实现这套校验放了也是白放。团队内部约定好协议即可。5.3 Header字节流验证方法最后分享一个最实用的验证手段。不管你是复用现成工具生成增量文件还是自己写了编码器拿到文件后第一时间用十六进制编辑器看前16字节56 43 44 00 00 00 ...对照规则偏移字节含义0-356 43 44 00VCD\0魔数400版本号500flags无特殊标记6...后续Window数据如果flags是0x04说明有appheader那么第6字节是appheader长度第7字节起是应用数据。如果flags是0x02说明有次级压缩器信息第6字节是sec_type第7-8字节是sec_id。这个手工校验法在排错时特别管用大概三分钟就能确定Header写得对不对。6. 从Header看增量格式设计的通用思路分析完Xdelta3的Header值得退一步总结一下这种二进制格式的通用设计逻辑。第一固定字段在前、可选字段在后。magic、version、flags是每个VCDIFF必有的所以放在最前面sec_type、sec_id、appheader是可选字段由flags决定是否出现。这种布局让解码器可以先读少量字节确定后续结构再决定要不要继续读非常节省解析成本。第二自描述信息要冗余但不过度。魔数是冗余的确保不是其他格式version也是冗余的确保解码器知道如何解释后面的内容flags则是索引告诉解码器哪些字段出现、哪些字段缺席。三者的冗余层次不同缺一不可。第三应用数据与格式数据分离。appheader是留给应用的自留地Xdelta3核心只保存和透传不理解和校验。这样既保证了格式的通用性又给了业务方扩展空间。很多格式设计者喜欢把业务字段揉进核心结构体里Xdelta3的做法更干净。第四状态机是解析器最好的朋友。InputStream不保证一次给全状态机天然适合接着上次继续读的场景。以后自己写解析器别再用一次性读满的假设状态机虽然在代码量上略多但健壮性提升是实打实的。