PR查询：工具支持的对象格式变化时怎样改输入规范，先判断变化发生在哪一层，而不是急着改模板
📱 Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
🔗 /ce2dc900ab99.html
📄
PR查询：工具支持的对象格式变化时怎样改输入规范，先判断变化发生在哪一层，而不是急着改模板
对象格式变化后，改输入规范的正确顺序是：先确认新格式的最小必填字段，再把旧规范拆成“仍适用”和“必须迁移”两部分，最后用一个可回退的样本验证，而不是一次性全量替换。缺少完整数据或权限时，你仍能完成字段映射和单条试跑，但不能据此断定查询结果完整或工具已完全兼容。
先判断变化发生在哪一层，而不是急着改模板
对象格式变化通常落在三个位置：标识符写法、字段结构、批量提交的封装方式。三者对输入规范的影响不同。标识符从纯数字变成带前缀的字符串，属于值层变化；字段从平铺变成嵌套，属于结构层变化；批量文件从一行一条变成数组包裹，属于封装层变化。判断错层，改出来的规范会在下一轮又失效。
假设情境：某团队原来用一行一个域名做PR查询输入，现在上游改成交付一个JSON数组，每条记录含域名和来源标记。此时变化同时发生在结构层和封装层，值层未变。若只把分隔符换掉，字段映射仍然对不上。
缺少完整数据和权限时仍可执行的最小动作
没有全量样本、也没有生产权限时，不要停在那里等。可以做的动作是：从新格式中取一到三条脱敏记录，手工写出“新字段 → 旧字段”的映射表，再用一条记录跑通输入解析。这一步的结果决定下一步：如果映射表里出现旧规范没有对应位置的字段，说明需要新增占位规则；如果所有新字段都能落到旧字段上，说明只需改封装，不必动查询逻辑。
这个动作能验证的是解析是否走得通，不能推出查询覆盖是否完整、去重是否仍然正确、结果条数是否与旧格式一致。解析通过只说明输入层没报错，属于必要条件，不是充分条件。
把旧规范拆成保留项、迁移项和废弃项
改规范时最容易犯的错是整份重写，把原本正确的约束一起丢掉。更稳的做法是逐条标注：
- 保留项：与格式无关的约束，例如去重规则、空值跳过、字符集要求。这些不随对象格式变化，应原样保留。
- 迁移项：位置或写法变了但语义没变，例如域名从独立字段移入嵌套对象。需要改取值路径。
- 废弃项：新格式已不再提供的字段。不要用空值硬填，否则查询会把缺失当成有效输入。
标注完成后，先只改迁移项，保留项不动，废弃项显式报错。这样一旦结果异常，排查范围被限制在迁移项内。
用可回退的样本验证，并明确不能推出的结论
验证时保留旧格式的一条记录作为对照，用同一查询条件分别跑新旧输入。可观察的差异包括：命中条数、字段缺失提示、重复记录数。若新格式命中数明显少于旧格式，合理解释有多种：字段映射漏了一个维度、来源标记过滤掉了部分记录、或新格式本身覆盖范围就不同。命中数下降本身不能单独证明规范改错了，也不能证明工具不兼容。
只有当映射表、解析日志和对照结果三者指向同一处差异时，才把该处判定为规范缺陷并回改。回改后重跑同一条对照记录，确认差异收敛，再考虑扩大样本。这个顺序保证每次改动都有可归因的证据。
把新规范写成可执行条目，而不是描述性说明
规范落地时，写成能被程序或人工直接执行的条目，例如：字段路径用records[].domain表示，空值处理写“缺失即拒绝该条并记录行号”，而不是写“注意字段可能为空”。可执行条目让下一位执行者不必重新推断你的意图。若涉及具体品牌工具的字段名、按钮位置或当前支持范围，需要以该工具的实际文档为准核对，不要凭旧教程推断。
最后确认一件事：新规范是否保留了回退到旧格式的入口。保留回退入口，格式再次变化时你只需改映射层，不必重写整条输入链路。
