标准项目结构基础结构my_project/ ├── Cargo.toml # 项目配置文件包名、版本、依赖等 ├── Cargo.lock # 锁定依赖版本自动生成不提交到 git ├── .gitignore # Git 忽略文件配置 ├── src/ # 源码目录 │ ├── main.rs # 二进制入口文件 │ └── lib.rs # 库入口文件 ├── tests/ # 集成测试目录 ├── benches/ # 性能测试目录 ├── examples/ # 示例代码目录 ├── bin/ # 多个二进制文件目录可选 ├── build.rs # 构建脚本 └── target/ # 编译输出目录自动生成不提交详细目录说明1. 源码目录 (src/)基础结构src/ ├── main.rs # 二进制 crate 的主入口 ├── lib.rs # 库 crate 的主入口 ├── bin/ # 多个二进制文件目录 │ ├── server.rs # 可执行文件server │ ├── client.rs # 可执行文件client │ └── tool.rs # 可执行文件tool ├── lib/ # 库模块目录可选 │ ├── mod.rs # 模块定义 │ ├── utils.rs # 工具函数模块 │ └── config.rs # 配置模块 └── modules/ # 功能模块可选 ├── mod.rs ├── auth.rs ├── database.rs └── api.rssrc/bin/ 子目录说明每个.rs文件都会被编译成独立的二进制文件文件名即为二进制文件名可以通过cargo run --bin server运行特定二进制文件2. 测试目录 (tests/)tests/ ├── integration_test.rs # 集成测试文件 ├── api_test.rs # API 测试 ├── database_test.rs # 数据库测试 └── common/ # 测试辅助模块 ├── mod.rs # 公共测试工具 └── test_utils.rs # 测试工具函数测试特点每个文件都是一个独立的 crate可以访问项目的公共 API用于编写集成测试单元测试通常放在源码文件中使用#[cfg(test)]3. 性能测试目录 (benches/)benches/ ├── benchmark.rs # 基准测试文件 ├── io_benchmark.rs # I/O 性能测试 ├── algorithm_benchmark.rs # 算法性能测试 └── data/ # 测试数据目录 ├── large_dataset.txt └── sample_data.json使用方式# 运行所有基准测试cargobench# 运行特定基准测试cargobench benchmark_name# 需要 nightly Rustrustup overridesetnightly4. 示例目录 (examples/)examples/ ├── basic_usage.rs # 基本使用示例 ├── advanced_usage.rs # 高级用法示例 ├── web_server.rs # Web 服务器示例 ├── cli_example.rs # 命令行工具示例 └── integration/ # 复杂示例的模块 ├── mod.rs └── helper.rs运行示例# 运行特定示例cargorun--examplebasic_usage# 编译所有示例cargobuild--examples完整项目结构示例典型 Rust 库项目awesome_lib/ ├── Cargo.toml ├── Cargo.lock ├── README.md # 项目说明文档 ├── CHANGELOG.md # 版本变更记录 ├── LICENSE # 开源许可证 ├── .gitignore ├── .github/ # GitHub 配置 │ └── workflows/ │ ├── ci.yml # CI 配置 │ └── release.yml # 发布配置 ├── src/ │ ├── lib.rs # 库入口 │ ├── error.rs # 错误类型定义 │ ├── core/ │ │ ├── mod.rs │ │ ├── engine.rs │ │ └── processor.rs │ ├── utils/ │ │ ├── mod.rs │ │ ├── string_utils.rs │ │ └── file_utils.rs │ └── bin/ # 提供的命令行工具 │ ├── lib_cli.rs │ └── lib_tool.rs ├── tests/ │ ├── integration_test.rs │ ├── unit_test.rs │ └── common/ │ ├── mod.rs │ └── setup.rs ├── benches/ │ ├── throughput.rs │ ├── latency.rs │ └── memory.rs ├── examples/ │ ├── simple.rs │ ├── advanced.rs │ └── custom_config.rs └── target/ # 编译产物不提交 ├── debug/ # 开发模式编译 ├── release/ # 发布模式编译 └── doc/ # 生成的文档典型 Rust 二进制项目awesome_app/ ├── Cargo.toml ├── Cargo.lock ├── README.md ├── .env.example # 环境变量示例 ├── .dockerignore # Docker 忽略文件 ├── Dockerfile # Docker 镜像构建文件 ├── docker-compose.yml # Docker 编排配置 ├── config/ # 配置文件目录 │ ├── default.toml # 默认配置 │ ├── production.toml # 生产环境配置 │ └── development.toml # 开发环境配置 ├── src/ │ ├── main.rs # 主入口 │ ├── config/ │ │ ├── mod.rs │ │ ├── app_config.rs │ │ └── logger.rs │ ├── handlers/ │ │ ├── mod.rs │ │ ├── http_handler.rs │ │ └── grpc_handler.rs │ ├── models/ │ │ ├── mod.rs │ │ ├── user.rs │ │ └── product.rs │ ├── services/ │ │ ├── mod.rs │ │ ├── auth_service.rs │ │ └── data_service.rs │ ├── utils/ │ │ ├── mod.rs │ │ └── helpers.rs │ └── bin/ # 辅助工具 │ ├── migrate.rs # 数据库迁移工具 │ ├── seed.rs # 数据填充工具 │ └── worker.rs # 后台工作进程 ├── tests/ │ ├── integration/ │ │ ├── api_tests.rs │ │ └── db_tests.rs │ ├── e2e/ # 端到端测试 │ │ └── workflow.rs │ └── fixtures/ # 测试数据 │ ├── users.json │ └── products.json ├── benches/ │ ├── api_benchmark.rs │ └── db_benchmark.rs ├── examples/ │ ├── api_client.rs │ └── custom_middleware.rs ├── scripts/ # 辅助脚本 │ ├── setup.sh │ └── deploy.sh └── target/ └── ...关键文件说明Cargo.toml 配置文件[package] name awesome_app version 0.1.0 edition 2021 authors [Your Name emailexample.com] description A brief description license MIT repository https://github.com/user/awesome_app readme README.md keywords [rust, example, cli] categories [command-line-utilities] [lib] name awesome_lib path src/lib.rs [[bin]] name main_app path src/main.rs [[bin]] name cli_tool path src/bin/cli_tool.rs [dependencies] serde { version 1.0, features [derive] } tokio { version 1.0, features [full] } [dev-dependencies] criterion 0.5 # 性能测试依赖 rand 0.8 # 测试数据生成 [build-dependencies] cc 1.0 # 构建脚本依赖 [features] default [std] std [] custom_feature [] [profile.dev] opt-level 0 debug true [profile.release] opt-level 3 lto true debug false [[bench]] name my_benchmark harness false # 使用自定义 benchmark harness构建脚本 (build.rs)// build.rsfnmain(){// 在编译前运行的代码println!(cargo:rerun-if-changedsrc/ffi/wrapper.h);// 链接系统库println!(cargo:rustc-link-libssl);// 设置环境变量println!(cargo:rustc-envBUILD_TIMESTAMP{},chrono::Utc::now().to_rfc3339());}特殊目录说明1. 配置文件目录config/: 存放应用程序配置文件.env: 环境变量配置通常不提交.env.example: 环境变量示例模板2. 文档目录docs/: 额外的文档文件book/: 使用 mdbook 生成的文档API 文档: 通过cargo doc自动生成到target/doc/3. 资源目录assets/: 静态资源文件图片、字体等data/: 数据文件migrations/: 数据库迁移文件4. 脚本目录scripts/: 构建、部署、维护脚本tools/: 开发工具脚本命名规范文件命名模块文件: 使用snake_case(如user_service.rs)测试文件:*_test.rs或test_*.rs示例文件:example_*.rs或*.example.rs配置目录: 使用kebab-case(如my-config/)导出约定lib.rs: 公开导出公共 APImod.rs: 模块的入口文件prelude.rs: 常用类型和函数的预导入模块最佳实践模块组织遵循单一职责原则合理拆分模块测试覆盖单元测试与源码同文件集成测试放在tests/示例完整examples/提供可运行的完整示例性能基准关键路径必须有性能测试文档完善保持 README 和 API 文档的更新这个结构遵循 Rust 社区的惯例便于其他开发者理解和贡献代码。
【Rust】Rust 项目结构详解
标准项目结构基础结构my_project/ ├── Cargo.toml # 项目配置文件包名、版本、依赖等 ├── Cargo.lock # 锁定依赖版本自动生成不提交到 git ├── .gitignore # Git 忽略文件配置 ├── src/ # 源码目录 │ ├── main.rs # 二进制入口文件 │ └── lib.rs # 库入口文件 ├── tests/ # 集成测试目录 ├── benches/ # 性能测试目录 ├── examples/ # 示例代码目录 ├── bin/ # 多个二进制文件目录可选 ├── build.rs # 构建脚本 └── target/ # 编译输出目录自动生成不提交详细目录说明1. 源码目录 (src/)基础结构src/ ├── main.rs # 二进制 crate 的主入口 ├── lib.rs # 库 crate 的主入口 ├── bin/ # 多个二进制文件目录 │ ├── server.rs # 可执行文件server │ ├── client.rs # 可执行文件client │ └── tool.rs # 可执行文件tool ├── lib/ # 库模块目录可选 │ ├── mod.rs # 模块定义 │ ├── utils.rs # 工具函数模块 │ └── config.rs # 配置模块 └── modules/ # 功能模块可选 ├── mod.rs ├── auth.rs ├── database.rs └── api.rssrc/bin/ 子目录说明每个.rs文件都会被编译成独立的二进制文件文件名即为二进制文件名可以通过cargo run --bin server运行特定二进制文件2. 测试目录 (tests/)tests/ ├── integration_test.rs # 集成测试文件 ├── api_test.rs # API 测试 ├── database_test.rs # 数据库测试 └── common/ # 测试辅助模块 ├── mod.rs # 公共测试工具 └── test_utils.rs # 测试工具函数测试特点每个文件都是一个独立的 crate可以访问项目的公共 API用于编写集成测试单元测试通常放在源码文件中使用#[cfg(test)]3. 性能测试目录 (benches/)benches/ ├── benchmark.rs # 基准测试文件 ├── io_benchmark.rs # I/O 性能测试 ├── algorithm_benchmark.rs # 算法性能测试 └── data/ # 测试数据目录 ├── large_dataset.txt └── sample_data.json使用方式# 运行所有基准测试cargobench# 运行特定基准测试cargobench benchmark_name# 需要 nightly Rustrustup overridesetnightly4. 示例目录 (examples/)examples/ ├── basic_usage.rs # 基本使用示例 ├── advanced_usage.rs # 高级用法示例 ├── web_server.rs # Web 服务器示例 ├── cli_example.rs # 命令行工具示例 └── integration/ # 复杂示例的模块 ├── mod.rs └── helper.rs运行示例# 运行特定示例cargorun--examplebasic_usage# 编译所有示例cargobuild--examples完整项目结构示例典型 Rust 库项目awesome_lib/ ├── Cargo.toml ├── Cargo.lock ├── README.md # 项目说明文档 ├── CHANGELOG.md # 版本变更记录 ├── LICENSE # 开源许可证 ├── .gitignore ├── .github/ # GitHub 配置 │ └── workflows/ │ ├── ci.yml # CI 配置 │ └── release.yml # 发布配置 ├── src/ │ ├── lib.rs # 库入口 │ ├── error.rs # 错误类型定义 │ ├── core/ │ │ ├── mod.rs │ │ ├── engine.rs │ │ └── processor.rs │ ├── utils/ │ │ ├── mod.rs │ │ ├── string_utils.rs │ │ └── file_utils.rs │ └── bin/ # 提供的命令行工具 │ ├── lib_cli.rs │ └── lib_tool.rs ├── tests/ │ ├── integration_test.rs │ ├── unit_test.rs │ └── common/ │ ├── mod.rs │ └── setup.rs ├── benches/ │ ├── throughput.rs │ ├── latency.rs │ └── memory.rs ├── examples/ │ ├── simple.rs │ ├── advanced.rs │ └── custom_config.rs └── target/ # 编译产物不提交 ├── debug/ # 开发模式编译 ├── release/ # 发布模式编译 └── doc/ # 生成的文档典型 Rust 二进制项目awesome_app/ ├── Cargo.toml ├── Cargo.lock ├── README.md ├── .env.example # 环境变量示例 ├── .dockerignore # Docker 忽略文件 ├── Dockerfile # Docker 镜像构建文件 ├── docker-compose.yml # Docker 编排配置 ├── config/ # 配置文件目录 │ ├── default.toml # 默认配置 │ ├── production.toml # 生产环境配置 │ └── development.toml # 开发环境配置 ├── src/ │ ├── main.rs # 主入口 │ ├── config/ │ │ ├── mod.rs │ │ ├── app_config.rs │ │ └── logger.rs │ ├── handlers/ │ │ ├── mod.rs │ │ ├── http_handler.rs │ │ └── grpc_handler.rs │ ├── models/ │ │ ├── mod.rs │ │ ├── user.rs │ │ └── product.rs │ ├── services/ │ │ ├── mod.rs │ │ ├── auth_service.rs │ │ └── data_service.rs │ ├── utils/ │ │ ├── mod.rs │ │ └── helpers.rs │ └── bin/ # 辅助工具 │ ├── migrate.rs # 数据库迁移工具 │ ├── seed.rs # 数据填充工具 │ └── worker.rs # 后台工作进程 ├── tests/ │ ├── integration/ │ │ ├── api_tests.rs │ │ └── db_tests.rs │ ├── e2e/ # 端到端测试 │ │ └── workflow.rs │ └── fixtures/ # 测试数据 │ ├── users.json │ └── products.json ├── benches/ │ ├── api_benchmark.rs │ └── db_benchmark.rs ├── examples/ │ ├── api_client.rs │ └── custom_middleware.rs ├── scripts/ # 辅助脚本 │ ├── setup.sh │ └── deploy.sh └── target/ └── ...关键文件说明Cargo.toml 配置文件[package] name awesome_app version 0.1.0 edition 2021 authors [Your Name emailexample.com] description A brief description license MIT repository https://github.com/user/awesome_app readme README.md keywords [rust, example, cli] categories [command-line-utilities] [lib] name awesome_lib path src/lib.rs [[bin]] name main_app path src/main.rs [[bin]] name cli_tool path src/bin/cli_tool.rs [dependencies] serde { version 1.0, features [derive] } tokio { version 1.0, features [full] } [dev-dependencies] criterion 0.5 # 性能测试依赖 rand 0.8 # 测试数据生成 [build-dependencies] cc 1.0 # 构建脚本依赖 [features] default [std] std [] custom_feature [] [profile.dev] opt-level 0 debug true [profile.release] opt-level 3 lto true debug false [[bench]] name my_benchmark harness false # 使用自定义 benchmark harness构建脚本 (build.rs)// build.rsfnmain(){// 在编译前运行的代码println!(cargo:rerun-if-changedsrc/ffi/wrapper.h);// 链接系统库println!(cargo:rustc-link-libssl);// 设置环境变量println!(cargo:rustc-envBUILD_TIMESTAMP{},chrono::Utc::now().to_rfc3339());}特殊目录说明1. 配置文件目录config/: 存放应用程序配置文件.env: 环境变量配置通常不提交.env.example: 环境变量示例模板2. 文档目录docs/: 额外的文档文件book/: 使用 mdbook 生成的文档API 文档: 通过cargo doc自动生成到target/doc/3. 资源目录assets/: 静态资源文件图片、字体等data/: 数据文件migrations/: 数据库迁移文件4. 脚本目录scripts/: 构建、部署、维护脚本tools/: 开发工具脚本命名规范文件命名模块文件: 使用snake_case(如user_service.rs)测试文件:*_test.rs或test_*.rs示例文件:example_*.rs或*.example.rs配置目录: 使用kebab-case(如my-config/)导出约定lib.rs: 公开导出公共 APImod.rs: 模块的入口文件prelude.rs: 常用类型和函数的预导入模块最佳实践模块组织遵循单一职责原则合理拆分模块测试覆盖单元测试与源码同文件集成测试放在tests/示例完整examples/提供可运行的完整示例性能基准关键路径必须有性能测试文档完善保持 README 和 API 文档的更新这个结构遵循 Rust 社区的惯例便于其他开发者理解和贡献代码。
