# 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
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
```

**方式二：创建本地配置文件**
```bash
# 复制开发环境配置
cp config/development.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（默认，修改 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
```

**生产环境**：

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

```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