220 lines
5.2 KiB
Markdown
220 lines
5.2 KiB
Markdown
# Web Rust Template
|
||
|
||
基于 Rust + Axum 0.7 的生产级 Web 服务器模板，采用 DDD 分层架构设计。
|
||
|
||
## 核心特性
|
||
|
||
### 架构特色
|
||
- **DDD 分层架构**：领域层、基础设施层、应用层清晰分离
|
||
- **生产就绪**：JWT 双 Token 认证、Argon2 密码哈希、结构化日志
|
||
- **多数据库支持**：MySQL / PostgreSQL / SQLite 无缝切换
|
||
|
||
### 技术栈
|
||
- **Web 框架**：Axum 0.7 + Tokio
|
||
- **数据库 ORM**：SeaORM 1.1（支持多数据库）
|
||
- **认证**：JWT (Access Token 15min + Refresh Token 7天)
|
||
- **缓存**：Redis 存储 Refresh Token
|
||
- **安全**：Argon2 密码哈希、CORS 支持
|
||
|
||
## 快速开始
|
||
|
||
### 1. 克隆并安装依赖
|
||
|
||
```bash
|
||
git clone <repository>
|
||
cd web-rust-template
|
||
cargo build
|
||
```
|
||
|
||
### 2. 配置项目
|
||
|
||
**使用默认配置（SQLite，最简单）**：
|
||
|
||
无需配置，直接运行即可：
|
||
```bash
|
||
cargo run
|
||
```
|
||
|
||
**使用 MySQL/PostgreSQL**：
|
||
|
||
复制对应的配置文件并修改：
|
||
```bash
|
||
# 使用 MySQL
|
||
cp config/development.mysql.toml config/local.toml
|
||
|
||
# 或使用 PostgreSQL
|
||
cp config/development.postgresql.toml config/local.toml
|
||
|
||
# 编辑 config/local.toml，修改数据库连接信息
|
||
# 然后运行
|
||
cargo run -- -c config/local.toml
|
||
```
|
||
|
||
### 3. 运行服务
|
||
|
||
```bash
|
||
# 使用默认配置（SQLite）
|
||
cargo run
|
||
|
||
# 或使用指定配置文件
|
||
cargo run -- -c config/local.toml
|
||
```
|
||
|
||
服务将在 http://localhost:3000 启动
|
||
|
||
## 快速测试
|
||
|
||
### 用户注册
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/auth/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"email": "user@example.com", "password": "password123"}'
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"email": "user@example.com",
|
||
"created_at": "2026-02-13T12:00:00.000Z",
|
||
"access_token": "eyJ...",
|
||
"refresh_token": "eyJ..."
|
||
}
|
||
}
|
||
```
|
||
|
||
> 查看 [完整 API 文档](docs/api/api-overview.md) 了解所有接口
|
||
|
||
## 核心配置
|
||
|
||
### 配置方式
|
||
|
||
**开发环境**：
|
||
|
||
使用 `config/` 目录下的配置文件：
|
||
|
||
```bash
|
||
# SQLite（默认）
|
||
cargo run
|
||
|
||
# MySQL
|
||
cp config/development.mysql.toml config/local.toml
|
||
# 编辑 config/local.toml
|
||
cargo run -- -c config/local.toml
|
||
|
||
# PostgreSQL
|
||
cp config/development.postgresql.toml config/local.toml
|
||
# 编辑 config/local.toml
|
||
cargo run -- -c config/local.toml
|
||
```
|
||
|
||
**生产环境**：
|
||
|
||
使用环境变量或配置文件：
|
||
|
||
```bash
|
||
# 使用环境变量
|
||
DATABASE_TYPE=postgresql DATABASE_HOST=localhost cargo run -- -e production
|
||
|
||
# 或使用配置文件
|
||
cargo run -- -e production -c config/production.toml
|
||
```
|
||
|
||
> 查看 [完整配置文档](docs/deployment/configuration.md) 或 [环境变量配置](docs/deployment/environment-variables.md)
|
||
|
||
## API 接口概览
|
||
|
||
### 公开接口
|
||
|
||
- `GET /health` - 健康检查
|
||
- `GET /info` - 服务器信息
|
||
- `POST /auth/register` - 用户注册
|
||
- `POST /auth/login` - 用户登录
|
||
- `POST /auth/refresh` - 刷新 Token
|
||
|
||
### 需要认证的接口
|
||
|
||
- `POST /auth/delete` - 删除账号
|
||
- `POST /auth/delete-refresh-token` - 删除 Refresh Token
|
||
|
||
> 查看 [完整 API 文档](docs/api/api-overview.md)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── main.rs # 入口文件
|
||
├── config/ # 配置模块
|
||
│ ├── app.rs
|
||
│ ├── auth.rs
|
||
│ ├── database.rs
|
||
│ └── redis.rs
|
||
├── domain/ # 领域层（DDD）
|
||
│ ├── dto/ # 数据传输对象
|
||
│ ├── entities/ # 实体
|
||
│ └── vo/ # 视图对象
|
||
├── handlers/ # HTTP 处理器层
|
||
├── services/ # 业务逻辑层
|
||
├── repositories/ # 数据访问层
|
||
└── infra/ # 基础设施层
|
||
├── middleware/ # 中间件
|
||
└── redis/ # Redis 客户端
|
||
```
|
||
|
||
> 查看 [完整项目结构文档](docs/development/project-structure.md)
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| Web 框架 | Axum | 0.7 |
|
||
| 异步运行时 | Tokio | 1.x |
|
||
| 数据库 ORM | SeaORM | 1.1 |
|
||
| 认证 | JWT | 9.x |
|
||
| 密码哈希 | Argon2 | 0.5 |
|
||
| 缓存 | Redis | 0.27 |
|
||
| 日志 | tracing | 0.1 |
|
||
|
||
## 文档导航
|
||
|
||
- [API 接口文档](docs/api/api-overview.md) - 完整的 API 接口说明和示例
|
||
- [快速开始指南](docs/development/getting-started.md) - 详细的安装和配置指南
|
||
- [开发规范](docs/development/ddd-architecture.md) - DDD 架构和代码规范
|
||
- [部署文档](docs/deployment/configuration.md) - 配置和部署指南
|
||
|
||
## 日志格式
|
||
|
||
日志采用三段式结构：
|
||
|
||
1. 📥 **请求开始**：显示请求方法和路径
|
||
2. 🔧 **请求处理**：显示请求参数和响应内容
|
||
3. ✅ **请求完成**：显示状态码和耗时
|
||
|
||
示例：
|
||
|
||
```
|
||
================================================================================
|
||
GET /health
|
||
================================================================================
|
||
[uuid-...] 📥 查询参数: 无 | 时间: 2026-02-12 13:30:45.123
|
||
[uuid-...] ✅ 状态码: 200 | 耗时: 5ms
|
||
================================================================================
|
||
```
|
||
|
||
## 安全特性
|
||
|
||
- ✅ 密码使用 Argon2 哈希
|
||
- ✅ JWT Token 认证
|
||
- ✅ Refresh Token 轮换机制
|
||
- ✅ Token 过期时间可配置
|
||
- ✅ 密码验证后才删除账号
|
||
|
||
|
||
## 许可证
|
||
|
||
MIT
|