enoch
28afc7532f
- 创建 Cargo.toml 配置文件，包含所有必要依赖 - 建立完整的项目模块结构（config, models, handlers, routes, services, storage, middleware, utils） - 实现用户数据模型和内存存储 - 创建基础的 HTTP 处理器和路由配置 - 添加错误处理和 JWT 认证中间件 - 配置环境变量和日志系统 - 创建项目文档和学习指南 - 服务器可以成功编译和启动
167 lines
5.4 KiB
Markdown
167 lines
5.4 KiB
Markdown
# 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 应用的开发者。 |