标准项目结构
基础结构
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使用方式：
bash
# 运行所有基准测试
cargo bench
# 运行特定基准测试
cargo bench benchmark_name
# 需要 nightly Rust
rustup override set nightly4. 示例目录 (examples/)
examples/
├── basic_usage.rs # 基本使用示例
├── advanced_usage.rs # 高级用法示例
├── web_server.rs # Web 服务器示例
├── cli_example.rs # 命令行工具示例
└── integration/ # 复杂示例的模块
├── mod.rs
└── helper.rs运行示例：
bash
# 运行特定示例
cargo run --example basic_usage
# 编译所有示例
cargo build --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 配置文件
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)
rust
// build.rs
fn main() {
// 在编译前运行的代码
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());
}特殊目录说明
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: 公开导出公共 API
- mod.rs: 模块的入口文件
- prelude.rs: 常用类型和函数的预导入模块
最佳实践
- 模块组织：遵循单一职责原则，合理拆分模块
- 测试覆盖 ：单元测试与源码同文件，集成测试放在
tests/ - 示例完整 ：
examples/提供可运行的完整示例 - 性能基准：关键路径必须有性能测试
- 文档完善：保持 README 和 API 文档的更新
这个结构遵循 Rust 社区的惯例，便于其他开发者理解和贡献代码。