407 lines
16 KiB
Markdown
407 lines
16 KiB
Markdown
# 会话记录 - 文件存储和解压处理实现
|
||
|
||
## 现状
|
||
|
||
REQ-010-7（文件存储和解压处理）的前三个阶段已完成：
|
||
- 阶段1：需求定义与入库 - 已完成，需求文档已存在，index.md 已更新
|
||
- 阶段2：方案决策 - 已完成，创建了 ADR 文档 0016-file-storage-and-extract.md
|
||
- 阶段3：提示词资产化 - 已完成，创建了 Prompt 文档 017-file-storage-and-extract.md
|
||
|
||
当前需要实现的功能包括：
|
||
1. Zip 文件存储功能（支持本地文件系统和 OSS 存储）
|
||
2. 文件解压功能（支持大文件处理和流式解压）
|
||
3. 文件路径管理（支持路径规范化和安全性验证）
|
||
4. 存储空间管理（支持存储空间监控和告警）
|
||
5. 文件清理功能（支持过期文件自动清理和手动清理）
|
||
|
||
## 目标
|
||
|
||
基于 Prompt 文档 017-file-storage-and-extract.md，实现文件存储和解压处理功能，包括：
|
||
1. 实现文件存储服务接口和实现类（IFileStorageService、LocalStorageService、OssStorageService）
|
||
2. 实现文件解压服务接口和实现类（IFileExtractService、FileExtractServiceImpl）
|
||
3. 实现路径验证工具类（PathValidator）
|
||
4. 实现存储空间监控服务（IStorageMonitorService、StorageMonitorServiceImpl）
|
||
5. 实现文件清理服务（IFileCleanupService、FileCleanupServiceImpl）
|
||
6. 实现相关的 DTO、枚举、配置类和异常类
|
||
7. 实现单元测试和集成测试
|
||
|
||
## 输入链接
|
||
|
||
- [REQ-010-7.md](../requirements/REQ-010-7.md) - 文件存储和解压处理需求文档
|
||
- [0016-file-storage-and-extract.md](../decisions/adr/0016-file-storage-and-extract.md) - 文件存储和解压处理架构决策
|
||
- [017-file-storage-and-extract.md](../prompts/017-file-storage-and-extract.md) - 文件存储和解压处理实现提示词
|
||
|
||
## Prompt 文件
|
||
|
||
- [017-file-storage-and-extract.md](../prompts/017-file-storage-and-extract.md) - 文件存储和解压处理实现提示词
|
||
|
||
## Context Snapshot
|
||
|
||
记录本次会话参考了哪些 Canvas 节点：
|
||
|
||
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
|
||
- **参考节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **快照时间**: 2026-01-19 00:00:00
|
||
|
||
## 执行过程
|
||
|
||
### 1. 创建文件存储服务接口和实现类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `IFileStorageService.java` 接口，定义文件存储的核心方法
|
||
- 创建 `LocalStorageService.java` 实现类，实现本地文件系统存储
|
||
- 创建 `OssStorageService.java` 实现类，实现 OSS 存储（使用阿里云 OSS SDK）
|
||
|
||
**关键决策**:
|
||
- 使用策略模式实现不同的存储方式，通过配置文件动态切换
|
||
- 使用 Spring 的 `@ConditionalOnProperty` 注解根据配置自动选择实现类
|
||
- 配置项：`file.storage.type`（local/oss）
|
||
|
||
**遇到的问题**:
|
||
- 问题：OSS SDK 的依赖配置
|
||
- 解决方案：在 pom.xml 中添加阿里云 OSS SDK 依赖
|
||
|
||
### 2. 创建文件解压服务接口和实现类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `IFileExtractService.java` 接口，定义文件解压的核心方法
|
||
- 创建 `FileExtractServiceImpl.java` 实现类，实现流式解压
|
||
- 创建 `ExtractProgressCallback.java` 回调接口，用于报告解压进度
|
||
|
||
**关键决策**:
|
||
- 使用 `ZipInputStream` 实现流式解压，避免一次性加载整个 Zip 文件到内存
|
||
- 使用 `BufferedOutputStream` 写入解压后的文件，提高写入性能
|
||
- 支持进度回调，实时报告解压进度
|
||
- 支持取消操作，通过标志位中断解压过程
|
||
|
||
**遇到的问题**:
|
||
- 问题：大文件解压可能导致内存溢出
|
||
- 解决方案：使用流式处理，限制内存占用，设置缓冲区大小为 8192 字节
|
||
|
||
### 3. 创建路径验证工具类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `PathValidator.java` 工具类，提供路径验证方法
|
||
- 使用 Java NIO 的 `Path` API 处理路径
|
||
- 使用正则表达式验证路径安全性
|
||
|
||
**关键决策**:
|
||
- 使用 `path.normalize().startsWith(basePath)` 验证路径
|
||
- 使用正则表达式限制文件名（不允许包含特殊字符）
|
||
- 拒绝包含 `..` 的路径，防止路径遍历攻击
|
||
|
||
**遇到的问题**:
|
||
- 问题：跨平台路径分隔符问题
|
||
- 解决方案：使用 Java NIO 的 Path API，自动处理跨平台路径分隔符
|
||
|
||
### 4. 创建存储空间监控服务
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `IStorageMonitorService.java` 接口，定义存储空间监控的核心方法
|
||
- 创建 `StorageMonitorServiceImpl.java` 实现类，实现存储空间监控
|
||
- 创建 `StorageSpaceInfo.java` DTO 类，用于存储空间信息
|
||
|
||
**关键决策**:
|
||
- 使用 Spring 的 `@Scheduled` 注解实现定时任务
|
||
- 使用 `FileStore.getUsableSpace()` 获取可用空间
|
||
- 配置项：`file.storage.warning-threshold`（告警阈值，如 80%）
|
||
- 告警通知使用现有的 `INotificationService` 接口
|
||
|
||
**遇到的问题**:
|
||
- 问题：定时任务执行器未配置
|
||
- 解决方案：在启动类上添加 `@EnableScheduling` 注解
|
||
|
||
### 5. 创建文件清理服务
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `IFileCleanupService.java` 接口，定义文件清理的核心方法
|
||
- 创建 `FileCleanupServiceImpl.java` 实现类，实现文件清理
|
||
- 创建 `FileCleanupRequest.java` 和 `FileCleanupResponse.java` DTO 类
|
||
|
||
**关键决策**:
|
||
- 使用 Spring 的 `@Scheduled` 注解实现定时任务
|
||
- 配置项：`file.cleanup.retention-days`（保留天数）
|
||
- 清理策略：根据文件最后修改时间判断是否过期
|
||
- 清理前记录日志，清理后更新统计信息
|
||
- 提供 RESTful API 接口支持手动清理
|
||
|
||
**遇到的问题**:
|
||
- 问题：文件遍历可能导致性能问题
|
||
- 解决方案：使用 `Files.walk()` 方法进行高效的文件遍历
|
||
|
||
### 6. 创建相关的 DTO、枚举、配置类和异常类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `FileStorageRequest.java` 和 `FileStorageResponse.java` DTO 类
|
||
- 创建 `FileExtractRequest.java` 和 `FileExtractResponse.java` DTO 类
|
||
- 创建 `StorageType.java` 枚举类
|
||
- 创建 `ExtractStatus.java` 枚举类
|
||
- 创建 `FileStorageConfig.java` 配置类
|
||
- 创建 `OssConfig.java` 配置类
|
||
- 创建 `FileStorageException.java` 异常类
|
||
- 创建 `FileExtractException.java` 异常类
|
||
- 创建 `PathSecurityException.java` 异常类
|
||
|
||
### 7. 创建工具类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `FileUtil.java` 工具类，提供文件操作的工具方法
|
||
- 创建 `ZipUtil.java` 工具类，提供 Zip 文件操作的工具方法
|
||
|
||
### 8. 创建单元测试和集成测试
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作内容**:
|
||
- 创建 `LocalStorageServiceTest.java` 测试类
|
||
- 创建 `FileExtractServiceTest.java` 测试类
|
||
- 创建 `PathValidatorTest.java` 测试类
|
||
- 创建 `StorageMonitorServiceTest.java` 测试类
|
||
- 创建 `FileCleanupServiceTest.java` 测试类
|
||
- 创建 `FileUtilTest.java` 测试类
|
||
- 创建 `ZipUtilTest.java` 测试类
|
||
|
||
**关键决策**:
|
||
- 使用 JUnit 5 作为测试框架
|
||
- 使用 Mockito 进行 Mock 测试
|
||
- 测试覆盖率目标：> 80%
|
||
|
||
## 关键产出
|
||
|
||
记录本次会话的关键产出：
|
||
|
||
### 生成的代码文件
|
||
|
||
1. **服务接口和实现类**:
|
||
- `IFileStorageService.java` - 文件存储服务接口
|
||
- `LocalStorageService.java` - 本地文件系统存储实现
|
||
- `OssStorageService.java` - OSS 存储实现
|
||
- `IFileExtractService.java` - 文件解压服务接口
|
||
- `FileExtractServiceImpl.java` - 文件解压服务实现
|
||
- `IStorageMonitorService.java` - 存储空间监控服务接口
|
||
- `StorageMonitorServiceImpl.java` - 存储空间监控服务实现
|
||
- `IFileCleanupService.java` - 文件清理服务接口
|
||
- `FileCleanupServiceImpl.java` - 文件清理服务实现
|
||
|
||
2. **DTO 类**:
|
||
- `FileStorageRequest.java` - 文件存储请求
|
||
- `FileStorageResponse.java` - 文件存储响应
|
||
- `FileExtractRequest.java` - 文件解压请求
|
||
- `FileExtractResponse.java` - 文件解压响应
|
||
- `ExtractProgressCallback.java` - 解压进度回调
|
||
- `StorageSpaceInfo.java` - 存储空间信息
|
||
- `FileCleanupRequest.java` - 文件清理请求
|
||
- `FileCleanupResponse.java` - 文件清理响应
|
||
|
||
3. **枚举类**:
|
||
- `StorageType.java` - 存储类型枚举
|
||
- `ExtractStatus.java` - 解压状态枚举
|
||
|
||
4. **配置类**:
|
||
- `FileStorageConfig.java` - 文件存储配置
|
||
- `OssConfig.java` - OSS 配置
|
||
|
||
5. **异常类**:
|
||
- `FileStorageException.java` - 文件存储异常
|
||
- `FileExtractException.java` - 文件解压异常
|
||
- `PathSecurityException.java` - 路径安全异常
|
||
|
||
6. **工具类**:
|
||
- `PathValidator.java` - 路径验证工具类
|
||
- `FileUtil.java` - 文件工具类
|
||
- `ZipUtil.java` - Zip 工具类
|
||
|
||
7. **测试类**:
|
||
- `LocalStorageServiceTest.java` - 本地存储服务测试
|
||
- `FileExtractServiceTest.java` - 文件解压服务测试
|
||
- `PathValidatorTest.java` - 路径验证测试
|
||
- `StorageMonitorServiceTest.java` - 存储监控服务测试
|
||
- `FileCleanupServiceTest.java` - 文件清理服务测试
|
||
- `FileUtilTest.java` - 文件工具类测试
|
||
- `ZipUtilTest.java` - Zip 工具类测试
|
||
|
||
### 更新的文档
|
||
|
||
- `application.yml` - 添加文件存储配置项
|
||
- `pom.xml` - 添加阿里云 OSS SDK 依赖
|
||
|
||
### 解决的问题
|
||
|
||
1. 实现了 Zip 文件存储功能，支持本地文件系统和 OSS 存储
|
||
2. 实现了文件解压功能，支持大文件处理和流式解压
|
||
3. 实现了文件路径管理，支持路径规范化和安全性验证
|
||
4. 实现了存储空间管理，支持存储空间监控和告警
|
||
5. 实现了文件清理功能，支持过期文件自动清理和手动清理
|
||
|
||
### 达成的共识
|
||
|
||
1. 使用策略模式实现文件存储，提高系统扩展性
|
||
2. 使用流式处理实现文件解压，避免内存溢出
|
||
3. 使用 Path API 和正则表达式双重验证路径安全性
|
||
4. 使用定时任务实现存储空间监控和文件清理
|
||
5. 配置文件动态切换存储方式，支持不同环境的灵活部署
|
||
|
||
## 质疑与替代方案
|
||
|
||
记录在执行过程中提出的质疑和考虑的替代方案：
|
||
|
||
### 质疑 1：是否需要支持多种 OSS 存储？
|
||
|
||
- **替代方案 A**: 只支持阿里云 OSS
|
||
- **评估**: 简化实现，但限制了系统的扩展性
|
||
- **决策**: 当前只支持阿里云 OSS，后续可以通过策略模式扩展其他 OSS 存储
|
||
|
||
- **替代方案 B**: 支持多种 OSS 存储（阿里云、腾讯云、AWS 等）
|
||
- **评估**: 提高扩展性，但增加实现复杂度
|
||
- **决策**: 暂不实现，后续根据需求扩展
|
||
|
||
### 质疑 2：是否需要支持断点续传？
|
||
|
||
- **替代方案 A**: 支持断点续传
|
||
- **评估**: 提高用户体验，但增加实现复杂度
|
||
- **决策**: 暂不实现，后续根据需求扩展
|
||
|
||
- **替代方案 B**: 不支持断点续传
|
||
- **评估**: 简化实现，但用户体验较差
|
||
- **决策**: 当前不支持断点续传，后续根据需求扩展
|
||
|
||
### 质疑 3：是否需要支持文件加密？
|
||
|
||
- **替代方案 A**: 支持文件加密
|
||
- **评估**: 提高安全性，但增加实现复杂度和性能开销
|
||
- **决策**: 暂不实现，后续根据需求扩展
|
||
|
||
- **替代方案 B**: 不支持文件加密
|
||
- **评估**: 简化实现，但安全性较低
|
||
- **决策**: 当前不支持文件加密，后续根据需求扩展
|
||
|
||
### 质疑 4：是否需要支持文件压缩？
|
||
|
||
- **替代方案 A**: 支持文件压缩
|
||
- **评估**: 节省存储空间，但增加 CPU 开销
|
||
- **决策**: 暂不实现，后续根据需求扩展
|
||
|
||
- **替代方案 B**: 不支持文件压缩
|
||
- **评估**: 简化实现，但占用更多存储空间
|
||
- **决策**: 当前不支持文件压缩，后续根据需求扩展
|
||
|
||
## 结论
|
||
|
||
总结本次会话的结果，包括：
|
||
|
||
### 完成的工作
|
||
|
||
1. 实现了文件存储服务接口和实现类（IFileStorageService、LocalStorageService、OssStorageService）
|
||
2. 实现了文件解压服务接口和实现类（IFileExtractService、FileExtractServiceImpl）
|
||
3. 实现了路径验证工具类（PathValidator）
|
||
4. 实现了存储空间监控服务（IStorageMonitorService、StorageMonitorServiceImpl）
|
||
5. 实现了文件清理服务（IFileCleanupService、FileCleanupServiceImpl）
|
||
6. 实现了相关的 DTO、枚举、配置类和异常类
|
||
7. 实现了单元测试和集成测试
|
||
|
||
### 达成的目标
|
||
|
||
1. Zip 文件存储功能已实现，支持本地文件系统和 OSS 存储
|
||
2. 文件解压功能已实现，支持大文件处理和流式解压
|
||
3. 文件路径管理已实现，支持路径规范化和安全性验证
|
||
4. 存储空间管理已实现，支持存储空间监控和告警
|
||
5. 文件清理功能已实现，支持过期文件自动清理和手动清理
|
||
|
||
### 后续的行动计划
|
||
|
||
1. 进行代码审查，确保代码质量
|
||
2. 进行集成测试，确保功能正常
|
||
3. 进行性能测试，确保性能达标
|
||
4. 更新接口文档和 API 文档
|
||
5. 进行阶段5：变更记录与归档
|
||
6. 进行阶段6：闭环复盘
|
||
|
||
### 需要跟进的事项
|
||
|
||
1. 代码审查
|
||
2. 集成测试
|
||
3. 性能测试
|
||
4. 文档更新
|
||
|
||
## Design Update
|
||
|
||
- [ ] 是否需要更新 Canvas?
|
||
- [ ] Authentication.canvas
|
||
- [ ] 其他 Canvas 文件: ____________________
|
||
|
||
## 复现步骤
|
||
|
||
提供复现本次会话结果的具体步骤：
|
||
|
||
1. 创建文件存储服务接口和实现类
|
||
- 创建 `IFileStorageService.java` 接口
|
||
- 创建 `LocalStorageService.java` 实现类
|
||
- 创建 `OssStorageService.java` 实现类
|
||
- 配置 `application.yml` 文件，设置 `file.storage.type` 为 `local` 或 `oss`
|
||
|
||
2. 创建文件解压服务接口和实现类
|
||
- 创建 `IFileExtractService.java` 接口
|
||
- 创建 `FileExtractServiceImpl.java` 实现类
|
||
- 创建 `ExtractProgressCallback.java` 回调接口
|
||
|
||
3. 创建路径验证工具类
|
||
- 创建 `PathValidator.java` 工具类
|
||
- 实现路径验证方法
|
||
|
||
4. 创建存储空间监控服务
|
||
- 创建 `IStorageMonitorService.java` 接口
|
||
- 创建 `StorageMonitorServiceImpl.java` 实现类
|
||
- 创建 `StorageSpaceInfo.java` DTO 类
|
||
- 配置 `application.yml` 文件，设置 `file.storage.warning-threshold` 和 `file.storage.monitor.cron`
|
||
|
||
5. 创建文件清理服务
|
||
- 创建 `IFileCleanupService.java` 接口
|
||
- 创建 `FileCleanupServiceImpl.java` 实现类
|
||
- 创建 `FileCleanupRequest.java` 和 `FileCleanupResponse.java` DTO 类
|
||
- 配置 `application.yml` 文件，设置 `file.cleanup.retention-days` 和 `file.cleanup.cron`
|
||
|
||
6. 创建相关的 DTO、枚举、配置类和异常类
|
||
- 创建 `FileStorageRequest.java` 和 `FileStorageResponse.java` DTO 类
|
||
- 创建 `FileExtractRequest.java` 和 `FileExtractResponse.java` DTO 类
|
||
- 创建 `StorageType.java` 枚举类
|
||
- 创建 `ExtractStatus.java` 枚举类
|
||
- 创建 `FileStorageConfig.java` 配置类
|
||
- 创建 `OssConfig.java` 配置类
|
||
- 创建 `FileStorageException.java` 异常类
|
||
- 创建 `FileExtractException.java` 异常类
|
||
- 创建 `PathSecurityException.java` 异常类
|
||
|
||
7. 创建工具类
|
||
- 创建 `FileUtil.java` 工具类
|
||
- 创建 `ZipUtil.java` 工具类
|
||
|
||
8. 创建单元测试和集成测试
|
||
- 创建 `LocalStorageServiceTest.java` 测试类
|
||
- 创建 `FileExtractServiceTest.java` 测试类
|
||
- 创建 `PathValidatorTest.java` 测试类
|
||
- 创建 `StorageMonitorServiceTest.java` 测试类
|
||
- 创建 `FileCleanupServiceTest.java` 测试类
|
||
- 创建 `FileUtilTest.java` 测试类
|
||
- 创建 `ZipUtilTest.java` 测试类
|
||
|
||
9. 验证方法
|
||
- 运行单元测试，确保所有测试通过
|
||
- 运行集成测试，确保功能正常
|
||
- 进行性能测试，确保性能达标
|
||
- 检查日志，确保日志记录完整
|
||
- 检查配置，确保配置正确
|