🚀 從零開始：打造基於 Laravel、Sanctum、Redis Queue 與 GitHub Actions 的事件驅動 WMS 原型
哈囉，各位 Laravel 同伴們！ 👋
相信許多開發者在規劃中大型系統時，都會面臨如何建構一個既穩定、又具擴展性的後端架構。今天，我們要來探討一個實戰專案：一個事件驅動 (Event-Driven) 的倉儲管理系統 (WMS) 原型。這個專案結合了 Laravel 框架的強大功能，搭配 Laravel Sanctum 進行 API 認證、Redis Queue 處理非同步任務，並透過 GitHub Actions 實現 CI/CD 自動化流程。
這篇文章將帶您從專案的核心概念出發，一步步了解其架構設計，並提供詳細的環境建置與啟動教學，讓您能輕鬆地將這個原型運行起來，作為未來專案的參考基石。
💡 為什麼選擇事件驅動與佇列？
在倉儲管理這類業務流程複雜、操作頻繁的系統中，單純的同步處理往往會造成性能瓶頸，甚至影響使用者體驗。想像一下，當一筆大訂單出貨時，需要同時更新庫存、產生出貨單、記錄審計日誌並發送通知，如果這些都同步執行，前端介面可能會卡頓好幾秒。
這時候，事件驅動架構 就派上用場了！
- 事件驅動 (Event-Driven)：當系統中發生某個「事件」（例如：「入庫單已完成」、「出庫單已發貨」），我們不直接執行後續所有動作，而是發出一個「事件通知」。相關的「監聽器 (Listeners)」會接收到這些事件，並各自處理對應的業務邏輯。
- 優點：解耦 (Decoupling)、高擴展性 (Scalability)、高內聚 (High Cohesion)，使程式碼更容易維護與測試。
- 非同步佇列 (Asynchronous Queue)：搭配事件驅動，將那些耗時且不影響主流程響應的任務（例如：發送電子郵件、生成報告、複雜的庫存調整）推送到佇列中，由後台的 Worker 處理。
- 優點：提高系統的響應速度、確保流量尖峰時的穩定性、避免因單一任務失敗而影響整個流程。
在這個 WMS 原型中，我們大量運用了 Laravel 內建的事件 (Events)、監聽器 (Listeners) 和佇列 (Queue) 機制，並搭配 Redis 作為佇列驅動，讓整個系統更加流暢且可靠。
🛠️ 專案核心技術堆疊
這個 WMS 原型整合了多項業界常用的技術，旨在提供一個企業級應用開發的良好起點：
- 後端框架：Laravel 10.x - PHP 生態系中功能最完整、開發效率最高的框架。
- API 認證：Laravel Sanctum - 輕量級 API Token 認證，特別適合 SPA (Single Page Application) 或行動應用程式。
- 非同步處理：Redis Queue - 高效能的記憶體資料庫 Redis 作為 Laravel Queue 的驅動，實現訊息佇列。
- 權限管理：Spatie Laravel Permission - 強大的 RBAC (Role-Based Access Control) 套件，輕鬆實現角色與權限的細緻控制。我們預設了
Super Admin、Manager、Picker、Receiver等角色。 - 資料庫：MySQL - 穩定可靠的關聯式資料庫。
- 容器化：Docker & Docker Compose - 提供一致且隔離的開發環境，降低環境配置的複雜度。
- 持續整合/部署：GitHub Actions - 自動化測試與部署驗證流程，確保程式碼品質與可靠性。
- 審計日誌：透過自定義事件監聽器，自動記錄重要操作，方便追蹤與審核。
🏗️ 專案架構概覽 (Service/Repository 模式)
為了保持程式碼的清晰度與可維護性，本專案採用了常見的 Service 層/Repository 層模式：
- Controller (控制器)：負責接收 HTTP 請求、驗證輸入，並協調 Service 層處理業務邏輯。保持精簡。
- Service (服務層)：包含核心業務邏輯，處理跨多個 Repository 的操作、觸發事件等。這是業務規則的主要實現地點。
- Repository (資料庫操作層)：負責與資料庫進行互動，提供 CRUD (新增、讀取、更新、刪除) 等操作。它抽象了資料存取細節，讓 Service 層無需關心底層資料庫實現。
- Events & Listeners (事件與監聽器)：解耦業務流程，例如：
- 當入庫單完成時 (
InboundOrderCompleted事件)，可以同時由多個監聽器處理：更新庫存、發送通知、記錄審計日誌。
- 當入庫單完成時 (
- Queues (佇列)：將耗時的監聽器任務推送到佇列中處理，避免阻塞主應用程式。
這種分層設計不僅讓程式碼結構更清晰，也大大提升了單元測試與整合測試的便利性。
🚀 專案快速啟動：三步驟搞定！
為了讓大家能快速體驗這個 WMS 原型，我們提供了完整的 Docker 化環境。請確保您的電腦已安裝 Docker 和 Docker Compose。
-
複製專案到本地：
首先，將專案從 GitHub 複製到您的開發環境。
Bashgit clone https://github.com/BpsEason/laravel-wms-system.git # 請將 BpsEason 替換為您的 GitHub 用戶名 cd laravel-wms-system -
配置環境變數：
建立 .env 檔案，這是 Laravel 專案配置的關鍵。
Bashcp .env.example .env這個檔案包含了資料庫連線、Redis 設定、應用程式金鑰等重要資訊。
-
啟動 Docker 服務並初始化專案：
這一步驟將啟動所有必要的容器 (Nginx, PHP-FPM, MySQL, Redis)，並安裝 Laravel 依賴、執行資料庫遷移與填充。
Bash# 啟動並建置 Docker 容器 docker-compose up -d --build # 進入 app 容器執行 Laravel 初始化指令 docker-compose exec app composer install # 安裝 Composer 依賴 docker-compose exec app php artisan key:generate # 生成應用程式金鑰 docker-compose exec app php artisan vendor:publish --provider="Spatie\\Permission\\PermissionServiceProvider" --tag=migrations # 發布 Spatie Permission 的資料庫遷移 docker-compose exec app php artisan migrate --seed # 執行資料庫遷移並填充預設資料 (包含角色權限與管理員帳號)大功告成！🎉
現在，您的 Laravel WMS API 已經在
http://localhost上運行了。
測試帳號 (預設密碼皆為 password)：
- 管理員 (Super Admin)：
admin@example.com - 倉儲經理 (Manager)：
manager@example.com - 揀貨員 (Picker)：
picker@example.com - 收貨員 (Receiver)：
receiver@example.com
您可以試著使用這些帳號，搭配 Postman 或其他 API 工具進行登入和測試。
🔍 API 簡要說明
本專案提供了以下核心功能模組的 API 端點，並已實施 RBAC 權限控制：
- 產品管理：新增、查詢、更新產品資訊。
- 倉庫管理：管理倉庫的基本資訊。
- 儲位管理：定義倉庫內的具體儲位。
- 庫存查詢：查詢各產品在不同儲位的庫存量。
- 入庫管理：創建入庫單、處理收貨流程。
- 出庫管理：創建出庫單、處理揀貨與出貨流程。
- 認證：用戶註冊、登入 (Sanctum Token)。
（如果您有自動生成 API 文件，例如使用 Scribe 或 Swagger，建議在這裡引導讀者到相關路徑，例如 http://localhost/api/documentation。）
📈 持續整合 (CI/CD)
這個專案預設配置了 GitHub Actions 工作流程 (.github/workflows/main.yml)。這意味著：
- 當您將程式碼推送到 GitHub 倉庫時，Actions 會自動觸發，執行測試。
- 這有助於確保每次程式碼變動都能維持一定的品質，即時發現問題。
您可以在您的 GitHub 倉庫的 "Actions" 分頁中查看 CI/CD 的執行狀態。
結語
這個 Laravel WMS 原型提供了一個現代化、高效率的後端系統範例。透過事件驅動與佇列的應用，您可以有效提升系統的響應能力和可擴展性。無論您是想學習 Laravel 的進階應用、理解事件驅動架構，還是作為一個新專案的起點，這個原型都能提供寶貴的參考價值。
希望這篇文章能幫助您更好地理解並運用這些技術。如果您有任何問題或建議，歡迎在下方留言交流，或是到 GitHub 專案頁面開立 Issue！
Happy Coding! 🚀
沒有留言:
張貼留言