refactor(version): 统一版本解析逻辑到 utils/version.rs

[jsrcode]

📋 概述

统一版本解析逻辑到单一模块 utils/version.rs，消除分散在多处的重复代码，提升维护性和一致性。

---

🔍 问题分析

当前版本解析逻辑存在以下问题：

1. 分散定义：版本解析逻辑分散在 3 个位置

   • services/tool/version.rs - VersionService::parse_version()
   • utils/version.rs - parse_version_string()
   • services/tool/detector_trait.rs - extract_version_default()

2. 重复代码：3 处正则表达式定义，维护成本高

3. 潜在风险：版本比对逻辑不一致，可能导致错误的更新判断

---

✅ 解决方案

架构设计

单一数据源原则：所有版本解析逻辑统一到 utils/version.rs 模块

公共接口

提供两个公共方法：

1. parse_version_string(raw: &str) -> String

   • 提取版本字符串
   • 支持复杂格式（括号、空格分隔、v 前缀）
   • 用于简单的版本字符串提取场景

2. parse_version(raw: &str) -> Option<semver::Version> ⭐ 新增

   • 解析为强类型 semver::Version 对象
   • 用于版本比较和排序
   • 内部调用 parse_version_string() 确保一致性

格式支持

✅ 2.0.61 → 2.0.61
✅ v1.2.3 → 1.2.3
✅ 2.0.61 (Claude Code) → 2.0.61
✅ codex-cli 0.65.0 → 0.65.0
✅ 1.2.3-beta.1 → 1.2.3-beta.1
✅ rust-v0.55.0 → 0.55.0
✅ v0.13.0-preview.2 → 0.13.0-preview.2

---

📦 主要变更

1. utils/version.rs (+70 行)

新增功能

• ✅ 新增 parse_version() 方法返回 semver::Version
• ✅ 新增 test_parse_version_semver() 测试（7 个断言）
• ✅ 保留完整的 4 层回退策略
  1. 正则表达式提取标准版本号
  2. 处理括号格式：2.0.61 (Claude Code)
  3. 处理空格分隔：codex-cli 0.65.0
  4. 移除 v 前缀作为最后回退

代码示例

/// 新增方法：解析为 semver::Version 对象
pub fn parse_version(raw: &str) -> Option<Version> {
    let version_str = parse_version_string(raw);
    Version::parse(&version_str).ok()
}

---

2. services/tool/version.rs (-10 行)

重构内容

• ❌ 删除内部正则表达式定义和捕获逻辑
• ❌ 删除未使用的导入：once_cell::sync::Lazy、regex::Regex
• ✅ 替换为单行调用：crate::utils::version::parse_version(version)

代码对比

// 重构前（12 行）
fn parse_version(version: &str) -> Option<Version> {
    static VERSION_REGEX: Lazy<Regex> = Lazy::new(|| {
        Regex::new(r"(\d+\.\d+\.\d+(?:-[0-9A-Za-z\.-]+)?)").expect("invalid version regex")
    });
    let trimmed = version.trim();
    let captures = VERSION_REGEX.captures(trimmed)?;
    let matched = captures.get(1)?.as_str();
    Version::parse(matched).ok()
}

// 重构后（1 行）
fn parse_version(version: &str) -> Option<Version> {
    crate::utils::version::parse_version(version)
}

---

3. services/tool/detector_trait.rs (+2 行)

重构内容

• ❌ 删除内联正则创建：regex::Regex::new(...)
• ✅ 调用 crate::utils::version::parse_version_string()
• ✅ 增强文档注释，列出支持的所有格式

代码对比

// 重构前
fn extract_version_default(&self, output: &str) -> Option<String> {
    let re = regex::Regex::new(r"v?(\d+\.\d+\.\d+(?:-[\w.]+)?)").ok()?;
    re.captures(output)?.get(1).map(|m| m.as_str().to_string())
}

// 重构后
fn extract_version_default(&self, output: &str) -> Option<String> {
    let version = crate::utils::version::parse_version_string(output);
    let trimmed = version.trim();
    if trimmed.is_empty() {
        None
    } else {
        Some(version)
    }
}

---

4. CLAUDE.md (+12 行)

新增章节

• ✅ 在"架构记忆"部分添加"版本解析统一架构"条目
• ✅ 记录单一数据源原则
• ✅ 记录公共方法、格式支持、调用者统一情况
• ✅ 记录测试覆盖和代码减少统计

---

✅ 测试覆盖

单元测试结果

# 版本相关测试全部通过
cargo test --locked --lib -- version
running 14 tests
test utils::version::tests::test_parse_standard_version ... ok
test utils::version::tests::test_parse_version_with_v_prefix ... ok
test utils::version::tests::test_parse_version_with_bracket ... ok
test utils::version::tests::test_parse_version_with_prefix ... ok
test utils::version::tests::test_parse_version_with_prerelease ... ok
test utils::version::tests::test_parse_complex_version ... ok
test utils::version::tests::test_parse_version_semver ... ok ⭐ 新增
test services::tool::version::tests::test_version_parsing ... ok
test services::tool::version::tests::test_version_comparison ... ok
...

test result: ok. 14 passed; 0 failed; 0 ignored

全量测试结果

cargo test --locked
test result: ok. 196 passed; 1 failed; 12 ignored
# 注：1 个 WSL 测试失败与本次重构无关（环境依赖问题）

代码质量检查

npm run check
✅ AI Agent 配置检查: 通过
✅ 前端 ESLint 检查: 通过
✅ 后端 Rust Clippy 检查: 通过（零警告）
✅ 前端 Prettier 检查: 通过
✅ 后端 Rust fmt 检查: 通过

---

📊 影响分析

代码变更统计

文件	变更	说明
utils/version.rs	+70 行	新增 parse_version() + 测试
services/tool/version.rs	-10 行	删除重复逻辑 + 清理导入
detector_trait.rs	+2 行	简化逻辑 + 增强文档
CLAUDE.md	+12 行	架构文档更新
总计	+74 行	净增加（测试占 46%）

逻辑统一性

指标	重构前	重构后	改进
版本解析实现点	3 处	1 处	✅ -67%
正则表达式定义	3 个	1 个	✅ -67%
重复代码行数	~25 行	0 行	✅ -100%

---

🚀 性能影响

编译时

• ✅ 无影响（semver 已是项目依赖）

运行时

• ✅ 微小提升（正则表达式使用 Lazy 单例，仅初始化一次）

内存

• ✅ 无显著变化

---

🔄 向后兼容性

API 兼容性

• ✅ parse_version_string() 签名和行为完全不变
• ✅ 所有现有调用者无需修改
• ✅ 新增 parse_version() 为增量功能，不影响旧代码

测试验证

• ✅ 所有现有测试通过（196/197）
• ✅ 版本相关测试 100% 通过（14/14）
• ✅ 无功能回归

---

📋 Checklist

• 已运行 npm run check 且全部通过
• Rust 单元测试已运行（14/14 版本相关测试通过）
• 代码遵循 Conventional Commits 规范
• 架构文档已更新（CLAUDE.md）
• 无破坏性变更
• 测试覆盖充分

---

🎯 后续优化建议

1. 渐进迁移：考虑将其他模块（registry.rs、installer.rs）的版本比较逻辑迁移到 parse_version()
2. 性能测试：可增加正则编译开销的性能测试
3. 错误处理：parse_version() 失败时可返回更详细的错误信息
4. WSL 测试修复：修复 WSL 相关测试的环境依赖问题

---

📚 相关 Issue

解决 #问题2：版本解析逻辑分散（来自代码审查）