干货：显式映射 vs 自动判据

显式映射 vs 自动判据：template 强制路由与禁用开关的取舍

两条路到同一个插件

用什么插件解析一份 PDF，有两条路：

1. 自动判据 ：遍历所有插件跑 recognizes，谁命中用谁。
2. 显式映射 ：HTTP 请求带 template 业务标识，或配置里写 p_template，直接按 ID 锁死指定插件。

两条路都能到插件，但语义完全不同。

显式映射的代码

# 优先 config.json 的 p_template，为空回退 HTTP 的 template
template = (json_data.get("p_template") or "").strip()
if not template:
    template = (item.get("template") or "").strip()

if template:
    plugin = manager.by_id(template)   # 显式按ID
else:
    plugin = manager.auto_route(pdf)   # 自动按recognizes

两者的取舍

• 自动判据：省事，不用配置，但遇到相似格式可能选错。
• 显式映射：确定，指哪打哪，但要多传一个参数。

关键矛盾：禁用开关在两条路上不同

我们设计的规则：禁用只拦自动判据，不拦显式映射。

# 自动路由：过滤掉禁用的
plugin = manager.auto_route(pdf, enabled_only=True)
# 显式路由：直接按ID，不过滤禁用
plugin = manager.by_id(template)

为什么？因为禁用是"自动识别时别选它"，更偏向"防误判"。而显式指定是用户明确点名，用户的意图不该被一个自动开关挡住。硬挡反而违背用户操作。比如某个模板暂时被禁用防误判，但用户就是要手动解析它，没理由拦。

一句话

自动判据追求省事，显式映射追求确定；禁用只管自动，不管显式，既防误判又不妨碍用户明确意图。

---