cc-switch/docs/BACKEND_REFACTOR_PLAN.md

CC Switch Rust 后端重构方案

目录

• 背景与现状
• 问题确认
• 方案评估
• 渐进式重构路线
• 测试策略
• 风险与对策
• 总结

背景与现状

• 前端已完成重构，后端 (Tauri + Rust) 仍维持历史结构。
• 核心文件集中在 src-tauri/src/commands.rs、lib.rs 等超大文件中，业务逻辑与界面事件耦合严重。
• 测试覆盖率低，只有零散单元测试，缺乏集成验证。

问题确认

提案问题	实际情况	严重程度
commands.rs 过长	✅ 1526 行，包含 32 个命令，职责混杂	🔴 高
lib.rs 缺少服务层	✅ 541 行，托盘/事件/业务逻辑耦合	🟡 中
Result<T, String> 泛滥	✅ 118 处，错误上下文丢失	🟡 中
全局 Mutex 阻塞	✅ 31 处 .lock() 调用，读写不分离	🟡 中
配置逻辑分散	✅ 分布在 5 个文件 (config/app_config/app_store/settings/codex_config)	🟢 低

代码规模分布（约 5.4k SLOC）：

• commands.rs: 1526 行（28%）→ 第一优先级 🎯
• lib.rs: 541 行（10%）→ 托盘逻辑与业务耦合
• mcp.rs: 732 行（14%）→ 相对清晰
• migration.rs: 431 行（8%）→ 一次性逻辑
• 其他文件合计：2156 行（40%）

方案评估

✅ 优点

1. 分层架构清晰

   • commands/：Tauri 命令薄层
   • services/：业务流程，如供应商切换、MCP 同步
   • infrastructure/：配置读写、外设交互
   • domain/：数据模型 (Provider, AppType 等)
     → 提升可测试性、降低耦合度、方便团队协作。

2. 统一错误处理

   • 引入 AppError（thiserror），保留错误链和上下文。
   • Tauri 命令仍返回 Result<T, String>，通过 From<AppError> 自动转换。
   • 改善日志可读性，利于排查。

3. 并发优化

   • AppState 切换为 RwLock<MultiAppConfig>。
   • 读多写少的场景提升吞吐（如频繁查询供应商列表）。

⚠️ 风险

1. 过度设计

   • 完整 DDD 四层在 5k 行项目中会增加 30-50% 维护成本。
   • Rust trait + repository 样板较多，收益不足。
   • 推荐“轻量分层”而非正统 DDD。

2. 迁移成本高

   • commands.rs 拆分、错误统一、锁改造触及多文件。
   • 测试缺失导致重构风险高，需先补测试。
   • 估算完整改造需 5-6 周；建议分阶段输出可落地价值。

3. 技术选型需谨慎

   • parking_lot 相比标准库 RwLock 提升有限，不必引入。
   • spawn_blocking 仅用于 >100ms 的阻塞任务，避免滥用。
   • 以现有依赖为主，控制复杂度。

实施进度

• 阶段 1：统一错误处理 ✅
  • 引入 thiserror 并在 src-tauri/src/error.rs 定义 AppError，提供常用构造函数和 From<AppError> for String，保留错误链路。
  • 配置、存储、同步等核心模块（config.rs、app_config.rs、app_store.rs、store.rs、codex_config.rs、claude_mcp.rs、claude_plugin.rs、import_export.rs、mcp.rs、migration.rs、speedtest.rs、usage_script.rs、settings.rs、lib.rs 等）已统一返回 Result<_, AppError>，避免字符串错误丢失上下文。
  • Tauri 命令层继续返回 Result<_, String>，通过 ? + Into<String> 统一转换，前端无需调整。
  • cargo check 通过，rg "Result<[^>]+, String" 巡检确认除命令层外已无字符串错误返回。
• 阶段 2：拆分命令层 ✅
  • 已将单一 src-tauri/src/commands.rs 拆分为 commands/{provider,mcp,config,settings,misc,plugin}.rs 并通过 commands/mod.rs 统一导出，保持对外 API 不变。
  • 每个文件聚焦单一功能域（供应商、MCP、配置、设置、杂项、插件），命令函数平均 150-250 行，可读性与后续维护性显著提升。
  • 相关依赖调整后 cargo check 通过，静态巡检确认无重复定义或未注册命令。
• 阶段 3：补充测试 🚧
  • 新增 tests/import_export_sync.rs 集成测试，覆盖配置备份与 Claude 供应商 live 同步路径（使用隔离的 HOME 目录，避免污染真实环境）。
  • 扩展 lib.rs 对核心数据结构与错误处理 API 的导出，便于后续服务层测试复用。
  • 当前覆盖率聚焦配置导入导出模块，后续待补充 MCP 同步、供应商切换等跨模块场景。

渐进式重构路线

阶段 1：统一错误处理（高收益 / 低风险）

• 新增 src-tauri/src/error.rs，定义 AppError。
• 底层文件 IO、配置解析等函数返回 Result<T, AppError>。
• 命令层通过 ? 自动传播，最终 .map_err(Into::into)。
• 预估 3-5 天，立即启动。

阶段 2：拆分 commands.rs（高收益 / 中风险）

• 按业务拆分为 commands/provider.rs、commands/mcp.rs、commands/config.rs、commands/settings.rs、commands/misc.rs。
• commands/mod.rs 统一导出和注册。
• 文件行数降低到 200-300 行/文件，职责单一。
• 预估 5-7 天，可并行进行部分重构。

阶段 3：补充测试（中收益 / 中风险）

• 引入 tests/ 或 src-tauri/tests/ 集成测试，覆盖供应商切换、MCP 同步、配置迁移。
• 使用 tempfile/tempdir 隔离文件系统，组合少量回归脚本。
• 预估 5-7 天，为后续重构提供安全网。

阶段 4：提取轻量服务层（中收益 / 中风险）

• 新增 services/provider_service.rs、services/mcp_service.rs。
• 不强制使用 trait；直接以自由函数/结构体实现业务流程。

  pub struct ProviderService;
  impl ProviderService {
      pub fn switch(config: &mut MultiAppConfig, app: AppType, id: &str) -> Result<(), AppError> {
          // 业务流程：验证、回填、落盘、更新 current、触发事件
      }
  }
  

• 命令层负责参数解析，服务层处理业务逻辑，托盘逻辑重用同一接口。
• 预估 7-10 天，可在测试补齐后执行。

阶段 5：锁与阻塞优化（低收益 / 低风险）

• AppState 从 Mutex 改为 RwLock。
• 读写操作分别使用 read()/write()，减少不必要的互斥。
• 长耗时任务（如归档、批量迁移）用 spawn_blocking 包裹，其余直接同步调用。
• 预估 3-5 天，可在主流程稳定后安排。

测试策略

• 优先覆盖场景
  • 供应商切换：状态更新 + live 配置同步
  • MCP 同步：enabled 服务器快照与落盘
  • 配置迁移：归档、备份与版本升级
• 推荐结构

  #[cfg(test)]
  mod integration {
      use super::*;
      #[test]
      fn switch_provider_updates_live_config() { /* ... */ }
      #[test]
      fn sync_mcp_to_codex_updates_claude_config() { /* ... */ }
      #[test]
      fn migration_preserves_backup() { /* ... */ }
  }
  

• 目标覆盖率：关键路径 >80%，文件 IO/迁移 >70%。

风险与对策

• 测试不足 → 阶段 3 强制补齐，建立基础集成测试。
• 重构跨度大 → 按阶段在独立分支推进（如 refactor/backend-step1 等）。
• 回滚困难 → 每阶段结束打 tag（如 v3.6.0-backend-step1），保留回滚点。
• 功能回归 → 重构后执行手动冒烟流程：供应商切换、托盘操作、MCP 同步、配置导入导出。

总结

• 当前规模下不建议整体引入完整 DDD/四层架构，避免过度设计。
• 建议遵循“错误统一 → 命令拆分 → 补测试 → 服务层抽象 → 锁优化”的渐进式策略。
• 完成阶段 1-3 后即可显著提升可维护性与可靠性；阶段 4-5 可根据资源灵活安排。
• 重构过程中同步维护文档与测试，确保团队成员对架构演进保持一致认知。