重构：文件系统模块化架构，优化应用启动流程
This commit is contained in:
370
docs/filesystem-architecture.md
Normal file
370
docs/filesystem-architecture.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# 文件管理模块架构升级方案
|
||||
|
||||
## 📋 目录
|
||||
- [现状分析](#现状分析)
|
||||
- [架构目标](#架构目标)
|
||||
- [核心设计](#核心设计)
|
||||
- [模块划分](#模块划分)
|
||||
- [实施路线图](#实施路线图)
|
||||
|
||||
---
|
||||
|
||||
## 🔍 现状分析
|
||||
|
||||
### 当前问题
|
||||
1. **全局变量泛滥**：4个全局单例（auditLogger, recycleBin, lockChecker, fileServer）
|
||||
2. **代码重复严重**：路径验证、文件类型检查、错误处理模式重复
|
||||
3. **魔法数字遍布**：至少15处硬编码常量
|
||||
4. **过度防御性**：删除操作有3层硬限制
|
||||
5. **性能隐患**：重复目录遍历、随机字符串生成低效
|
||||
6. **可测试性差**：依赖全局状态，难以编写单元测试
|
||||
|
||||
### 技术债务评估
|
||||
| 类别 | 债务量 | 优先级 | 影响范围 |
|
||||
|------|--------|--------|----------|
|
||||
| 重复代码 | 高 | P1 | 可维护性 |
|
||||
| 性能问题 | 高 | P0 | 用户体验 |
|
||||
| 架构问题 | 高 | P1 | 可扩展性 |
|
||||
| 代码风格 | 中 | P2 | 可读性 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 架构目标
|
||||
|
||||
### 设计原则
|
||||
1. **单一职责**：每个模块只负责一个功能领域
|
||||
2. **依赖倒置**：面向接口编程，降低耦合
|
||||
3. **开放封闭**：对扩展开放，对修改封闭
|
||||
4. **配置驱动**：安全策略可配置，不硬编码
|
||||
|
||||
### 质量目标
|
||||
- ✅ 零代码重复（DRY原则）
|
||||
- ✅ 零全局变量（依赖注入）
|
||||
- ✅ 零魔法数字（命名常量）
|
||||
- ✅ 零性能隐患（优化热点）
|
||||
- ✅ 100% 可测试（支持mock）
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 核心设计
|
||||
|
||||
### 1. 分层架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Application Layer (app.go) │
|
||||
│ - 对外接口（Bindings） │
|
||||
└────────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────────▼────────────────────────┐
|
||||
│ Service Layer (FileSystemService) │
|
||||
│ - 编排业务逻辑 │
|
||||
│ - 事务管理 │
|
||||
└────────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────────▼────────────────────────┐
|
||||
│ Component Layer │
|
||||
│ ┌────────────┬────────────┬──────────┐ │
|
||||
│ │Validator │Manager │Handler │ │
|
||||
│ │路径验证 │文件管理 │文件服务 │ │
|
||||
│ └────────────┴────────────┴──────────┘ │
|
||||
└────────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────────▼────────────────────────┐
|
||||
│ Infrastructure Layer │
|
||||
│ ┌──────────┬──────────┬──────────────┐ │
|
||||
│ │Audit │Recycle │Lock │ │
|
||||
│ │审计日志 │回收站 │文件锁 │ │
|
||||
│ └──────────┴──────────┴──────────────┘ │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. 核心接口设计
|
||||
|
||||
```go
|
||||
// FileService 文件操作核心接口
|
||||
type FileService interface {
|
||||
Read(path string) (string, error)
|
||||
Write(path, content string) error
|
||||
Delete(path string) error
|
||||
List(path string) ([]FileInfo, error)
|
||||
Create(path string, isDir bool) error
|
||||
Move(src, dst string) error
|
||||
GetInfo(path string) (*FileInfo, error)
|
||||
}
|
||||
|
||||
// PathValidator 路径验证接口
|
||||
type PathValidator interface {
|
||||
Validate(path string) *ValidationError
|
||||
IsSafe(path string) bool
|
||||
IsSensitive(path string) bool
|
||||
}
|
||||
|
||||
// FileTypeManager 文件类型管理接口
|
||||
type FileTypeManager interface {
|
||||
GetMIMEType(ext string) string
|
||||
IsAllowed(ext string) bool
|
||||
GetMaxSize(ext string) int64
|
||||
}
|
||||
|
||||
// SecurityGuard 安全策略接口
|
||||
type SecurityGuard interface {
|
||||
CheckDelete(path string) error
|
||||
CheckAccess(path string) error
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 配置驱动设计
|
||||
|
||||
```go
|
||||
// Config 文件系统配置
|
||||
type Config struct {
|
||||
// 安全配置
|
||||
Security SecurityConfig
|
||||
// 性能配置
|
||||
Performance PerformanceConfig
|
||||
// 功能开关
|
||||
Features FeatureConfig
|
||||
}
|
||||
|
||||
// SecurityConfig 安全策略配置
|
||||
type SecurityConfig struct {
|
||||
// 路径验证
|
||||
PathValidation PathValidationConfig
|
||||
// 删除限制
|
||||
DeleteRestrictions DeleteRestrictionsConfig
|
||||
// 文件类型
|
||||
FileTypes FileTypeConfig
|
||||
}
|
||||
|
||||
// DeleteRestrictionsConfig 删除限制配置
|
||||
type DeleteRestrictionsConfig struct {
|
||||
Enabled bool // 是否启用限制
|
||||
MaxSizeGB float64 // 最大文件大小（GB）
|
||||
MaxDepth int // 最大目录深度
|
||||
MaxFileCount int // 最大文件数量
|
||||
RequireConfirm bool // 超过限制是否需要确认
|
||||
ForbiddenPaths []string // 禁止删除的路径
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 模块划分
|
||||
|
||||
### 模块1: 核心文件操作 (fs_core)
|
||||
```
|
||||
fs_core/
|
||||
├── service.go # FileService 实现
|
||||
├── file_info.go # FileInfo 结构
|
||||
└── errors.go # 错误定义
|
||||
```
|
||||
|
||||
### 模块2: 路径验证 (validator)
|
||||
```
|
||||
validator/
|
||||
├── path_validator.go # PathValidator 接口和实现
|
||||
├── config.go # 验证配置
|
||||
└── errors.go # 验证错误
|
||||
```
|
||||
|
||||
### 模块3: 文件类型管理 (filetype)
|
||||
```
|
||||
filetype/
|
||||
├── manager.go # FileTypeManager 实现
|
||||
├── types.go # 文件类型配置
|
||||
└── mime.go # MIME 类型映射
|
||||
```
|
||||
|
||||
### 模块4: 基础设施 (infra)
|
||||
```
|
||||
infra/
|
||||
├── audit/
|
||||
│ └── logger.go # 审计日志
|
||||
├── recycle/
|
||||
│ └── bin.go # 回收站
|
||||
├── lock/
|
||||
│ └── checker.go # 文件锁检查
|
||||
└── server/
|
||||
└── handler.go # HTTP 文件服务
|
||||
```
|
||||
|
||||
### 模块5: ZIP 操作 (zip)
|
||||
```
|
||||
zip/
|
||||
├── reader.go # ZIP 读取
|
||||
├── writer.go # ZIP 写入
|
||||
├── security.go # ZIP 安全检查
|
||||
└── temp.go # 临时文件管理
|
||||
```
|
||||
|
||||
### 模块6: 配置管理 (config)
|
||||
```
|
||||
config/
|
||||
├── constants.go # 常量定义
|
||||
├── config.go # 配置结构
|
||||
└── defaults.go # 默认配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ 实施路线图
|
||||
|
||||
### 阶段1: 紧急修复（P0）- 1天
|
||||
**目标**: 修复严重性能和稳定性问题
|
||||
|
||||
- [x] 任务1: 修复 `generateRandomString` 的 `time.Sleep`
|
||||
- [x] 任务2: 修复文件锁检查的破坏性 rename
|
||||
|
||||
**影响**: 立即提升性能和稳定性
|
||||
|
||||
---
|
||||
|
||||
### 阶段2: 基础建设（P1）- 2天
|
||||
**目标**: 统一配置和常量，消除技术债务
|
||||
|
||||
- [x] 任务3: 创建 constants.go，定义所有命名常量
|
||||
- [x] 任务4: 创建 config.go，统一配置管理
|
||||
- [x] 任务5: 定义核心接口（FileService, PathValidator, FileTypeManager）
|
||||
|
||||
**影响**: 提升代码质量，为重构打基础
|
||||
|
||||
---
|
||||
|
||||
### 阶段3: DRY重构（P1）- 3天
|
||||
**目标**: 消除代码重复，提升可维护性
|
||||
|
||||
- [x] 任务6: 重构路径验证逻辑（PathValidator）
|
||||
- [x] 任务7: 重构文件类型管理（FileTypeManager）
|
||||
- [x] 任务8: 重构 ZIP 操作（withZipReader）
|
||||
|
||||
**影响**: 减少30%+代码量，提升可维护性
|
||||
|
||||
---
|
||||
|
||||
### 阶段4: 安全优化（P1）- 2天
|
||||
**目标**: 优化过度防御，改善用户体验
|
||||
|
||||
- [x] 任务9: 重构 DeletePath 安全检查
|
||||
- [x] 任务10: 配置化安全策略
|
||||
|
||||
**影响**: 提升用户体验，保留安全性
|
||||
|
||||
---
|
||||
|
||||
### 阶段5: 架构升级（P1）- 3天
|
||||
**目标**: 引入依赖注入，消除全局变量
|
||||
|
||||
- [x] 任务11: 创建 FileSystemService
|
||||
- [x] 任务12: 重构各组件为独立模块
|
||||
- [x] 任务13: 消除全局变量
|
||||
|
||||
**影响**: 提升可测试性和可扩展性
|
||||
|
||||
---
|
||||
|
||||
### 阶段6: 代码质量（P2）- 2天
|
||||
**目标**: 统一代码风格，完善文档
|
||||
|
||||
- [x] 任务14: 统一错误处理
|
||||
- [x] 任务15: 添加结构化日志
|
||||
- [x] 任务16: 统一注释风格
|
||||
- [x] 任务17: 编写单元测试
|
||||
|
||||
**影响**: 提升代码可读性和可维护性
|
||||
|
||||
---
|
||||
|
||||
### 阶段7: 测试验证（P2）- 2天
|
||||
**目标**: 确保重构质量，回归测试
|
||||
|
||||
- [x] 任务18: 编写集成测试
|
||||
- [x] 任务19: 性能基准测试
|
||||
- [x] 任务20: 安全测试
|
||||
|
||||
**影响**: 确保重构质量，无回归问题
|
||||
|
||||
---
|
||||
|
||||
## 📊 预期收益
|
||||
|
||||
### 代码质量
|
||||
- **代码量**: 预计减少 30-40%
|
||||
- **重复率**: 从 25% 降至 < 5%
|
||||
- **圈复杂度**: 平均降低 40%
|
||||
|
||||
### 性能提升
|
||||
- **删除操作**: 性能提升 60%（消除重复遍历）
|
||||
- **回收站**: 性能提升 99%（修复 time.Sleep）
|
||||
- **文件锁**: 安全性提升 100%（消除破坏性操作）
|
||||
|
||||
### 可维护性
|
||||
- **测试覆盖率**: 从 0% 提升至 80%+
|
||||
- **可测试性**: 从困难变为简单（依赖注入）
|
||||
- **扩展性**: 新增功能无需修改核心代码
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术选型
|
||||
|
||||
### 依赖注入
|
||||
- 考虑 Uber Fx 或 Google Wire
|
||||
- 或者手动 DI（更简单，适合当前规模）
|
||||
|
||||
### 配置管理
|
||||
- 使用结构体配置
|
||||
- 支持 JSON/YAML 导入导出
|
||||
- 环境变量覆盖
|
||||
|
||||
### 日志
|
||||
- 结构化日志（logrus 或 zap）
|
||||
- 可配置日志级别
|
||||
- 支持日志轮转
|
||||
|
||||
### 测试
|
||||
- 单元测试：testify/assert
|
||||
- Mock：gomock
|
||||
- 基准测试：内置 testing/benchmark
|
||||
|
||||
---
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
### 兼容性
|
||||
- 保持对外接口（app.go 的方法）不变
|
||||
- 内部重构对前端透明
|
||||
|
||||
### 渐进式重构
|
||||
- 不重写，只重构
|
||||
- 一次只改一个模块
|
||||
- 每次重构后运行测试
|
||||
|
||||
### 回滚计划
|
||||
- 使用 Git 分支管理
|
||||
- 每个阶段完成后打 tag
|
||||
- 出现问题可快速回滚
|
||||
|
||||
---
|
||||
|
||||
## 🎯 成功标准
|
||||
|
||||
### 功能完整性
|
||||
- ✅ 所有现有功能正常工作
|
||||
- ✅ 无新增 bug
|
||||
- ✅ 性能不下降
|
||||
|
||||
### 代码质量
|
||||
- ✅ 代码重复率 < 5%
|
||||
- ✅ 测试覆盖率 > 80%
|
||||
- ✅ 代码审查通过
|
||||
|
||||
### 文档完整性
|
||||
- ✅ 架构文档完整
|
||||
- ✅ API 文档完整
|
||||
- ✅ 配置文档完整
|
||||
|
||||
---
|
||||
|
||||
*文档版本: 1.0*
|
||||
*创建日期: 2026-01-27*
|
||||
*作者: Claude Code*
|
||||
Reference in New Issue
Block a user