項目架構(gòu)

該項目采用清潔架構(gòu)原則，強調(diào)關(guān)注點分離，確保框架、數(shù)據(jù)庫和其他服務(wù)的獨立性。這種設(shè)計使核心業(yè)務(wù)邏輯獨立于外部服務(wù)，便于測試和維護，同時也能在需要時替換外部依賴。

項目結(jié)構(gòu)

項目的主要組成部分包括：

• src：包含主應(yīng)用程序代碼。

使用的技術(shù)棧

• Axum：用于構(gòu)建 Web 服務(wù)的 Rust 框架。
• SQLx：異步 SQL 數(shù)據(jù)庫工具，支持 PostgreSQL。
• PostgreSQL：關(guān)系型數(shù)據(jù)庫。
• Redis：用于緩存和會話管理的 NoSQL 數(shù)據(jù)庫。
• JWT：實現(xiàn)無狀態(tài)的身份驗證和授權(quán)。

跨源資源共享（CORS）

項目中的 CORS 配置允許任何來源、任何方法和任何標(biāo)頭。您可以根據(jù)需求自定義這些設(shè)置，以確保安全性和靈活性。

REST API 端點

公共端點

身份驗證

• 登錄：POST /v1/auth/login

用戶

• 列出用戶：GET /v1/users

賬戶

• 列出賬戶：GET /v1/accounts

交易

• 轉(zhuǎn)賬：POST /v1/transactions/transfer

API 錯誤處理

錯誤響應(yīng)格式

所有錯誤響應(yīng)均采用結(jié)構(gòu)化格式，確保一致性和清晰度。其字段包括：

• 狀態(tài)：HTTP 狀態(tài)碼（如 404、422）。
• errors：包含詳細錯誤信息的數(shù)組。

每個錯誤條目可能包含以下字段：

• code（可選）：唯一錯誤代碼（如 user_not_found）。
• kind（可選）：錯誤類型（如 resource_not_found）。
• message（必填）：簡短的錯誤描述。
• description（可選）：詳細的錯誤描述。
• detail（可選）：與錯誤相關(guān)的附加信息。
• 原因（可選）：錯誤的原因。
• instance（可選）：導(dǎo)致錯誤的請求 URI。
• trace_id（可選）：用于日志追蹤的標(biāo)識符。
• timestamp（必填）：錯誤發(fā)生的時間。
• help（可選）：解決錯誤的指導(dǎo)信息。
• doc_url（可選）：指向相關(guān)文檔的鏈接。

錯誤響應(yīng)示例

錯誤響應(yīng)可以包含多個錯誤條目，這對于用戶界面的清晰指引非常有幫助。此外，trace_id 字段便于在日志中追蹤錯誤。

配置和設(shè)置

服務(wù)配置

• SERVICE_HOST：服務(wù)運行的主機名或 IP 地址。

Redis 配置

• REDIS_HOST：Redis 服務(wù)器的主機名或 IP 地址。

PostgreSQL 配置

• POSTGRES_USER：PostgreSQL 數(shù)據(jù)庫的用戶名。

JWT 配置

• JWT_SECRET：用于簽名 JWT 的密鑰。

使用 JWT 進行身份驗證和授權(quán)

JWT 以其高效性和無狀態(tài)特性被廣泛用于身份驗證和授權(quán)。其優(yōu)點包括：

• 無需維護會話狀態(tài)，支持高并發(fā)請求。
• 自包含特性，減少數(shù)據(jù)庫查詢。

然而，JWT 的無狀態(tài)特性也帶來了一些挑戰(zhàn)，例如無法在令牌過期前撤銷令牌。為解決此問題，可以使用 Redis 維護服務(wù)器端黑名單，從而實現(xiàn)令牌的強制失效。

項目中實現(xiàn)了以下功能：

• 登錄、注銷、刷新和撤銷操作。
• 基于角色的授權(quán)。
• 生成和驗證訪問及刷新令牌。
• 設(shè)置令牌過期時間。
• 使用 Redis 實現(xiàn)令牌撤銷。

數(shù)據(jù)存儲與操作

使用 Redis 內(nèi)存存儲

Redis 用于緩存和會話管理，支持高效的數(shù)據(jù)存儲和檢索。

使用 PostgreSQL 和 SQLx

PostgreSQL 是一個功能強大的開源關(guān)系型數(shù)據(jù)庫，支持高級數(shù)據(jù)類型和性能優(yōu)化。SQLx 是一個異步的 Rust SQL 工具，支持編譯時查詢檢查，減少運行時錯誤。

項目中包括以下數(shù)據(jù)庫操作示例：

• 數(shù)據(jù)庫遷移：使用 SQLx 管理數(shù)據(jù)庫模式。
• 異步 CRUD 操作：支持創(chuàng)建、讀取、更新和刪除。
• 事務(wù)處理：適用于復(fù)雜的多步驟操作。

日志記錄

通過設(shè)置環(huán)境變量 RUST_LOG，可以指定服務(wù)啟動時的日志級別。

優(yōu)雅關(guān)機

Axum 支持優(yōu)雅關(guān)機，通過 with_graceful_shutdown 方法監(jiān)聽 SIGINT 和 SIGTERM 信號，確保服務(wù)安全關(guān)閉。

測試

數(shù)據(jù)庫隔離測試

每次測試前后都會設(shè)置和清理數(shù)據(jù)庫狀態(tài)，確保測試的獨立性。

按順序運行測試

測試按預(yù)定義順序執(zhí)行，避免依賴問題。

構(gòu)建與運行服務(wù)

開發(fā)模式

在開發(fā)模式下運行服務(wù)，便于調(diào)試和快速迭代。

發(fā)布模式

發(fā)布模式啟用編譯器優(yōu)化，顯著提升性能并減小二進制文件大小。建議在生產(chǎn)環(huán)境中使用發(fā)布模式運行服務(wù)。

使用 Docker 部署

運行 PostgreSQL 和 Redis 服務(wù)

通過 Docker 容器運行數(shù)據(jù)庫服務(wù)，簡化部署流程。

構(gòu)建 API 服務(wù)

使用 Rust 官方鏡像構(gòu)建 API 服務(wù)。

全棧部署

通過 Docker Compose 部署 API、PostgreSQL 和 Redis 服務(wù)的完整棧。

持續(xù)集成（CI）

項目使用 GitHub Actions 實現(xiàn)持續(xù)集成，自動化以下任務(wù)：

• 檢查安全漏洞和許可證。
• 檢查代碼格式。
• 發(fā)現(xiàn)常見錯誤并優(yōu)化代碼。
• 運行測試。
• 構(gòu)建應(yīng)用程序。

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

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

#你可能也喜歡這些API文章!

使用NestJS和Prisma構(gòu)建REST API：身份驗證

深入解析API網(wǎng)關(guān)策略：認證、授權(quán)、安全、流量處理與可觀測性

深入解析 DeepSeek API 密鑰：獲取、使用與最佳實踐

使用 FastAPI 和 RabbitMQ 構(gòu)建端到端微服務(wù)：綜合指南

DeepSeek+dify 工作流應(yīng)用,自然語言查詢數(shù)據(jù)庫信息并展示

API 認證：JWT、OAuth 與 API KEY對比

微信API接口調(diào)用憑證+Access token泄露

WebSocket和REST的區(qū)別：功能、適用范圍、性能與示例解析

如何使用 DeepSeek 構(gòu)建 AI Agent：終極指南