📘 Rust Web API开发教程：用Rust写一个”今日诗词”API（手把手）

🌟 本教程适合Rust零基础读者，是一份详细的Rust Web API开发教程，每一步都有代码、有命令行操作、有截图指引，1小时内可以跑通。通过本教程，你将学习如何使用Rust和Actix-Web框架创建一个随机诗词API，快速上手Rust后端开发。

🦀 关于Rust：它是什么？为什么用它？

Rust 是一门由Mozilla开发的系统编程语言，2015年发布第一个稳定版本。它旨在提供 C/C++级别的性能，同时通过独特的 所有权系统 在编译阶段保证 内存安全，无需垃圾回收。这些特性使Rust成为Rust后端开发和Web服务开发的理想选择。

它的核心优点

🔒 内存安全

Rust的编译器会在编译时检查所有内存访问，杜绝空指针、悬垂指针和数据竞争，让你写出更健壮的代码。

⚡ 零成本抽象

像迭代器、泛型等高级特性在编译后会被优化为与手写底层代码一样高效，不会有运行时开销。

🔄 无畏并发

所有权系统让线程间数据共享变得安全，编译器会阻止大多数并发错误。

🛠️ 现代工具链

cargo 不仅是包管理器，还能构建、测试、生成文档，配合 rustfmt（格式化）和 clippy（lint）让开发体验极佳。

🌱 丰富的生态

Web开发（Actix-Web、Rocket）、嵌入式、WASM、命令行工具等领域都有成熟框架。

在Web API场景下，Rust能提供 极致的性能和稳定性，适合对延迟敏感、高并发的服务。这也是为什么越来越多的开发者选择Rust后端开发和Web服务开发。今天我们就用Rust写一个简单的诗词API，亲身体验Rust Web API的开发流程。

🎯 最终效果

🌐 API访问效果

通过本Rust Web API开发教程创建的诗词API，在浏览器访问 http://localhost:8080/poem，会返回一句随机古诗词，格式为JSON。例如：

1
{"poem":"离离原上草，一岁一枯荣。野火烧不尽，春风吹又生。","line_count":3}

访问根路径 http://localhost:8080/ 则显示欢迎信息。这个简单的Rust后端服务展示了Rust在Web开发中的应用。

📷 操作截图

最终效果展示

💡 操作环境说明：以下操作在Windows的PowerShell终端中进行

🛠️ 第一步：环境准备

安装Rust（如果还没装）

📥 安装Rust

打开PowerShell终端，执行以下命令：

1
2
Invoke-WebRequest -Uri https://win.rustup.rs -OutFile rustup-init.exe
.\rustup-init.exe

提示：使用官网的curl命令在Windows上可能安装不了，推荐使用上面的PowerShell命令

📷 操作截图

执行安装命令

安装完成后，最后几行应该显示：

1
Rust is installed now. Great!

📷 操作截图

安装完成结果

在Windows上，如果上面命令还是无效，可以到 rustup.rs 直接下载安装程序。

📷 操作截图

官网下载安装程序

验证安装

✅ 验证安装

在原PowerShell终端，运行：

1
2
rustc --version
cargo --version

预期结果：两条命令都应该输出版本号，例如 rustc 1.75.0 和 cargo 1.75.0

📷 操作截图

验证安装结果

🆕 第二步：创建新项目

🚀 创建新项目

在PowerShell终端中，进入你想存放项目的目录（例如 cd ~/诗词api），然后运行：

1
2
cargo new poem_api
cd poem_api

预期结果：终端显示 Created binary (application) 'poem_api' package

📷 操作截图

创建新项目结果

💡 操作环境说明：以下在VS Code或者其他编辑器中进行操作

📦 第三步：添加依赖

📝 添加依赖

编辑项目根目录下的 Cargo.toml 文件，在 [dependencies] 部分添加三个依赖：

1
2
3
4
5
6
7
8
9
[package]
name = "poem_api"
version = "0.1.0"
edition = "2021"

[dependencies]
actix-web = "4"
rand = "0.8"
serde = { version = "1", features = ["derive"] }

📷 操作截图

添加依赖后的Cargo.toml文件

🔧 actix-web

高性能的Rust Web框架，用于处理HTTP请求和响应

🎲 rand

用于生成随机数，随机选择诗词

📋 serde

用于将数据结构序列化为JSON格式

📄 第四步：准备诗词数据

📚 准备诗词数据

在 src 目录下新建一个文件，命名为 poems.rs，然后写入以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// src/poems.rs

pub const POEMS: [&str; 10] = [
    "床前明月光，疑是地上霜。举头望明月，低头思故乡。",
    "春眠不觉晓，处处闻啼鸟。夜来风雨声，花落知多少。",
    "白日依山尽，黄河入海流。欲穷千里目，更上一层楼。",
    "红豆生南国，春来发几枝。愿君多采撷，此物最相思。",
    "千山鸟飞绝，万径人踪灭。孤舟蓑笠翁，独钓寒江雪。",
    "墙角数枝梅，凌寒独自开。遥知不是雪，为有暗香来。",
    "白日不到处，青春恰自来。苔花如米小，也学牡丹开。",
    "锄禾日当午，汗滴禾下土。谁知盘中餐，粒粒皆辛苦。",
    "离离原上草，一岁一枯荣。野火烧不尽，春风吹又生。",
    "向晚意不适，驱车登古原。夕阳无限好，只是近黄昏。",
];

这里定义了一个常量数组，包含10句经典唐诗（其实是整首诗，但没关系）。

📷 操作截图

准备诗词数据文件

🧠 第五步：编写主程序逻辑

💻 编写主程序逻辑

现在修改 src/main.rs，这是项目的主入口，我们将在这里编写Web服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// src/main.rs

mod poems;  // 引入刚才写的诗词模块

use actix_web::{get, web, App, HttpResponse, HttpServer, Responder};
use rand::Rng;
use serde::Serialize;

// 定义API返回的JSON结构
#[derive(Serialize)]
struct PoemResponse {
    poem: String,          // 诗词内容
    line_count: usize,     // 诗句数量（以句号分隔估算）
}

// 根路径处理函数
#[get("/")]
async fn hello() -> impl Responder {
    HttpResponse::Ok().body("欢迎访问今日诗词API！请访问 /poem 获取随机诗词")
}

// /poem 路径处理函数
#[get("/poem")]
async fn random_poem() -> impl Responder {
    let mut rng = rand::thread_rng();
    let index = rng.gen_range(0..poems::POEMS.len());  // 随机选择一个索引
    let poem = poems::POEMS[index].to_string();
    
    // 计算大概的诗句数（以句号分割）
    let line_count = poem.split('。').count();
    
    let response = PoemResponse {
        poem,
        line_count,
    };
    
    HttpResponse::Ok().json(response)  // 返回JSON
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    println!("🚀 服务器启动在 http://localhost:8080");
    
    HttpServer::new(|| {
        App::new()
            .service(hello)           // 注册根路由
            .service(random_poem)      // 注册/poem路由
    })
    .bind(("127.0.0.1", 8080))?        // 绑定地址和端口
    .run()
    .await
}

📷 操作截图

编写主程序逻辑

代码解释

🔍 代码解析

  • 📦 模块引入：mod poems; 告诉Rust我们要使用同目录下的 poems.rs 模块
  • 🎯 路由处理：#[get("/")] 是一个属性宏，表示这个函数处理GET请求的根路径
  • 📋 JSON序列化：HttpResponse::Ok().json(...) 返回状态码200，并将数据自动转为JSON
  • 🚀 服务器启动：在main函数中，我们启动HTTP服务器，监听本地8080端口
  • 🎲 随机选择：使用 rand::thread_rng() 生成随机数，随机选择一首诗词

💡 操作环境说明：以下操作在Windows的PowerShell终端中进行

🏃 第六步：运行项目

🔥 运行项目

回到终端，确保当前目录是 poem_api，然后执行：

1
cargo run

提示：第一次运行会下载依赖并编译，可能需要几分钟（以后就快了）

📷 操作截图

在终端运行项目

运行成功后，终端会显示：

1
🚀 服务器启动在 http://localhost:8080

📷 操作截图

运行结果

💡 重要提示：服务器运行后，不要关闭终端，否则服务会停止

🌐 第七步：测试API

🌍 测试API

打开浏览器（Edge、Chrome、Firefox等），在地址栏输入：

1
http://localhost:8080/

然后访问：

1
http://localhost:8080/poem

预期结果：浏览器页面显示一个JSON对象，例如：

1
{"poem":"离离原上草，一岁一枯荣。野火烧不尽，春风吹又生。","line_count":3}

特别说明：刷新几次，诗词内容会随机变化

📷 操作截图

最终效果展示

🎉 恭喜！你已经完成了第一个Rust Web API

🎊 恭喜你！

你刚刚用Rust写了一个简单的Web服务，它：

🌐

接收HTTP请求

🎲

随机选择诗词

📋

返回格式化的JSON

💡 扩展挑战（读者可以自己尝试）

🚀 扩展挑战

📚 增加更多诗词

修改 poems.rs，添加更多古诗

👤 增加作者信息

返回诗词标题和作者，扩展数据结构

🔍 支持查询参数

例如 ?count=3 返回多首诗词

☁️ 部署到云端

尝试用 Shuttle 或 Railway 一键部署

❓ 常见问题

🔧 cargo run 时报错 "linker not found"

解决方案：在Linux上可能需要安装build-essential：sudo apt install build-essential。Mac上需要安装Xcode命令行工具：xcode-select --install。

📡 端口8080被占用怎么办？

解决方案：修改 main.rs 中的 bind 参数，比如改成 ("127.0.0.1", 8081)，然后重新运行。

🌐 浏览器访问不到？

解决方案：确保程序运行后没有报错，并且浏览器地址是 http://localhost:8080 而不是 https。

📝 这篇Rust Web API开发教程已经足够详细，读者按照截图和代码一步步操作，一定能跑通。通过本教程，你不仅学会了如何用Rust和Actix-Web框架创建一个诗词API，还对Rust后端开发有了初步的了解。
🌟 希望你喜欢这个Rust Web API项目，开始你的Rust学习之旅！

📅 更新时间：2026-02-20
✍️ 作者：Jay