模板方法+MQ智能派单：文档向量化服务架构重构实践

如果你维护过一个支持 PDF、Word、Markdown、HTML、TXT 等多种格式文档向量化的服务，大概率遇到过这种场面：新增一种格式时，打开那个号称“统一入口”的工厂类，往里再塞一个 if 分支。刚开始几个分支还挺整齐，等到格式超过七八种，你会发现工厂类已经不是“工厂”了，它更像是把解析、清洗、分块、向量化全部粘在一起的巨型胶水类。更难受的是，每次新增格式，你都得把“读取文件 -> 解析 -> 清洗 -> 分块 -> 向量化 -> 入库”这套流程在子类里重新复制一遍，稍有不慎就把某个环节的细节改错。

这篇文章记录的是我后来做的一次彻底重构：引入模板方法模式固定向量化流程的骨架，再用 MQ 的直连模式按 routingKey 做智能派单，把不同格式的文档拆成独立任务异步消费。整条链路还加上了 requestId 全链路追踪和 intent 意图字段，用来决定后续的精排和检索策略。文章会包含完整的架构设计思路、C++ 和 Java 的模板方法落地代码、MQ 直连模式与广播模式的选型取舍，以及我部署 MQ 时踩过的管理后台进不去的坑。适合正在做知识库向量化、RAG 检索服务，或者想优化文档解析吞吐的同学参考。

1. 单一工厂架构在向量化场景下的“变形”信号

1.1 分支爆炸：每加一种格式，工厂类就膨胀一圈

大多数项目的第一版是这么写的，我见过很多类似代码，自己也写过。以 Java 为例：

java复制public class DocumentVectorizeFactory {
    public VectorizeResult vectorize(String filePath) {
        String suffix = getSuffix(filePath);
        String text;
        if ("pdf".equals(suffix)) {
            text = pdfParser.parse(filePath);
        } else if ("docx".equals(suffix)) {
            text = docxParser.parse(filePath);
        } else if ("md".equals(suffix)) {
            text = mdParser.parse(filePath);
        } else if ("html".equals(suffix)) {
            text = htmlParser.parse(filePath);
        } else {
            throw new UnsupportedFormatException(suffix);
        }
        String cleaned = TextCleaner.clean(text);
        List<Chunk> chunks = ChunkSplitter.split(cleaned);
        List<float[]> vectors = EmbeddingService.embed(chunks);
        saveToVectorDB(vectors);
        return VectorizeResult.success(chunks, vectors);
    }
}

这种写法在只有两三种格式的时候确实简单，业务方催得紧时能快速上线。但一旦格式超过五种，问题就开始显性化。每新增一种格式，就往工厂里塞一个 else if 分支；Word 解析遇到编码问题想单独调整清洗规则，结果发现清洗逻辑是全局共用的，只能给清洗函数加一个 format 参数，再写 if (docx) { ... } 做特殊的清理。等你把 PDF 表格提取、Word 页眉页脚过滤、HTML 标签剔除这些逻辑全部堆进去，这个工厂类能拉到几百行，而且没有任何一个人敢动它。

1.2 流程被格式类型绑架：相同步骤在子类里反复复制

单一工厂架构的另一个副作用是流程被格式类型绑架。表面上看，工厂帮你选了“用什么解析器”，但这只解决了“解析”这一步。剩余的清洗、分块、向量化、入库，仍然和格式类型强耦合地写在同一个方法体里。一旦某个格式的解析结果需要特殊分块策略（比如 PDF 按版式分块、Markdown 按标题层级分块），你就得在分块器里再加一层 if。

后来我试图用策略模式去拆，给每个格式写一个完整的 Processor，代码变成这样：

java复制public class PdfProcessor {
    public void process(String filePath) {
        String text = pdfParser.parse(filePath);
        text = TextCleaner.clean(text);
        text = cleanPdfFooter(text);  // PDF 专属
        List<Chunk> chunks = PdfChunkSplitter.split(text);
        List<float[]> vectors = EmbeddingService.embed(chunks);
        saveToVectorDB(vectors);
    }
}

public class DocxProcessor {
    public void process(String filePath) {
        String text = docxParser.parse(filePath);
        text = TextCleaner.clean(text);
        text = cleanDocxHeader(text);
        List<Chunk> chunks = DefaultChunkSplitter.split(text);
        List<float[]> vectors = EmbeddingService.embed(chunks);
        saveToVectorDB(vectors);
    }
}

代码确实解耦了，但看不到简单的部分：每个 Processor 里都复制了“清洗 -> 分块 -> 向量化 -> 入库”这套几乎相同的主干逻辑。六个格式就有六份几乎一样的流程代码，只是中间某一步有差异。后续如果要在向量化前加一个“敏感信息过滤”，你得改六个类；如果要在入库后加一个“构建倒排索引”，你还得改六个类。这种重复比分支爆炸更隐蔽，因为每个类的行数都不多，但维护成本是乘数的。

1.3 同步调用成为批量向量化的瓶颈

工厂模式重构前的第三个问题，也是最容易被忽略的问题：整个过程是同步的。上层接口调用 vectorize() 时，调用方必须阻塞等待整个解析、分块、向量化、入库流程跑完，才能拿到结果。单篇文档还好，但知识库初始化、历史数据迁移、定时增量更新这些场景一来就是成百上千个文档，同步循环逐条处理会慢到让人怀疑人生。

我做过一次粗略统计：一份 50 页的 PDF，解析耗时约 1~2 秒，分块约 0.1 秒，向量化要看模型和 batch 大小，当时用 CPU 推理，单条文本向量化约 80 毫秒，一份文档分出来的 120 个 chunk 就是 9.6 秒，再加上入库写向量数据库的耗时，整篇文档跑完大约 12 秒。如果是 3000 份文档，同步跑就是 10 个小时。这显然不合理。异步化、并行化是必然选择，而 MQ 恰恰是解耦和削峰的好工具。

2. 模板方法：把文档向量化流程固化成流水线骨架

2.1 从“选处理器”到“定骨架”：思维转变

工厂模式解决的是“创建谁”的问题，模板方法解决的是“流程怎么固定”的问题。两者的关注点不一样，但可以很好地配合。重构时我的思路是这样的：不管什么格式，文档向量化的主干流程其实是固定的，都是“加载原始内容 -> 解析成文本 -> 清洗 -> 分块 -> 向量化 -> 入库”。格式差异只体现在“解析成文本”这一步，偶尔体现在“清洗”和“分块”的策略上。

模板方法模式正好匹配这个结构。基类定义好整个流程的骨架，并且用 final 或 non-virtual 锁死，子类只负责实现那些真正有差异的步骤。公共步骤放在基类里实现，差异步骤定义为虚函数或抽象方法下沉到子类。这样以后新增格式，只需要新增一个子类，实现解析逻辑，复用公共的清洗、分块、向量化、入库逻辑，主干流程一行都不用改。

2.2 六步流水线：哪些步骤固定，哪些步骤下沉

我把整个流程拆成了六步：

loadRawContent 之所以固定，是因为所有格式的原始文件读取方式都一样，区别只在于路径是 oss:// 还是 http://，这可以通过注册 url handler 来处理，不需要每个子类重复。cleanText 虽然叫“通用”，但 PDF 解析出来的文本经常带页脚页码，Markdown 解析出来的文本可能残留 # 和 **，这些不适合放在通用清洗里，所以我留了一个 postClean 钩子，子类有需要就覆写，没需要就用基类的空实现。Chunk 策略也类似：默认按固定 token 窗口切分，如果某个格式有更好的切分维度（比如 HTML 按标题、PDF 按版面），子类覆写 createChunkSplitter() 返回自己的 Splitter 实例即可。

这种设计最核心的价值是：公共逻辑只写一次，后续改一次生效。比如我要在向量化之前统一加一个“去除重复段落”的步骤，只需要改基类的 vectorize() 方法，所有格式的子类同时生效。这在原有的工厂/策略堆叠方案里是不可想象的。

2.3 C++/Java 落地示例：基类定义骨架，子类实现差异

我实际是用 C++ 写核心解析服务的，后来在 Java 网关侧也套了同一套模板思想。C++ 侧大致长这样：

cpp复制class DocumentVectorizer {
public:
    virtual ~DocumentVectorizer() = default;

    // 模板方法：锁死流程，子类不要重写
    void vectorize(const Document& doc) {
        std::string raw = loadRawContent(doc.uri());

        std::string text = parseToText(raw, doc.format());

        text = cleanText(text);
        text = postClean(text);   // 钩子，默认返回原文本

        auto splitter = createChunkSplitter();
        auto chunks = splitter->split(text);

        auto vectors = embedChunks(chunks);
        saveToVectorDB(doc, chunks, vectors);
    }

protected:
    // 子类必须实现：格式解析
    virtual std::string parseToText(const std::string& raw,
                                    DocumentFormat format) = 0;

    // 子类可选覆写：格式专属清洗
    virtual std::string postClean(const std::string& text) {
        return text;
    }

    // 子类可选覆写：自定义分块策略
    virtual std::shared_ptr<ChunkSplitter> createChunkSplitter() {
        return std::make_shared<DefaultChunkSplitter>();
    }

private:
    std::string loadRawContent(const std::string& uri) {
        // 公共逻辑：根据 uri 协议选择本地/OSS/HTTP 加载
    }

    std::string cleanText(const std::string& text) {
        // 公共逻辑：去掉乱码、压缩空白等
    }

    std::vector<std::vector<float>> embedChunks(
        const std::vector<Chunk>& chunks) {
        // 公共逻辑：加载 embedding 模型，按 batch 推理
    }

    void saveToVectorDB(const Document& doc,
                        const std::vector<Chunk>& chunks,
                        const std::vector<std::vector<float>>& vectors) {
        // 公共逻辑：写入向量库
    }
};

再写一个 PDF 子类：

cpp复制class PdfVectorizer : public DocumentVectorizer {
protected:
    std::string parseToText(const std::string& raw,
                            DocumentFormat format) override {
        // PDF 解析：提取文字、表格、元信息
    }

    std::string postClean(const std::string& text) override {
        // PDF 专属清洗：去掉页眉页脚、页码
    }
};

Java 侧思路完全一致，只是把虚函数换成了抽象方法，把 protected 换成了模板方法模式的常见写法。用 Java 实现时要注意一点：模板方法本身声明为 final，防止子类无意中覆盖整个流程。

C++ 写模板方法的坑在于，析构函数必须声明为 virtual，否则通过基类指针删除子类对象时会触发未定义行为。另外，如果在构造函数里调用虚函数，C++ 不会分发到子类实现，这是很多人踩过的坑，我在实际代码里也把 vectorize() 设计成不下发子类的非虚方法。

3. MQ 智能派单：直连模式的 routingKey 路由与广播模式的取舍

3.1 直连模式：按文档格式精确派单

模板方法解决了“一个格式类内部流程怎么组织”的问题，但还没有解决“多个格式、大批量文档怎么调度”的问题。如果还是同步 for 循环调用，模板方法只会让你的代码更好维护，改变不了吞吐量。所以第二刀切在调度层：把每次向量化任务丢进 MQ，用直连模式（direct）按文档格式精确派发给对应的消费者。

直连模式的思想是：生产者声明一个 direct 类型的交换机，发送消息时带上一个 routingKey；交换机会把消息投递到 bindingKey 与该 routingKey 完全匹配的队列。我这里的 routingKey 就是文档格式，比如 pdf、docx、md、html。每个格式对应一个消费队列，队列后面挂多个消费者实例做水平扩展。

用 RabbitMQ 的 Java 客户端做一个简单示例：

java复制// 生产者：发送向量化任务
String routingKey = detectDocType(fileName); // pdf / docx / md ...
channel.basicPublish("doc.vectorize.exchange", routingKey,
        MessageProperties.PERSISTENT_TEXT_PLAIN,
        messageBody.getBytes(StandardCharsets.UTF_8));

消费者侧声明队列并绑定到交换机：

java复制String queueName = "queue.doc." + routingKey;
channel.queueDeclare(queueName, true, false, false, null);
channel.queueBind(queueName, "doc.vectorize.exchange", routingKey);

这种设计的直接好处是：PDF 解析慢、消耗资源大，可以单独给 queue.doc.pdf 挂 10 个消费者；Markdown 解析快，挂 2 个消费者就够。不同格式的消费能力互不影响。之前同步工厂时代，“一份 PDF 拖慢整个批量任务”的问题就消失了。

3.2 广播模式：什么时候才真的需要它

既然直连模式这么好用，为什么还需要广播模式（fanout）？因为有些消息不是“某个格式专属的”，而是“所有消费者都要知道的”。

举例来说，向量化模型升级后，需要所有格式的消费者清空旧的本地模型缓存；或者知识库里的某个文档被删除了，所有格式的索引队列都要收到删除指令；再比如发布一个全量重建指令，所有格式的消费者都要从消息里拿到重建批次范围。这类场景用 fanout 交换机最合适：消息发给交换机后，交换机会复制一份投递给所有绑定的队列，每个消费者都能处理一次。

我自己实际用 broadcast 的场景是索引版本切换。向量化底座从早期模型切到 SigLIP2 时，需要通知所有消费者：“老版本的向量索引全部标记为过期，新版本从某个时间点开始生效。”如果只发到一个格式队列，其他格式的消费者会继续用旧模型处理新文档，导致索引混用。用 fanout 一次性广播，所有队列同时收到切换信号，确保整个系统在新旧版本交替期间保持一致。

选型上我的建议是：按格式派发用直连或 topic，全局通知用广播。不要什么都用 fanout，否则每个消费者都会收到大量无关消息，白白浪费消费资源。

3.3 requestId 与 intent：让派单过程可追踪、可决策

引入 MQ 之后，链路从“一次同步调用”变成了“生产者 -> 交换机 -> 队列 -> 消费者 -> 向量库”的异步链路，排查问题的难度明显上升。这个痛点靠一个贯穿全链路的 requestId 解决。

生产者在文档进入系统时生成一个 requestId，比如 UUID.randomUUID().toString()，把它放进消息头，后续所有日志、数据库写入、向量库元数据都带上这个字段。消费者在处理消息时把这个 requestId 打印到日志里，再配合日志平台的 traceId 关联，就能把“文档从进入系统到向量入库”的完整路径串起来。如果哪一步异常，直接拿 requestId 去日志里 grep，比之前同步时代盲目翻日志高效得多。

intent 字段则是为了做更精细的决策。同样是 PDF 文档，它的最终用途可能不同：可能是进知识库做检索，可能是做数据抽取，也可能是做精排训练样本。我在消息体里加了一个 intent 字段，消费者拿到消息后先读 intent，再决定后续流程：

json复制{
  "requestId": "8f3a2e1c-8d2e-4c7f-9b64-aa5c2e3f7d11",
  "docType": "pdf",
  "fileName": "2024年度报告.pdf",
  "storageUrl": "oss://bucket/2024/年报.pdf",
  "priority": 5,
  "intent": "knowledge_base_embedding",
  "modelProfile": "siglip2-text"
}

intent 在业务流程上的作用比 docType 更上一位。比如 intent = knowledge_base_embedding 时，消费者执行标准的模板方法流程；intent = rerank_pretraining 时，消费者会跳过入库步骤，而是把分块结果写入训练样本管道。这让我在同一个 MQ 架构下支持多种业务，而不是每种业务都重新搭一套解析流程。

4. 重构后的端到端流程：从文档进入 MQ 到向量入库

4.1 消息体设计：不要把文档内容塞进消息

很多人在设计 MQ 消息时会犯一个错误：把文档内容直接塞进消息体。这是一个大坑。文档内容可能几十 MB 甚至几百 MB，MQ 消息过大会带来两个问题：一是网络传输开销大，二是消费失败重投时反复传输同样的体积，队列积压和磁盘占用都会飙升。

我的做法是：消息体里只放文档的元信息和存储地址，真正的文档内容留在 OSS 或本地磁盘上。消费者收到消息后，通过 storageUrl 去拉取原始文件。这样消息体保持轻量，即使在高峰时段，消息积压也只是元数据的堆积，不会把 MQ 集群的磁盘打爆。

消息体设计可以给出一套比较通用的模板：

json复制{
  "requestId": "8f3a2e1c-8d2e-4c7f-9b64-aa5c2e3f7d11",
  "docType": "pdf",
  "fileName": "2024年度报告.pdf",
  "storageUrl": "oss://bucket/2024/年报.pdf",
  "priority": 5,
  "intent": "knowledge_base_embedding",
  "modelProfile": "siglip2-text",
  "retryCount": 0
}

retryCount 也很重要。消费者处理失败后，消息会重投，重投次数是无上限的。我一般建议在消费端捕获可重试异常后，判断 retryCount 是否超过阈值，超过则转为死信或告警，防止一条坏消息无限循环。

4.2 消费者编排：模板方法骨架与 MQ 消息驱动的结合

消费者是模板方法和 MQ 结合的核心。消费者从队列拿到消息后，根据 docType 从注册表中找到对应的 DocumentVectorizer 子类实例，调用 vectorize()。这一步看似是工厂模式又回来了，但注意：工厂只负责“根据格式返回一个子类实例”，不负责定义流程；流程已经锁死在模板基类里。工厂的代码降到最简：

cpp复制class VectorizerRegistry {
public:
    void registerVectorizer(DocumentFormat format,
                            std::unique_ptr<DocumentVectorizer> vec) {
        registry_[format] = std::move(vec);
    }

    DocumentVectorizer* get(DocumentFormat format) {
        auto it = registry_.find(format);
        if (it == registry_.end()) {
            return nullptr;
        }
        return it->second.get();
    }

private:
    std::unordered_map<DocumentFormat,
                       std::unique_ptr<DocumentVectorizer>> registry_;
};

消费者核心流程示意（Java 伪代码）：

java复制public void onMessage(Message message) {
    String requestId = message.getRequestId();
    String docType = message.getDocType();
    DocumentVectorizer vectorizer = registry.get(docType);
    if (vectorizer == null) {
        log.error("[{}] 不支持的文档类型: {}", requestId, docType);
        return;
    }
    try {
        Document doc = loadDocument(message.getStorageUrl());
        vectorizer.vectorize(doc);
        log.info("[{}] 向量化完成", requestId);
    } catch (Exception e) {
        log.error("[{}] 向量化失败: {}", requestId, e.getMessage(), e);
        if (message.getRetryCount() < MAX_RETRY) {
            message.setRetryCount(message.getRetryCount() + 1);
            mqTemplate.send(delayExchange, message);
        } else {
            deadLetterQueue.send(message);
        }
    }
}

整个链路变成：API 网关接收到上传请求 -> 把文件写入 OSS -> 发送 MQ 消息 -> 消费者从队列拿消息 -> 根据 docType 找模板子类 -> 执行模板方法 -> 写向量库。调用方不再同步等待向量化结果，而是立即拿到“已受理”的响应，后台任务异步完成。吞吐量从之前的单机串行，变成了多个消费者实例并行消费，理论上只要下游资源扛得住，水平扩展消费实例数量就能线性提升吞吐。

4.3 向量化模型的选型：SigLIP2 与精排环节的串联

聊到向量化，就绕不开模型的选型。很多知识库初期用通用 embedding 模型，比如 BGE 系列或 OpenAI 的 embedding 接口；后来要处理图文混合文档，就需要多模态向量模型。SigLIP2 这种多模态模型，能把文本和图片映射到同一个向量空间，对知识库里的图文混排内容有更好的语义对齐效果。

在这个架构里，模型选型被抽象成 embedChunks 步骤的内部实现，不污染模板方法。模板方法只关心“分块结果 -> 向量”，至于用哪个模型，由配置和消息里的 modelProfile 决定。这样模型升级时，只需要改配置或消息路由，不需要改动流程代码。

精排和向量化是两个环节。向量化负责召回：先从向量库召回 TopK 候选；精排负责把候选重新打分，通常用交叉编码器模型。有人把精排也塞进向量化流程，这是错误的。向量化是离线任务，精排是检索在线链路里的实时计算，两者不应该混在同一个 MQ 流程里。我的经验是：消息里的 intent 字段在在线检索阶段发挥作用，比如 intent = retrieval 时，在线服务会先向量召回 Top100，再用精排模型重排成 Top10。精排模型跑在独立服务上，不消费 MQ 的向量化任务，它消费的是检索请求。

5. 部署期间踩过的坑：MQ 安装后管理后台进不去的完整排查过程

5.1 症状：服务起来了，控制台却打不开

架构设计完成后，要落地的第一步是部署 MQ 集群。我选用的是 RabbitMQ，安装很顺利，服务状态显示 running，但访问管理后台的 15672 端口却始终超时。当时第一个直觉是端口没开，但 ss -lntp 查看端口监听状态，发现 15672 确实没有监听。这就奇怪了：服务本身是 running 的，为什么管理端口没监听？

网上查资料发现，RabbitMQ 3.x 之后，管理后台默认不随主服务启动，需要通过插件显式启用。如果你的 MQ 安装后无法进入管理后台，八成是 rabbitmq_management 插件没有启用，或者启用后忘了重启生效。

5.2 排查链路：从端口、插件到用户权限

完整的排查过程我整理成了三步，每一步都有可能踩到：

第一步：确认服务真的在运行

bash复制systemctl status rabbitmq-server

如果 service 显示 active (running)，再看一下 Erlang 节点是否注册：

bash复制rabbitmqctl status

这一步能确认节点名字、内存占用、运行状态。如果 rabbitmqctl status 报错，说明 Erlang 节点可能没起来，或者 epmd 端口 4369 被防火墙挡了，节点之间无法通信。

第二步：检查管理插件是否启用

bash复制rabbitmq-plugins list

输出里会看到一堆 [ ] 或 [E] 标记的插件。rabbitmq_management 和 rabbitmq_management_agent 这两项必须是 [E] 状态。如果显示未启用，执行：

bash复制rabbitmq-plugins enable rabbitmq_management

启用后通常会自动触发监听，但如果没监听，重启一下 RabbitMQ：

bash复制systemctl restart rabbitmq-server

注意：启用插件失败时，先看日志。我遇到过一次插件启用成功但 15672 还是没有监听的情况，原因竟然是 RabbitMQ 的 Erlang cookie 文件权限不对，导致管理插件无法正常加载。日志在 /var/log/rabbitmq/ 下，仔细看就能找到线索。

第三步：检查 15672 端口是否被防火墙拦截

管理器监听起来后，再用 ss -lntp | grep 15672 验证。如果监听存在，但在浏览器里还是打不开，那大概率是防火墙问题：

bash复制firewall-cmd --permanent --add-port=15672/tcp
firewall-cmd --reload

除此之外，还有一个隐藏比较深的坑：RabbitMQ 默认的 guest 用户只能通过 localhost 访问，如果通过服务器公网 IP 访问管理后台，会被拒绝。需要创建一个新用户并授权：

bash复制rabbitmqctl add_user admin your_password
rabbitmqctl set_user_tags admin administrator
rabbitmqctl set_permissions -p / admin ".*" ".*" ".*"

这几个步骤做完，管理后台基本就能正常访问了。

5.3 最终根因和恢复操作

我那次故障的根因是个组合问题：插件没有启用，同时 Erlang cookie 权限不对导致插件加载失败，表面上看起来像“端口没开”，实际上不是。恢复操作按照上面的三步走完就解决了。这里给一条经验提醒：不要以 ss 或者 netstat 的输出作为端口不存在就一定有问题，先检查插件状态，再排查权限和防火墙。顺序反了会浪费很多时间。

6. 这套架构的边界：什么场景下不该用模板方法 + MQ

6.1 复杂度对照：小项目用大架构得不偿失

模板方法 + MQ 这套组合确实解决了很多问题，但它带来的复杂度也是实实在在的：需要部署 MQ 集群、维护消费者实例、处理消息重试和死信、配置队列和交换机、加日志链路追踪。如果只是做一个内部工具，每天处理几十个文档，且格式不超过三种，直接同步工厂模式反而更快、更好维护。

我判断是否值得引入这套架构有个简单的标准：文档格式数量超过五个，或者单日处理量超过几千篇，或者不同格式的处理耗时有明显差异。三个条件满足任意一个，这套架构的价值就体现出来了；如果三个都不满足，硬上 MQ 只会给自己徒增运维负担。

6.2 消息堆积与顺序问题

引入 MQ 也不是银弹。如果某个格式的消费者实例挂掉了，堆积的消息会越来越多，处理延迟飙升。我遇到过 PDF 队列积压了十几万条消息，消费者恢复正常后追了几小时才追平。所以一定要做好积压监控，每个队列的 backlog 数量、消费速率、最近消费延迟都要落到监控大盘上，超过阈值就告警。

另外，如果文档之间存在严格的先后依赖（比如先解析基础文档，再解析扩展文档），MQ 的天然乱序特性会破坏这种依赖。多数文档向量化场景不要求严格顺序，但如果你遇到了，建议不要过度依赖 MQ 的排序能力，而是通过消息里的时间戳或版本号在消费端做重排，或者把有依赖关系的文档归类到同一个队列里，利用单一队列的 FIFO 特性保序。

6.3 什么时候回到同步工厂反而更合适

最后说一个反直觉的结论：有些场景下，同步工厂反而更合适。比如实时的单文档预览、调试时的单文档向量化、低并发内部工具。这类场景延迟敏感且量小，走 MQ 反而多一次网络跳转，实时性和逻辑复杂度都不占优。我在最终架构里保留了同步调用入口，生产环境仍然走 MQ，但调试工具和预览接口直接同步调用模板方法。这也算是一条经验：架构重构不是把旧方案全盘否定，而是给不同场景保留不同的通道。

模板方法把流程固定住了，MQ 把调度解耦了，同步入口则保留了一种简单直接的选择。三种方式各有各的适用范围，只有把它们放进同一个系统里合理分工，才真正达到重构的目的。