You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
22 KiB
22 KiB
文件服务模块(crm-file)
**本文引用的文件** - [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java) - [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java) - [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java) - [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java) - [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java) - [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java) - [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java) - [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java) - [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java) - [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java) - [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java) - [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java) - [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java) - [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java) - [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java) - [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java) - [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)目录
简介
本文件为 crm-file 文件服务模块的详细技术文档。该模块提供统一的文件上传下载、分片上传与断点续传、在线预览、存储管理与元数据管理等功能，并通过 MinIO 作为对象存储后端，结合定时任务清理孤立的分片文件，保障系统稳定性与可维护性。文档面向开发者与运维人员，既包含接口设计、配置项说明，也涵盖并发处理、性能优化与扩展方案。
项目结构
crm-file 模块采用分层组织：
- API 层：对外暴露统一接口定义（FileApi）
- Controller 层：HTTP 控制器（FileController）
- Service 层：业务逻辑实现（FileApiImpl、FileInfoServiceImpl）
- Client 层：第三方能力集成（KkFileViewClient）
- Config 层：配置与初始化（MinioConfig、FileProperties、SchedulingConfig）
- Domain 层：实体与 DTO（FileInfo、UploadSession、各类 DTO）
- Mapper 层：持久化访问（FileInfoMapper）
- Task 层：定时任务（OrphanChunkCleanupTask）
- Constant 层：常量定义（FileConstants）
graph TB
subgraph "API 层"
A["FileApi"]
end
subgraph "控制器层"
C["FileController"]
end
subgraph "服务层"
S1["FileApiImpl"]
S2["FileInfoServiceImpl"]
end
subgraph "客户端层"
K["KkFileViewClient"]
end
subgraph "配置层"
M["MinioConfig"]
F["FileProperties"]
SC["SchedulingConfig"]
end
subgraph "领域层"
E["FileInfo"]
D1["UploadSession"]
D2["MultipartInitDTO"]
D3["FileDownloadDTO"]
D4["FileInfoDTO"]
end
subgraph "持久化层"
MAP["FileInfoMapper"]
end
subgraph "任务层"
T["OrphanChunkCleanupTask"]
end
subgraph "常量层"
CON["FileConstants"]
end
A --> C
C --> S1
C --> S2
S1 --> MAP
S1 --> K
S1 --> M
S1 --> F
S2 --> MAP
T --> MAP
T --> F
S1 --> E
S1 --> D1
S1 --> D2
S1 --> D3
S1 --> D4
S2 --> E
S1 --> CON
S2 --> CON
图表来源
- FileController.java
- FileApi.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- KkFileViewClient.java
- MinioConfig.java
- FileProperties.java
- SchedulingConfig.java
- FileInfoMapper.java
- FileInfo.java
- UploadSession.java
- MultipartInitDTO.java
- FileDownloadDTO.java
- FileInfoDTO.java
- OrphanChunkCleanupTask.java
- FileConstants.java
章节来源
- FileController.java
- FileApi.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- MinioConfig.java
- FileProperties.java
- SchedulingConfig.java
- FileInfoMapper.java
- FileInfo.java
- UploadSession.java
- MultipartInitDTO.java
- FileDownloadDTO.java
- FileInfoDTO.java
- OrphanChunkCleanupTask.java
- FileConstants.java
核心组件
- FileController：HTTP 接口入口，封装上传、分片上传、下载、预览等请求到服务层。
- FileApi 与 FileApiImpl：文件操作的核心服务接口与实现，协调 MinIO、分片会话、元数据持久化与预览服务。
- FileInfoServiceImpl：文件信息管理服务，负责文件元数据的增删改查与状态维护。
- KkFileViewClient：对接 kkFileView 进行在线预览，返回预览链接或流式内容。
- MinioConfig 与 FileProperties：MinIO 客户端与文件相关配置（端点、桶名、密钥、分片大小、超时等）。
- FileInfoMapper：文件元数据持久化访问。
- OrphanChunkCleanupTask：定时清理未完成的分片上传残留，释放存储空间。
- 领域模型：FileInfo（文件元数据）、UploadSession（分片会话）、各 DTO（上传初始化、下载参数、文件信息等）。
章节来源
- FileController.java
- FileApi.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- KkFileViewClient.java
- MinioConfig.java
- FileProperties.java
- FileInfoMapper.java
- FileInfo.java
- UploadSession.java
- MultipartInitDTO.java
- FileDownloadDTO.java
- FileInfoDTO.java
- OrphanChunkCleanupTask.java
架构总览
文件服务模块以 HTTP 接口为入口，通过服务层编排 MinIO 对象存储、kkFileView 预览服务与数据库元数据持久化。分片上传流程由 UploadSession 驱动，支持断点续传；下载流程支持范围请求与流式输出；预览通过 kkFileView 生成预览地址或直接返回内容。定时任务定期扫描并清理孤立分片，避免存储膨胀。
sequenceDiagram
participant Client as "客户端"
participant Controller as "FileController"
participant Service as "FileApiImpl"
participant MinIO as "MinIO 客户端"
participant DB as "FileInfoMapper"
participant Preview as "KkFileViewClient"
Client->>Controller : "发起上传/分片上传/下载/预览请求"
Controller->>Service : "调用文件服务方法"
alt 普通上传
Service->>MinIO : "上传完整文件"
Service->>DB : "写入文件元数据"
Service-->>Controller : "返回文件信息"
else 分片上传
Service->>Service : "初始化分片会话(UploadSession)"
loop 每个分片
Client->>Service : "上传分片(chunk)"
Service->>MinIO : "上传分片"
Service->>Service : "更新分片进度"
end
Service->>MinIO : "合并分片"
Service->>DB : "写入文件元数据"
Service-->>Controller : "返回文件信息"
else 下载
Service->>MinIO : "读取文件流"
Service-->>Controller : "返回文件流"
else 预览
Service->>Preview : "生成预览链接/获取预览内容"
Preview-->>Service : "预览结果"
Service-->>Controller : "返回预览结果"
end
Controller-->>Client : "响应结果"
图表来源
- FileController.java
- FileApiImpl.java
- FileInfoMapper.java
- KkFileViewClient.java
- MinioConfig.java
详细组件分析
控制器层：FileController
- 职责：接收 HTTP 请求，校验参数，路由到对应服务方法，处理响应格式与异常。
- 关键能力：
- 文件上传：支持单文件与多文件上传。
- 分片上传：初始化会话、上传分片、合并分片。
- 文件下载：按文件标识或路径下载，支持范围请求。
- 文件预览：调用预览服务返回预览链接或内容。
- 错误处理：对非法参数、权限不足、存储异常等进行统一包装与提示。
章节来源
- FileController.java
服务层：FileApi 与 FileApiImpl
- 职责：实现文件上传、分片上传、断点续传、下载、预览等核心业务逻辑。
- 关键能力：
- 分片会话管理：基于 UploadSession 跟踪分片上传状态，支持断点续传。
- MinIO 集成：上传、分片上传、合并分片、下载流式读取。
- 元数据管理：创建、更新、查询文件元数据（FileInfo）。
- 预览集成：通过 KkFileViewClient 获取预览链接或内容。
- 并发处理：对分片上传进行并发控制，确保分片顺序与完整性。
- 事务与一致性：在分片合并成功后再持久化元数据，保证最终一致性。
classDiagram
class FileApi {
+ "上传文件(file)"
+ "分片初始化(params)"
+ "上传分片(sessionId, chunkIndex, data)"
+ "合并分片(sessionId)"
+ "下载文件(downloadDTO)"
+ "预览文件(fileInfo)"
}
class FileApiImpl {
- "minioClient"
- "fileInfoService"
- "kkFileViewClient"
- "fileProperties"
+ "上传文件(file)"
+ "分片初始化(params)"
+ "上传分片(sessionId, chunkIndex, data)"
+ "合并分片(sessionId)"
+ "下载文件(downloadDTO)"
+ "预览文件(fileInfo)"
}
class FileInfoService {
+ "保存文件元数据(info)"
+ "更新文件状态(id, status)"
+ "查询文件信息(id)"
}
class KkFileViewClient {
+ "获取预览链接(url)"
+ "获取预览内容(url)"
}
class MinioConfig {
+ "endpoint"
+ "bucketName"
+ "accessKey"
+ "secretKey"
}
class FileProperties {
+ "chunkSize"
+ "maxFileSize"
+ "timeout"
}
FileApi <|.. FileApiImpl : "实现"
FileApiImpl --> FileInfoService : "依赖"
FileApiImpl --> KkFileViewClient : "依赖"
FileApiImpl --> MinioConfig : "依赖"
FileApiImpl --> FileProperties : "依赖"
图表来源
- FileApi.java
- FileApiImpl.java
- IFileInfoService.java
- KkFileViewClient.java
- MinioConfig.java
- FileProperties.java
章节来源
- FileApi.java
- FileApiImpl.java
- IFileInfoService.java
- KkFileViewClient.java
- MinioConfig.java
- FileProperties.java
元数据服务：FileInfoServiceImpl
- 职责：文件元数据的持久化与查询，包括创建、更新、删除、分页查询等。
- 关键能力：
- 文件记录创建：上传完成后写入 FileInfo。
- 状态更新：分片上传过程中更新进度与状态。
- 查询与过滤：按文件名、类型、时间范围等条件查询。
- 与 Mapper 的交互：通过 FileInfoMapper 执行 SQL 操作。
章节来源
- FileInfoServiceImpl.java
- FileInfoMapper.java
- FileInfo.java
预览服务：KkFileViewClient
- 职责：对接 kkFileView 服务，生成预览链接或获取预览内容。
- 关键能力：
- 根据文件 URL 或路径生成预览链接。
- 直接获取预览内容（如 PDF、图片等）。
- 错误处理：网络异常、预览服务不可用时的降级策略。
章节来源
- KkFileViewClient.java
配置与初始化：MinioConfig、FileProperties、SchedulingConfig
- MinioConfig：MinIO 客户端配置（端点、桶名、密钥、连接池等）。
- FileProperties：文件相关配置（分片大小、最大文件大小、超时、临时目录等）。
- SchedulingConfig：定时任务开关与调度策略（如分片清理任务的执行周期）。
章节来源
- MinioConfig.java
- FileProperties.java
- SchedulingConfig.java
领域模型：FileInfo、UploadSession、DTOs
- FileInfo：文件元数据实体（名称、路径、大小、类型、状态、创建时间等）。
- UploadSession：分片上传会话（sessionId、总大小、已上传分片集合、状态等）。
- DTOs：
- MultipartInitDTO：分片初始化参数。
- FileDownloadDTO：下载参数（文件标识、路径、范围等）。
- FileInfoDTO：文件信息传输对象。
章节来源
- FileInfo.java
- UploadSession.java
- MultipartInitDTO.java
- FileDownloadDTO.java
- FileInfoDTO.java
定时任务：OrphanChunkCleanupTask
- 职责：周期性扫描未完成的分片上传会话，清理孤立分片文件，释放存储空间。
- 关键能力：
- 扫描长时间未更新的 UploadSession。
- 删除对应的 MinIO 分片文件。
- 清理或标记会话状态。
- 配置：通过 FileProperties 与 SchedulingConfig 控制执行频率与阈值。
章节来源
- OrphanChunkCleanupTask.java
- FileProperties.java
- SchedulingConfig.java
常量：FileConstants
- 职责：集中定义文件相关常量（如 MIME 类型、错误码、默认值等）。
章节来源
- FileConstants.java
依赖关系分析
- 控制器依赖服务层，服务层依赖 MinIO 客户端、预览客户端与数据库 Mapper。
- 定时任务依赖配置与 Mapper，用于清理孤立分片。
- 领域模型在各层之间传递，保证数据结构一致。
graph LR
FC["FileController"] --> FA["FileApiImpl"]
FA --> FMS["FileInfoServiceImpl"]
FA --> MINIO["MinioConfig"]
FA --> KK["KkFileViewClient"]
FMS --> MAP["FileInfoMapper"]
TASK["OrphanChunkCleanupTask"] --> MAP
TASK --> FP["FileProperties"]
图表来源
- FileController.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- MinioConfig.java
- KkFileViewClient.java
- FileInfoMapper.java
- OrphanChunkCleanupTask.java
- FileProperties.java
章节来源
- FileController.java
- FileApiImpl.java
- FileInfoServiceImpl.java
- MinioConfig.java
- KkFileViewClient.java
- FileInfoMapper.java
- OrphanChunkCleanupTask.java
- FileProperties.java
性能考量
- 分片上传：合理设置分片大小与并发数，平衡内存占用与上传速度。
- 流式处理：下载时采用流式读取，避免大文件内存溢出。
- 缓存策略：对频繁访问的文件元数据进行缓存，减少数据库压力。
- 连接池：优化 MinIO 客户端连接池大小与超时配置。
- 异步处理：将非关键路径（如预览生成）异步化，提升响应速度。
- 资源清理：定时任务及时清理孤立分片，防止存储膨胀。
[本节为通用指导，不直接分析具体文件]
故障排查指南
- 上传失败：检查 MinIO 配置、网络连通性与权限；查看分片会话状态与日志。
- 分片丢失：确认客户端分片顺序与重试机制；检查定时任务是否误删。
- 预览失败：验证 kkFileView 服务可用性；检查文件路径与 MIME 类型。
- 下载缓慢：调整流式缓冲大小与网络带宽；检查 MinIO 性能。
- 存储膨胀：检查孤立分片清理任务是否正常运行；手动清理残留分片。
章节来源
- OrphanChunkCleanupTask.java
- FileApiImpl.java
- KkFileViewClient.java
- MinioConfig.java
- FileProperties.java
结论
crm-file 模块提供了完整的文件处理能力，涵盖上传下载、分片上传、断点续传、预览与存储管理。通过清晰的架构设计与合理的配置，能够满足企业级应用对文件服务的稳定、高效与可扩展需求。建议在生产环境中充分测试并发与异常场景，并根据实际负载优化配置参数。
[本节为总结性内容，不直接分析具体文件]
附录
- 接口设计建议：统一返回格式、明确错误码、提供幂等性支持。
- 存储策略配置：按业务划分桶与目录，设置生命周期规则。
- 扩展方案：抽象存储后端接口，支持多存储切换；插件化预览服务。
- 监控与告警：记录上传下载成功率、延迟与错误率，设置阈值告警。
[本节为补充性内容，不直接分析具体文件]