Actix-Web完整项目实战：博客 API

一、概述

在前面几篇文章中，已经熟悉了 Actix-Web框架，各个组件。接下来实现一个博客 API，基于RESTful API风格，集成token验证。

 
二、项目结构

代码结构

新建一个项目blog-api，代码结构如下：

1. ./
2. ├── Cargo.toml
3. └── src
4.     ├── db.rs
5.     ├── handlers
6.     │   ├── dev.rs
7.     │   ├── mod.rs
8.     │   ├── post_handler.rs
9.     │   └── user_handler.rs
10.     ├── jwt.rs
11.     ├── main.rs
12.     ├── middleware
13.     │   ├── auth.rs
14.     │   └── mod.rs
15.     └── models
16.         ├── mod.rs
17.         ├── post.rs
18.         └── user.rs

复制代码

 
表结构

数据库在阿里云上面，创建一个测试数据库

1. CREATE DATABASE rust_blog
2. CHARACTER SET utf8mb4
3. COLLATE utf8mb4_unicode_ci;

复制代码

新建表users

1. CREATE TABLE `users` (
2.   `id` bigint NOT NULL AUTO_INCREMENT,
3.   `username` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
4.   `password` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
5.   `email` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL,
6.   `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
7.   PRIMARY KEY (`id`)
8. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

复制代码

新建表posts

1. CREATE TABLE `posts` (
2.   `id` bigint NOT NULL AUTO_INCREMENT,
3.   `title` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
4.   `content` text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
5.   `author_id` bigint NOT NULL,
6.   `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
7.   `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
8.   PRIMARY KEY (`id`)
9. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

复制代码

依赖组件
Cargo.toml

1. [package]
2. name = "actix_swagger"
3. version = "0.1.0"
4. edition = "2024"
6. [dependencies]
7. actix-web = { version = "4.12", features = ["compress-gzip"] }
8. tokio = { version = "1", features = ["full"] }
9. serde = { version = "1", features = ["derive"] }
10. serde_json = "1.0"
11. utoipa = { version = "5", features = ["actix_extras", "chrono"] }
12. utoipa-swagger-ui = { version = "9", features = ["actix-web"] }
13. log = "0.4"      # 日志门面
14. env_logger = "0.11"     # 控制台实现
15. # 异步 MySQL 驱动，支持 8.x
16. chrono = { version = "0.4", default-features = false, features = ["serde", "clock"] }
17. sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "mysql", "chrono"] }
18. dotenvy = "0.15"   # 读取 .env
19. futures-util = { version = "0.3", default-features = false, features = ["std"] }
20. actix-cors = "0.7"
21. md5 = "0.8"        # 轻量、零配置
22. jsonwebtoken = { version = "10.2", features = ["rust_crypto"] }

复制代码

 
数据模型

src/models/user.rs

1. use chrono::NaiveDateTime;
2. use serde::{Deserialize, Serialize};
3. use sqlx::FromRow;
5. #[derive(Debug, Serialize, Deserialize, FromRow, utoipa::ToSchema)]
6. pub struct User {
7.     pub id: i64,
8.     pub username: String,               // NOT NULL
9.     #[serde(skip)]
10.     #[allow(dead_code)]
11.     pub password: String,               // NOT NULL
12.     pub email: Option<String>,          // NULL  -> Option
13.     pub create_time: Option<NaiveDateTime>, // NULL -> Option
14. }
16. #[derive(Debug, Deserialize, utoipa::ToSchema)]
17. pub struct CreateUser {
18.     pub username: String,
19.     pub email: String,
20.     pub password: String,
21. }

复制代码

 
src/models/post.rs

1. use chrono::NaiveDateTime;
2. use serde::{Deserialize, Serialize};
3. use sqlx::FromRow;
5. #[derive(Debug, Serialize, Deserialize, FromRow, utoipa::ToSchema)]
6. pub struct Post {
7.     pub id: i64,
8.     pub title: String,
9.     pub content: String,
10.     pub author_id: i64,
11.     pub create_time: NaiveDateTime,
12.     pub update_time: Option<NaiveDateTime>, // 允许 NULL
13. }
15. #[derive(Debug, Deserialize, utoipa::ToSchema)]
16. pub struct CreatePost {
17.     pub title: String,
18.     pub content: String,
19. }

复制代码

 
数据库操作

src/db.rs

1. use sqlx::{mysql::MySqlPool};
2. use crate::models::{User, CreateUser, Post, CreatePost};
3. use md5;
4. pub async fn create_user(
5.     pool: &MySqlPool,
6.     user: CreateUser,
7. ) -> Result<User, sqlx::Error> {
8.     let mut tx = pool.begin().await?;
10.     // 1. 插入
11.     //计算 MD5（16 进制小写）
12.     let password_hash = format!("{:x}", md5::compute(&user.password));
13.     sqlx::query!(
14.         r#"
15.         INSERT INTO users (username, password, email, create_time)
16.         VALUES (?, ?, ?, NOW())
17.         "#,
18.         user.username,
19.         password_hash,          // 已加密
20.         user.email,
21.     )
22.     .execute(&mut *tx)
23.     .await?;
25.     // 2. LAST_INSERT_ID() 返回 u64，不需要 unwrap_or
26.     let id: u64 = sqlx::query_scalar!("SELECT LAST_INSERT_ID()")
27.         .fetch_one(&mut *tx)
28.         .await?;
30.     // 3. 查新行 —— 明确列 NULL 性，与 User 结构体对应
31.     let user = sqlx::query_as!(
32.         User,
33.         "SELECT id, username, password, email, create_time FROM users WHERE id = ?",
34.         id as i64
35.     )
36.     .fetch_one(&mut *tx)
37.     .await?;
39.     tx.commit().await?;
40.     Ok(user)
41. }
43. pub async fn get_user_by_id(pool: &MySqlPool, id: i64) -> Result<Option<User>,sqlx::Error> {
44.     let user = sqlx::query_as::<_, User>(
45.         "SELECT id, username, email, create_time, '' as password FROM users WHERE id = ?"
46.     )
47.     .bind(id)
48.     .fetch_optional(pool)
49.     .await?;
50.    
51.     Ok(user)
52. }
54. pub async fn create_post(
55.     pool: &MySqlPool,
56.     post: CreatePost,
57.     author_id: i64,
58. ) -> Result<Post, sqlx::Error> {
59.     let mut tx = pool.begin().await?;
61.     // 1. 插入
62.     sqlx::query!(
63.         r#"
64.         INSERT INTO posts (title, content, author_id, create_time, update_time)
65.         VALUES (?, ?, ?, NOW(), NULL)
66.         "#,
67.         post.title,
68.         post.content,
69.         author_id
70.     )
71.     .execute(&mut *tx)
72.     .await?;
74.     // 2. 取新 id
75.     let id: u64 = sqlx::query_scalar!("SELECT LAST_INSERT_ID()")
76.         .fetch_one(&mut *tx)
77.         .await?;
79.     // 3. 再查整行
80.     let new_post = sqlx::query_as!(
81.         Post,
82.         "SELECT id, title, content, author_id, create_time, update_time
83.          FROM posts WHERE id = ?",
84.         id as i64
85.     )
86.     .fetch_one(&mut *tx)
87.     .await?;
89.     tx.commit().await?;
90.     Ok(new_post)
91. }
93. pub async fn get_posts(pool: &MySqlPool, limit: i64) -> Result<Vec<Post>,sqlx::Error> {
94.     let posts = sqlx::query_as::<_, Post>(
95.         "SELECT id, title, content, author_id, create_time, update_time
96.          FROM posts
97.          ORDER BY create_time DESC
98.          LIMIT ?"
99.     )
100.     .bind(limit)
101.     .fetch_all(pool)
102.     .await?;
103.    
104.     Ok(posts)
105. }
107. pub async fn get_users(pool: &MySqlPool, limit: i64) -> Result<Vec<User>,sqlx::Error> {
108.     let users = sqlx::query_as::<_, User>(
109.         "SELECT id, username, '' as password, email, create_time
110.          FROM users
111.          ORDER BY create_time DESC
112.          LIMIT ?"
113.     )
114.     .bind(limit)
115.     .fetch_all(pool)
116.     .await?;
117.    
118.     Ok(users)
119. }
121. /// 根据ID获取单个帖子
122. pub async fn get_post_by_id(pool: &MySqlPool, id: i64) -> Result<Option<Post>,sqlx::Error> {
123.     let post = sqlx::query_as::<_, Post>(
124.         "SELECT id, title, content, author_id, create_time, update_time
125.          FROM posts WHERE id = ?"
126.     )
127.     .bind(id)
128.     .fetch_optional(pool)
129.     .await?;
130.    
131.     Ok(post)
132. }

复制代码

 
环境变量

.env

1. DATABASE_URL=mysql://root:123456@localhost:3306/rust_blog

复制代码

注意：如果密码带有@符号，需要进行URL-encode编码
打开在线url编码器，链接：https://www.convertstring.com/zh_CN/EncodeDecode/UrlEncode
请求处理器

 src/handlers/user_handler.rs

1. use actix_web::{web, HttpResponse, Result};
2. use sqlx::{mysql::MySqlPool};
3. use crate::{db, models::CreateUser};
4. use crate::models::User;
6. // 用户相关API接口模块
7. // 提供用户创建和查询功能
9. /// 创建新用户接口
10. ///
11. /// 用于注册新用户，创建用户账号并返回用户信息
12. #[utoipa::path(
13.     post,
14.     path = "/api/users",
15.     request_body = CreateUser,
16.     description = "注册新用户账号",
17.     summary = "创建用户",
18.     responses(
19.         (status = 200, description = "用户创建成功", body = User),
20.         (status = 400, description = "请求参数格式错误或用户已存在"),
21.         (status = 500, description = "服务器内部错误")
22.     ),
23.     tag = "用户管理"
24. )]
25. pub async fn create_user_handler(
26.     pool: web::Data<MySqlPool>,
27.     user: web::Json<CreateUser>,
28. ) -> Result<HttpResponse> {
29.     match db::create_user(pool.get_ref(), user.into_inner()).await {
30.         Ok(user) => Ok(HttpResponse::Created().json(user)),
31.         Err(e) => Ok(HttpResponse::InternalServerError().json(serde_json::json!({
32.             "error": e.to_string()
33.         })))
34.     }
35. }
37. /// 根据ID获取用户信息接口
38. ///
39. /// 通过用户ID查询特定用户的详细信息
40. #[utoipa::path(
41.     get,
42.     path = "/api/users/{id}",
43.     description = "根据用户ID获取用户详细信息",
44.     summary = "查询用户详情",
45.     responses(
46.         (status = 200, description = "查询成功", body = User),
47.         (status = 404, description = "用户不存在"),
48.         (status = 500, description = "服务器内部错误")
49.     ),
50.     params(
51.         ("id" = i64, Path, description = "用户ID，用于唯一标识用户")
52.     ),
53.     tag = "用户管理"
54. )]
55. pub async fn get_user_handler(
56.     pool: web::Data<MySqlPool>,
57.     user_id: web::Path<i64>,
58. ) -> Result<HttpResponse> {
59.     match db::get_user_by_id(pool.get_ref(), user_id.into_inner()).await {
60.         Ok(Some(user)) => Ok(HttpResponse::Ok().json(user)),
61.         Ok(None) => Ok(HttpResponse::NotFound().json(serde_json::json!({
62.             "error": "User not found"
63.         }))),
64.         Err(e) => Ok(HttpResponse::InternalServerError().json(serde_json::json!({
65.             "error": e.to_string()
66.         })))
67.     }
68. }
70. /// 获取用户列表接口
71. ///
72. /// 获取系统中的用户列表，支持分页查询
73. #[utoipa::path(
74.     get,
75.     path = "/api/users",
76.     description = "获取用户列表，支持通过limit参数限制返回数量",
77.     summary = "查询用户列表",
78.     responses(
79.         (status = 200, description = "查询成功", body = [User]),
80.         (status = 500, description = "服务器内部错误")
81.     ),
82.     params(
83.         ("limit" = Option<i64>, Query, description = "限制返回数量，默认为10"),
84.         ("page" = Option<i64>, Query, description = "页码，从1开始")
85.     ),
86.     tag = "用户管理"
87. )]
88. pub async fn get_users_handler(
89.     pool: web::Data<MySqlPool>,
90.     query: web::Query<std::collections::HashMap<String, String>>,
91. ) -> Result<HttpResponse> {
92.     let limit = query.get("limit")
93.         .and_then(|s| s.parse().ok())
94.         .unwrap_or(10);
95.    
96.     match db::get_users(pool.get_ref(), limit).await {
97.         Ok(users) => Ok(HttpResponse::Ok().json(users)),
98.         Err(e) => Ok(HttpResponse::InternalServerError().json(serde_json::json!({
99.             "error": e.to_string()
100.         })))
101.     }
102. }

复制代码

 
 src/handlers/post_handler.rs

1. use sqlx::{mysql::MySqlPool};
2. use crate::models::{CreatePost, Post};   // 模型
3. use crate::db;                           // 数据库函数
4. use std::collections::HashMap;           // HashMap
5. use actix_web::{web, HttpRequest, HttpMessage,HttpResponse}; // 解决 extensions() 不可见
7. // 帖子相关API接口模块
8. // 提供帖子创建和查询功能
10. /// 创建新帖子接口
11. ///
12. /// 允许认证用户创建新的帖子内容，帖子将与当前认证用户关联
13. #[utoipa::path(
14.     post,
15.     path = "/api/posts",
16.     request_body = CreatePost,
17.     description = "创建新的博客帖子，需要用户认证",
18.     summary = "创建帖子",
19.     responses(
20.         (status = 200, description = "帖子创建成功", body = Post),
21.         (status = 400, description = "请求参数格式错误"),
22.         (status = 404, description = "未找到相关资源"),
23.         (status = 500, description = "服务器内部错误")
24.     ),
25.     tag = "帖子管理"
26. )]
27. pub async fn create_post_handler(
28.     pool: web::Data<MySqlPool>,
29.     post: web::Json<CreatePost>,
30.     req: HttpRequest,
31. ) -> Result<HttpResponse, actix_web::Error> {
32.     // 从请求扩展中获取认证的用户ID
33.     let author_id = req.extensions().get::<i64>().copied().unwrap_or(1);
34.     println!("author_id: {}", author_id);
35.    
36.     match db::create_post(pool.get_ref(), post.into_inner(), author_id).await {
37.         Ok(post) => Ok(HttpResponse::Created().json(post)),
38.         Err(e) => Ok(HttpResponse::InternalServerError().json(serde_json::json!({
39.             "error": e.to_string()
40.         })))
41.     }
42. }
44. /// 获取帖子列表接口
45. ///
46. /// 获取系统中的帖子列表，支持分页查询
47. #[utoipa::path(
48.     get,
49.     path = "/api/posts",
50.     description = "获取帖子列表，支持通过limit参数限制返回数量",
51.     summary = "查询帖子列表",
52.     responses(
53.         (status = 200, description = "查询成功", body = [Post]),
54.         (status = 500, description = "服务器内部错误")
55.     ),
56.     params(
57.         ("limit" = Option<i64>, Query, description = "限制返回数量，默认为10"),
58.         ("page" = Option<i64>, Query, description = "页码，从1开始")
59.     ),
60.     tag = "帖子管理"
61. )]
62. pub async fn get_posts_handler(
63.     pool: web::Data<MySqlPool>,
64.     query: web::Query<HashMap<String, String>>,
65. ) -> Result<HttpResponse, actix_web::Error> {
66.     let limit = query.get("limit")
67.         .and_then(|s| s.parse().ok())
68.         .unwrap_or(10);
69.    
70.     match db::get_posts(pool.get_ref(), limit).await {
72.         Ok(posts) => Ok(HttpResponse::Ok().json(posts)),
73.         Err(e) => Ok(HttpResponse::InternalServerError().json(serde_json::json!({
74.             "error": e.to_string()
75.         })))
76.     }
77. }
79. /// 获取帖子详情接口
80. ///
81. /// 根据帖子ID获取单个帖子的详细信息
82. #[utoipa::path(
83.     get,
84.     path = "/api/posts/{id}",
85.     description = "根据ID获取单个帖子的详细信息",
86.     summary = "查询帖子详情",
87.     responses(
88.         (status = 200, description = "查询成功", body = Post),
89.         (status = 404, description = "帖子不存在"),
90.         (status = 500, description = "服务器内部错误")
91.     ),
92.     params(
93.         ("id" = i64, Path, description = "帖子ID", example = 1)
94.     ),
95.     tag = "帖子管理"
96. )]
97. pub async fn get_post_handler(
98.     pool: web::Data<MySqlPool>,
99.     id: web::Path<i64>,
100. ) -> Result<HttpResponse, actix_web::Error> {
101.     match db::get_post_by_id(pool.get_ref(), *id).await {
102.         Ok(Some(post)) => Ok(HttpResponse::Ok().json(post)),
103.         Ok(None) => Ok(HttpResponse::NotFound().json(serde_json::json!({
104.             "error": "帖子不存在"
105.         }))),
106.         Err(e) => Ok(HttpResponse::InternalServerError().json(serde_json::json!({
107.             "error": e.to_string()
108.         })))
109.     }
110. }

复制代码

 
src/handlers/dev.rs

1. use actix_web::{get, web, HttpResponse, Responder};
2. use serde::{Serialize};
3. use utoipa::{ToSchema};
5. #[derive(Serialize, ToSchema)]
6. struct TokenReply {
7.     message: String,
8. }
10. // 内部函数，处理实际的token生成逻辑
11. fn generate_token(user_id: u32) -> String {
12.     let user_id_i64: i64 = user_id as i64;
13.     let t = crate::jwt::make_token(user_id_i64, 24);
14.     format!("Bearer {}", t)
15. }
17. /// 生成开发测试token（指定用户ID）
18. ///
19. /// 用于开发环境测试时快速生成认证令牌，使用指定的用户ID
20. #[utoipa::path(
21.     get,
22.     path = "/dev/token/{user_id}",
23.     responses(
24.         (status = 200, description = "成功生成测试token", body = TokenReply)
25.     ),
26.     tag = "开发工具"
27. )]
28. #[get("/token/{user_id:[0-9]+}")]
29. pub async fn dev_token(user_id: web::Path<u32>) -> impl Responder {
30.     let token = generate_token(*user_id);
31.     HttpResponse::Ok().body(token)
32. }
34. /// 生成开发测试token（默认用户ID=1）
35. ///
36. /// 用于开发环境测试时快速生成认证令牌，使用默认用户ID=1
37. #[utoipa::path(
38.     get,
39.     path = "/dev/token",
40.     responses(
41.         (status = 200, description = "成功生成测试token", body = TokenReply)
42.     ),
43.     tag = "开发工具"
44. )]
45. #[get("/token")]
46. pub async fn dev_token_default() -> impl Responder {
47.     // 直接调用内部函数生成token，使用默认user_id=1
48.     let token = generate_token(1);
49.     HttpResponse::Ok().body(token)
50. }

复制代码

 
src/handlers/mod.rs

1. // 把子模块引进来
2. pub mod user_handler;
3. pub mod post_handler;
4. pub mod dev;  
6. // 再导出给 main.rs 用
7. pub use user_handler::{create_user_handler, get_user_handler, get_users_handler};
8. pub use post_handler::{get_posts_handler, create_post_handler, get_post_handler};<br>

复制代码

 
中间件

src/middleware/auth.rs
[code]use actix_web::{    dev::{forward_ready, Service, ServiceRequest, ServiceResponse, Transform},    Error, HttpMessage,};use futures_util::future:ocalBoxFuture;use jsonwebtoken::{decode, Algorithm, DecodingKey, Validation};use crate::jwt::{Claims, SECRET};pub struct AuthMiddleware;pub struct AuthMiddlewareService {    service: S,}impl Transform for AuthMiddlewarewhere    S: Service,    S::Future: 'static,    B: 'static,{    type Response = ServiceResponse<B>;    type Error = Error;    type InitError = ();    type Transform = AuthMiddlewareService;    type Future = std::future::Ready;    fn new_transform(&self, service: S) -> Self::Future {        std::future::ready(Ok(AuthMiddlewareService { service }))    }}impl Service for AuthMiddlewareServicewhere    S: Service,    S::Future: 'static,    B: 'static,{    type Response = ServiceResponse<B>;    type Error = Error;    type Future = LocalBoxFuture