# Rust REST API Server Demo 项目规划

## 项目概述

这是一个专为学习 Rust web 开发设计的渐进式 REST API server 项目。项目从简单的内存存储开始，逐步扩展到数据库集成和高级功能，帮助您全面掌握 Rust web 开发的核心概念。

## 技术栈

- **Web 框架**: Axum（现代、高性能、类型安全）
- **序列化**: Serde（JSON 处理）
- **异步运行时**: Tokio（异步编程基础）
- **数据库**: 先用 HashMap（内存），后扩展到 SQLite
- **身份认证**: JWT tokens
- **测试**: 内置测试框架 + reqwest（HTTP 客户端测试）

## 项目结构

```
rust-user-api/
├── Cargo.toml                 # 项目配置和依赖
├── README.md                  # 项目说明文档
├── src/
│   ├── main.rs               # 应用入口点
│   ├── lib.rs                # 库入口，导出公共模块
│   ├── config/
│   │   └── mod.rs            # 配置管理
│   ├── models/
│   │   ├── mod.rs            # 数据模型模块
│   │   └── user.rs           # 用户数据模型
│   ├── handlers/
│   │   ├── mod.rs            # 处理器模块
│   │   └── user.rs           # 用户相关的 API 处理器
│   ├── services/
│   │   ├── mod.rs            # 业务逻辑服务模块
│   │   └── user_service.rs   # 用户业务逻辑
│   ├── storage/
│   │   ├── mod.rs            # 存储抽象模块
│   │   ├── memory.rs         # 内存存储实现
│   │   └── database.rs       # 数据库存储实现（后期）
│   ├── middleware/
│   │   ├── mod.rs            # 中间件模块
│   │   └── auth.rs           # 身份认证中间件
│   ├── utils/
│   │   ├── mod.rs            # 工具函数模块
│   │   └── errors.rs         # 错误处理
│   └── routes/
│       └── mod.rs            # 路由配置
├── tests/
│   ├── integration_tests.rs  # 集成测试
│   └── api_tests.rs          # API 测试
└── docs/
    └── api.md                # API 文档
```

## API 端点设计

### 用户管理 API
```
GET    /api/users           # 获取所有用户（支持分页）
GET    /api/users/{id}      # 获取特定用户
POST   /api/users           # 创建新用户
PUT    /api/users/{id}      # 更新用户信息
DELETE /api/users/{id}      # 删除用户
POST   /api/auth/login      # 用户登录
POST   /api/auth/register   # 用户注册
```

## 数据模型设计

### 用户模型
```rust
pub struct User {
    pub id: u64,
    pub username: String,
    pub email: String,
    pub password_hash: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

pub struct UserResponse {
    pub id: u64,
    pub username: String,
    pub email: String,
    pub created_at: DateTime<Utc>,
}
```

## 学习路径

### 阶段 1: 基础搭建
- **目标**: 建立项目基础，理解 Rust 项目结构
- **重点学习**: Cargo 项目管理、模块系统、基础 HTTP 服务

### 阶段 2: 核心功能实现
- **目标**: 实现完整的 CRUD 操作
- **重点学习**: Axum 框架、异步编程、JSON 处理

### 阶段 3: 错误处理和验证
- **目标**: 添加健壮的错误处理机制
- **重点学习**: Rust 错误处理最佳实践、请求验证

### 阶段 4: 身份认证
- **目标**: 实现 JWT 身份认证系统
- **重点学习**: 安全编程、中间件设计

### 阶段 5: 测试和文档
- **目标**: 完善测试覆盖和 API 文档
- **重点学习**: 单元测试、集成测试、API 文档编写

### 阶段 6: 数据持久化
- **目标**: 从内存存储迁移到数据库
- **重点学习**: 数据库集成、迁移管理、连接池

### 阶段 7: 高级功能
- **目标**: 添加分页、搜索、过滤等功能
- **重点学习**: 性能优化、复杂查询处理

### 阶段 8: 生产准备
- **目标**: 添加日志、配置管理、容器化
- **重点学习**: 生产环境最佳实践、部署策略

## 架构设计

```mermaid
graph TB
    Client[客户端] --> Router[路由层]
    Router --> Auth[认证中间件]
    Auth --> Handler[处理器层]
    Handler --> Service[业务逻辑层]
    Service --> Storage[存储层]
    
    Storage --> Memory[内存存储]
    Storage --> Database[数据库存储]
    
    Handler --> Response[响应处理]
    Response --> Client
    
    subgraph "错误处理"
        ErrorHandler[错误处理器]
        Handler --> ErrorHandler
        Service --> ErrorHandler
        Storage --> ErrorHandler
    end
```

## 项目优势

1. **渐进式学习**: 从简单开始，逐步增加复杂性
2. **模块化架构**: 清晰的分层设计，便于理解和维护
3. **实用性强**: 涵盖真实项目中的常见需求
4. **最佳实践**: 遵循 Rust 社区的最佳实践和惯例
5. **完整覆盖**: 从基础语法到生产部署的全流程学习

## 预期学习成果

完成这个项目后，您将掌握：
- Rust 项目组织和模块系统
- 异步编程和 Tokio 运行时
- Web 框架（Axum）的使用
- REST API 设计和实现
- 数据库集成和 ORM 使用
- 身份认证和安全编程
- 错误处理和测试编写
- 生产环境部署准备

这个项目将为您提供一个完整的 Rust web 开发学习体验，帮助您从初学者成长为能够独立开发 Rust web 应用的开发者。