json get page header index 于动态链接库

上周排查一个崩溃问题时，于动抓到的态链调用栈顶部写着 json_get_page_header_index，后面跟了个模块名 libdataflow.so。接库这事本身就挺有意思——一个看起来像 JSON 解析的于动函数，居然躺在动态链接库里，态链还跟"page header index"这种偏底层的接库概念绑在一起。

先把这个函数名拆开看。于动json_get_page_header_index 的态链命名风格很典型：动词开头，下划线分隔，接库语义堆叠。于动它想干的态链事大概是——从一段 JSON 里取出某个"页头"的索引值。但"页头"和"索引"凑一起，接库就说明这里的于动 JSON 不是随便什么配置，而是态链描述某种分页结构的元数据。比如一个文档流被切成若干页，接库每页有自己的 header 区域，这个函数负责定位当前页头在整体结构里的位置。

它为什么不在可执行文件里

放在 .so 里，意味着这段逻辑被多个进程共享。我翻了翻符号表，发现同一个库里还有 json_get_page_footer_index、json_validate_page_layout 这些兄弟函数。它们共同构成一套页面布局的 JSON 描述解析器。宿主程序可能是个渲染引擎，或者某种文档转换工具，主程序只负责调度，真正的解析规则全扔进动态库，方便热更新——改布局规则不用重新编译整个应用。

动态链接带来的一个直接后果是：崩溃时你拿到的地址是相对偏移，得先算出加载基址才能映射回源码行。当时我对着 0x7f3a... 这种地址愣了半天，最后用 dladdr 才把符号还原出来。这种体验很具体，不是读文档能替代的。

JSON 和页头的错位感

JSON 天生是树形结构，键值对嵌套。而"页头索引"是个线性概念——第几页、第几个 header。要把树拍平成序号，中间必然有个遍历和计数过程。我猜这个函数的实现大概是递归下降，遇到 type: "header" 的节点就累加计数器，直到匹配目标页号。问题在于，如果 JSON 里页的顺序和实际渲染顺序不一致，索引就会错位。这种 bug 特别隐蔽，因为 JSON 本身合法，解析也不报错，只是取出来的 index 指向了错误的页头。

我见过一个案例：某次更新后，PDF 导出的页眉全部偏移了一页。查到最后就是 json_get_page_header_index 在遍历时把封面页的 header 也算进去了，而封面在业务逻辑里不该有页眉。修复方式很粗暴——在 JSON 里给封面加了个 "skip_header": true，函数里加个判断。但根因是索引计算和业务语义脱节，动态库只认结构不认含义。

动态库调试的土办法

没有源码的时候，我习惯用 LD_PRELOAD 挂一个自己的 json_get_page_header_index，在里面打印入参和返回值，再调真正的实现。这样能快速确认是不是索引算错了。有一次发现传入的 JSON 字符串里，某个该有的 pages 数组变成了对象，导致遍历逻辑直接跳过，返回了 -1。上层没检查 -1，拿去当数组下标，段错误就来了。

这类函数的设计有个通病：返回值用 int，-1 表示失败，但调用方经常忘记判负。动态库的接口一旦定下来，改返回类型成本很高，只能靠文档和 code review 兜底。我现在的习惯是，凡是从 .so 里出来的 index 类返回值，先跟 -1 比一下再用。

那个崩溃最后定位到是并发调用导致的——两个线程同时改同一个 JSON 解析上下文，索引互相覆盖。动态库本身没做线程安全，调用方以为它是纯函数。这种坑，函数名里可看不出来。