lxy/u-desk
Private
Public Access
1
0
Fork 0
Code Activity
Files
eb2cbad17b3dce1ac70668e5189e48b4433d74e0
u-desk/docs/filesystem-architecture.md

10 KiB
Raw Blame History

文件管理模块架构升级方案

📋 目录

🔍 现状分析

当前问题

  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. 核心接口设计

// 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. 配置驱动设计

// 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天

目标: 修复严重性能和稳定性问题

  • 任务1: 修复 generateRandomString 的 time.Sleep
  • 任务2: 修复文件锁检查的破坏性 rename

影响: 立即提升性能和稳定性

阶段2: 基础建设（P1）- 2天

目标: 统一配置和常量，消除技术债务

  • 任务3: 创建 constants.go，定义所有命名常量
  • 任务4: 创建 config.go，统一配置管理
  • 任务5: 定义核心接口（FileService, PathValidator, FileTypeManager）

影响: 提升代码质量，为重构打基础

阶段3: DRY重构（P1）- 3天

目标: 消除代码重复，提升可维护性

  • 任务6: 重构路径验证逻辑（PathValidator）
  • 任务7: 重构文件类型管理（FileTypeManager）
  • 任务8: 重构 ZIP 操作（withZipReader）

影响: 减少30%+代码量，提升可维护性

阶段4: 安全优化（P1）- 2天

目标: 优化过度防御，改善用户体验

  • 任务9: 重构 DeletePath 安全检查
  • 任务10: 配置化安全策略

影响: 提升用户体验，保留安全性

阶段5: 架构升级（P1）- 3天

目标: 引入依赖注入，消除全局变量

  • 任务11: 创建 FileSystemService
  • 任务12: 重构各组件为独立模块
  • 任务13: 消除全局变量

影响: 提升可测试性和可扩展性

阶段6: 代码质量（P2）- 2天

目标: 统一代码风格，完善文档

  • 任务14: 统一错误处理
  • 任务15: 添加结构化日志
  • 任务16: 统一注释风格
  • 任务17: 编写单元测试

影响: 提升代码可读性和可维护性

阶段7: 测试验证（P2）- 2天

目标: 确保重构质量，回归测试

  • 任务18: 编写集成测试
  • 任务19: 性能基准测试
  • 任务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

View Git Blame Copy Permalink