# ESP String Parser 重构计划
## 已完成任务 ✅
### P0: 文档修正（已完成）
- ✅ README.md - 去除夸张表述，添加测试环境说明
- ✅ CHANGELOG.md - 补充版本记录，去除 emoji，使用客观描述
- ✅ ARCHITECTURE.md - 确认可读性
### P1: CLI 升级（已完成）
- ✅ 升级 CLI 版本号从 0.2.0 到 0.6.0
- ✅ 将所有 `Plugin::new()` 替换为 `Plugin::load()`（5 处）
- ✅ 移除 `#![allow(deprecated)]`
- ✅ 所有测试通过（49/49）
### P2.1: 拆分 src/plugin.rs（已完成 - 2025-11-26）
**目标**：将 1264 行的单一大文件拆分为职责清晰的子模块
**实施结果**：
```
src/plugin/
├── mod.rs # Plugin 结构体和公共接口 (150 行)
├── parser.rs # 加载和解析逻辑 (240 行)
├── strings.rs # 字符串提取 (180 行)
├── translate.rs # 翻译应用 (380 行)
├── writer.rs # 文件写入 (130 行)
├── stats.rs # 统计信息 (70 行)
└── esl.rs # ESL FormID 重编号 (80 行)
```
**验证结果**：
- ✅ 所有 49 个单元测试通过
- ✅ Clippy 检查通过（仅少量警告）
- ✅ 向后兼容：公共 API 保持不变
- ✅ 代码结构清晰，职责分明
**重构效果**：
- 代码行数：1264 行 → 分散到 7 个文件（平均 ~180 行/文件）
- 职责清晰：每个模块负责特定功能
- 易于维护：相关代码集中在一起
- 测试稳定：所有现有测试继续工作
### P2.2: 拆分 src/string_file.rs（已完成 - 2025-11-26）
**目标**：分离字符串文件的不同职责
**实施结果**：
```
src/string_file/
├── mod.rs # 公共接口和基础类型 (95 行)
├── file.rs # StringFile 结构体和方法 (380 行)
├── set.rs # StringFileSet 集合操作 (320 行)
├── bsa.rs # BSA fallback 逻辑 (70 行)
├── io.rs # 文件名解析工具 (54 行)
└── tests.rs # 测试模块 (271 行)
```
**验证结果**：
- ✅ 所有 49 个单元测试通过
- ✅ 所有 string_file 相关测试通过
- ✅ Clippy 检查通过（仅少量警告）
- ✅ 向后兼容：公共 API 保持不变
- ✅ 代码结构清晰，职责分明
**重构效果**：
- 代码行数：1119 行 → 分散到 6 个文件（平均 ~190 行/文件）
- 职责清晰：每个模块负责特定功能
- 易于维护：相关代码集中在一起
- 测试稳定：所有现有测试继续工作
### P2.3: 提取字符串路由为独立模块（已完成 - 2025-11-26）
**目标**：将 `data/string_records.json` 的使用逻辑独立化
**实施结果**：
```
src/string_routes/
├── mod.rs # 公共接口导出
├── router.rs # StringRouter trait 和 DefaultStringRouter 实现
└── data.rs # 加载 string_records.json
```
**接口实现**：
```rust
pub trait StringRouter: Send + Sync + Debug {
fn get_string_subrecord_types(&self, record_type: &str) -> Option<&[String]>;
fn supports_strings(&self, record_type: &str, subrecord_type: &str) -> bool;
}
#[derive(Debug)]
pub struct DefaultStringRouter {
routes: HashMap<String, Vec<String>>,
}
```
**集成结果**：
- ✅ Plugin 添加 `string_router: Arc<dyn StringRouter>` 字段
- ✅ 保留 `string_records` 字段用于向后兼容（标记 deprecated）
- ✅ 更新 `extract_strings` 和 `apply_translations` 使用路由器
- ✅ 新增 3 个路由器单元测试
- ✅ 所有 54 个库测试通过
- ✅ Clippy 检查通过
**重构效果**：
- 职责清晰：路由逻辑独立为模块
- 易于扩展：可自定义 StringRouter 实现
- 向后兼容：旧代码继续工作
### P2.4: 实现 IO 抽象层注入（已完成 - 2025-11-26）
**目标**：让核心流程通过 IO trait 而非直接使用 std::fs
**实施结果**：
IO trait 已在 v0.4.0 中完善（src/io/）：
- ✅ EspReader/EspWriter trait
- ✅ StringFileReader/StringFileWriter trait
- ✅ DefaultEspReader/DefaultEspWriter 实现
**新增方法**：
```rust
// Plugin 添加 reader 注入方法
impl Plugin {
pub fn load_with_reader(
path: PathBuf,
reader: &dyn EspReader
) -> Result<Self> {
let raw_data = reader.read(&path)?;
// 解析逻辑...
}
// 保留原方法（向后兼容）
pub fn load(path: PathBuf) -> Result<Self> {
// 使用 memmap 优化的默认实现
}
}
// StringFileSet 添加 reader 注入方法
impl StringFileSet {
pub fn load_from_directory_with_reader(
directory: &Path,
plugin_name: &str,
language: &str,
reader: &dyn StringFileReader,
) -> Result<Self> {
// 使用注入的 reader 加载文件
}
// 保留原方法（向后兼容）
pub fn load_from_directory(...) -> Result<Self> {
// 默认实现
}
}
```
**验证结果**：
- ✅ 所有 54 个库测试通过
- ✅ 9/10 集成测试通过（1个性能测试超时，非功能问题）
- ✅ Clippy 检查通过
- ✅ 向后兼容：旧代码无需修改
**重构效果**：
- 依赖倒置：核心逻辑依赖抽象而非具体实现
- 易于测试：可注入 mock reader
- 易于扩展：可实现网络 IO、内存 IO 等
- 向后兼容：保留便捷方法
### P3: Workspace 结构规划 ❌ 已取消
**状态**：已取消 (2025-11-27)
**原因**：
1. **功能单一**：这是一个专门处理 ESP 文件字符串的库，使用场景聚焦
2. **维护成本**：多个 crate 意味着多套版本号管理和发布流程
3. **收益有限**：~3000 行项目，workspace 带来的增量编译收益不明显
4. **架构已优化**：P2 重构已达到良好的模块化状态
**如未来出现以下情况可重新考虑**：
- 有人想单独复用 `esp-format-core` 等核心模块
- 编译时间成为明显瓶颈
- 需要独立发布子模块到 crates.io
## 实施优先级
### ✅ 全部完成（2025-11-27）
- [x] P0: 文档修正
- [x] P1: CLI 升级
- [x] P2.1: 拆分 plugin.rs (1264 行 → 7 个文件)
- [x] P2.2: 拆分 string_file.rs (1119 行 → 6 个文件)
- [x] P2.3: 提取字符串路由模块
- [x] P2.4: 实现 IO 抽象层注入
- [x] P3: Workspace 结构规划 → ❌ 已取消（过度工程化）
## P2 重构总结
### 重构统计
- **模块拆分**: 2个大文件 → 13个小文件（plugin: 7个，string_file: 6个）
- **代码行数**: 2383 行 → 分散到 13 个文件（平均 ~183 行/文件）
- **新增模块**: string_routes（3个文件）
- **测试通过率**: 54/54 库测试，9/10 集成测试
### 架构改进
1. **职责分离**: 每个模块负责特定功能
2. **依赖倒置**: 核心逻辑依赖抽象接口
3. **易于扩展**: StringRouter 和 IO 层可自定义
4. **向后兼容**: 旧代码无需修改
### 技术债务清理
- ✅ 消除了 `string_records` 字段的直接依赖（使用路由器）
- ✅ 消除了 `std::fs` 的直接依赖（使用 IO trait）
- ✅ 保持了性能优化（memmap 等）
- ✅ 保持了向后兼容性
## 测试策略
每个重构步骤后必须：
1. 运行 `cargo test` 确保所有测试通过
2. 运行 `cargo clippy` 检查代码质量
3. 运行 `cargo build --release --features cli` 验证 CLI
4. 手动测试关键功能（提取、应用翻译、ESL 转换）
## 回滚计划
如果重构导致问题：
1. 使用 git 回滚到上一个稳定版本
2. 创建新分支进行重构
3. 通过 PR 审查后再合并
## 注意事项
1. **保持向后兼容**：公共 API 不应有破坏性变更
2. **渐进式重构**：每次只改一个模块，确保稳定
3. **文档同步更新**：代码结构变化后更新 ARCHITECTURE.md
4. **性能监控**：重构不应降低性能，必要时添加 benchmark
## 参考资料
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- [SOLID 原则在 Rust 中的应用](https://doc.rust-lang.org/book/)
- [Cargo Workspace 文档](https://doc.rust-lang.org/cargo/reference/workspaces.html)