干货：业务标识 vs 自动判据

在世修行2026-10-06 9:08

可选 template 参数：业务标识 vs 自动判据的绑定

一个参数，决定走哪条解析路

上传时可以带一个可选的 template。它是个业务标识：明确告诉引擎"这份文件用哪个模板插件解析"。不带，就退回自动判据去猜。

python 复制代码

item = {"p_FolderPath": folder, "p_TaskId": ...}
if template:
    item["template"] = template

引擎那侧：

python 复制代码

template = (json_data.get("p_template") or "").strip()
if not template:
    template = (item.get("template") or "").strip()   # HTTP 传的
if template:
    plugin = manager.by_id(template)   # 显式锁定
else:
    plugin = manager.auto_route(pdf)   # 自动识别

什么时候该带，什么时候不该

业务方自己知道是什么格式 → 带 template，指哪打哪，最稳。
业务方不知道 、靠系统猜 → 不带，让 recognizes 挨个试。

一个隐患：标识传了但不存在

如果 template 传了一个不在映射表里/没有对应插件的标识，怎么办？我们的规则是直接报错，不静默回退：

python 复制代码

# 显式指定了 template，却找不到插件 → 报 400，不猜
if template and manager.by_id(template) is None:
    raise HTTPException(status_code=400, detail="未知的业务标识，请检查")

宁可提示业务方改参数，也别让它当成"没指定"悄悄走了通用流程------那会解析出错还难查。

优先级要讲清楚

config.json 里的 p_template 优先于 HTTP 传的 template。也就是说：如果目录配置已经指定了模板，HTTP 参数就不生效。配置为准，参数是兜底。

一句话：template 是"业务语言到解析器"的绑定，显式传给最稳；传了却不知 → 报错，别猜。