那个下午，我下定决心为我正在做的工具加上一个解析器。需求看着很直白：让它能吞下标准格式的追踪文件（OTLP / OpenInference），不管用户用的什么框架，都能把数据喂进来。我翻出规范文档，脑子里很快有了JSON结构的清晰蓝图——嵌套、大写的十六进制ID、Unix纳秒串——然后就打算照着这副脑图开写。
但在写第一行代码之前，我做了一件让自己有点烦的事：先把真实SDK跑出来的输出导出，和规范里的示例比一下。这一比，救了我一条命。我发现我脑子里装的几乎每一个假设都是错的。
我设想的是大写十六进制追踪ID、UnixNano格式的字符串时间戳，以及嵌套的resourceSpans结构——全部照抄规范。可真实SDK输出的是带0x前缀的ID、ISO格式的日期时间，以及一张扁平的数组。那份被我当作标准“OTLP-JSON”的规范示例，原来没有任何一个工具真的照着它生成数据。如果我真按自己的思维模型写完解析器，它会在我的手造测试用例上完美通过，然后在所有真实文件面前集体挂掉。那种“泛化能力”，从头假到尾。
这还不算完。第二轮对比给了我一个更大的教训。我原本假定用户的硬盘里都乖乖躺着追踪文件，等着被解析。可现实里，多数人根本没有这些文件，OpenInference自己的示例是用HTTP把span直接往仪表盘上发的。所以“把你的追踪文件发给我”这个前提本身就跑偏了。整件事里最有价值的产出不是一个解析器，而是一段三行代码的片段，让用户能先产生一个文件。一个没有附带“怎么造文件”指南的解析器，等于没人能用。
于是工作范围悄悄起变化：只支持真实SDK输出实际用到的那一种格式；碰到其他格式不默默失败，而是给出一条清晰的报错——“像这样转换”；再附上那段可以复制粘贴的代码片段，并且真的端到端跑一遍验证它，而不只跑解析器自己的单元测试。
我从这件事里再次捡起那条老教训：一份针对你想象中数据得出的正确结果，不代表它对这个世界真实抛出的数据有任何意义。在你去为数据构建工具之前，先动手看一眼真实的数据长什么样。今天的支持范围写得很显眼：只有一种导出格式得到直接支持；仪表盘或proto导出会收到转换提示，而不是沉默；检测引擎和它已知的局限没有改变——这一轮打磨的，只是入口那扇门，不是里面的探测器。
热门跟贴