Files

enoch 28afc7532f feat: [阶段1] 项目初始化和基础设置

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

2025-08-04 16:49:50 +08:00

5.4 KiB

Raw Blame History

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   # 用户注册

数据模型设计

用户模型

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: 生产准备

目标: 添加日志、配置管理、容器化
重点学习: 生产环境最佳实践、部署策略

架构设计

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

项目优势

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

预期学习成果

完成这个项目后，您将掌握：

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

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

5.4 KiB Raw Blame History Unescape Escape