14个文本转图像AI API
使用Rust和Axum构建高性能REST API
2024-12-06
传统上，Rust 主要应用于构建命令行界面（CLI）、嵌入式系统以及性能要求极高的应用程序。然而，自 Rust 1.39 版本引入 async/await 语法后，Rust 生态系统迎来了重大变革。
这一变革为创建基于 Web 和桌面的应用程序提供了一种更为便捷的方法。此外，Rust 以其安全优先的设计理念、强大的并发模型以及高效的内存管理能力，在这些领域的开发中脱颖而出，成为理想之选。
本教程将深入探讨如何利用 Rust 和 Axum 框架来构建功能完备的 REST API。我们将涵盖以下内容：如何设置路由和 API 终端节点、处理 API 请求中的查询参数、请求体以及动态 URL 参数、将 API 与 MySQL 数据库进行连接、集成中间件，以及一些保持 API 高性能的实用建议。
先决条件
要顺利跟随本教程进行操作，您需要满足以下前提条件：
- 对基本编程概念有所了解，如函数、数据结构、控制流、模块以及基础的异步编程知识。
- 已在您的系统上成功安装 Rust 和 Cargo。
- 准备好一个 MySQL 数据库。如需安装指南，请参考适用于 Mac/Linux 和 Windows 的设置说明。
什么是Axum？
Axum 是一个专注于提升性能和简化开发的 Web 框架。它充分利用了超库（一个高性能的 HTTP 服务器库）的优势，以加速 Web 应用程序的响应速度和提升并发处理能力。此外，Axum 与 Tokio 库紧密集成，将 Rust 的 async/await 特性发挥到极致，为开发高性能的异步 API 和 Web 应用程序提供了强有力的支持。
Axum 的核心功能构建于 Tokio 运行时之上，后者为 Rust 提供了强大的非阻塞、事件驱动的任务管理能力。这一特性对于高效处理大量并发请求至关重要。
此外，Axum 是使用 Rust 的强类型系统和所有权规则构建的，这些规则对常见的 Web 开发陷阱（如数据竞争和内存泄漏）施加了编译时保护措施。同时，Axum 的模块化设计理念使得开发者能够根据需要添加必要的组件，从而创建出轻量级且专注的应用程序。
创建新的 Rust 应用程序
现在，让我们通过运行以下命令来启动一个新的 Rust 应用程序项目。
cargo new my_rest_api
cd my_rest_api执行这些命令后，我们将获得一个新的 Rust 应用程序框架;
这个框架包括一个 cargo.toml 文件，用于管理应用程序的依赖项，以及一个 src/main.rs 文件，其中包含一个 Rust 函数，能够在控制台输出 “hello world”。
安装所需依赖项
接下来，我们需要为应用程序安装必要的依赖项。在本教程中，我们将安装 Axum、Serde 和 Tokio。Serde 用于 JSON 数据的序列化和反序列化，因为 Rust 本身不直接支持 JSON 格式的处理。Tokio 则提供异步运行时支持，这也是 Rust 标准库所不具备的功能。
为了进行这些安装，请打开 cargo.toml 文件，并在 dependencies 部分添加以下配置。
. . .
[dependencies]
axum = {version = "0.6.20", features = ["headers"]}
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0.68"
tokio = { version = "1.0", features = ["full"] }接下来，通过运行以下命令安装依赖项：
cargo build执行该命令会从 Crates.io（Rust 的包注册表）下载所需的包到您的项目中。如果您有 JavaScript 和 npm 的使用经验，这个过程相当于在 package.json 文件中添加依赖项，然后运行 npm install 来安装它们。
你好，Rust！
现在，我们已经成功安装了所有必要的依赖包。接下来，让我们进一步探索并扩展默认提供的端点。请打开 src/main.rs 文件，并使用以下代码对其进行更新：
use axum::{routing::get, Router};
#[tokio::main]
async fn main() {
let app = Router::new().route("/", get(|| async { "Hello, Rust!" }));
println!("Running on http://localhost:3000");
axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}在代码的第一行，我们导入了 Axum 的 Router 并调用了它的 get() 方法来设置一个路由。接着，我们使用 #[tokio::main] 宏来标记 main() 函数，这样它就可以绑定到 Tokio 的异步运行时上。然后，我们定义了一个默认路由，该路由会对 GET 请求响应 “Hello, Rust!” 字符串。最后，我们将这个服务设置为监听所有接口上的 3000 端口；这意味着现在可以通过 http://localhost:3000 来访问它。
启动应用程序
要启动应用程序，请在终端中运行以下命令：
cargo run执行上述命令后，您应当会在终端中看到 “Running on http://localhost:3000” 的输出信息。此时，您可以在浏览器中访问该地址，或者使用 curl 等工具，来查看显示的 “Hello, Rust!” 消息。
Axum 基础知识
路由和处理程序
在 Axum 框架中，路由机制扮演着将接收到的 HTTP 请求引导至相应处理程序的重要角色。这些处理程序本质上就是包含请求处理逻辑的函数。
简而言之，每当我们定义一个新的端点时，其实也在定义一个用于处理该端点接收到的请求的函数，在 Axum 中，这些函数被称为处理程序。
在此过程中，router 对象发挥着至关重要的作用，因为它负责将特定的 URL 映射到处理程序函数，并指明端点所能接受的 HTTP 方法。以下示例将更深入地阐释这一概念。
请打开 src/main.rs 文件，并用以下代码替换其内容。
use axum::{
body::Body,
http::StatusCode,
response::{IntoResponse, Response},
routing::{get, post},
Json, Router,
};
use serde::Serialize;
#[derive(Serialize)]
struct User {
id: u64,
name: String,
email: String,
}
// Handler for /create-user
async fn create_user() -> impl IntoResponse {
Response::builder()
.status(StatusCode::CREATED)
.body(Body::from("User created successfully"))
.unwrap()
}
// Handler for /users
async fn list_users() -> Json<Vec<User>> {
let users = vec![
User {
id: 1,
name: "Elijah".to_string(),
email: "elijah@example.com".to_string(),
},
User {
id: 2,
name: "John".to_string(),
email: "john@doe.com".to_string(),
},
];
Json(users)
}
#[tokio::main]
async fn main() {
// Define Routes
let app = Router::new()
.route("/", get(|| async { "Hello, Rust!" }))
.route("/create-user", post(create_user))
.route("/users", get(list_users));
println!("Running on http://localhost:3000");
// Start Server
axum::Server::bind(&"127.0.0.1:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}上述代码段向我们展示了Axum中如何实际设置路由和处理程序。通过Router::new()，我们为应用程序定义了路由规则，明确了HTTP方法（例如GET、POST等）与它们各自对应的处理函数。
以/users路由为例，它被设定为响应GET请求，而list_users()函数则作为该请求的处理程序。这个函数是一个简单的JSON响应函数，它会返回一个包含两个预定义用户的JSON数组。由于Rust原生并不直接支持JSON格式，因此我们需要为User结构体实现Serde的Serialize trait，以便能够将User实例转换为JSON格式。
另一方面，/create-user路由则设计为接受POST请求，其处理程序是create_user()函数。这个函数通过status(StatusCode::CREATED)返回了一个201状态码，并附带了一个静态响应：“User created successfully”。
想要实际体验一下这些功能吗？那就重新启动你的代码，并使用以下curl命令向/create-user端点发送一个POST请求吧！
curl -X POST http://localhost:3000/create-user您应该看到消息“用户创建成功”。
另外，如果您在浏览器中访问/users路径，应该会看到一个显示我们预先定义的静态用户列表的页面，内容大致如下。
Axum 提取器
Axum 框架中的提取器（Extractor）是一项极为强大的功能，它能够解析传入的 HTTP 请求中的部分内容，并将其转换为处理程序函数所能直接使用的类型化数据。通过这一机制，开发者能够以类型安全的方式便捷地访问请求中的各类参数，如路径段（Path Segments）、查询字符串（Query Strings）以及请求正文（Request Body）等。
带有路径和查询提取器的 GET 请求
若想要捕获动态的 URL 路径值以及查询字符串中的参数，我们只需在处理程序函数的参数列表中明确指定这些值及其预期的类型即可。以下是一个具体的代码示例，展示了如何在 src/main.rs 文件中利用这一功能。通过此示例，您可以直观地看到提取器是如何在实际应用中发挥作用的。
use axum::{
extract::{Path, Query},
routing::get,
Router,
};
use serde::Deserialize;
// A struct for query parameters
#[derive(Deserialize)]
struct Page {
number: u32,
}
// A handler to demonstrate path and query extractors
async fn show_item(Path(id): Path<u32>, Query(page): Query<Page>) -> String {
format!("Item {} on page {}", id, page.number)
}
#[tokio::main]
async fn main() {
let app = Router::new().route("/item/:id", get(show_item));
axum::Server::bind(&"127.0.0.1:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}在此示例中，我们利用/path/:id这样的模式定义了一个包含动态部分的URL。这种语法在其他编程语言中也颇为常见。此外，show_item()处理程序通过路径提取器从URL中捕获了项目ID，并利用查询提取器从查询字符串中获取了页码信息。当向该端点发送请求时，Axum框架会自动调用相应的处理程序，并将已提取的数据作为参数传递给该处理程序。
接下来，您可以尝试重新启动应用程序，并通过运行以下curl命令来验证这一功能：
curl "http://localhost:3000/item/42?number=2"执行上述curl命令后，您应该会在终端中看到“第 2 页第 42 项”的输出。
使用 JSON 正文提取器的 POST 请求
在处理 POST 请求时，经常需要解析请求正文中发送的数据。Axum 框架为我们提供了 JSON 提取器，它能够轻松地将 JSON 数据转换为 Rust 中的数据类型。接下来，我们将通过更新 src/main.rs 文件来展示如何使用这一功能。
use axum::{extract::Json, routing::post, Router};
use serde::Deserialize;
// A struct for the JSON body
#[derive(Deserialize)]
struct Item {
title: String,
}
// A handler to demonstrate the JSON body extractor
async fn add_item(Json(item): Json<Item>) -> String {
format!("Added item: {}", item.title)
}
#[tokio::main]
async fn main() {
let app = Router::new().route("/add-item", post(add_item));
axum::Server::bind(&"127.0.0.1:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}在上面的例子中，我们设计了一个新的 /add-item 端点，它专门用于接收 POST 请求。在这个端点的处理函数 add_item() 中，我们巧妙地运用了 JSON 提取器，它能将接收到的 JSON 请求体解析为我们定义的 Item 结构体。这一操作直观地展示了 Axum 在解析传入请求体时的便捷与高效。
现在，您可以重新启动您的应用程序，并通过执行以下命令来亲自体验这个示例：
curl -X POST http://localhost:3000/add-item \
-H "Content-Type: application/json" \
-d '{"title": "Some random item"}'一旦执行上述命令，我们应该会收到一条响应消息：“添加的项目：一些随机项目”。
错误处理
Axum框架为开发者提供了一种在应用层面统一处理错误的有效途径。具体而言，处理程序（Handler）可以返回Result类型，这一特性使得开发者能够优雅地处理错误情况，并据此返回恰当的HTTP响应。
以下是一个在处理程序函数中实现错误处理的示例。为了直观地看到这一机制的实际效果，您可以按照以下代码更新您的src/main.rs文件，并重新启动您的应用程序。
use axum::{
extract::Path, http::StatusCode, response::IntoResponse, routing::delete, Json, Router,
};
use serde::Serialize;
#[derive(Serialize)]
struct User {
id: u64,
name: String,
}
// Define a handler that performs an operation and may return an error
async fn delete_user(Path(user_id): Path<u64>) -> Result<Json<User>, impl IntoResponse> {
match perform_delete_user(user_id).await {
Ok(_) => Ok(Json(User {
id: user_id,
name: "Deleted User".into(),
})),
Err(e) => Err((
StatusCode::INTERNAL_SERVER_ERROR,
format!("Failed to delete user: {}", e),
)),
}
}
// Hypothetical async function to delete a user by ID
async fn perform_delete_user(user_id: u64) -> Result<(), String> {
// Simulate an error for demonstration
if user_id == 1 {
Err("User cannot be deleted.".to_string())
} else {
// Logic to delete a user...
Ok(())
}
}
#[tokio::main]
async fn main() {
let app = Router::new().route("/delete-user/:user_id", delete(delete_user));
println!("Running on http://localhost:3000");
axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}在上面的例子中，我们设计了一个名为 /delete-user/:user_id 的路由，该路由旨在模拟删除具有特定 user_id 的用户操作。在其对应的处理函数 delete_user 中，我们尝试调用一个假设的 perform_delete_user() 函数来执行删除动作。若删除成功，函数会返回一个包含虚拟用户 JSON 响应的 Ok 值；若遇到错误，则会返回一个包含 HTTP 500 状态码（内部服务器错误）及错误信息的 Err 值。
为了测试这个 /delete-user 端点，您可以使用以下 curl 命令：
curl -X DELETE http://localhost:3000/delete-user/1上述命令会向用户ID为1的/delete-user端点发送一个删除请求。根据示例代码中的逻辑，这通常会触发错误条件，并导致服务器返回一个错误响应，然而，如果您想要测试成功删除的场景，只需将用户ID 1 替换为任意其他数字即可。例如：
curl -X DELETE http://localhost:3000/delete-user/2执行上述命令将模拟一个成功的删除操作，并促使服务器返回一个表示操作成功的响应。通过这种方式，您可以验证/delete-user端点在不同情况下的行为是否符合预期。
Axum 中的高级技术
在掌握了 Axum 的基础知识之后，让我们一同深入挖掘那些对于构建功能强大的 API 至关重要的其他高级功能。
数据库集成
在 API 开发过程中，数据库的集成是至关重要的一环。幸运的是，Axum 能够与任何异步 Rust 数据库库实现无缝对接。在此，我们以 sqlx crate 为例，展示如何将其与 MySQL 数据库进行集成。sqlx 是一个支持 async/await 的数据库库，与 Axum 的异步特性完美契合。
要开始进行集成工作，请确保您的 MySQL 服务已在后台正常运行。接下来，您需要在 Cargo.toml 文件中添加 sqlx 及其对应的 MySQL 特性依赖，以及必要的异步运行时依赖。
sqlx = { version = "0.7.2", features = ["runtime-tokio", "mysql"] }然后，运行以下命令以获取新的依赖项：
cargo build在完成相关的配置后，您现在可以利用 MySqlPool::connect() 方法来创建一个与 MySQL 数据库的连接池。在此过程中，请确保将 database_url 定义中的占位符替换为实际的数据库连接信息，如下所示：
use axum::{routing::get, Router};
use sqlx::MySqlPool;
#[tokio::main]
async fn main() {
let database_url = "mysql://<<USERNAME>>:<<PASSWORD>>@<<HOSTNAME>>/<<DATABASE NAME>>";
let pool = MySqlPool::connect(&database_url)
.await
.expect("Could not connect to the database");
let app = Router::new().route("/", get(|| async { "Hello, Rust!" }));
println!("Running on http://localhost:3000");
axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
} 连接池准备就绪后，您现在可以使用以下语法开始在函数中执行数据库查询：
async fn fetch_data(pool: MySqlPool) -> Result<Json<MyDataType>, sqlx::Error> {
let data = sqlx::query_as!(MyDataType, "SELECT * FROM my_table")
.fetch_all(&pool)
.await?;
Ok(Json(data))
}在与Axum进行集成时，我们的处理程序函数需要接收一个类型为 Extension<MySqlPool> 的参数。这一设置使得Axum能够在向我们的端点发送请求时，自动将 MySqlPool（即数据库连接池）传递给处理程序函数。
举个例子，如果我们希望某个端点能够返回MySQL数据库中存储的所有用户信息，那么首先需要在MySQL数据库中创建一个名为 users 的新表，并为其设计合适的表结构。
create table users (
id int primary key auto_increment,
name varchar(200) not null,
email varchar(200) not null
);然后，运行以下命令向该表添加新条目。
INSERT INTO users (id, name, email)
VALUES (1, 'Alice Smith', 'alice.smith@example.com'),
(2, 'Bob Johnson', 'bob.johnson@example.com'),
(3, 'Charlie Lee', 'charlie.lee@example.com'),
(4, 'Dana White', 'dana.white@example.com'),
(5, 'Evan Brown', 'evan.brown@example.com');设置表后，您通常会将 Axum 设置为使用 SQLx，如下所示。
use axum::{extract::Extension, response::IntoResponse, routing::get, Json, Router, Server};
use serde_json::json;
use sqlx::{MySqlPool, Row};
// Define the get_users function as before
async fn get_users(Extension(pool): Extension<MySqlPool>) -> impl IntoResponse {
let rows = match sqlx::query("SELECT id, name, email FROM users")
.fetch_all(&pool)
.await
{
Ok(rows) => rows,
Err(_) => {
return (
axum::http::StatusCode::INTERNAL_SERVER_ERROR,
"Internal server error",
)
.into_response()
}
};
let users: Vec<serde_json::Value> = rows
.into_iter()
.map(|row| {
json!({
"id": row.try_get::<i32, _>("id").unwrap_or_default(),
"name": row.try_get::<String, _>("name").unwrap_or_default(),
"email": row.try_get::<String, _>("email").unwrap_or_default(),
})
})
.collect();
(axum::http::StatusCode::OK, Json(users)).into_response()
}
#[tokio::main]
async fn main() {
// Set up the database connection pool
let database_url = "mysql://<<USERNAME>>:<<PASSWORD>>@<<HOSTNAME>>/<<DATABASE_NAME>>";
let pool = MySqlPool::connect(&database_url)
.await
.expect("Could not connect to the database");
// Create the Axum router
let app = Router::new()
.route("/users", get(get_users))
.layer(Extension(pool));
// Run the Axum server
Server::bind(&"127.0.0.1:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}在这个升级后的示例中，我们对应用程序的路由器进行了更新，增加了一个新的扩展定义，用于传入 MySQL 连接池，得益于这一改动，在处理程序函数中，我们现在可以轻松地访问到这个连接池。
处理程序函数会执行一个 SQL 查询，从数据库中检索用户信息，并根据查询结果提取用户的 id、name 和 email 字段。随后，这些信息会被封装在响应体中，通过 API 终端节点返回给客户端。
在将 src/main.rs 文件中的代码替换为上述示例后，您可以启动应用程序，并在浏览器中访问 http://localhost:3000/users。此时，您应该会看到一个包含用户信息的 JSON 数组，具体内容取决于您数据库中存储的数据。
中间件
Axum 框架提供的中间件功能，使得开发者能够在请求抵达处理程序之前，以及响应发送至客户端之前，对请求和响应进行一系列操作。这一特性在处理日志记录、身份验证以及设置通用响应头部等任务时显得尤为实用。
以下是一个添加简单日志记录中间件的示例方法：
use axum::{
body::Body,
http::Request,
middleware::{self, Next},
response::Response,
routing::get,
Router, Server,
};
async fn logging_middleware(req: Request<Body>, next: Next<Body>) -> Response {
println!("Received a request to {}", req.uri());
next.run(req).await
}
#[tokio::main]
async fn main() {
let app = Router::new()
.route("/", get(|| async { "Hello, world!" }))
.layer(middleware::from_fn(logging_middleware));
Server::bind(&"127.0.0.1:3000".parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}现在，无论何时访问任何终端节点，它都会按以下方式记录到控制台中：
Received a request to /users
Received a request to /
Received a request to /test
Received a request to /todos提升 REST API 性能的建议
Rust 语言所具备的独特并发处理机制、零成本抽象以及强大的类型系统，为高性能 API 的开发奠定了坚实的基础。而在使用 Axum 框架时，这些优势更是得到了进一步的发挥。
然而，要想让 API 的性能更上一层楼，我们还需要深入理解并灵活运用 Rust 的所有权和借用原则，从而实现对内存的有效管理。此外，减少共享资源的锁竞争、精心选择序列化方法以避免性能瓶颈，也是提升性能的关键。在选择序列化格式和库时，我们应优先考虑效率和性能，正如本文示例中所展示的那样。
但仅编写高效的代码是不够的，我们还需要借助如 Criterion 等性能分析工具，对代码进行定期的性能评估。通过这些工具，我们可以及时发现并解决潜在的性能瓶颈。例如，利用 Criterion 对关键函数进行基准测试，就是一种非常有效的性能调优手段。
use criterion::{black_box, criterion_group, criterion_main, Criterion};
fn process_data(data: &[u8]) -> usize {
// Simulate data processing
data.len()
}
fn benchmark(c: &mut Criterion) {
c.bench_function("process_data", |b| {
b.iter(|| process_data(black_box(&[1, 2, 3, 4, 5])))
});
}
criterion_group!(benches, benchmark);
criterion_main!(benches);为了持续享受 Rust 和 Axum 带来的性能优势，保持 Rust 编译器及其依赖项的更新至关重要。这样，您的项目就能不断从最新的性能优化和特性改进中获益。
总结：构建高性能 REST API 的 Rust 与 Axum 之道
本文全面探讨了利用 Rust 和 Axum 构建高性能 REST API 的精髓。我们从框架的核心功能出发，逐步深入到路由处理、错误管理、数据库集成以及中间件等进阶话题。同时，我们还分享了一系列提升 API 性能的有效策略。
感谢阅读！
原文链接：https://www.twilio.com/en-us/blog/build-high-performance-rest-apis-rust-axum
同话题下的热门内容
内容关键字