shenjianZ/web-rust-template-project

Fork 0

Files

T

shenjianZ ce89569bf3 feat: 完善生产级 Rust Web 模板

2026-07-21 16:00:03 +08:00

6.5 KiB

Raw Blame History

Web Rust Template

基于 Rust + Axum 0.7 的生产级 Web 服务器模板，采用 DDD 分层架构设计。

核心特性

架构特色

DDD 分层架构：领域层、基础设施层、应用层清晰分离
生产就绪：JWT 双 Token 认证、Argon2 密码哈希、可选 Redis/SMTP、结构化日志与请求保护
多数据库支持：MySQL / PostgreSQL / SQLite 无缝切换

技术栈

Web 框架：Axum 0.7 + Tokio
数据库 ORM：SeaORM 1.1（支持多数据库）
认证：JWT (Access Token 15min + Refresh Token 7天)
缓存：Redis 存储 Refresh Token
安全：Token 类型隔离、软删除校验、配置化 CORS、超时、正文/并发/频率限制、panic 捕获和安全响应头

可选能力

Redis 默认关闭；服务无需 Redis 即可启动。Token 轮换、验证码等依赖 Redis 的接口会在不可用时返回 503。
邮件默认关闭；启用后提供验证码、密码重置和邮件发送记录接口，可选择同步 SMTP 或 Redis 队列 Worker。
Accept-Language 支持 zh-CN 与 en，认证错误会按请求语言返回。

快速开始

1. 克隆并安装依赖

git clone <repository>
cd web-rust-template
cargo build

2. 配置项目

使用默认配置（SQLite，最简单）：

无需配置，直接运行即可：

cargo run

使用 MySQL/PostgreSQL：

使用环境变量配置或创建本地配置文件：

方式一：使用环境变量（推荐）

# 使用 MySQL
DATABASE_TYPE=mysql DATABASE_HOST=localhost DATABASE_PORT=3306 DATABASE_USER=root DATABASE_PASSWORD=your-password DATABASE_DATABASE=web_template_dev cargo run

# 或使用 PostgreSQL
DATABASE_TYPE=postgresql DATABASE_HOST=localhost DATABASE_PORT=5432 DATABASE_USER=postgres DATABASE_PASSWORD=your-password DATABASE_DATABASE=web_template_dev cargo run

方式二：创建本地配置文件

# 复制开发环境配置
cp config/development.toml config/local.toml

# 编辑 config/local.toml，修改数据库连接信息
# 然后运行
cargo run -- -c config/local.toml

3. 运行服务

# 使用默认配置（SQLite）
cargo run

# 或使用指定配置文件
cargo run -- -c config/local.toml

服务将在 http://localhost:3000 启动

快速测试

用户注册

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "email": "user@example.com",
    "created_at": "2026-02-13T12:00:00.000Z",
    "access_token": "eyJ...",
    "refresh_token": "eyJ..."
  }
}

查看完整 API 文档了解所有接口

核心配置

配置方式

开发环境：

使用 config/ 目录下的配置文件：

# SQLite（默认，修改 config/development.toml 中的 database.type 为 "sqlite"）
cargo run

# MySQL（修改 config/development.toml 中的 database.type 为 "mysql"）
cargo run

# PostgreSQL（修改 config/development.toml 中的 database.type 为 "postgresql"）
cargo run

生产环境：

使用环境变量或配置文件：

# 使用环境变量
DATABASE_TYPE=postgresql DATABASE_HOST=localhost cargo run -- -e production

# 或使用配置文件
cargo run -- -e production -c config/production.toml

查看完整配置文档或环境变量配置

API 接口概览

公开接口

GET /health - 健康检查
GET /info - 服务器信息
POST /auth/register - 用户注册
POST /auth/login - 用户登录
POST /auth/refresh - 刷新 Token
POST /auth/request-verification-code - 发送验证码（邮件启用时）
POST /auth/reset-password - 重置密码（邮件启用时）

需要认证的接口

POST /auth/delete - 删除账号
POST /auth/delete-refresh-token - 删除 Refresh Token
POST /auth/logout - 注销 Refresh Token
GET|PUT|DELETE /api/user/profile - 当前用户资料
GET /api/email/latest-log - 最近邮件记录（邮件启用时）
GET /api/email/queue-status - 邮件能力状态（邮件启用时）

查看完整 API 文档

项目结构

src/
├── main.rs              # 入口文件
├── config/              # 配置模块
│   ├── app.rs
│   ├── auth.rs
│   ├── database.rs
│   └── redis.rs
├── domain/              # 领域层（DDD）
│   ├── dto/            # 数据传输对象
│   ├── entities/       # 实体
│   └── vo/             # 视图对象
├── handlers/           # HTTP 处理器层
├── services/           # 业务逻辑层
├── repositories/       # 数据访问层
└── infra/              # 基础设施层
    ├── middleware/     # 中间件
    ├── mail/           # SMTP 邮件发送
    └── redis/          # Redis 客户端

查看完整项目结构文档

技术栈

组件	技术	版本
Web 框架	Axum	0.7
异步运行时	Tokio	1.x
数据库 ORM	SeaORM	1.1
认证	JWT	9.x
密码哈希	Argon2	0.5
缓存	Redis	0.27
日志	tracing	0.1

文档导航

API 接口文档 - 完整的 API 接口说明和示例
快速开始指南 - 详细的安装和配置指南
开发规范 - DDD 架构和代码规范
部署文档 - 配置和部署指南

日志格式

日志采用三段式结构：

📥 请求开始：显示请求方法和路径
🔧 请求处理：显示请求参数和响应内容
✅ 请求完成：显示状态码和耗时

示例：

================================================================================
GET /health
================================================================================
[uuid-...] 📥 查询参数: 无 | 时间: 2026-02-12 13:30:45.123
[uuid-...] ✅ 状态码: 200 | 耗时: 5ms
================================================================================

安全特性

✅ 密码使用 Argon2 哈希
✅ JWT Token 认证
✅ Refresh Token 轮换机制
✅ Token 过期时间可配置
✅ 密码验证后才删除账号

许可证

MIT

6.5 KiB Raw Blame History Unescape Escape