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

GitHub： Rust 近年来的受欢迎程度持续攀升。作为一种功能强大且经过验证的编程语言，Rust 提供了高效、安全的软件开发解决方案，同时避免了垃圾回收器的开销。随着 Rust 2024 版本的发布，这种趋势预计将进一步加速，巩固其在技术领域的地位。 Rust 在开发任务关键型 Web 后端组件或系统时表现尤为出色，尤其是在需要高效性能、一致资源消耗和强大安全性的场景中。然而，对于新手服务。该项目支持基于 JWT 的身份验证与授权、异步数据库操作、账户间转账示例，以及结构化的 API 错误处理。 —

项目架构 该项目采用清洁架构原则，强调关注点分离，确保框架、数据库和其他服务的独立性。这种设计使核心业务逻辑独立于外部服务，便于测试和维护，同时也能在需要时替换外部依赖。 — ## 项目结构 项目的主要组成部分包括： – src：包含主应用程序代码。 — ## 使用的技术栈 – Axum：用于构建 Web 服务的 Rust 框架。 – SQLx：异步 SQL 数据库工具，支持 PostgreSQL。 – PostgreSQL：关系型数据库。 – Redis：用于缓存和会话管理的 NoSQL 数据库。 – JWT：实现无状态的身份验证和授权。 — ## 跨源资源共享（CORS） 项目中的 CORS 配置允许任何来源、任何方法和任何标头。您可以根据需求自定义这些设置，以确保安全性和灵活性。 — ## REST API 端点 ### 公共端点 #### 身份验证 – 登录：POST /v1/auth/login #### 用户 – 列出用户：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 管理数据库模式。 – 异步 创建、读取、更新和删除。 – 事务处理：适用于复杂的多步骤操作。 — ## 日志记录 通过设置环境变量 RUST_LOG，可以指定服务启动时的日志级别。 — ## 优雅关机 Axum 支持优雅关机，通过 with_graceful_shutdown 方法监听 SIGINT 和 SIGTERM 信号，确保服务安全关闭。 — ## 测试 ### 数据库隔离测试 每次测试前后都会设置和清理数据库状态，确保测试的独立性。 ### 按顺序运行测试 测试按预定义顺序执行，避免依赖问题。 — ## 构建与运行服务 ### 开发模式 在开发模式下运行服务，便于调试和快速迭代。 ### 发布模式 发布模式启用编译器优化，显著提升性能并减小二进制文件大小。建议在生产环境中使用发布模式运行服务。 — ## 使用 Docker 部署 ### 运行 PostgreSQL 和 Redis 服务 通过 Docker 容器运行数据库服务，简化部署流程。 ### 构建 API 服务 使用 Rust 官方镜像代码格式。 – 发现常见错误并优化代码。 – 运行测试。 – 构建应用程序。 — 源代码可以在 GitHub 上找到： 原文链接: http://sheroz.com/pages/blog/rust-axum-rest-api-postgres-redis-jwt-docker.html