WordPress插件输入规范遇到对象格式变化时怎么改
📱 Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
🔗 /de94cc5454c7.html
📄
WordPress插件输入规范遇到对象格式变化时怎么改
先判断变化属于“同一语义换了写法”还是“新增了原规范未定义的对象类型”。前者通常只需扩展解析规则，后者必须先改输入契约，再改校验与错误提示，否则样本能过、批量数据一定出例外。
先分清两种格式变化，处理顺序完全不同
假设你维护一个批量导入插件，输入规范原本要求每行是 标题|分类|标签，标签用逗号分隔。某天上游开始输出 标题|分类|标签1;标签2，同时个别行出现 标题|分类|。这里其实是两个变化叠加：分隔符变了，空值也有了新的含义。
- 写法变化：字段数量、字段含义不变，只是分隔符或转义方式不同。此时可以增加兼容解析，保留旧格式分支。
- 对象类型变化：出现了原规范没有的字段，或者原字段开始承载结构化内容（如把纯文本标签换成带层级路径的标签）。此时兼容解析只能拖延问题，必须重新定义输入契约。
判断依据不是“样本能不能跑通”，而是把最近一批数据按字段拆开后，是否存在任何一种取值无法映射回原字段语义。只要存在，就属于对象类型变化。
先做一次字段映射，再决定改哪一层
把新旧输入各取若干行，列成三列：原字段、新写法、能否无损映射。能无损映射的，放进解析层做兼容；不能无损映射的，进入规范层讨论。
以假设情境为例：旧规范里“标签”是字符串数组，新数据里标签变成了 父级/子级 路径。如果业务上只需要展示，可以拆成两段存进原数组；如果后续要按层级筛选，就必须在输入规范里新增“标签路径”这个对象类型，而不是继续塞进字符串数组。
这个动作的结果会直接影响下一步：映射无损，改解析器即可，回归测试覆盖旧样本；映射有损，先改规范文档和字段定义，再改解析器，否则校验规则会和实际数据长期打架。
改输入规范时，先写清“不接受什么”
规范里只写“支持 A、B、C”不够，规模化后出例外的原因往往是没写拒绝条件。建议在规范中明确三类内容：
- 必填与可空：空字符串、缺失字段、占位符分别代表什么，是否允许。
- 转义与边界：分隔符出现在字段内容里时如何转义，是否允许嵌套分隔符。
- 版本标识：输入方是否能声明自己用的是哪一版格式。没有版本标识时，解析器只能靠猜测，例外会持续出现。
对应到插件实现，校验失败时应返回“第几行、哪个字段、期望什么、实际什么”，而不是只报“格式错误”。错误信息越具体，上游修正输入的成本越低，后续批量导入的例外率才可控。
用一组对照条件决定是否保留旧格式
是否继续兼容旧格式，取决于两个条件同时成立：旧格式的数据源仍在持续产出，且新旧格式能被同一个解析入口无歧义地区分。
如果旧数据源已经停止输出，只保留历史数据，那么更稳妥的做法是把历史数据一次性转换后归档，而不是让解析器长期维护双分支。双分支的代价是每次改校验规则都要回归两套样本，维护成本会随字段增加而上升。
如果新旧格式无法无歧义区分（例如同样是竖线分隔，但字段数量可能相同也可能不同），就不要靠猜测兼容，应要求输入方增加版本标识或改用显式字段名。
改完后验证什么，才算这一步结束
验证重点不是“新样本能导入”，而是旧样本、新样本、混合样本、边界样本四类都能得到预期结果。边界样本至少覆盖：空字段、字段内含分隔符、超长字段、字段数量多一个或少一个。
当某次导入的失败行数下降时，不能直接认定规范改对了。失败行数归零也可能是因为校验被放宽、错误被静默跳过，或者上游恰好只送了规整数据。合理解释还包括：样本量太小、上游临时清洗过数据、解析器把异常值映射成了默认值。要区分这些原因，需要同时看失败明细、默认值填充记录和字段分布，而不是只看一个总数。
把这次判断写成一句话留在规范里：本次变化属于写法变化还是对象类型变化，对应改了哪一层，哪类输入从此不再接受。下一轮上游再变格式时，这句话就是最快的判断起点。
