使用 Axum 框架在 Rust 中入门 REST API Web 服务开发...

GitHub：https://github.com/sheroz/axum-rest-api-sample

Rust 近年来的受欢迎程度持续攀升。作为一种功能强大且经过验证的编程语言，Rust 提供了高效、安全的软件开发解决方案，同时避免了垃圾回收器的开销。随着 Rust 2024 版本的发布，这种趋势预计将进一步加速，巩固其在技术领域的地位。

Rust 在开发任务关键型 Web 后端组件或系统时表现尤为出色，尤其是在需要高效性能、一致资源消耗和强大安全性的场景中。然而，对于新手开发者来说，学习 Rust 及其不断扩展的生态系统可能需要一定的时间和努力。

本文将通过一个示例项目，演示如何使用 Axum 框架、JSON Web Tokens（JWT）、SQLx、PostgreSQL 和 Redis 构建一个 REST API Web 服务。该项目支持基于 JWT 的身份验证与授权、异步数据库操作、账户间转账示例，以及结构化的 API 错误处理。

项目架构

该项目采用清洁架构原则，强调关注点分离，确保框架、数据库和其他服务的独立性。这种设计使核心业务逻辑独立于外部服务，便于测试和维护，同时也能在需要时替换外部依赖。

项目结构

项目的主要组成部分包括：

src：包含主应用程序代码。

使用的技术栈

Axum：用于构建 Web 服务的 Rust 框架。
SQLx：异步 SQL 数据库工具，支持 PostgreSQL。
PostgreSQL：关系型数据库。
Redis：用于缓存和会话管理的 NoSQL 数据库。
JWT：实现无状态的身份验证和授权。

跨源资源共享（CORS）

项目中的 CORS 配置允许任何来源、任何方法和任何标头。您可以根据需求自定义这些设置，以确保安全性和灵活性。

REST API 端点

公共端点

身份验证

用户

列出用户：GET /v1/users

账户

列出账户：GET /v1/accounts

交易

转账：POST /v1/transactions/transfer

API 错误处理

错误响应格式

所有错误响应均采用结构化格式，确保一致性和清晰度。其字段包括：

状态：HTTP 状态码（如 404、422）。
errors：包含详细错误信息的数组。

每个错误条目可能包含以下字段：

code（可选）：唯一错误代码（如 user_not_found）。
kind（可选）：错误类型（如 resource_not_found）。
message（必填）：简短的错误描述。
description（可选）：详细的错误描述。
detail（可选）：与错误相关的附加信息。
原因（可选）：错误的原因。
instance（可选）：导致错误的请求 URI。
trace_id（可选）：用于日志追踪的标识符。
timestamp（必填）：错误发生的时间。
help（可选）：解决错误的指导信息。
doc_url（可选）：指向相关文档的链接。

错误响应示例

错误响应可以包含多个错误条目，这对于用户界面的清晰指引非常有帮助。此外，trace_id 字段便于在日志中追踪错误。

配置和设置

服务配置

SERVICE_HOST：服务运行的主机名或 IP 地址。

Redis 配置

REDIS_HOST：Redis 服务器的主机名或 IP 地址。

PostgreSQL 配置

POSTGRES_USER：PostgreSQL 数据库的用户名。

JWT 配置

JWT_SECRET：用于签名 JWT 的密钥。

使用 JWT 进行身份验证和授权

JWT 以其高效性和无状态特性被广泛用于身份验证和授权。其优点包括：

无需维护会话状态，支持高并发请求。
自包含特性，减少数据库查询。

然而，JWT 的无状态特性也带来了一些挑战，例如无法在令牌过期前撤销令牌。为解决此问题，可以使用 Redis 维护服务器端黑名单，从而实现令牌的强制失效。

项目中实现了以下功能：

登录、注销、刷新和撤销操作。
基于角色的授权。
生成和验证访问及刷新令牌。
设置令牌过期时间。
使用 Redis 实现令牌撤销。

数据存储与操作

使用 Redis 内存存储

Redis 用于缓存和会话管理，支持高效的数据存储和检索。

使用 PostgreSQL 和 SQLx

PostgreSQL 是一个功能强大的开源关系型数据库，支持高级数据类型和性能优化。SQLx 是一个异步的 Rust SQL 工具，支持编译时查询检查，减少运行时错误。

项目中包括以下数据库操作示例：

数据库迁移：使用 SQLx 管理数据库模式。
异步 CRUD 操作：支持创建、读取、更新和删除。
事务处理：适用于复杂的多步骤操作。

日志记录

通过设置环境变量 RUST_LOG，可以指定服务启动时的日志级别。

优雅关机

Axum 支持优雅关机，通过 with_graceful_shutdown 方法监听 SIGINT 和 SIGTERM 信号，确保服务安全关闭。

测试

数据库隔离测试

每次测试前后都会设置和清理数据库状态，确保测试的独立性。

按顺序运行测试

测试按预定义顺序执行，避免依赖问题。

构建与运行服务

开发模式

在开发模式下运行服务，便于调试和快速迭代。

发布模式

发布模式启用编译器优化，显著提升性能并减小二进制文件大小。建议在生产环境中使用发布模式运行服务。

使用 Docker 部署

运行 PostgreSQL 和 Redis 服务

通过 Docker 容器运行数据库服务，简化部署流程。

构建 API 服务

使用 Rust 官方镜像构建 API 服务。

全栈部署

通过 Docker Compose 部署 API、PostgreSQL 和 Redis 服务的完整栈。

持续集成（CI）

项目使用 GitHub Actions 实现持续集成，自动化以下任务：

检查安全漏洞和许可证。
检查代码格式。
发现常见错误并优化代码。
运行测试。
构建应用程序。

源代码可以在 GitHub 上找到：https://github.com/sheroz/axum-rest-api-sample

原文链接: http://sheroz.com/pages/blog/rust-axum-rest-api-postgres-redis-jwt-docker.html