---
title: "02-前后端模块划分与调用关系"
created: 2026-05-21
aliases:
  - 前后端模块划分与调用关系
tags:
  - 项目
---
# 前后端模块划分与调用关系

这篇文档聚焦后端部分，把 Super Agent 的 Maven 模块划分、聊天业务的包结构、各层核心类的职责和调用关系都理清楚。看完之后，你拿到任何一个类名，都能快速定位它在整个架构中的位置和作用。

## Maven 模块总览

Super Agent 后端采用多模块 Maven 结构，每个模块有明确的职责边界：

![[Fq60nJNh7rAaC-J2_z26RmiTQeqJ-9da8daa4.png]]

| 模块 | 职责 |
| --- | --- |
| `super-agent-common` | 通用基础设施：枚举定义（`ChatQueryMode`、`ChatTurnStatus`）、工具类、统一响应封装 |
| `super-agent-id-generator-framework` | 分布式 ID 生成，为会话和轮次提供全局唯一标识 |
| `super-agent-redisson-framework` | Redis 相关能力：分布式锁、重复执行限制、**会话租约管理**（`RedisLeaseManager`） |
| `super-agent-business-chat` | 聊天系统的全部业务代码，是最核心的模块 |

## 聊天业务包结构

`super-agent-business-chat` 是整个聊天系统的核心，内部按职责划分成多个包。下面这张图展示了包之间的层次关系：

![[Fs5xUdVh1HltiTnzdakhGZvuYUnl-37666ced.png]]

### 各包职责详解

下面逐个说明每个包里装了什么、负责什么：

**controller —— 请求入口**

只有一个类 `BusinessChatController`，负责接收前端 HTTP 请求、参数校验，然后转交给 Service 层。这一层不做任何业务逻辑。

```java
// 控制器只做两件事：接参数、转交 Service
@RestController
@RequestMapping("/api/chat")
public class BusinessChatController {
    private final BusinessChatService businessChatService;

    @PostMapping(value = "/stream", produces = "text/event-stream;charset=UTF-8")
    public Flux<String> stream(@Valid @RequestBody ChatRequestDto dto) {
        return businessChatService.openConversationStream(dto);
    }
    // 还有 stop、reset、session 等接口...
}
```

**dto / vo —— 数据传输**

- `dto` 包：前端传入的请求参数，比如 `ChatRequestDto`（问题、会话 ID、聊天模式）
- `vo` 包：返回给前端的响应结果，比如 `ConversationStopVo`、`ConversationResetVo`

**service —— 业务核心**

这是整个聊天系统最重要的包，核心类包括：

| 类名 | 职责 |
| --- | --- |
| `BusinessChatService` | 会话编排总控：启动、执行、停止、重置、查询的入口 |
| `TaskInfo` | 运行时上下文：聚合了一次会话执行所需的所有状态 |
| `StreamLaunchPlan` | 启动计划：规范化后的请求参数 |
| `ChatRuntimeRegistry` | 运行态注册表：跟踪当前正在执行的会话任务 |
| `ConversationArchiveStore` | 归档存储接口：会话和轮次的持久化 |
| `MybatisConversationArchiveStore` | 归档存储的 MyBatis 实现 |
| `ConversationMemoryService` | 会话记忆服务：长期摘要和最近对话窗口管理 |
| `ConversationTraceRecorder` | 执行追踪记录器：记录每个阶段的状态和耗时 |
| `ChatCheckpointManager` | Checkpoint 管理：底层 Agent 的状态快照 |
| `RecommendationService` | 推荐追问生成 |
| `ObservedChatModelService` | 带观测的模型调用封装 |

**rag —— 检索增强生成**

这个包是 RAG 链路的核心，内部又分了几个子包：

- `rag/executor`：执行器实现，每种执行模式对应一个执行器
  - `ConversationExecutorRegistry` —— 执行器注册表
  - `RagChatExecutor` —— RAG 检索问答
  - `ReactAgentExecutor` —— 开放式 Agent
  - `GraphOnlyExecutor` —— 纯图查询
  - `GraphThenEvidenceExecutor` —— 图查询 + 证据补充
  - `ClarificationExecutor` —— 澄清确认
- `rag/service`：RAG 链路中的各个服务
  - `ChatPreparationOrchestrator` —— 编排器，决定走哪条执行路径
  - `ChatQueryRewriteService` —— 问题改写
  - `DocumentQuestionRouter` —— 文档问题路由
  - `RagRetrievalEngine` —— 检索引擎
  - `RagPromptAssemblyService` —— Prompt 组装
  - `StructureGraphQueryEngine` —— 结构图查询引擎
  - `HttpDocumentRerankPostProcessor` —— 重排序后处理
- `rag/retrieve/channel`：检索通道实现（向量检索、关键词检索等）
- `rag/model`：执行计划、检索上下文等数据模型
  - `ExecutionMode` —— 执行模式枚举
  - `ConversationExecutionPlan` —— 执行计划

**support —— 支撑组件**

- `StreamEventWriter` —— SSE 事件格式化和写入
- `SinkEmitHelper` —— Reactor Sink 安全发送封装
- `StreamEventMetadata` —— 事件元信息（会话 ID、轮次 ID）
- `TimeSensitiveQueryHelper` —— 时效性问题判断
- `ChatContextKeys` —— 上下文键常量

**tool —— 工具实现**

Agent 可调用的外部工具，比如 `TavilySearchTool`（联网搜索）。

**manage —— 文档管理**

文档知识库的管理能力，包括文档上传、解析、索引、知识路由等。这部分虽然和聊天在同一个 Maven 模块里，但逻辑上是独立的子系统。

## 核心调用链路

理解了包结构之后，我们来看一次完整的聊天请求在这些类之间是怎么流转的。

### 主链路：从请求到响应

![[FvhnZD0NptZ0ngzs75GVtbZA4c7Q-7ac86601.png]]

### 编排器内部的调用关系

编排器 `ChatPreparationOrchestrator` 是决策中枢，它内部会调用多个服务来完成执行计划的生成：

```java
// ChatPreparationOrchestrator 的依赖注入
public class ChatPreparationOrchestrator {
    private final ChatRagProperties properties;              // RAG 配置
    private final ConversationMemoryService memoryService;   // 会话记忆
    private final AnswerHistoryContextAssembler historyAssembler; // 历史上下文组装
    private final ChatQueryRewriteService rewriteService;    // 问题改写
    private final DocumentQuestionRouter documentRouter;     // 文档问题路由
    private final KnowledgeRouteService knowledgeRouteService; // 知识范围路由
    private final DocumentKnowledgeService documentKnowledgeService; // 文档知识服务
}
```

它的调用顺序是：

- `ConversationMemoryService` → 加载会话记忆（长期摘要 + 最近窗口）
- `AnswerHistoryContextAssembler` → 组装回答用的历史上下文
- `ChatQueryRewriteService` → 把用户问题改写成检索友好的表达
- `KnowledgeRouteService` → 自动文档模式下，路由到目标文档
- `DocumentQuestionRouter` → 判断走图查询还是混合检索

### Service 层的依赖全景

`BusinessChatService` 是整个聊天系统的总控，它依赖的组件最多：

```java
// BusinessChatService 的依赖注入（共 14 个组件）
public class BusinessChatService {

    // Agent 相关
    private final ReactAgent businessChatReactAgent;         // 底层 ReactAgent
    private final ChatCheckpointManager checkpointManager;   // Checkpoint 管理

    // 配置
    private final ChatAgentProperties chatAgentProperties;   // 聊天配置

    // 会话生命周期
    private final ConversationArchiveStore archiveStore;     // 归档存储
    private final ChatRuntimeRegistry runtimeRegistry;       // 运行态注册表
    private final ConversationMemoryService memoryService;   // 会话记忆

    // 执行编排
    private final ChatPreparationOrchestrator orchestrator;  // 编排器
    private final ConversationExecutorRegistry executorRegistry; // 执行器注册表

    // 输出与推荐
    private final StreamEventWriter streamEventWriter;       // SSE 事件写入
    private final RecommendationService recommendationService; // 推荐追问

    // 分布式控制
    private final RedisLeaseManager redisLeaseManager;       // Redis 租约

    // 观测与追踪
    private final ConversationTraceStageStore traceStageStore; // 阶段追踪存储
    private final RetrievalObserveStore retrievalObserveStore; // 检索观察存储
    private final StageBenchmarkService stageBenchmarkService; // 阶段基准

    // 文档知识
    private final DocumentKnowledgeService documentKnowledgeService; // 文档知识服务
}
```

> 设计思路
>
> 虽然 `BusinessChatService` 依赖的组件看起来很多，但每个组件的职责都很单一。这种"轻度的总控 + 厚度的组件"的设计，让每个组件都可以独立测试和替换，总控只负责把它们串起来。

## 分层架构总结

从整体来看，Super Agent 后端的聊天系统是一个清晰的分层架构：

| 层次 | 包 | 核心职责 |
| --- | --- | --- |
| **接入层** | `controller` | 接收 HTTP 请求，参数校验，返回 SSE 流 |
| **编排层** | `service` | 会话生命周期管理、执行流组装、收尾落库 |
| **决策层** | `rag/service` | 意图分析、问题改写、知识路由、执行模式判定 |
| **执行层** | `rag/executor` | 按模式执行具体的检索/生成/澄清逻辑 |
| **检索层** | `rag/retrieve` | 多路检索通道（向量、关键词等） |
| **支撑层** | `support` | SSE 事件格式化、时效性判断、上下文管理 |
| **持久层** | `data` / `mapper` | 数据库实体和 MyBatis 映射 |
| **基础设施** | `common` / `redisson` / `id-generator` | 枚举、分布式锁、租约、ID 生成 |

每一层只依赖它下面的层，不会反向依赖，这保证了架构的清晰度和可维护性。

---

**企业级项目导航**：⬅️ [[01-从用户提问到答案返回的总流程|01-从用户提问到答案返回的总流程]] | 02-前后端模块划分与调用关系 | ➡️ [[03-提问到返回|03-提问到返回]]