rust-user-api/learning_guide.md

Rust REST API 学习指南

学习前准备

必备知识

• Rust 基础语法（所有权、借用、生命周期）
• 基本的 HTTP 协议知识
• REST API 设计原则
• JSON 数据格式

开发环境

• Rust 1.70+
• VS Code 或其他 IDE
• Postman 或 curl（API 测试）
• Git（版本控制）

详细学习路径

第一周：基础搭建（阶段 1-2）

学习目标

• 掌握 Cargo 项目管理
• 理解 Axum 框架基础
• 学会创建基本的 HTTP 服务

关键概念

1. Cargo.toml 配置

   • 依赖管理和版本控制
   • 特性（features）选择
   • 开发依赖 vs 运行时依赖

2. 异步编程基础

   • async/await 语法
   • Tokio 运行时
   • Future 和 Task 概念

3. Axum 框架核心

   • Router 和路由定义
   • 处理器函数（Handler）
   • 响应类型和状态码

实践练习

// 练习1: 创建健康检查端点
async fn health() -> Json<Value> {
    Json(json!({
        "status": "ok",
        "timestamp": Utc::now(),
        "uptime": "1h 30m"
    }))
}

// 练习2: 添加版本信息端点
async fn version() -> Json<Value> {
    Json(json!({
        "version": env!("CARGO_PKG_VERSION"),
        "name": env!("CARGO_PKG_NAME")
    }))
}

常见问题和解决方案

• 编译错误: 检查依赖版本兼容性
• 异步函数理解: 从同步思维转向异步思维
• 模块导入: 理解 Rust 的模块系统

---

第二周：数据模型和存储（阶段 3-4）

学习目标

• 掌握 Serde 序列化
• 理解内存存储设计
• 实现完整的 CRUD 操作

关键概念

1. 数据建模

   • 结构体设计原则
   • 序列化和反序列化
   • 类型转换和 From trait

2. 并发安全

   • Arc<RwLock<T>> 模式
   • 读写锁的使用场景
   • 线程安全的数据共享

3. HTTP 方法映射

   • GET, POST, PUT, DELETE
   • RESTful 设计原则
   • 路径参数提取

实践练习

// 练习1: 扩展用户模型
#[derive(Debug, Serialize, Deserialize)]
pub struct User {
    pub id: Uuid,
    pub username: String,
    pub email: String,
    pub profile: UserProfile,
    pub status: UserStatus,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct UserProfile {
    pub first_name: String,
    pub last_name: String,
    pub bio: Option<String>,
}

// 练习2: 实现用户搜索
pub async fn search_users(
    State(store): State<MemoryUserStore>,
    Query(params): Query<SearchParams>,
) -> Json<Vec<UserResponse>> {
    // 实现按用户名或邮箱搜索
}

调试技巧

• 使用 println! 和 dbg! 宏调试
• 理解借用检查器错误信息
• 使用 Postman 测试 API 端点

---

第三周：错误处理和验证（阶段 5）

学习目标

• 掌握 Rust 错误处理模式
• 实现请求数据验证
• 创建统一的错误响应

关键概念

1. 错误处理哲学

   • Result<T, E> 类型
   • ? 操作符的使用
   • 错误传播和转换

2. 自定义错误类型

   • 枚举定义错误类型
   • IntoResponse trait 实现
   • 错误信息的用户友好化

3. 数据验证

   • 输入验证策略
   • 自定义验证规则
   • 验证错误的处理

实践练习

// 练习1: 扩展错误类型
#[derive(Debug)]
pub enum ApiError {
    ValidationError(ValidationErrors),
    DatabaseError(String),
    NotFound(String),
    Conflict(String),
    Unauthorized,
    Forbidden,
}

// 练习2: 实现自定义验证器
fn validate_username(username: &str) -> Result<(), ValidationError> {
    if username.len() < 3 {
        return Err(ValidationError::new("Username too short"));
    }
    if username.contains(' ') {
        return Err(ValidationError::new("Username cannot contain spaces"));
    }
    Ok(())
}

最佳实践

• 永远不要 unwrap() 在生产代码中
• 提供有意义的错误信息
• 区分内部错误和用户错误

---

第四周：身份认证（阶段 6）

学习目标

• 理解 JWT 工作原理
• 实现中间件模式
• 掌握安全编程基础

关键概念

1. JWT 认证流程

   • Token 生成和验证
   • Claims 和 Payload
   • 安全密钥管理

2. 中间件设计

   • 请求拦截和处理
   • 状态传递机制
   • 条件性中间件应用

3. 安全考虑

   • 密码哈希（bcrypt）
   • Token 过期处理
   • HTTPS 和安全头

实践练习

// 练习1: 实现角色基础访问控制
#[derive(Debug, Serialize, Deserialize)]
pub enum UserRole {
    Admin,
    User,
    Guest,
}

pub async fn admin_only_middleware(
    claims: Claims,
    req: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    if claims.role != UserRole::Admin {
        return Err(StatusCode::FORBIDDEN);
    }
    Ok(next.run(req).await)
}

// 练习2: 实现刷新 Token 机制
pub async fn refresh_token(
    State(store): State<MemoryUserStore>,
    RequestJson(payload): RequestJson<RefreshTokenRequest>,
) -> Result<Json<TokenResponse>, ApiError> {
    // 验证刷新 token 并生成新的访问 token
}

安全检查清单

• 使用强密码哈希算法
• 实现 Token 过期机制
• 验证所有输入数据
• 记录安全相关事件

---

第五周：测试和文档（阶段 7）

学习目标

• 编写全面的测试套件
• 创建清晰的 API 文档
• 掌握测试驱动开发

关键概念

1. 测试策略

   • 单元测试 vs 集成测试
   • 测试数据管理
   • Mock 和 Stub 技术

2. API 测试

   • HTTP 客户端测试
   • 异步测试编写
   • 测试环境隔离

3. 文档编写

   • OpenAPI/Swagger 规范
   • 代码注释最佳实践
   • 示例和用例

实践练习

// 练习1: 编写完整的用户 CRUD 测试
#[tokio::test]
async fn test_user_lifecycle() {
    let app = create_test_app().await;
    
    // 创建用户
    let user = create_test_user(&app, "testuser").await;
    assert_eq!(user.username, "testuser");
    
    // 获取用户
    let fetched_user = get_user(&app, user.id).await;
    assert_eq!(fetched_user.id, user.id);
    
    // 更新用户
    let updated_user = update_user(&app, user.id, "newname").await;
    assert_eq!(updated_user.username, "newname");
    
    // 删除用户
    delete_user(&app, user.id).await;
    assert!(get_user(&app, user.id).await.is_err());
}

// 练习2: 性能测试
#[tokio::test]
async fn test_concurrent_user_creation() {
    let app = create_test_app().await;
    let mut handles = vec![];
    
    for i in 0..100 {
        let app_clone = app.clone();
        let handle = tokio::spawn(async move {
            create_test_user(&app_clone, &format!("user{}", i)).await
        });
        handles.push(handle);
    }
    
    let results = futures::future::join_all(handles).await;
    assert_eq!(results.len(), 100);
}

---

第六周及以后：高级功能（阶段 8-12）

数据库集成（阶段 8-9）

• SQLite 和 PostgreSQL 集成
• ORM 选择（Diesel vs SQLx）
• 数据库迁移管理
• 连接池配置

高级功能（阶段 10）

• 分页实现
• 搜索和过滤
• 排序和聚合
• 缓存策略

生产准备（阶段 11-12）

• 配置管理（环境变量）
• 结构化日志记录
• 监控和指标收集
• Docker 容器化
• 部署策略

学习资源推荐

官方文档

• Rust Book
• Axum Documentation
• Tokio Tutorial

实用工具

• Postman - API 测试
• SQLite Browser - 数据库管理
• Docker - 容器化

社区资源

• Rust Users Forum
• r/rust
• Rust Discord

常见问题解答

Q: 为什么选择 Axum 而不是其他框架？

A: Axum 是由 Tokio 团队开发的现代 web 框架，具有以下优势：

• 类型安全的提取器系统
• 优秀的性能表现
• 与 Tokio 生态系统深度集成
• 活跃的社区支持

Q: 内存存储什么时候应该迁移到数据库？

A: 当您需要以下功能时：

• 数据持久化
• 复杂查询
• 事务支持
• 多实例部署

Q: 如何处理大量并发请求？

A: 考虑以下策略：

• 使用连接池
• 实现请求限流
• 添加缓存层
• 优化数据库查询
• 使用负载均衡

Q: 生产环境部署需要注意什么？

A: 关键考虑因素：

• 环境配置管理
• 日志记录和监控
• 安全性（HTTPS、防火墙）
• 备份和恢复策略
• 性能监控

通过这个详细的学习指南，您将能够系统性地掌握 Rust web 开发的各个方面，从基础概念到生产级应用开发。