Rust Project Structure

Understanding standard Rust project organization and file architecture.

Intermediate⏱️ 40 min📚 Prerequisites: 2

Rust Project Structure

Proper project structure is essential for maintainable, scalable Rust applications.

Standard Rust Project Layout

my-project/
├── Cargo.toml          # Project manifest
├── Cargo.lock          # Dependency lock file
├── README.md           # Project documentation
├── .gitignore          # Git ignore rules
├── src/                # Source code
│   ├── main.rs         # Binary entry point
│   ├── lib.rs          # Library entry point
│   ├── bin/            # Additional binaries
│   │   └── cli.rs
│   ├── modules/        # Application modules
│   │   ├── mod.rs
│   │   ├── api.rs
│   │   └── db.rs
│   └── utils/          # Utility functions
│       └── helpers.rs
├── tests/              # Integration tests
│   └── integration_test.rs
├── examples/           # Example code
│   └── basic_example.rs
├── benches/            # Benchmark tests
│   └── performance.rs
└── docs/               # Additional documentation

Cargo.toml Structure


TOML
[package]
name = "my-project"
version = "0.1.0"
edition = "2021"
authors = ["Your Name"]
description = "Project description"
license = "MIT"

[dependencies]
# External crates
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

[dev-dependencies]
# Test dependencies
mockito = "1.0"

[build-dependencies]
# Build-time dependencies

[[bin]]
name = "my-binary"
path = "src/bin/my_binary.rs"

[lib]
name = "my_lib"
path = "src/lib.rs"

Module Organization

Flat Structure (Small Projects)

src/
├── main.rs
├── api.rs
├── database.rs
├── models.rs
└── utils.rs

Hierarchical Structure (Medium Projects)

src/
├── main.rs
├── lib.rs
├── api/
│   ├── mod.rs
│   ├── routes.rs
│   └── handlers.rs
├── database/
│   ├── mod.rs
│   ├── connection.rs
│   └── migrations.rs
└── models/
    ├── mod.rs
    ├── user.rs
    └── transaction.rs

Domain-Driven Structure (Large Projects)

src/
├── main.rs
├── lib.rs
├── domain/
│   ├── mod.rs
│   ├── user/
│   │   ├── mod.rs
│   │   ├── model.rs
│   │   └── service.rs
│   └── transaction/
│       ├── mod.rs
│       ├── model.rs
│       └── service.rs
├── infrastructure/
│   ├── mod.rs
│   ├── database.rs
│   └── cache.rs
└── api/
    ├── mod.rs
    └── routes.rs

Workspace Structure (Multiple Crates)

workspace/
├── Cargo.toml          # Workspace manifest
├── api/                # API crate
│   ├── Cargo.toml
│   └── src/
├── core/               # Core business logic
│   ├── Cargo.toml
│   └── src/
├── database/           # Database layer
│   ├── Cargo.toml
│   └── src/
└── shared/             # Shared utilities
    ├── Cargo.toml
    └── src/

Workspace Cargo.toml:


TOML
[workspace]
members = ["api", "core", "database", "shared"]
resolver = "2"

[workspace.dependencies]
# Shared dependencies
serde = "1.0"
tokio = "1.0"

Best Practices

Separation of concerns: Keep business logic separate from infrastructure
Module visibility: Use pub carefully, prefer private by default
Feature flags: Use Cargo features for optional functionality
Tests alongside code: Unit tests in same file, integration tests in tests/
Documentation: Use /// for public API docs
Error types: Centralize error definitions
Configuration: Separate config from code

Code Examples

Module Structure Example

Organizing code into modules

RUST

pub mod api;
pub mod database;
pub mod models;
pub mod routes;
pub mod handlers;
pub fn setup_routes() {
    println!("Setting up API routes");
}
pub fn handle_request() {
    println!("Handling request");
}
pub mod connection;
pub mod migrations;
pub mod user;
pub mod transaction;
fn main() {
    println!("Project structure:");
    println!("- lib.rs: Library entry point");
    println!("- mod.rs: Module declarations");
    println!("- Separate files: Different concerns");
}

Explanation:

Modules organize code into logical units. Each module can be in its own file or directory with a mod.rs file.

Workspace Structure

Multi-crate workspace organization

RUST

fn main() {
    println!("Workspace benefits:");
    println!("- Multiple related crates");
    println!("- Shared dependencies");
    println!("- Independent versioning");
    println!("- Faster compilation");
}

Explanation:

Workspaces allow managing multiple related crates together. They share a dependency resolver and can reference each other.

Exercises

Create Module Structure

Create a module structure with api, database, and models modules!

Easy

Starter Code:

RUST

fn main() {
    println!("Modules created!");
}

Previous Lesson

← 58 monitoring observability

Next Lesson

60 layered architecture →