当前位置：首页 > news >正文

【Rust】Rust 项目结构详解

news 2026/5/11 18:07:05

标准项目结构

基础结构

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.rs

src/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 overridesetnightly

4. 示例目录 (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 <email@example.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-changed=src/ffi/wrapper.h");// 链接系统库println!("cargo:rustc-link-lib=ssl");// 设置环境变量println!("cargo:rustc-env=BUILD_TIMESTAMP={}",chrono::Utc::now().to_rfc3339());}