Development

开发与构建

环境要求

• Rust 1.85+（Edition 2024）
• 仓库未包含 rustfmt.toml 或 clippy.toml，遵循 Rust 默认规范

常用构建命令

所有命令均需在 workspace 根目录下执行：

cargo build                      # 构建全部 crate
cargo test                       # 执行全部测试
cargo test -p lyrics-helper      # 仅执行门面 crate 集成测试
cargo test test_parse_lrc        # 执行指定单元测试
cargo clippy --all-targets       # 代码检查
cargo fmt                        # 格式化代码
cargo doc --no-deps              # 生成离线文档（别名：cargo doc-local）

离线构建与验证

搜索模块依赖网络库；修改底层解析或核心逻辑时，需同时验证禁用默认 feature 的编译与测试：

cargo build --workspace --no-default-features
cargo clippy --workspace --no-default-features

运行示例程序

示例代码位于 crates/lyrics-helper/examples/：

# 格式解析与生成
cargo run --example demo -- parsers-demo
cargo run --example demo -- generators-demo
cargo run --example demo -- parse crates/lyrics-helper/tests/test_data/LrcDemo.txt lrc
cargo run --example demo -- generate crates/lyrics-helper/tests/test_data/QrcDemo.txt qrc lrc

# 在线搜索测试（需要网络连接）
cargo run --example search_test
cargo run --example search_lyrics_test

测试组织

• 集成测试位于 crates/lyrics-helper/tests/parser_tests.rs，覆盖解析器、生成器与解密器。
• 测试数据存放在 crates/lyrics-helper/tests/test_data/，包含各格式的典型真实样本。
• 单元测试遵循 Rust 惯例，直接置于被测模块所在文件的 #[cfg(test)] mod tests 中。

代码维护原则

• 移植对标：移植自上游 C# 项目的模块应与原版保持语义一致，并在注释中注明对应的 C# 类型或方法名。
• 差异标注：若因 Rust 语言特性或上游 Bug 修复而产生有意偏离（如 BOM 剥离、模型 Sync 支持、QRC 时长保留等），必须在文档注释中明确说明缘由。
• 分层边界：跨 crate 逻辑变动需保证依赖单向流动，禁止向上层 crate 添加依赖引用。