上传接口与文档主记录创建
这篇文档要讲的是：用户上传一份文档后，后端到底做了哪些事情？从 Controller 接到请求开始，一直到最后把消息丢进 Kafka 队列，整条链路我们一步步拆开来看。
先上一张总览流程图，有个整体印象之后再逐段看源码。
上传链路总览
Controller 层：接收 multipart 请求
上传接口的入口在 DocumentManageController，它是一个标准的 Spring MVC 控制器。这个接口比较特殊——不是普通的 JSON 请求，而是 multipart/form-data，同时包含二进制文件和文档元信息两部分。
/**
* 上传文档并投递后续解析任务。
* <p>
* 请求体采用 multipart/form-data，通常包含两部分：
* 1. {@code file}：真实上传的文档二进制内容；
* 2. {@code meta}：可选的文档元信息，例如展示名称、知识范围、业务分类、操作人等。
* </p>
* <p>
* 控制器本身不直接处理文件落盘、对象存储、文档入库或任务投递，
* 这里只负责把 multipart 中的两部分正确绑定出来，然后交给服务层统一完成：
* 文件校验、文件类型识别、对象存储上传、文档主表写入、任务表写入、日志记录和 Kafka 投递。
* </p>
*
* @param file 上传的文档文件，必须通过 multipart 的 {@code file} 字段传入
* @param dto 上传附带的文档元信息，来自 multipart 的 {@code meta} 字段，可为空
* @return 上传结果，包含文档 ID、任务 ID 以及当前解析/策略/索引状态
*/
@Operation(summary = "上传文档并投递解析任务")
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ApiResponse<DocumentUploadVo> upload(@RequestPart("file") MultipartFile file,
@Valid @RequestPart(value = "meta", required = false) DocumentUploadDto dto) {
// meta 允许前端不传；这里统一兜底成一个空 DTO，避免服务层重复判空，让后续取字段时更稳定。
return ApiResponse.ok(documentManageService.upload(file, dto == null ? new DocumentUploadDto() : dto));
}
这段代码的要点：
- 用
@RequestPart("file")接收上传的文件二进制内容，用@RequestPart("meta")接收可选的元信息 JSON meta标记了required = false，前端可以不传。Controller 这里做了一个兜底：如果dto为 null，就 new 一个空的DocumentUploadDto，这样服务层就不用到处判空了- Controller 本身不做任何业务逻辑，纯粹是参数绑定 + 转发给 Service
关于 DocumentUploadDto
DocumentUploadDto 是上传时可选的元信息，包含以下字段：
documentName：文档展示名称（不传则用原始文件名）operatorId：操作人 ID（不传则视为系统触发）knowledgeScopeCode/knowledgeScopeName：知识范围编码和名称businessCategory：业务分类documentTags：文档标签
Service 层：upload 方法全流程
接下来就是核心了——DocumentManageServiceImpl.upload() 方法。这个方法没有在方法级别加 @Transactional 注解，而是通过 TransactionTemplate 手动控制事务边界：数据库写入操作（文档主表、任务表、任务日志）放在 transactionTemplate.execute() 内部，事务提交成功后再发送 Kafka 消息。这样做的目的是避免"消息已发出但事务还没提交"的时间窗口问题。
我们按执行顺序，一段一段来看。
付费内容提示
该文档的全部内容仅对「码力全开」项目实战&技术讲解 知识星球用户开放
加入星球，一次获得完整项目资料、全栈技术知识库和长期答疑服务。
100万+字全栈技术知识库深入讲解技术核心、数据库、中间件和分布式等内容
8套热门的实战项目持续更新的企业级项目覆盖高并发、微服务、数据中台 和 AI Agent 等方向
AI 技术知识大模型面试详解覆盖 AI 模型原理、Agent、RAG、MCP、Skills、Harness 等核心知识点
文档 + 视频两种讲解形式既能系统阅读，也能跟随视频理解核心业务
完整项目实战资料
每套项目均包含从 0 到 1 讲解文档核心业务讲解视频从基础项目到复杂业务场景，项目资料会持续更新。
- 01Nexus Agent AI 智能体
- 02Nexus Agent Pro 完全版
- 03黑马点评Plus
- 04大麦
- 05大麦Pro
- 06大麦AI
- 07流量切换
- 08数据中台
加入后还能获得
进入星球后，即可享受上述所有服务，保证不会再有其他隐藏费用。从学习、面试到项目启动，都可以继续获得支持。
- 1 对 1 解答项目和技术问题都可以提问
- 针对性补充没有讲清楚的内容会继续补充
- 面试与简历指导梳理回答技巧和项目亮点
- 中间件云环境项目依赖可以直接接入使用
- 面试后复盘被问住的问题可以继续交流
- 远程问题解决项目启动问题可协助排查
