Rust Rocket Web 应用项目结构详解（MVC 风格）

✅ 项目总览：Rust Rocket Web 应用结构（MVC 风格）

bash 复制代码

rocket-web-app/
├── Cargo.toml              # Rust 项目配置文件
├── Rocket.toml             # Rocket 框架配置文件
├── src/
│   ├── main.rs             # 应用入口文件
│   ├── lib.rs              # 模块聚合文件
│   ├── models/             # 数据模型层（目录）
│   ├── services/           # 业务逻辑层（目录）
│   ├── controllers/        # 请求处理层（目录）
│   ├── views/              # 视图上下文（目录）（可选）
│   ├── db/                 # 数据库连接管理（目录）
│   ├── utils/              # 工具模块（目录）（错误处理等）
│   └── config/             # 配置管理（目录）
├── templates/              # HTML 模板（目录）（Tera 引擎）
├── static/                 # 静态资源（目录）（CSS/JS/图片）
└── migrations/             # 数据库迁移脚本（目录）

1. 项目结构设计思想

🎯 核心目标

可维护性：模块职责清晰，修改不影响全局
可扩展性：新增功能不破坏已有结构
可测试性：业务逻辑可独立测试
可部署性：配置清晰，支持多环境

2. 各目录详细解释

目录	作用	设计理由
`models/`	定义数据结构（User、Post等）	与数据库表一一对应，作为"数据载体"
`services/`	实现业务逻辑（CRUD、验证等）	控制器不直接操作数据库，保持"瘦控制器"
`controllers/`	处理HTTP请求，调用服务，返回响应	只负责"接收请求 → 调用服务 → 返回结果"
`views/`	构造模板渲染所需上下文	把复杂数据结构转成模板易用的格式
`db/`	管理数据库连接池	统一入口，避免重复建立连接
`utils/`	工具函数、错误类型定义	避免重复代码，统一错误处理风格
`config/`	读取配置文件（Rocket.toml + 环境变量）	支持本地/测试/生产多环境切换

3. 模板目录结构（templates）

bash 复制代码

templates/
├── base.html.tera          # 公共布局（导航栏、页脚）
├── index.html.tera         # 首页
├── users/
│   ├── list.html.tera      # 用户列表页
│   ├── detail.html.tera    # 用户详情页
│   └── create.html.tera    # 创建用户表单页
└── posts/
    ├── list.html.tera      # 帖子列表页
    ├── detail.html.tera    # 帖子详情页
    └── create.html.tera    # 创建帖子表单页

✅ 模板按"功能模块"分子目录，避免根目录臃肿，便于前端协作。

4. 静态资源目录（static）

bash 复制代码

static/
├── css/
│   └── style.css           # 全局样式
└── js/
    └── main.js             # 全局脚本

✅ 静态资源路径在 Rocket.toml 中配置，Rocket 会自动映射为 /static/css/style.css 这类 URL。

5. 数据库迁移目录（migrations）

bash 复制代码

migrations/
└── 001_initial_schema.sql  # 初始建表语句

✅ 使用纯 SQL 文件，方便 DBA 审查；也可接入 sqlx migrate 工具做版本管理。

6. 配置文件（Rocket.toml）

配置块	作用
`[default]`	默认配置（端口、模板路径、数据库URL）
`[debug]`	开发环境日志级别
`[release]`	生产环境日志级别
`[databases]`	数据库连接池配置

✅ 支持环境变量覆盖，例如 ROCKET_PORT=8080 cargo run

7. 模块依赖关系图（单向依赖）

bash 复制代码

main.rs
  ├─ config     ← 读取配置
  ├─ db         ← 创建连接池
  ├─ services   ← 依赖 db + models
  ├─ controllers ← 依赖 services + models
  └─ templates  ← 由 controllers 渲染

✅ 禁止反向依赖：

controllers 不能直接调用 sqlx

services 不能依赖 rocket 相关类型

models 保持纯数据结构，不依赖任何框架

8. 新增功能时的"标准操作流程"

假设要新增 "评论系统"：

1、models/ 新增 comment.rs 定义结构

2、migrations/ 新增 002_add_comment_table.sql

3、services/ 新增 comment_service.rs 实现业务

4、controllers/ 新增 comment_controller.rs 注册路由

5、templates/comments/ 新建模板文件

6、controllers/mod.rs 把新路由合并到总路由表

✅ 每一步只动一个模块，不碰其他目录，多人协作不冲突。

9. 部署相关文件（可扩展）

bash 复制代码

├── Dockerfile              # 容器镜像构建
├── docker-compose.yml      # 本地一站式启动（Web+DB）
├── .env.example            # 环境变量模板
├── README.md               # 项目说明
└── .github/
    └── workflows/
        └── ci.yml          # GitHub Actions 自动测试

✅ 这些文件放在根目录，不污染 src，方便 DevOps 直接读取。

10. 一句话总结

维度	一句话总结
架构风格	严格 MVC + 单向依赖，Rust 类型系统做"编译期契约"
目录规则	"一功能一目录，一角色一目录"，同层模块不交叉引用
配置策略	代码只认 `Rocket.toml` + 环境变量，绝不硬编码
扩展方式	新增功能 = 新增一组 {model, service, controller, template}，不改旧文件