Rust 代码组织与模块化：架构设计的工程实践

引言

代码组织与模块化是软件工程中最基础却最容易被忽视的能力。Rust 的模块系统设计精巧，它不仅提供了命名空间隔离和访问控制，更通过编译期检查强制开发者建立清晰的依赖关系。与其他语言不同，Rust 的模块系统与文件系统结构紧密关联，但又不完全等同，这种设计哲学体现了 Rust 对显式声明的偏好。深入理解模块系统的工作原理，能够帮助我们构建可维护、可测试、可扩展的大型项目。

模块系统的核心概念

Rust 的模块系统建立在几个关键概念之上。Crate 是编译的基本单元，可以是二进制 crate 或库 crate。Module 是代码组织的逻辑单元，通过 mod 关键字声明。Path 是访问模块内项的方式，支持绝对路径（从 crate 根开始）和相对路径（使用 self、super）。可见性通过 pub 关键字控制，默认为私有，这种"默认私有"的设计鼓励开发者明确 API 边界。

特别值得注意的是，Rust 2018 版本引入的路径解析规则大幅简化了模块引用。使用 crate:: 前缀可以明确表示从当前 crate 根开始的绝对路径，避免了旧版本中 :: 的歧义。同时，use 语句支持嵌套和重命名，使得导入管理更加灵活。这些改进不仅提升了代码可读性，也减少了重构时的心智负担。

文件系统映射策略

Rust 提供了两种主流的文件组织方式。传统方式使用 mod.rs 文件表示模块根，子模块以独立文件或文件夹形式存在。现代方式则允许 module_name.rs 与 module_name/ 文件夹并存，其中 .rs 文件充当模块声明，文件夹包含子模块。这种灵活性让开发者可以根据模块复杂度选择合适的组织形式，但也要求团队建立统一的编码规范。

从实践角度看，小型模块适合单文件形式，当模块内部逻辑增长到数百行时，应考虑拆分为文件夹结构。这种演进式的组织方式符合敏捷开发理念，避免了过早优化。同时，文件夹层级不宜过深，通常三层以内最为合理，过深的嵌套会增加认知负担。

深度实践：领域驱动的模块设计

让我们通过一个实际的 Web API 项目来展示专业的模块化设计。这个项目采用领域驱动设计（DDD）思想，将业务逻辑、数据访问和表现层清晰分离。

// src/lib.rs
pub mod domain;
pub mod infrastructure;
pub mod application;
pub mod api;

pub mod prelude {
    pub use crate::domain::{User, Order, OrderStatus};
    pub use crate::application::{UserService, OrderService};
    pub use crate::infrastructure::database::DbPool;
}

// src/domain/mod.rs
mod user;
mod order;
mod value_objects;

pub use user::{User, UserId, UserRepository};
pub use order::{Order, OrderId, OrderStatus, OrderRepository};
pub use value_objects::{Email, Money};

pub trait Repository<T, ID> {
    fn find_by_id(&self, id: ID) -> Result<Option<T>, RepositoryError>;
    fn save(&self, entity: &T) -> Result<(), RepositoryError>;
}

#[derive(Debug)]
pub enum RepositoryError {
    NotFound,
    DatabaseError(String),
}

// src/domain/order.rs
use super::{UserId, Money};
use chrono::{DateTime, Utc};

#[derive(Debug, Clone)]
pub struct OrderId(uuid::Uuid);

#[derive(Debug, Clone, PartialEq)]
pub enum OrderStatus {
    Pending,
    Paid,
    Shipped,
    Completed,
    Cancelled,
}

pub struct Order {
    id: OrderId,
    user_id: UserId,
    items: Vec<OrderItem>,
    total: Money,
    status: OrderStatus,
    created_at: DateTime<Utc>,
}

impl Order {
    pub fn new(user_id: UserId, items: Vec<OrderItem>) -> Result<Self, OrderError> {
        if items.is_empty() {
            return Err(OrderError::EmptyOrder);
        }
        
        let total = items.iter()
            .map(|item| item.subtotal())
            .sum();
        
        Ok(Self {
            id: OrderId(uuid::Uuid::new_v4()),
            user_id,
            items,
            total,
            status: OrderStatus::Pending,
            created_at: Utc::now(),
        })
    }
    
    pub fn mark_as_paid(&mut self) -> Result<(), OrderError> {
        match self.status {
            OrderStatus::Pending => {
                self.status = OrderStatus::Paid;
                Ok(())
            }
            _ => Err(OrderError::InvalidStatusTransition),
        }
    }
}

#[derive(Debug)]
pub enum OrderError {
    EmptyOrder,
    InvalidStatusTransition,
}

#[derive(Debug, Clone)]
struct OrderItem {
    product_id: String,
    quantity: u32,
    unit_price: Money,
}

impl OrderItem {
    fn subtotal(&self) -> Money {
        self.unit_price * self.quantity
    }
}

// src/infrastructure/database/mod.rs
mod connection;
mod repositories;

pub use connection::DbPool;
pub use repositories::{UserRepositoryImpl, OrderRepositoryImpl};

use sqlx::PgPool;

pub struct DbPool {
    pool: PgPool,
}

impl DbPool {
    pub async fn new(database_url: &str) -> Result<Self, sqlx::Error> {
        let pool = PgPool::connect(database_url).await?;
        Ok(Self { pool })
    }
    
    pub(crate) fn pool(&self) -> &PgPool {
        &self.pool
    }
}

// src/application/services/order_service.rs
use crate::domain::{Order, OrderId, OrderRepository, UserId};
use std::sync::Arc;

pub struct OrderService {
    order_repo: Arc<dyn OrderRepository>,
}

impl OrderService {
    pub fn new(order_repo: Arc<dyn OrderRepository>) -> Self {
        Self { order_repo }
    }
    
    pub async fn create_order(
        &self,
        user_id: UserId,
        items: Vec<OrderItemDto>,
    ) -> Result<OrderId, ServiceError> {
        // 业务逻辑封装
        let order = Order::new(user_id, items.into())?;
        self.order_repo.save(&order).await?;
        Ok(order.id())
    }
    
    pub async fn process_payment(
        &self,
        order_id: OrderId,
    ) -> Result<(), ServiceError> {
        let mut order = self.order_repo
            .find_by_id(order_id)
            .await?
            .ok_or(ServiceError::OrderNotFound)?;
        
        order.mark_as_paid()?;
        self.order_repo.save(&order).await?;
        Ok(())
    }
}

#[derive(Debug)]
pub enum ServiceError {
    OrderNotFound,
    InvalidOperation(String),
}

专业思考与架构原则

这个设计体现了多个关键的工程原则。依赖倒置通过 trait 定义抽象接口，领域层不依赖具体的数据库实现，这使得单元测试可以使用内存模拟实现。单一职责确保每个模块有明确的边界，domain 专注业务规则，infrastructure 处理技术细节，application 协调用例流程。

可见性控制是模块化的核心武器。注意 domain/mod.rs 中只导出必要的类型，内部实现细节（如 OrderItem）保持私有。这种信息隐藏防止了外部模块的不当依赖，使得重构更加安全。同时，使用 pub(crate) 可以在 crate 内部共享实现，但不暴露给外部用户。

Prelude 模式提供了便捷的导入方式，用户只需 use myapp::prelude:😗 即可获取常用类型，无需记忆复杂的路径。但要注意，prelude 应该只包含高频使用的类型，避免导入污染。对于可能冲突的名称，应该让用户显式导入。

错误处理的模块化同样重要。每个层次定义自己的错误类型，使用 From trait 实现错误转换。这避免了底层错误泄漏到上层，也使得错误信息更加语义化。例如，ServiceError 对应业务异常，而 RepositoryError 表示数据访问失败。

从测试角度看，良好的模块化使得测试策略更加清晰。领域逻辑可以完全独立测试，不需要数据库或网络。应用服务层使用 mock repository 进行集成测试。API 层则可以使用端到端测试验证完整流程。这种分层测试策略提高了测试覆盖率和执行效率。