Lucene80DocValuesConsumer 五种类型源码阅读顺序

阅读这5个方法的顺序，绝对不能按照代码中出现的物理顺序（Numeric → Binary → Sorted → SortedNumeric → SortedSet），而应该按照依赖关系和复用链条来读。

推荐的阅读顺序是：Numeric → Binary → Sorted → SortedNumeric → SortedSet。

这个顺序正好对应了 Lucene DocValues 从"原子类型"到"组合类型"的构建过程。以下是具体的阅读路线图：

第一步：读 addNumericField + writeValues （基石）

• 地位：所有数值编码的根基。
• 阅读重点 ：不要只看 addNumericField 那几行壳子，必须深入 writeValues 这个200多行的私有方法。理解 GCD 计算、MinMaxTracker、BlockPacked vs SingleBlock 的决策逻辑、IndexedDISI 位图写入。
• 原因 ：这是整个 Consumer 中最重、最独立的编码实现。后面两个组合类型都会直接或间接调用它。不读懂这个，后面看到 writeValues 被调用时就会卡住。

第二步：读 addBinaryField + CompressedBinaryBlockWriter （独立分支）

• 地位：与 Numeric 完全正交的另一条原子类型线。
• 阅读重点 ：LZ4 压缩块的分块策略、临时文件 tempBinaryOffsets 的使用模式、长度编码的偷位优化（allLengthsSame）。
• 原因：它和 Numeric 没有任何复用关系，是一条独立的编码管线。放在第二步读，是因为它的复杂度仅次于 Numeric，且后续不会被其他方法复用，读完就可以"放下"。

第三步：读 addSortedField + doAddSortedField + addTermsDict （词典基石）

• 地位：所有有序类型的根基。
• 阅读重点 ：doAddSortedField 中的序数编码（DirectWriter）、addTermsDict 中的前缀编码字典、writeTermsIndex 中的反向索引。注意它如何写 docsWithField 位图（和 Numeric 类似但独立实现）。
• 原因 ：Sorted 是 SortedSet 的基础。不读懂字典结构和序数映射，读 SortedSet 时就会对 addTermsDict(values) 这一行感到困惑。

第四步：读 addSortedNumericField （Numeric 的组合扩展）

• 地位：Numeric + 地址表。
• 阅读重点 ：看它如何一行调用 writeValues 复用 Numeric 编码，然后只在多值时追加一个 DirectMonotonicWriter 地址表。
• 原因 ：此时你已经读过 writeValues，所以这个方法的核心逻辑一眼就能看穿。你会把注意力集中在"地址表是怎么补上去的"这个增量知识上，而不是重新理解数值编码。

第五步：读 addSortedSetField （终极组合体）

• 地位：Sorted + SortedNumeric 的组合。
• 阅读重点 ：
  • 单值分支：如何用 SortedSetSelector.wrap() 伪装成 Sorted 并委托给 doAddSortedField
  • 多值分支：序数编码（复用 Sorted 模式）+ 地址表（复用 SortedNumeric 模式）+ 字典（复用 addTermsDict）
• 原因 ：这是复用链条的终点。只有在前四个都读完的情况下，你才能体会到这个方法"短"的真正含义------它不是在写编码，而是在组装前面已经实现的组件。

📌 总结：一张依赖图

addNumericField ──→ writeValues ←── addSortedNumericField
                        │
addBinaryField          │  (独立，无复用)
                        │
addSortedField ──→ doAddSortedField ←── addSortedSetField(单值)
      │                    │
      └──→ addTermsDict ←──┘←── addSortedSetField(多值)

按这个顺序读，每一步都只引入增量知识，不会遇到"这个方法调了什么我还没看过的东西"的情况。这也是为什么我之前说它们不是"最简单"而是"最聪明地偷懒"------阅读顺序本身就是理解这种偷懒设计的最佳路径。