PHP/Laravel 完全指南 - Bobo 的學思山丘

PHP/Laravel 完全指南：從這裡開始你自己的旅程

Tue, 10 Jun 2025 00:00:00 GMT

十五章，從 PHP 基礎語法走到 Production 部署，你已經用 Laravel 12 從零打造了一個完整的團購平台。揪好買其實不只是個練習專案，它幾乎把現代 Web 應用開發的每個核心面向都摸過一遍： - 路由與控制器、資料庫遷移與 Eloquent ORM - 認證授權、表單驗證、檔案上傳 - 佇列任務、Event／Listener、Notification - API 設計、後台管理、自動化測試 - 一直到部署上線這些不是教科書上的範例，而是你在任何 Laravel 專案中都會用到的實戰技能。但說實話，這本書能涵蓋的只是 Laravel 生態系的冰山一角。Laravel 之所以強大，框架本身設計得好只是一半，真正關鍵的是它背後有一整個生態系在支撐：Nova 給你企業級後台、Vapor 讓你跑 Serverless、Pennant 做 Feature Flag、Pulse 做即時效能監控。加上 Laracasts 這個可能是全世界最好的程式教學平台，你的學習資源幾乎是用不完的。這最後一章，我們要做三件事：回顧這 15 章到底學了什麼、看看揪好買還能往哪些方向擴展、然後幫你畫一張接下來的學習路線圖。你已經有了穩固的基礎，接下來的路，你可以自己決定怎麼走。 ## Laravel 完全指南回顧：15 章學到了什麼先用一張表把整趟旅程看清楚： | 章 | 主題 | 你學會的核心技能 | | --- | ------------------ | ----------------------------------------------- | | 1 | PHP 快速入門 | PHP 8.4+ 型別系統、Enum、Match、Composer | | 2 | Laravel 起手式 | 安裝、目錄結構、Route、Blade、Artisan | | 3 | Request Lifecycle | Service Container、DI、Middleware、Facade | | 4 | Eloquent ORM | Migration、Model、Relationship、Factory | | 5 | Blade + Livewire | Component、Livewire 即時互動、Alpine.js | | 6 | 認證與授權 | Starter Kit、Gate、Policy、Role Enum | | 7 | 表單驗證與檔案上傳 | Form Request、Validation Rules、Storage | | 8 | 跟團與成團邏輯 | Session、業務邏輯設計、Cache、狀態機 | | 9 | 訂單與金流 | Stripe Cashier、Webhook、Database Transaction | | 10 | Queue 與 Event | Job、Event/Listener、Notification、Mail | | 11 | RESTful API | Sanctum Token、API Resource、Rate Limiting | | 12 | 後台管理 | Filament 4、N+1 優化、Query Scopes、Debugbar | | 13 | 測試 | Pest、HTTP Tests、Mock/Fake、GitHub Actions CI | | 14 | 部署 | Forge、Docker、Octane、Cloud Run、Zero-Downtime | | 15 | 路線圖 | 你正在讀的這一章 | 從語言基礎到 Production 部署，這是一條完整的學習路徑。你不再是「想學 Laravel 的人」，你已經是「用 Laravel 建過完整專案的開發者」了。 ## 揪好買的完成功能清單讓我們盤點一下揪好買目前有什麼： **使用者系統** - ✅ 註冊、登入、登出、忘記密碼 - ✅ Email 驗證 - ✅ 角色系統：一般會員 / 開團主 / 管理員 **團購功能** - ✅ 開團（表單驗證 + 圖片上傳） - ✅ 跟團（+1、選數量、即時人數更新） - ✅ 成團判斷（最低人數 + 截止時間） - ✅ 團購列表（即時搜尋、篩選、排序、分頁） **金流與訂單** - ✅ Stripe 串接（Checkout Session + Webhook） - ✅ 訂單建立與狀態管理 - ✅ 成團後統一收款 **通知系統** - ✅ 成團確認 Email - ✅ 站內通知（database notification） - ✅ 背景佇列處理 **API** - ✅ RESTful API（團購列表、跟團、訂單查詢） - ✅ Sanctum Token 認證 - ✅ Rate Limiting **管理後台** - ✅ Filament 管理員後台 - ✅ 開團主儀表板 **DevOps** - ✅ Pest 測試套件 - ✅ GitHub Actions CI - ✅ Docker 容器化 - ✅ Production 部署這已經是一個具備核心功能的 MVP（最小可行產品）了。 ## 功能擴展方向：搜尋、推薦、多語系揪好買還有很多可以做的。以下是幾個值得考慮的方向： ### 全文搜尋目前的搜尋用 `LIKE %keyword%`，資料量大時效能很差。升級方案： - **Laravel Scout + Meilisearch**，全文搜尋引擎，支援中文斷詞、模糊搜尋、過濾排序 - `composer require laravel/scout` + `composer require meilisearch/meilisearch-php` - Model 加上 `use Searchable;`，幾行設定就能讓搜尋體驗飛起來 ### 推薦系統「你可能也想跟的團」，根據使用者的跟團歷史推薦相似的團購： - 簡單版：同品類的熱門團購（SQL 就能做） - 進階版：協同過濾（Collaborative Filtering），可以用 Python microservice 處理 ### 多語系（i18n）讓揪好買支援繁中/英文切換： - Laravel 內建 `resources/lang/` 翻譯檔 - `__('messages.welcome')` helper - Middleware 偵測使用者語言偏好 ### 即時通訊開團主和跟團者之間的即時聊天： - **Laravel Reverb**，Laravel 官方的 WebSocket 伺服器 - 搭配 Livewire 或 Echo（JavaScript）做即時更新 - 適合討論團購細節、配送安排 ### 多租戶（Multi-tenancy）讓不同公司/社區各自有獨立的揪好買實例： - **stancl/tenancy** 套件 - 每個租戶有獨立的資料庫或共用資料庫加 tenant_id - 適合 B2B SaaS 模式 ## LINE 整合深化：從概念到實作 [第十一章](/blog/laravel-guide-api-sanctum-rest/)我們留了一個 LINE Bot 的概念性範例。如果要真正做起來： ### LINE Messaging API ```bash composer require linecorp/line-bot-sdk ``` 核心流程： 1. 在 LINE Developers Console 建立 Provider 和 Channel 2. 設定 Webhook URL 指向你的 Laravel API endpoint 3. 使用者在 LINE 群組裡輸入「!開團辦公室零食箱」 4. 你的 webhook controller 解析指令、呼叫 GroupBuy service 5. 透過 LINE API 回覆結果 ### LINE LIFF（LINE Frontend Framework）更進一步，你可以在 LINE 裡嵌入 Web 頁面： - 使用者在 LINE 裡直接打開揪好買的團購詳情頁 - 不需要跳轉到瀏覽器，體驗更流暢 - 搭配 Sanctum API 做認證 ### LINE Pay 台灣使用者最常用的行動支付之一： - 可以取代或補充 Stripe - 需要另外串接 LINE Pay API（目前 Cashier 不支援，需自己整合） ## Laravel 生態系工具推薦 Laravel 的生態系大到你可能不知道從哪裡開始。以下是我認為**最值得認識**的工具： ### 開發工具 | 工具 | 用途 | 一句話說明 | | ---------------------- | ------------ | --------------------------------------------------- | | **Laravel Herd** | 本地開發環境 | 一鍵安裝 PHP + Nginx + 多版本切換（macOS/Windows） | | **Laravel Pint** | 程式碼格式化 | PHP 的 Prettier，Laravel 12 內建 | | **Laravel IDE Helper** | IDE 支援 | 幫 PhpStorm/VS Code 理解 Facade 和 Model 的自動補全 | | **Laravel Debugbar** | 效能偵測 | [第 12 章](/blog/laravel-guide-admin-filament-advanced-queries/)用過，開發階段必裝 | ### 官方套件 | 套件 | 用途 | 何時需要 | | ------------- | -------------------- | ---------------------------------- | | **Sanctum** | API Token 認證 | 你已經會了（[第 11 章](/blog/laravel-guide-api-sanctum-rest/)） | | **Cashier** | 金流整合 | 你已經會了（[第 9 章](/blog/laravel-guide-orders-stripe-cashier/)） | | **Scout** | 全文搜尋 | 搜尋功能需要升級時 | | **Horizon** | Queue 監控 Dashboard | Redis Queue 在 production 跑的時候 | | **Telescope** | Debug Dashboard | 開發階段觀察 request、query、job | | **Reverb** | WebSocket 伺服器 | 即時通訊、即時通知 | | **Pennant** | Feature Flags | A/B 測試、漸進式上線新功能 | | **Pulse** | 即時效能監控 | Production 觀察應用健康狀態 | ## Nova、Vapor、Pennant、Pulse 簡介這四個是 Laravel 官方的商業產品（需要付費授權），適合有預算的團隊： ### Laravel Nova（一次性授權，$99 / $199 / $299 per site）企業級後台管理面板。比 Filament 功能更完整，但需要付費： - 更多內建欄位類型和 Action - Metrics Dashboard 更豐富 - 權限管理更細緻 - 適合：中大型團隊、有預算、需要企業級後台 ### Laravel Vapor（$39/mo 起，另計 AWS 費用） Serverless 部署平台，底層跑在 AWS Lambda： - 自動擴縮容（Auto-scaling），流量大時自動加機器 - 不用管伺服器、不用管 Nginx - 適合：流量波動大（例如團購開團瞬間流量暴增）、有 AWS 預算的團隊 ### Laravel Pennant Feature Flag 管理： - 控制功能對哪些使用者可見（例如：先讓 10% 使用者看到新 UI） - A/B 測試 - 漸進式上線，降低風險 ### Laravel Pulse 即時應用程式效能監控： - 顯示 slow queries、slow requests、exceptions - Queue 和 Cache 使用狀態 - 比 Debugbar 更適合 production 使用 ## 社群與學習資源 ### Laracasts 如果你只能訂閱一個學習平台，選 Laracasts。Jeffrey Way 的教學品質是業界標竿，涵蓋 Laravel、PHP、Vue.js、Testing 等主題。大量免費內容可以先看看合不合口味。 ### Laravel News Laravel 生態系的新聞中心，每天更新套件推薦、教學文章、版本發布。訂閱 Newsletter 就能掌握最新動態。 ### Laravel Daily Povilas Korop 經營的 YouTube 頻道和部落格，專注實戰技巧和最佳實踐。影片短而精準，適合通勤時看。 ### 中文社群 - **Laravel 台灣** Facebook 社團，台灣最活躍的 Laravel 中文社群 - **LearnKu Laravel 中國**，簡體中文，但很多文章品質很高 - **PHP 也有 Day** 社群，台灣 PHP 開發者聚會 ### 推薦書籍 - _Laravel Up & Running_（Matt Stauffer），最完整的 Laravel 參考書 - _PHP: The Right Way_，免費線上書，現代 PHP 最佳實踐 - _Refactoring to Collections_（Adam Wathan），用 Collection 取代迴圈，提升程式碼品質 ## PHP 生態現況與未來展望 2026 年的 PHP 生態比以往任何時候都更健康： - **PHP 8.5** 已穩定發布，pipe operator（`|>`）、原生 URI 擴充、clone with 屬性覆寫讓語法更精煉（Property Hooks 和 Asymmetric Visibility 是 PHP 8.4 引進的） - **Laravel 拿到 $57M 融資**，代表商業生態系在成長 - **Packagist** 超過 45 萬個套件，生態系穩定且持續壯大 - **效能持續改善**，JIT 編譯器每個版本都在進步，搭配 Octane 更是翻倍 - **WordPress 依然佔全球 42.6% 的網站**，PHP 的市場不會消失 PHP 不是最潮的語言，也不需要是。它是最務實的選擇之一。 ### 值得關注的趨勢 - **Laravel Cloud**，Laravel 官方的全託管部署平台，已於 2025 年 2 月隨 Laravel 12 正式上線（Sandbox $0／Production $20/mo／Business $200/mo 起，另計用量） - **PHP 原生非同步**，Fibers 和 Revolt event loop 讓 PHP 能處理高並發場景 - **AI 整合**，Laravel Prompts、OpenAI 套件，PHP 也能做 AI 應用 ## 小結：從這裡開始你自己的旅程十五章、一個完整的團購平台、從 PHP 語法到 Production 部署。你已經走過了 Laravel 的完整學習路徑。但更重要的是，這趟下來你學到的其實不只 Laravel。你還學到了： - **框架思維**，不重複造輪子，善用生態系 - **分層架構**，Route → Controller → Service → Model，各司其職 - **測試文化**，有測試的程式碼才有信心重構和部署 - **DevOps 基礎**，CI/CD、容器化、環境管理這些技能是通用的。不管你將來用 Laravel、Rails、Django 還是 NestJS，底層的思維方式是一樣的。 ### 你的下一步根據你的方向，我推薦的學習路線： **想深入 Laravel？** → Laracasts 進階課程 → Laravel Horizon → Laravel Reverb → 讀 Laravel 原始碼 **想做自己的 SaaS？** → 加入 Stripe 訂閱制（Cashier 支援）→ Multi-tenancy → Vapor 部署 **想找 Laravel 相關工作？** → GitHub Profile 放上揪好買專案 → 寫技術部落格分享學習心得 → 加入 Laravel 台灣社群 **想把揪好買上線？** → 加入 LINE 整合 → 接 LINE Pay → 找幾個朋友當 Beta 使用者 → 真的拿去開團試試看不管你選哪條路，記住一件事：**最好的學習方式就是持續建造**。不要只看教學，要動手寫。寫出 Bug，修掉它。看到新套件，裝上去試試。遇到問題，去社群問。揪好買是你的起點，不是終點。祝你寫程式愉快。🚀

部署上線：從 Laravel Forge 到容器化的三條路

Tue, 03 Jun 2025 00:00:00 GMT

程式寫好了、測試通過了、功能也確認沒問題了。然後呢？「部署」這件事聽起來很簡單——把程式碼放到伺服器上就好了嘛——但實際操作起來，從環境設定、效能調校、SSL 憑證、到零停機部署，每一步都有它的眉角。選錯部署方式，你可能花更多時間在維運上，而不是開發新功能。 Laravel 生態系提供了三條截然不同的部署路線：Laravel Forge 讓你在 DigitalOcean 或 AWS 上一鍵部署，幾乎不用碰伺服器設定；Docker 容器化讓你的應用在任何環境都能一致運行；Cloud Run 和 Fly.io 這類雲端平台則讓你連伺服器都不用管。三條路各有優缺點，適合不同階段和不同規模的團隊。這一章我們會走過上線前的必要準備——Config Cache、Route Cache、Octane 加速——然後實際帶你用兩種方式部署揪好買：Forge 的一鍵流程和 Docker 的容器化流程。不管你最後選哪條路，上線前該做的事情都一樣，而這些知識會讓你省下無數個半夜被叫起來修 Bug 的夜晚。 ## Laravel 部署上線前的 Production 設定不管你選哪條部署路線，上線前有一份 checklist 是每個 Laravel 專案都必須走過的。這些設定漏掉任何一項，輕則效能低落，重則資料外洩。 ### 環境變數核心設定打開你的 `.env`（或部署平台的環境變數設定），確認這三項： ```bash APP_ENV=production APP_DEBUG=false APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` `APP_ENV=production` 告訴 Laravel 現在是正式環境，會影響一些行為——例如錯誤頁面不會顯示堆疊追蹤、某些開發工具會被停用。`APP_DEBUG=false` **絕對不能忘記**——如果設成 `true`，使用者在瀏覽器裡就能看到你的完整錯誤訊息，包含資料庫密碼、API Key、程式碼路徑，等於把系統的所有弱點攤在陽光下。 `APP_KEY` 是 Laravel 用來加密 Session、Cookie、Eloquent 加密欄位的密鑰。如果你在部署時沒有設定，所有加密功能都會失效。在新環境第一次部署時執行： ```bash php artisan key:generate ``` > **警告：** 正式環境的 `APP_KEY` 一旦設定就不要隨意更換。換了之後，所有舊的加密資料（包含使用者的 Session）都會失效，等同於強制所有使用者重新登入。 ### 上線前完整 Checklist ```bash # 1. 環境設定 APP_ENV=production APP_DEBUG=false APP_KEY=base64:... (已設定) # 2. 資料庫 DB_CONNECTION=mysql # 或 pgsql DB_HOST=your-production-db # 不要用 127.0.0.1，除非 DB 在同一台機器 DB_DATABASE=jiuhaobuy DB_USERNAME=jiuhaobuy_user # 不要用 root DB_PASSWORD=strong-password # 至少 20 字元 # 3. Cache & Session CACHE_STORE=redis # 正式環境用 Redis SESSION_DRIVER=redis QUEUE_CONNECTION=redis # 4. Mail（正式環境不要用 log） MAIL_MAILER=smtp MAIL_HOST=smtp.mailgun.org # 或 SES、Postmark # 5. URL APP_URL=https://jiuhaobuy.com ``` ### 執行 Migration 在正式環境執行 migration 時，加上 `--force` flag——因為 Laravel 在 production 環境會要求確認： ```bash php artisan migrate --force ``` **最佳做法：** 不要直接 SSH 進伺服器手動跑 migration。把它放進你的部署腳本（deploy script），讓它在每次部署時自動執行。Forge 和 Docker 都支援這種做法，後面會示範。 ### Queue Worker 設定 [上一章](/blog/laravel-guide-queues-events-notifications/)我們用 `php artisan queue:work` 在本地跑 Queue Worker。正式環境你需要一個 process manager 來確保 worker 持續運行。最常用的是 Supervisor： ```ini # /etc/supervisor/conf.d/jiuhaobuy-worker.conf [program:jiuhaobuy-worker] process_name=%(program_name)s_%(process_num)02d command=php /var/www/jiuhaobuy/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600 autostart=true autorestart=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/var/www/jiuhaobuy/storage/logs/worker.log ``` ### Scheduler 設定（Cron） Laravel 的 Task Scheduler 需要一個 cron job 每分鐘觸發一次。在伺服器上執行 `crontab -e`，加上這一行： ```bash * * * * * cd /var/www/jiuhaobuy && php artisan schedule:run >> /dev/null 2>&1 ``` 這一行 cron 會每分鐘執行 `schedule:run`，然後由 Laravel 內部判斷哪些排程任務該在這一分鐘執行。[上一章](/blog/laravel-guide-queues-events-notifications/)設定的截止提醒通知、定時清理過期團購，都靠這一行 cron 來驅動。 ## Config / Route / View Caching：榨乾每一滴效能 Laravel 在每次 request 進來時，預設會重新讀取所有 config 檔案、解析所有路由、編譯 Blade 模板。這在開發時很方便——改了 config 馬上生效——但在正式環境，這些重複的 I/O 和解析是純粹的浪費。 ### Config Cache ```bash php artisan config:cache ``` 這個指令把 `config/` 目錄下所有的設定檔合併成一個 PHP 檔案 `bootstrap/cache/config.php`。Laravel 載入一個檔案的速度遠快於掃描整個目錄。效果有多好？在有 30 個 config 檔案的專案裡，這一個指令就能減少 request bootstrap 時間約 40-60%。 **注意事項：** 一旦 cache 了 config，`env()` function 只能在 config 檔案裡使用。如果你在 Controller 或 Model 裡直接呼叫 `env('SOME_VAR')`，它會回傳 `null`。正確做法是永遠透過 `config('services.some_var')` 來取值，而不是直接呼叫 `env()`。 ### Route Cache ```bash php artisan route:cache ``` 把所有路由編譯成序列化的 PHP 陣列。Laravel 載入預編譯的路由比每次解析 `routes/web.php` 和 `routes/api.php` 快非常多——路由越多效果越明顯。有上百條路由的專案，啟動時間可以減少 50% 以上。 ### View Cache ```bash php artisan view:cache ``` 預先編譯所有 Blade 模板成 PHP 檔案，存放在 `storage/framework/views/`。正式環境不該讓第一個使用者承受模板編譯的延遲。 ### Event Cache ```bash php artisan event:cache ``` 把 Event 和 Listener 的對應關係快取起來，省去每次 request 掃描和自動發現的開銷。 ### 一鍵全部搞定 Laravel 提供了一個 `optimize` 指令，做上面所有快取的事： ```bash php artisan optimize ``` 這等同於執行 `config:cache` + `route:cache` + `view:cache` + `event:cache`。部署腳本裡通常就放這一行。開發時如果要清除所有快取： ```bash php artisan optimize:clear ``` ### Before / After 比較以「揪好買」的實際測量為例，在一台 1 vCPU / 1GB RAM 的伺服器上： | 指標 | 未快取 | 快取後 | 改善 | |------|--------|--------|------| | 首次 request 回應時間 | ~180ms | ~45ms | **75%** | | Config 載入時間 | ~12ms | ~1ms | 92% | | Route 解析時間 | ~8ms | ~1ms | 88% | | 記憶體使用 | ~32MB | ~24MB | 25% | 這些數字告訴你：**上線前跑 `php artisan optimize` 不是選配，是必做。** ## 路線一：Laravel Forge 一鍵部署如果你不想花時間在伺服器管理上——安裝 PHP、設定 Nginx、調整防火牆、更新系統套件——Laravel Forge 就是你的答案。它是 Laravel 官方團隊提供的伺服器管理服務。定價分為兩個主要方案：$12/月的 Hobby 方案支援無限台 Laravel 自家 VPS，但只允許連接 1 台外部主機商（DigitalOcean、AWS、Hetzner 等）的伺服器；若要連接無限台外部雲端主機商伺服器，需升級至 $19/月的 Growth 方案。對「揪好買」這種單機小專案，Hobby 方案已經足夠。 ### Forge 是什麼 Forge 不是主機商——它不賣伺服器。它是一個管理層：你提供 DigitalOcean、AWS、Hetzner、Vultr 等主機商的 API Key，Forge 幫你自動建立（provision）伺服器，然後持續管理它。Forge 幫你做的事包括： - 安裝 PHP（支援多版本切換）、Nginx、MySQL/PostgreSQL、Redis - 設定防火牆規則、SSH Key 管理 - 自動化部署：連結 GitHub repo，Push 到 main 就自動部署 - SSL 憑證：Let's Encrypt 一鍵設定、自動續約 - 排程任務和 Queue Worker 管理 - 資料庫備份 ### 部署流程 **第一步：註冊並連結主機商** 在 [forge.laravel.com](https://forge.laravel.com) 註冊帳號。到 Server Providers 頁面，把你的 DigitalOcean（或其他主機商）API Token 填進去。 **第二步：建立伺服器** 點「Create Server」，選擇主機商、地區、規格。以「揪好買」來說，一台 DigitalOcean $6/月的 Droplet（1 vCPU / 1GB RAM）就足以應付初期流量。Forge 會花大約 10 分鐘自動安裝所有需要的軟體。 **第三步：連結 GitHub Repo** 在 Forge 的 Sites 區塊點「New Site」，填入你的 domain name（例如 `jiuhaobuy.com`），然後連結 GitHub repository。Forge 會在伺服器上 clone 你的程式碼。 **第四步：設定 Deploy Script** Forge 預設的 deploy script 大概長這樣： ```bash cd /home/forge/jiuhaobuy.com git pull origin $FORGE_SITE_BRANCH composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader php artisan migrate --force php artisan optimize # 如果你用了 npm assets npm ci npm run build php artisan queue:restart ``` 每次你 Push 到 GitHub，Forge 就會自動執行這段腳本。 **第五步：SSL 憑證** 在 Forge 的 SSL 區塊，點「Let's Encrypt」，填入你的 domain，點確認。Forge 會自動申請、設定、並且在到期前自動續約。整個過程不到一分鐘。 ### Forge 的優缺點 | 優點 | 缺點 | |------|------| | 幾乎零學習曲線，UI 操作 | 月費 $12（加上主機費用） | | 自動化部署、SSL、備份 | 你的伺服器管理依賴 Forge | | 適合個人開發者和小團隊 | 不適合需要複雜基礎設施的場景 | | 官方維護，與 Laravel 整合最好 | 如果哪天想離開，需要自己接手伺服器管理 | 對於「揪好買」這種小型到中型的專案，Forge 是最快上線的方式。你可以把省下來的時間拿去做功能開發，而不是除錯 Nginx 設定。 ## 路線二：Docker 容器化部署 Docker 解決的核心問題是：**「在我電腦上可以跑」和「在伺服器上可以跑」不再是兩件事。** 你把應用程式和它的所有依賴（PHP 版本、擴充套件、系統套件）打包成一個 image，這個 image 在任何有 Docker 的機器上都能一致地運行。 ### 為什麼要用 Docker - **環境一致性**——開發、CI、正式環境用同一個 image，不會有「PHP 版本不對」的問題 - **可攜性**——image 可以跑在 AWS、GCP、Azure，或你辦公室的 NAS 上 - **CI/CD 友善**——Build image → Push to registry → Deploy，流程標準化 - **隔離性**——每個服務跑在自己的 container，互不干擾 ### Dockerfile：多階段建置多階段建置（multi-stage build）讓你的 production image 只包含必要的檔案，不會把 Composer、npm、開發工具帶進去： ```dockerfile # ===== 第一階段：安裝 PHP 依賴 ===== FROM composer:2 AS composer-build WORKDIR /app COPY composer.json composer.lock ./ RUN composer install --no-dev --no-scripts --no-autoloader --prefer-dist COPY . . RUN composer dump-autoload --optimize # ===== 第二階段：建置前端資源 ===== FROM node:24-alpine AS node-build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # ===== 第三階段：Production Image ===== FROM php:8.4-fpm-alpine # 安裝系統依賴和 PHP 擴充 RUN apk add --no-cache \ nginx \ supervisor \ libpng-dev \ libzip-dev \ icu-dev \ && docker-php-ext-install \ pdo_mysql \ gd \ zip \ intl \ opcache \ pcntl # 複製 Nginx 設定 COPY docker/nginx.conf /etc/nginx/http.d/default.conf # 複製 Supervisor 設定 COPY docker/supervisord.conf /etc/supervisord.conf # 複製應用程式碼 WORKDIR /var/www/html COPY --from=composer-build /app/vendor ./vendor COPY --from=node-build /app/public/build ./public/build COPY . . # 設定權限 RUN chown -R www-data:www-data storage bootstrap/cache \ && chmod -R 775 storage bootstrap/cache # OPcache 設定 COPY docker/opcache.ini /usr/local/etc/php/conf.d/opcache.ini EXPOSE 80 CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"] ``` ### docker-compose.yml 開發和測試時，用 `docker-compose` 把所有服務串起來： ```yaml # docker-compose.yml services: app: build: context: . dockerfile: Dockerfile ports: - "8080:80" environment: - APP_ENV=production - APP_DEBUG=false - DB_HOST=mysql - REDIS_HOST=redis env_file: - .env depends_on: mysql: condition: service_healthy redis: condition: service_started volumes: - storage:/var/www/html/storage mysql: image: mysql:8.4 environment: MYSQL_DATABASE: jiuhaobuy MYSQL_USER: jiuhaobuy_user MYSQL_PASSWORD: secret MYSQL_ROOT_PASSWORD: root_secret volumes: - mysql-data:/var/lib/mysql healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 5s timeout: 3s retries: 5 redis: image: redis:7-alpine volumes: - redis-data:/data queue-worker: build: context: . dockerfile: Dockerfile command: php artisan queue:work redis --sleep=3 --tries=3 --max-time=3600 env_file: - .env environment: - DB_HOST=mysql - REDIS_HOST=redis depends_on: - app scheduler: build: context: . dockerfile: Dockerfile command: sh -c "while true; do php artisan schedule:run --verbose --no-interaction & sleep 60; done" env_file: - .env environment: - DB_HOST=mysql - REDIS_HOST=redis depends_on: - app volumes: mysql-data: redis-data: storage: ``` ### 建置與執行 ```bash # 建置 image docker compose build # 啟動所有服務 docker compose up -d # 第一次啟動：跑 migration 和 cache docker compose exec app php artisan migrate --force docker compose exec app php artisan optimize # 查看 logs docker compose logs -f app # 停止所有服務 docker compose down ``` ### 推送到 Container Registry 正式部署時，你會把 image 推到 container registry（Docker Hub、GitHub Container Registry、Google Artifact Registry 等），然後在伺服器或雲端平台上拉取這個 image： ```bash # 建置並標記 image docker build -t ghcr.io/your-org/jiuhaobuy:latest . docker build -t ghcr.io/your-org/jiuhaobuy:v1.0.0 . # 推送到 GitHub Container Registry docker push ghcr.io/your-org/jiuhaobuy:latest docker push ghcr.io/your-org/jiuhaobuy:v1.0.0 ``` > **建議：** 除了 `latest` tag，永遠也打一個版本號 tag（例如 `v1.0.0` 或 Git commit SHA）。這樣你可以隨時回滾到指定版本。 ## Laravel Octane：Swoole / FrankenPHP 加速傳統的 PHP 執行模式是：每個 request 進來 → 載入框架 → 處理 request → 回應 → 丟掉所有東西。下一個 request 再從頭來一次。這就像每次客人進餐廳，你都要重新蓋一次廚房、擺一次桌椅、然後煮完菜再把整間餐廳拆掉。 Laravel Octane 改變了這個模式：它在第一次啟動時載入整個框架到記憶體裡，之後每個 request 都是在已經準備好的環境中處理，不需要重新 bootstrap。 ### FrankenPHP vs Swoole Octane 支援三種 server： | Server | 特點 | 適合場景 | |--------|------|---------| | **FrankenPHP** | Go 實作，簡單易用，支援 HTTP/3 | **推薦首選**，設定最少 | | **Swoole** | C 擴充，功能最多（WebSocket、協程） | 需要 WebSocket 或高併發場景 | | **RoadRunner** | Go 實作，穩定成熟 | 需要長期穩定的場景 | 對大多數 Laravel 應用來說，**FrankenPHP 是目前最推薦的選擇**——它是 Caddy web server 的一部分，安裝簡單，而且自帶 HTTPS 支援（Caddy 的 automatic HTTPS）。 ### 安裝與設定 ```bash composer require laravel/octane php artisan octane:install # 選擇 frankenphp ``` 啟動 Octane： ```bash # 開發環境（帶 watch 模式，改檔案自動重啟） php artisan octane:start --watch # 正式環境 php artisan octane:start --host=0.0.0.0 --port=8000 --workers=4 ``` ### 效能提升在「揪好買」的實測環境（同一台 1 vCPU 機器），使用 Apache Bench 測試 `/api/group-buys` endpoint： | 指標 | PHP-FPM | Octane (FrankenPHP) | 提升幅度 | |------|---------|---------------------|---------| | Requests/sec | ~120 | ~450 | **3.7x** | | 平均回應時間 | ~83ms | ~22ms | 3.8x | | P99 回應時間 | ~250ms | ~65ms | 3.8x | | 記憶體使用 | 每 request 獨立 | 共享 ~80MB | 整體更省 | 吞吐量提升 3-5 倍是常見的數字。對於流量還小的新專案，你可能感覺不到差異；但當流量成長到一定程度，Octane 可以讓你晚幾個月才需要升級伺服器規格。 ### 注意事項：記憶體和靜態狀態 Octane 把應用保持在記憶體裡，這帶來一個重要的副作用：**靜態變數和全域狀態會跨 request 存活。** ```php // ❌ 危險：這個計數器會在所有 request 之間共享 class SomeService { private static int $count = 0; public function handle(): void { self::$count++; // 每個 request 都會累加 } } // ✅ 正確：用 request-scoped 的方式 class SomeService { public function handle(Request $request): void { // 從 request 或 container 取值，不用靜態狀態 } } ``` Laravel 12 的核心服務都已經處理好 Octane 相容性。但如果你用了第三方套件，需要確認它們是否「Octane-friendly」。常見的陷阱： - **不要在 Service 裡存 request 相關的狀態**——每個 worker 會處理多個 request - **不要在 singleton 服務裡快取 per-request 資料**——它不會在下一個 request 被清除 - **資料庫連線可能因為太久沒用而斷開**——Octane 有內建的連線池管理，但要注意超時設定 ## 路線三：Cloud Run / Fly.io 雲端部署如果你不想管伺服器，也不想管伺服器上的作業系統更新和安全修補——那就讓雲端平台幫你管。 ### Google Cloud Run Cloud Run 的概念很單純：你給它一個 Docker image，它幫你跑起來。沒有流量的時候自動縮到零、有流量的時候自動擴展、SSL 自動搞定、domain mapping 一行指令。而且計費是 **per-request**——真的沒人用的時候，你一毛錢都不用付。部署揪好買到 Cloud Run： ```bash # 建置 image 並推送到 Google Artifact Registry gcloud builds submit --tag asia-east1-docker.pkg.dev/your-project/jiuhaobuy/app:latest # 部署到 Cloud Run gcloud run deploy jiuhaobuy \ --image asia-east1-docker.pkg.dev/your-project/jiuhaobuy/app:latest \ --platform managed \ --region asia-east1 \ --allow-unauthenticated \ --set-env-vars APP_ENV=production,APP_DEBUG=false \ --set-secrets APP_KEY=app-key:latest,DB_PASSWORD=db-password:latest \ --min-instances 0 \ --max-instances 10 ``` Cloud Run 的限制：它是 stateless 的，container 隨時可能被回收。這意味著： - **Session 和 Cache 不能用 file driver**——必須用 Redis 或 database - **Queue Worker 需要另外跑**——可以用 Cloud Run Jobs 或另一個 always-on 的 Cloud Run service - **Scheduler 要用 Cloud Scheduler 觸發**——設定一個每分鐘打一次 `/schedule` endpoint 的 cron job ### Laravel Cloud（官方第一方 serverless）如果要談「serverless 部署」，2026 年最對口的官方答案其實是 [Laravel Cloud](https://cloud.laravel.com)——Laravel 官方在 2025-02-24 隨 Laravel 12 一起推出的全託管部署平台，由 Laravel 團隊自己營運。它和 Laravel 整合最深：`git push` 就部署，內建 usage-based 計費與 scale-to-zero（閒置時自動縮到零、只付實際運算時間），佇列、排程、資料庫都幫你託管好，省去自己拼湊 Cloud Run Jobs + Cloud Scheduler 的工。實務上的取捨：Laravel Cloud 上手最快、最不用碰基礎設施，適合想專心寫 Laravel、不想管 DevOps 的團隊；Cloud Run / Fly.io 則給你更多底層掌控與跨雲彈性。如果你已經在 GCP/AWS 生態系裡，Cloud Run 仍是整合最順的選擇；但只要是 Laravel 專案要找 serverless，Laravel Cloud 都值得先列入評估。 ### Fly.io Fly.io 的思路和 Cloud Run 類似，但它提供了 persistent volumes（持久化儲存），對需要本地檔案儲存的應用更友善。部署同樣基於 Docker image： ```bash # 安裝 Fly CLI curl -L https://fly.io/install.sh | sh # 初始化專案 fly launch # 部署 fly deploy ``` Fly.io 的 `fly.toml` 設定檔： ```toml [build] dockerfile = "Dockerfile" [env] APP_ENV = "production" APP_DEBUG = "false" [http_service] internal_port = 8080 force_https = true auto_stop_machines = true auto_start_machines = true min_machines_running = 0 [[vm]] size = "shared-cpu-1x" memory = "512mb" ``` ### 三條路線比較 | 面向 | Forge | Docker + VPS | Cloud Run / Fly.io | |------|-------|-------------|-------------------| | 學習曲線 | 低 | 中 | 中 | | 初始設定時間 | 30 分鐘 | 2-4 小時 | 1-2 小時 | | 月費（小型專案） | ~$18 (Forge $12 + VPS $6) | ~$6 (VPS only) | ~$0-5 (pay-per-use) | | 伺服器管理 | Forge 代管 | 自己管 | 雲端平台代管 | | 擴展性 | 手動加機器 | 手動或用 K8s | 自動擴展 | | 自訂程度 | 中 | 高 | 受平台限制 | | CI/CD 整合 | Git push 自動部署 | 需自己設定 pipeline | Docker image + 一行指令 | | 適合對象 | 個人/小團隊 | 有 DevOps 經驗的團隊 | Serverless 愛好者 | ### 成本比較（月流量 10 萬 PV） | 項目 | Forge + DO | Docker + VPS | Cloud Run | |------|-----------|-------------|-----------| | 主機/運算 | $12 (2 vCPU) | $12 (2 vCPU) | ~$8 | | 管理服務 | $12 (Forge) | $0 | $0 | | 資料庫 | 含在 VPS | 含在 VPS | ~$10 (Cloud SQL) | | Redis | 含在 VPS | 含在 VPS | ~$6 (Memorystore) | | **合計** | **~$24/月** | **~$12/月** | **~$24/月** | 結論：小專案的話，三條路成本差不多。Docker + VPS 最便宜但你要自己管；Forge 和 Cloud Run 花錢買時間。 ## SSL / HTTPS 設定 2026 年了，HTTPS 不是選配——瀏覽器會把 HTTP 網站標記為「不安全」，SEO 也會被扣分。好消息是，免費的 SSL 憑證現在垂手可得。 ### Let's Encrypt（免費、自動續約） Let's Encrypt 提供免費的 SSL 憑證，有效期 90 天，支援自動續約。在不同部署方式下的設定方式： **Forge：** 前面提過，在 SSL 區塊點「Let's Encrypt」就搞定了。Forge 會自動設定 Nginx、自動續約。零操作。 **Docker + Caddy：** 如果你用 Caddy 取代 Nginx 當反向代理，HTTPS 是全自動的——Caddy 預設就會幫你申請和續約 Let's Encrypt 憑證： ```caddyfile # Caddyfile jiuhaobuy.com { reverse_proxy app:8080 } ``` 就這樣。不需要任何額外設定。這也是為什麼越來越多人在 Docker 部署時選擇 Caddy 而不是 Nginx。 **Docker + Nginx + Certbot：** 如果你堅持用 Nginx，需要搭配 Certbot： ```bash # 安裝 Certbot apt install certbot python3-certbot-nginx # 申請憑證 certbot --nginx -d jiuhaobuy.com -d www.jiuhaobuy.com # 自動續約（Certbot 會自動設定 cron） certbot renew --dry-run ``` **Cloud Run / Fly.io：** 自動提供 HTTPS，不需要任何設定。 ### Laravel 的 HTTPS 設定在 `AppServiceProvider` 裡強制所有 URL 使用 HTTPS： ```php public function boot(): void { if ($this->app->environment('production')) { URL::forceScheme('https'); } } ``` 同時在 `.env` 確認 `APP_URL` 使用 `https://`： ```bash APP_URL=https://jiuhaobuy.com ``` ## Zero-Downtime 部署策略使用者正在瀏覽你的網站，你按下部署按鈕，程式碼更新過程中——使用者看到一個 500 錯誤。這就是「有停機時間的部署」的問題。對一個團購平台來說，如果在結單的關鍵時刻出現錯誤，直接就是商譽和金錢的損失。 ### 問題出在哪傳統的 `git pull` + `composer install` 部署方式，中間有一段過渡期：舊的程式碼已經被覆蓋了，但新的依賴還沒裝好、cache 還沒更新。這段期間的 request 就會出錯。 ### Atomic Symlink 部署（Forge / Envoyer）原理：每次部署建立一個新的完整目錄（例如 `releases/20260831120000/`），在新目錄裡把所有東西準備好——Composer install、npm build、migration、cache——然後用一個 symlink 切換，把 `current/` 指向新的 release 目錄。Symlink 的切換是原子操作（atomic），不會有中間狀態。 ```text /var/www/jiuhaobuy/ ├── releases/ │ ├── 20260830_120000/ ← 上一版 │ └── 20260831_120000/ ← 新版（已經準備好了） ├── current -> releases/20260831_120000/ ← symlink 一切換，馬上生效 ├── storage/ ← 所有 release 共用 └── .env ← 所有 release 共用 ``` Laravel Forge 內建就支援這種部署模式。2026 年所有新的 Forge 訂閱（含 $12 Hobby 方案）都已內建單機 zero-downtime / atomic 部署，官方明確說明「不需要再額外訂閱 Envoyer」。[Laravel Envoyer](https://envoyer.io)（$12/月）現在的價值在於「把同一個專案部署到多台伺服器」這種多機情境——如果你只是單機部署，Forge 本身就夠用，不必為了 zero-downtime 再多付這筆錢。 ### Docker Rolling Update Docker 環境的零停機部署靠的是 rolling update：先啟動新版 container，確認健康檢查通過後，再停止舊版 container。如果用 Docker Compose： ```bash # 建置新 image docker compose build app # 滾動更新（先起新的，再停舊的） docker compose up -d --no-deps --build app ``` 在 Cloud Run 或 Kubernetes 環境，rolling update 是預設行為——你部署新版本後，平台會自動漸進式地把流量切換到新的 container。 ### Blue-Green 部署更進階的做法：同時維護兩套完全相同的環境（Blue 和 Green）。目前 Blue 在服務使用者，你把新版本部署到 Green，測試通過後，把 load balancer 切換到 Green。如果新版本有問題，馬上切回 Blue——回滾時間幾乎是零。這種做法的缺點是成本比較高（你要維護兩套環境），所以通常是有一定規模的團隊才會採用。「揪好買」初期用 Forge 的 atomic symlink 或 Docker 的 rolling update 就綽綽有餘。 ## 環境變數管理：Production 的 .env `.env` 檔案裡有你的資料庫密碼、API Key、加密金鑰——這些東西如果外洩，後果不堪設想。管理 production 環境變數有幾個鐵律： ### 絕對不要 Commit .env 到 Git 確認 `.gitignore` 裡有 `.env`。如果你不小心 commit 過，光是刪掉檔案不夠——歷史紀錄裡還在。你需要： 1. 立即更換所有外洩的密鑰（資料庫密碼、API Key 等） 2. 用 `git filter-branch` 或 BFG Repo-Cleaner 清除 Git 歷史 ### 各部署方式的環境變數管理 **Forge：** 在伺服器的 Environment 頁面直接編輯。Forge 會把內容寫到伺服器上的 `.env` 檔案，並設定正確的檔案權限。 **Docker：** 兩種常見做法： ```yaml # 方式一：env_file（適合開發和 CI） services: app: env_file: - .env.production # 方式二：Docker Secrets（適合正式環境） services: app: secrets: - db_password - app_key secrets: db_password: external: true app_key: external: true ``` **Cloud Run：** 使用 Google Cloud Secret Manager，在部署時透過 `--set-secrets` 把 secret 注入成環境變數： ```bash # 建立 secret echo -n "your-database-password" | gcloud secrets create db-password --data-file=- # 部署時注入 gcloud run deploy jiuhaobuy \ --set-secrets DB_PASSWORD=db-password:latest ``` ### 金鑰輪替策略好的安全實踐包括定期更換敏感的金鑰： - **資料庫密碼**——每 90 天更換一次 - **第三方 API Key**——依照服務商建議的頻率 - **APP_KEY**——除非有外洩疑慮，否則不要換（會影響所有加密資料） - **JWT Secret**——更換後所有舊的 token 會失效，要在低流量時段操作每次更換後，更新部署平台的環境變數，然後重新部署或重啟應用。 ## 實作：部署揪好買到正式環境講了這麼多理論，現在來實際操作。我們提供兩條路線，挑一條適合你的跟著做。 ### Option A：Forge 快速上線（5 步驟） **步驟 1：** 到 [forge.laravel.com](https://forge.laravel.com) 註冊，連結你的 DigitalOcean 帳號。 **步驟 2：** 建立伺服器——選 DigitalOcean、新加坡區域（離台灣最近）、$6/月的 1GB Droplet。等待約 10 分鐘。 **步驟 3：** 新增 Site——填入 domain（例如 `jiuhaobuy.com`），連結 GitHub repo，選 `main` branch。 **步驟 4：** 設定環境變數——在 Forge 的 Environment 頁面，貼上你的 production `.env` 內容（記得改 `APP_ENV=production`、`APP_DEBUG=false`、設定正確的資料庫連線）。 **步驟 5：** 按下「Deploy Now」。Forge 會執行 deploy script：拉程式碼、裝依賴、跑 migration、清快取。部署完成後，到 SSL 區塊申請 Let's Encrypt 憑證。完成。從註冊到上線大約 20-30 分鐘。 ### Option B：Docker + Cloud Run（Dockerfile → Build → Deploy） **步驟 1：** 確認專案根目錄有前面提到的 `Dockerfile`。 **步驟 2：** 在 Google Cloud 建立專案和 Artifact Registry： ```bash # 建立 Artifact Registry gcloud artifacts repositories create jiuhaobuy \ --repository-format=docker \ --location=asia-east1 # 設定 Secret Manager echo -n "base64:your-app-key" | gcloud secrets create app-key --data-file=- echo -n "your-db-password" | gcloud secrets create db-password --data-file=- ``` **步驟 3：** 建置並推送 image： ```bash gcloud builds submit \ --tag asia-east1-docker.pkg.dev/your-project/jiuhaobuy/app:v1.0.0 ``` **步驟 4：** 部署到 Cloud Run： ```bash gcloud run deploy jiuhaobuy \ --image asia-east1-docker.pkg.dev/your-project/jiuhaobuy/app:v1.0.0 \ --platform managed \ --region asia-east1 \ --allow-unauthenticated \ --set-env-vars APP_ENV=production,APP_DEBUG=false,APP_URL=https://jiuhaobuy.com \ --set-secrets APP_KEY=app-key:latest,DB_PASSWORD=db-password:latest \ --min-instances 1 \ --max-instances 10 \ --memory 512Mi ``` **步驟 5：** 設定 custom domain 和執行 migration： ```bash # 對應你的 domain gcloud run domain-mappings create --service jiuhaobuy \ --domain jiuhaobuy.com --region asia-east1 # 執行 migration（用 Cloud Run Jobs） # 第一次要先建立 job——直接 execute 會得到 job not found gcloud run jobs create jiuhaobuy-migrate \ --image asia-east1-docker.pkg.dev/your-project/jiuhaobuy/app:latest \ --region asia-east1 \ --set-secrets APP_KEY=app-key:latest,DB_PASSWORD=db-password:latest \ --command php \ --args artisan,migrate,--force # 建立後即可執行（之後每次部署重跑這行就好） gcloud run jobs execute jiuhaobuy-migrate --region asia-east1 ``` ### 部署後 Checklist 不管你選哪條路，部署完成後走過這份 checklist： ```bash # 1. 確認應用可以存取 curl -I https://jiuhaobuy.com # 應該回 200 # 2. 確認 HTTPS 正常 curl -I http://jiuhaobuy.com # 應該回 301 redirect 到 https # 3. 確認 migration 已執行 php artisan migrate:status # 所有 migration 應該都是 Ran # 4. 確認 cache 已建立 php artisan optimize # 建立 config/route/view/event cache # 5. 確認 Queue Worker 在運行 php artisan queue:monitor redis:default # 檢查 queue 狀態 # 6. 確認 Scheduler 在運行 # 等一分鐘後檢查 logs，看 schedule:run 有沒有被觸發 # 7. 測試核心功能 # - 註冊/登入 # - 建立團購 # - 加入團購 # - 付款流程（用 Stripe test mode） ``` ## 小結：選擇適合你的部署方式部署不是一個技術問題，它是一個「我願意花多少時間在維運上」的決策。 **決策矩陣：** - **一個人做 Side Project** → Forge。$18/月買回你的時間。 - **有 Docker 經驗、在意成本** → Docker + VPS。$6/月跑起來，但 server 你自己管。 - **已經在用 GCP/AWS** → Cloud Run / ECS。跟既有基礎設施整合最順。 - **想要極致效能** → 任何路線都可以加上 Octane。這一章涵蓋了從上線前設定、效能快取、三種部署路線、SSL、零停機部署、到環境變數管理——這些是 Laravel 應用正式上線的完整知識。不管你選哪條路，核心步驟都一樣：設定環境變數、跑 migration、建立 cache、確保 queue worker 和 scheduler 在跑。 [下一章](/blog/laravel-guide-roadmap-next-steps/)是這本書的最後一章。我們會回顧整個「揪好買」的旅程、盤點你學到的所有技能、展望 Laravel 生態系裡還有哪些強大的工具等著你探索，然後幫你畫一張接下來的進階學習路線圖。你已經具備了從零到上線的完整能力——接下來的路，你可以自己走了。

測試不是選配：用 Pest 寫出有信心的 Laravel 程式

Tue, 27 May 2025 00:00:00 GMT

> 本系列以 Laravel 12 為基準撰寫。Laravel 13 已於 2026 年 3 月 17 日正式發佈（最低需求 PHP 8.3），但本章的 Pest 測試內容在 Laravel 13 同樣適用，不需特別調整。「在我電腦上可以跑啊。」——這大概是軟體開發史上最經典的一句話。你改了一個 Model 的欄位，結果另一個頁面的表單壞了；你重構了一段商業邏輯，結果付款流程默默失效了。沒有測試的程式碼，每一次修改都是一場賭博，而你遲早會輸。 PHP 社群過去對測試的態度確實比較隨意，但 Pest 測試框架的出現改變了這件事。Pest 是建立在 PHPUnit 之上的現代測試框架，語法簡潔到你會覺得寫測試跟寫文件一樣自然。搭配 Laravel 內建的測試工具，寫測試的門檻已經低到沒有藉口不寫了： - **HTTP 測試**：模擬使用者操作，不需要真的開瀏覽器 - **RefreshDatabase**：讓每次測試都從乾淨的資料庫開始 - **Mail::fake()**：攔截寄信動作，不會真的發出 email - **Queue::fake()**：攔截佇列工作，不需要跑 worker 這一章我們要為揪好買的核心流程寫完整測試：開團建立、跟團加入、成團確認、付款流程。然後把這些測試串進 GitHub Actions CI pipeline，讓每一次 Push 都自動跑測試。從此以後，你可以安心重構、放心部署，晚上也能睡好覺。 ## 為什麼 Laravel 專案一定要寫測試：不是為了考試，是為了睡好覺先講兩個真實場景。 **場景一：** 某電商平台的工程師收到需求——「折扣碼不能跟團購優惠同時使用」。他改了結帳 Controller 裡的幾行邏輯，本機測了一下沒問題就部署了。隔天早上，客服收到 50 通投訴：「我加購商品怎麼價格變成零？」。原來改動影響了加購邏輯的金額計算，而沒有人發現——因為沒有測試。 **場景二：** 另一個團隊要把 Laravel 從 10 升級到 11。他們有 400 多個測試案例，跑一次 3 分鐘。升級完跑測試，紅了 12 個。每一個紅掉的測試都精確地告訴他們哪裡壞了、預期行為是什麼。他們花了一個下午修完，信心滿滿地部署上線。測試的價值不在於「證明程式碼正確」——你永遠無法證明複雜系統沒有 bug。測試的價值在三件事： **1. 安全網：讓你敢重構。** 沒有測試的程式碼，大家只敢「加程式碼」，不敢「改程式碼」。久了之後，程式碼就變成一堆層層疊加的 if-else 怪物。有測試保護，你可以放心把醜陋的程式碼重構成漂亮的架構，因為跑一次測試就知道有沒有搞壞東西。 **2. 活文件：測試本身就是規格書。** 你看一個 Controller 的程式碼，可能要花 10 分鐘才搞懂它的行為。但你看對應的測試——「未登入的使用者嘗試開團時應該被導向登入頁」「開團時名稱是必填欄位」「團購人數已滿時不能再加入」——30 秒就知道這個功能在幹嘛。而且這份文件是「可以執行的」，它不會跟程式碼脫節。 **3. 設計回饋：難測的程式碼通常設計不好。** 如果你發現一個 class 很難寫測試——需要 mock 一堆東西、需要準備很多前置狀態——那通常代表這個 class 做了太多事情。測試會倒逼你寫出鬆耦合、職責分明的程式碼。 ### 跨框架對照 | 概念 | Laravel (Pest) | Jest (Node.js) | pytest (Python) | | ---------- | --------------------- | ------------------- | --------------- | | 測試框架 | Pest / PHPUnit | Jest / Vitest | pytest | | 斷言語法 | `expect($x)->toBe(1)` | `expect(x).toBe(1)` | `assert x == 1` | | HTTP 測試 | `$this->get('/api')` | supertest | TestClient | | 測試資料庫 | RefreshDatabase | 自己管 | fixtures | | Mock | `Mail::fake()` | `jest.mock()` | `unittest.mock` | | 執行指令 | `php artisan test` | `npm test` | `pytest` | 如果你來自 JavaScript 世界，Pest 的語法會讓你非常有親切感——它就是 PHP 版的 Jest。 ## Pest 測試框架：比 PHPUnit 更好寫 Laravel 12 的 `laravel new` 安裝精靈會詢問你選擇 **Pest** 還是 **PHPUnit**；選了 Pest，它就會自動裝好、開箱即用。如果你用的是舊版 Laravel 或想手動安裝： ```bash composer require pestphp/pest pestphp/pest-plugin-laravel --dev --with-all-dependencies php artisan pest:install ``` `pest-plugin-laravel` 提供 `actingAs()`、Laravel 專屬斷言等整合功能；初始化建議用 `php artisan pest:install`（舊式 `./vendor/bin/pest --init` 仍可用，但新版以 `pest:install` 為主）。以 Laravel 12 來說，只要在 `laravel new` 時選 Pest，就能直接使用，不需要額外執行上面的指令。 ### Pest 語法 vs PHPUnit 語法先來看同一個測試用兩種方式怎麼寫： **PHPUnit（傳統方式）：** ```php get('/'); $response->assertStatus(200); } public function test_guest_cannot_create_group_buy(): void { $response = $this->post('/group-buys', [ 'title' => '大湖草莓團購', ]); $response->assertRedirect('/login'); } } ``` **Pest（現代方式）：** ```php get('/') ->assertStatus(200); }); it('prevents guest from creating group buy', function () { $this->post('/group-buys', [ 'title' => '大湖草莓團購', ])->assertRedirect('/login'); }); ``` 差異一目了然： - **不需要 class** —— 每個測試檔案就是一堆函數，不用寫 `extends TestCase` - **不需要 method 命名規範** —— 用 `it()` 或 `test()` 描述行為，讀起來像英文句子 - **不需要 use trait** —— `uses(RefreshDatabase::class)` 一行搞定 - **鏈式斷言** —— 所有東西串在一起，更流暢 ### `it()` 和 `test()` 的差別 ```php // 這兩個完全等價： it('creates a group buy successfully', function () { /* ... */ }); test('creates a group buy successfully', function () { /* ... */ }); // it() 在終端顯示為 "it creates a group buy successfully" // test() 在終端顯示為 "creates a group buy successfully" ``` 慣例上，`it()` 用來描述「這個東西應該做什麼」，`test()` 用來描述「做這件事的結果」。選一種風格並保持一致就好。本章統一用 `it()`。 ### `expect()` API——流暢的斷言 Pest 的 `expect()` API 借鏡了 Jest，讀起來非常自然： ```php // 基本型別 expect($user->name)->toBe('Bobo'); expect($user->age)->toBeGreaterThan(18); expect($user->email)->toContain('@'); expect($user->bio)->toBeNull(); expect($user->is_active)->toBeTrue(); // 陣列 expect($tags)->toHaveCount(3); expect($response->json())->toHaveKey('data'); expect($ids)->toContain(1, 2, 3); // 例外 expect(fn () => $service->join($closedGroupBuy)) ->toThrow(GroupBuyClosedException::class); // 鏈式 expect($user) ->name->toBe('Bobo') ->email->toEndWith('@example.com') ->role->toBe(UserRole::Organizer); ``` ### 跑測試 ```bash # 用 Artisan（推薦，有漂亮的輸出） php artisan test # 直接跑 Pest ./vendor/bin/pest # 跑特定檔案 php artisan test --filter=GroupBuyTest # 跑特定測試 php artisan test --filter="creates a group buy" # 平行執行（更快） php artisan test --parallel # 只跑上次失敗的 php artisan test --retry ``` `php artisan test` 的輸出非常漂亮——綠色的勾勾代表通過，紅色的叉叉代表失敗，還會告訴你每個測試花了多少毫秒。 ## Feature Test vs Unit Test：差在哪裡 Laravel 的測試資料夾結構很清楚： ``` tests/ ├── Feature/ # 功能測試（模擬完整 HTTP 請求） │ ├── GroupBuyTest.php │ └── Auth/ │ └── LoginTest.php ├── Unit/ # 單元測試（測試單一 class/method） │ └── Models/ │ └── GroupBuyTest.php ├── Pest.php # Pest 全域設定 └── TestCase.php # 基底 TestCase ``` ### Feature Test（功能測試）功能測試模擬完整的 HTTP 請求生命週期——從路由解析、middleware 檢查、Controller 執行、到 Response 返回。它測試的是「使用者做了某個操作，系統會有什麼反應」： ```php // tests/Feature/GroupBuyTest.php it('allows organizer to create a group buy', function () { $user = User::factory()->create(['role' => 'organizer']); $this->actingAs($user) ->post('/group-buys', [ 'title' => '大湖草莓團購', 'description' => '又到了草莓季', 'min_participants' => 10, 'max_participants' => 50, 'deadline' => now()->addWeek(), ]) ->assertRedirect('/group-buys'); $this->assertDatabaseHas('group_buys', [ 'title' => '大湖草莓團購', 'user_id' => $user->id, ]); }); ``` 這一個測試涵蓋了：路由是否正確、`auth` middleware 是否通過、Controller 是否正確處理資料、資料是否寫入資料庫、回應是否重導到正確頁面。 ### Unit Test（單元測試）單元測試只測試一個 class 或 method 的行為，不經過 HTTP 層，不碰資料庫（除非必要）： ```php // tests/Unit/Models/GroupBuyTest.php it('calculates if group buy has reached minimum participants', function () { $groupBuy = new GroupBuy([ 'min_participants' => 10, ]); // 用 mock 或直接設定 relationship count expect($groupBuy->hasReachedMinimum(8))->toBeFalse(); expect($groupBuy->hasReachedMinimum(10))->toBeTrue(); expect($groupBuy->hasReachedMinimum(15))->toBeTrue(); }); it('determines if group buy is still open', function () { $open = new GroupBuy(['deadline' => now()->addDay()]); $closed = new GroupBuy(['deadline' => now()->subDay()]); expect($open->isOpen())->toBeTrue(); expect($closed->isOpen())->toBeFalse(); }); ``` ### 什麼時候用哪個？ | 情境 | 選擇 | 原因 | | --------------------- | ------- | ---------------------- | | 測試 API endpoint | Feature | 需要完整 HTTP 生命週期 | | 測試使用者流程 | Feature | 涉及多個元件協作 | | 測試 Model 的計算邏輯 | Unit | 純函數，不需要 HTTP | | 測試 Service class | Unit | 單一職責，注入依賴 | | 測試授權 Policy | Feature | 需要 auth 上下文 | | 測試 Validation 規則 | Feature | 需要 Request 處理 | > **經驗法則：** 對於 Web 應用程式，**Feature Test 的投資報酬率最高**。一個 Feature Test 就能涵蓋路由、middleware、Controller、Model、View 的整合。先把核心流程的 Feature Test 寫好，再慢慢補 Unit Test 給複雜的商業邏輯。 ### Pest.php：全域設定 `tests/Pest.php` 是 Pest 的全域設定檔，你可以在這裡為不同資料夾的測試統一套用 trait： ```php // tests/Pest.php uses(Tests\TestCase::class, Illuminate\Foundation\Testing\RefreshDatabase::class) ->in('Feature'); uses(Tests\TestCase::class) ->in('Unit'); ``` 這樣你就不需要在每個 Feature 測試檔案裡都寫 `uses(RefreshDatabase::class)` 了——全域一次搞定。 ## HTTP Tests：模擬使用者操作 Laravel 的 HTTP 測試是你最常用的武器。它讓你模擬瀏覽器的行為——送出 GET、POST、PUT、DELETE 請求，然後檢查回應。 ### 基本 HTTP 方法 ```php // GET 請求——瀏覽頁面 $this->get('/group-buys') ->assertStatus(200) ->assertSee('大湖草莓團購'); // POST 請求——建立資源 $this->post('/group-buys', [ 'title' => '大湖草莓團購', 'min_participants' => 10, ])->assertRedirect('/group-buys'); // PUT 請求——更新資源 $this->put("/group-buys/{$groupBuy->id}", [ 'title' => '大湖有機草莓團購', ])->assertRedirect("/group-buys/{$groupBuy->id}"); // DELETE 請求——刪除資源 $this->delete("/group-buys/{$groupBuy->id}") ->assertRedirect('/group-buys'); ``` ### 常用斷言方法 ```php // 狀態碼 ->assertStatus(200) ->assertOk() // 等同 assertStatus(200) ->assertNotFound() // 等同 assertStatus(404) ->assertForbidden() // 等同 assertStatus(403) ->assertUnauthorized() // 等同 assertStatus(401) // 重導向 ->assertRedirect('/login') ->assertRedirectToRoute('group-buys.index') // 頁面內容 ->assertSee('大湖草莓團購') // 頁面包含這段文字 ->assertDontSee('已截止') // 頁面不包含這段文字 ->assertSeeText('10 人成團') // 只看純文字（忽略 HTML） // Session ->assertSessionHas('success', '開團成功！') ->assertSessionHasErrors(['title']) // 驗證失敗時的錯誤欄位 ->assertSessionHasNoErrors() // View ->assertViewIs('group-buys.show') ->assertViewHas('groupBuy') ``` ### 模擬登入使用者 ```php use App\Models\User; it('shows create form to organizers', function () { $organizer = User::factory()->create(['role' => 'organizer']); $this->actingAs($organizer) ->get('/group-buys/create') ->assertOk(); }); it('denies create form to regular members', function () { $member = User::factory()->create(['role' => 'member']); $this->actingAs($member) ->get('/group-buys/create') ->assertForbidden(); }); it('redirects guest to login', function () { $this->get('/group-buys/create') ->assertRedirect('/login'); }); ``` `actingAs()` 幫你模擬「以某個使用者身份登入」，不需要真的跑登入流程。 ### 測試 JSON API 回應 ```php it('returns group buys as JSON', function () { GroupBuy::factory()->count(3)->create(); $this->getJson('/api/group-buys') ->assertOk() ->assertJsonCount(3, 'data') ->assertJsonStructure([ 'data' => [ '*' => ['id', 'title', 'description', 'min_participants', 'deadline'], ], ]); }); it('returns specific group buy details', function () { $groupBuy = GroupBuy::factory()->create([ 'title' => '大湖草莓團購', ]); $this->getJson("/api/group-buys/{$groupBuy->id}") ->assertOk() ->assertJson([ 'data' => [ 'title' => '大湖草莓團購', ], ]); }); ``` 注意這裡用的是 `getJson()` 而不是 `get()`——它會自動帶上 `Accept: application/json` header，讓 Laravel 回傳 JSON 而不是 HTML。對應的還有 `postJson()`、`putJson()`、`deleteJson()`。 ## Database Testing：RefreshDatabase 的魔力測試最怕的是「測試之間互相影響」。你在測試 A 建了一個使用者，結果測試 B 因為資料庫裡多了這筆資料而失敗——這種問題 debug 起來讓人抓狂。 ### RefreshDatabase trait `RefreshDatabase` 解決這個問題的方式很聰明：它在每個測試之前用資料庫 transaction 包起來，測試結束後 rollback。效果等同於每個測試都從空白資料庫開始，但速度比真的 `migrate:fresh` 快得多。如果你按前面建議設定了 `tests/Pest.php`，所有 Feature 測試都自動有這個行為： ```php // tests/Pest.php uses(Tests\TestCase::class, RefreshDatabase::class)->in('Feature'); ``` ### 資料庫斷言 ```php use App\Models\GroupBuy; use App\Models\User; it('stores group buy in database', function () { $user = User::factory()->create(['role' => 'organizer']); $this->actingAs($user)->post('/group-buys', [ 'title' => '大湖草莓團購', 'description' => '又到了草莓季', 'min_participants' => 10, 'max_participants' => 50, 'deadline' => '2026-12-31', ]); // 確認資料庫裡有這筆資料 $this->assertDatabaseHas('group_buys', [ 'title' => '大湖草莓團購', 'user_id' => $user->id, ]); // 確認資料庫裡有正確的數量 $this->assertDatabaseCount('group_buys', 1); }); it('removes group buy from database on delete', function () { $user = User::factory()->create(['role' => 'organizer']); $groupBuy = GroupBuy::factory()->for($user)->create(); $this->actingAs($user)->delete("/group-buys/{$groupBuy->id}"); // 確認資料庫裡沒有這筆資料了 $this->assertDatabaseMissing('group_buys', [ 'id' => $groupBuy->id, ]); }); ``` ### 使用 SQLite in-memory 加速測試在 `phpunit.xml` 裡（Laravel 12 預設已經設好了），測試環境使用 SQLite in-memory 資料庫，跑起來飛快： ```xml ``` 這代表測試不會碰到你的開發資料庫——完全隔離。 ## Mock 與 Fake：Mail::fake()、Queue::fake() 測試不應該真的寄信、真的打第三方 API、真的觸發排程任務。Laravel 的 Fake 機制讓你攔截這些副作用，只檢查「系統是否正確地觸發了這些操作」。 ### Mail::fake() ```php use Illuminate\Support\Facades\Mail; use App\Mail\GroupBuyConfirmed; it('sends confirmation email when group buy reaches minimum', function () { Mail::fake(); $groupBuy = GroupBuy::factory()->create(['min_participants' => 2]); $participants = User::factory()->count(2)->create(); // 模擬兩個人加入，觸發成團 foreach ($participants as $participant) { $groupBuy->participants()->attach($participant); } $groupBuy->checkAndConfirm(); // 斷言：確認信被寄出了 Mail::assertSent(GroupBuyConfirmed::class, function ($mail) use ($groupBuy) { return $mail->groupBuy->id === $groupBuy->id; }); // 斷言：寄了正確的數量 Mail::assertSent(GroupBuyConfirmed::class, 2); }); it('does not send email when minimum not reached', function () { Mail::fake(); $groupBuy = GroupBuy::factory()->create(['min_participants' => 10]); $groupBuy->participants()->attach(User::factory()->create()); $groupBuy->checkAndConfirm(); Mail::assertNotSent(GroupBuyConfirmed::class); }); ``` `Mail::fake()` 攔截所有郵件，不會真的送出。你只需要驗證「正確的 Mailable 是否被送出、送給了誰」。 ### Queue::fake() ```php use Illuminate\Support\Facades\Queue; use App\Jobs\ProcessGroupBuyPayment; it('dispatches payment job when group buy is confirmed', function () { Queue::fake(); $groupBuy = GroupBuy::factory()->confirmed()->create(); $groupBuy->processPayments(); Queue::assertPushed(ProcessGroupBuyPayment::class, function ($job) use ($groupBuy) { return $job->groupBuyId === $groupBuy->id; }); }); ``` ### Notification::fake() ```php use Illuminate\Support\Facades\Notification; use App\Notifications\GroupBuyDeadlineReminder; it('sends deadline reminder to all participants', function () { Notification::fake(); $groupBuy = GroupBuy::factory()->create([ 'deadline' => now()->addDay(), ]); $participants = User::factory()->count(5)->create(); $groupBuy->participants()->attach($participants); $groupBuy->sendDeadlineReminders(); Notification::assertSentTo($participants, GroupBuyDeadlineReminder::class); }); ``` ### Event::fake() ```php use Illuminate\Support\Facades\Event; use App\Events\GroupBuyCreated; it('fires event when group buy is created', function () { Event::fake([GroupBuyCreated::class]); $user = User::factory()->create(['role' => 'organizer']); $this->actingAs($user)->post('/group-buys', [ 'title' => '大湖草莓團購', 'min_participants' => 10, 'max_participants' => 50, 'deadline' => now()->addWeek(), ]); Event::assertDispatched(GroupBuyCreated::class); }); ``` ### Storage::fake() ```php use Illuminate\Support\Facades\Storage; use Illuminate\Http\UploadedFile; it('uploads product image when creating group buy', function () { Storage::fake('public'); $user = User::factory()->create(['role' => 'organizer']); $image = UploadedFile::fake()->image('strawberry.jpg', 800, 600); $this->actingAs($user)->post('/group-buys', [ 'title' => '大湖草莓團購', 'image' => $image, 'min_participants' => 10, 'max_participants' => 50, 'deadline' => now()->addWeek(), ]); // 斷言：檔案確實被存到 public disk Storage::disk('public')->assertExists('group-buys/' . $image->hashName()); }); ``` `Storage::fake('public')` 建立一個 in-memory 檔案系統，不會真的寫檔案到磁碟。測試結束後自動清空。 ## 測試資料準備：Factory 的進階用法 [第五章](/blog/laravel-guide-eloquent-orm-models/)已經介紹過 Factory 的基本用法。在測試情境裡，Factory 的進階功能會讓你的測試更簡潔、更有表達力。 ### Factory States：用名稱描述狀態 ```php // database/factories/GroupBuyFactory.php class GroupBuyFactory extends Factory { public function definition(): array { return [ 'user_id' => User::factory(), 'title' => fake()->sentence(3), 'description' => fake()->paragraph(), 'min_participants' => fake()->numberBetween(5, 20), 'max_participants' => fake()->numberBetween(20, 100), 'deadline' => fake()->dateTimeBetween('+1 week', '+1 month'), 'status' => 'open', ]; } // State：已確認成團 public function confirmed(): static { return $this->state(fn (array $attributes) => [ 'status' => 'confirmed', 'confirmed_at' => now(), ]); } // State：已截止 public function expired(): static { return $this->state(fn (array $attributes) => [ 'deadline' => now()->subDay(), 'status' => 'expired', ]); } // State：已取消 public function cancelled(): static { return $this->state(fn (array $attributes) => [ 'status' => 'cancelled', 'cancelled_at' => now(), ]); } // State：已滿團 public function full(): static { return $this->state(fn (array $attributes) => [ 'max_participants' => 2, ])->afterCreating(function (GroupBuy $groupBuy) { $groupBuy->participants()->attach( User::factory()->count(2)->create() ); }); } } ``` 使用起來非常直覺： ```php $openGroupBuy = GroupBuy::factory()->create(); $confirmedGroupBuy = GroupBuy::factory()->confirmed()->create(); $expiredGroupBuy = GroupBuy::factory()->expired()->create(); $fullGroupBuy = GroupBuy::factory()->full()->create(); ``` ### Factory Relationships：`has()` 和 `for()` ```php // 建立一個開團主，有 3 個團購 $organizer = User::factory() ->has(GroupBuy::factory()->count(3)) ->create(['role' => 'organizer']); // 建立一個團購，屬於特定使用者 $groupBuy = GroupBuy::factory() ->for($organizer) ->create(); // 建立一個團購，帶有 5 個參與者 $groupBuy = GroupBuy::factory() ->hasParticipants(5) // 等同 has(User::factory()->count(5), 'participants') ->create(); ``` ### Factory Sequences：輪替值 ```php // 交替建立不同狀態的團購 $groupBuys = GroupBuy::factory() ->count(6) ->sequence( ['status' => 'open'], ['status' => 'confirmed'], ['status' => 'expired'], ) ->create(); // 結果：open, confirmed, expired, open, confirmed, expired ``` ### `recycle()`：在多個 Factory 之間共用 Model ```php // 同一個使用者同時是開團主和其他團的參與者 $user = User::factory()->create(); $groupBuys = GroupBuy::factory() ->count(3) ->recycle($user) // 所有 user_id 都用這個使用者 ->create(); ``` `recycle()` 避免了 Factory 每次都建一個新的關聯 Model——當你需要多個 Factory 共用同一筆資料時特別有用。 ## GitHub Actions CI：每次 Push 自動跑測試測試寫好了，但如果要「記得手動跑」才有用，那遲早會有人忘記。CI（Continuous Integration）的目的就是：每次有人 push 程式碼，自動跑測試。測試過了才能合併。 ### 完整的 GitHub Actions 設定在專案根目錄建立 `.github/workflows/tests.yml`： ```yaml name: Tests on: push: branches: [main] pull_request: branches: [main] jobs: tests: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: '8.4' extensions: mbstring, xml, ctype, json, bcmath, sqlite3 coverage: none - name: Cache Composer dependencies uses: actions/cache@v4 with: path: vendor key: composer-${{ hashFiles('composer.lock') }} restore-keys: composer- - name: Install dependencies run: composer install --no-interaction --prefer-dist --optimize-autoloader - name: Copy environment file run: cp .env.example .env - name: Generate application key run: php artisan key:generate - name: Run tests env: DB_CONNECTION: sqlite DB_DATABASE: ':memory:' run: php artisan test --parallel ``` 逐步拆解： 1. **觸發條件** —— push 到 `main` 或開 PR 到 `main` 時觸發 2. **PHP 設定** —— 安裝 PHP 8.4 和必要的擴充套件 3. **Composer Cache** —— 快取 `vendor/` 目錄，避免每次都重裝套件（省 30-60 秒） 4. **SQLite in-memory** —— 不需要真的 MySQL server，用 SQLite 跑測試更快 5. **平行執行** —— `--parallel` 讓測試跑更快 ### 把 Badge 加到 README ```markdown ![Tests](https://github.com/your-username/jiu-hao-mai/actions/workflows/tests.yml/badge.svg) ``` 這個 badge 會顯示在 README 最上方，讓所有人一眼就知道測試有沒有通過。綠色的 "passing" 就是信任的象徵。 ### 當 CI 失敗了 CI 紅了不可怕，可怕的是忽視它。當 CI 失敗時： 1. **點進 GitHub Actions 看 log** —— 找到紅色的步驟，看錯誤訊息 2. **在本機重現** —— `php artisan test --filter="失敗的測試名稱"` 3. **修好它** —— 不要跳過失敗的測試（`->skip()`），除非有非常正當的理由 4. **Push 修正** —— CI 會自動重新跑 > **絕對不要做的事：** 刪掉失敗的測試、在 CI 裡加 `continue-on-error: true`、或用 `@skip` 跳過。這些做法只是在掩耳盜鈴。 ## 實作：為揪好買核心流程寫測試理論講完了，現在動手。我們要為揪好買寫一組完整的 Feature Test，覆蓋最重要的使用者流程。建立測試檔案： ```bash php artisan make:test GroupBuyTest # 生成 tests/Feature/GroupBuyTest.php ``` ```php create(['role' => 'organizer']); $this->actingAs($organizer) ->post('/group-buys', [ 'title' => '大湖草莓團購', 'description' => '苗栗大湖有機草莓，產地直送', 'min_participants' => 10, 'max_participants' => 50, 'deadline' => now()->addWeek()->toDateString(), ]) ->assertRedirect('/group-buys'); $this->assertDatabaseHas('group_buys', [ 'title' => '大湖草莓團購', 'user_id' => $organizer->id, 'status' => 'open', ]); }); it('rejects group buy creation with missing required fields', function () { $organizer = User::factory()->create(['role' => 'organizer']); $this->actingAs($organizer) ->post('/group-buys', [ // title 沒填 'min_participants' => 10, ]) ->assertSessionHasErrors(['title', 'max_participants', 'deadline']); }); it('prevents guest from creating a group buy', function () { $this->post('/group-buys', [ 'title' => '大湖草莓團購', 'min_participants' => 10, 'max_participants' => 50, 'deadline' => now()->addWeek()->toDateString(), ])->assertRedirect('/login'); }); it('prevents regular member from creating a group buy', function () { $member = User::factory()->create(['role' => 'member']); $this->actingAs($member) ->post('/group-buys', [ 'title' => '大湖草莓團購', 'min_participants' => 10, 'max_participants' => 50, 'deadline' => now()->addWeek()->toDateString(), ]) ->assertForbidden(); }); // ── 跟團加入 ────────────────────────────────────── it('allows authenticated user to join an open group buy', function () { $user = User::factory()->create(); $groupBuy = GroupBuy::factory()->create(['status' => 'open']); $this->actingAs($user) ->post("/group-buys/{$groupBuy->id}/join") ->assertRedirect("/group-buys/{$groupBuy->id}"); $this->assertDatabaseHas('group_buy_user', [ 'user_id' => $user->id, 'group_buy_id' => $groupBuy->id, ]); }); it('prevents joining a group buy that is already full', function () { $user = User::factory()->create(); $groupBuy = GroupBuy::factory()->full()->create(); $this->actingAs($user) ->post("/group-buys/{$groupBuy->id}/join") ->assertStatus(422) ->assertSessionHasErrors(['capacity']); }); it('prevents duplicate join to the same group buy', function () { $user = User::factory()->create(); $groupBuy = GroupBuy::factory()->create(['status' => 'open']); $groupBuy->participants()->attach($user); $this->actingAs($user) ->post("/group-buys/{$groupBuy->id}/join") ->assertStatus(422) ->assertSessionHasErrors(['duplicate']); }); // ── 成團確認 ────────────────────────────────────── it('confirms group buy when minimum participants reached', function () { Mail::fake(); $groupBuy = GroupBuy::factory()->create([ 'min_participants' => 3, 'status' => 'open', ]); $participants = User::factory()->count(3)->create(); foreach ($participants as $participant) { $groupBuy->participants()->attach($participant); } $groupBuy->checkAndConfirm(); expect($groupBuy->fresh()->status)->toBe('confirmed'); Mail::assertSent(GroupBuyConfirmed::class, 3); }); it('does not confirm group buy below minimum participants', function () { $groupBuy = GroupBuy::factory()->create([ 'min_participants' => 10, 'status' => 'open', ]); $groupBuy->participants()->attach(User::factory()->create()); $groupBuy->checkAndConfirm(); expect($groupBuy->fresh()->status)->toBe('open'); }); // ── API Endpoints ───────────────────────────────── it('returns paginated group buys as JSON', function () { GroupBuy::factory()->count(15)->create(['status' => 'open']); $this->getJson('/api/group-buys') ->assertOk() ->assertJsonStructure([ 'data' => [ '*' => [ 'id', 'title', 'description', 'min_participants', 'max_participants', 'deadline', 'status', 'participants_count', ], ], 'meta' => ['current_page', 'last_page', 'total'], ]); }); it('requires authentication for API group buy creation', function () { $this->postJson('/api/group-buys', [ 'title' => '大湖草莓團購', ])->assertUnauthorized(); }); ``` 讓我們回顧這 11 個測試案例涵蓋了什麼： | # | 測試案例 | 驗證重點 | | --- | ------------------ | ---------------------- | | 1 | 開團主成功開團 | 認證 + 授權 + 資料寫入 | | 2 | 缺少必填欄位 | 表單驗證 | | 3 | 未登入者嘗試開團 | 認證 middleware | | 4 | 一般會員嘗試開團 | 授權 Policy | | 5 | 加入開放中的團購 | 正常流程 + pivot table | | 6 | 加入已滿的團購 | 容量限制 | | 7 | 重複加入同一團購 | 業務規則 | | 8 | 成團確認 + 寄信 | 商業邏輯 + Mail::fake | | 9 | 未達最低人數不成團 | 邊界條件 | | 10 | API 回應結構 | JSON 格式 + 分頁 | | 11 | API 認證 | Token 認證 | 跑測試： ```bash php artisan test tests/Feature/GroupBuyTest.php # PASS Tests\Feature\GroupBuyTest # ✓ it allows authenticated organizer to create a group buy 0.15s # ✓ it rejects group buy creation with missing required fields 0.08s # ✓ it prevents guest from creating a group buy 0.05s # ✓ it prevents regular member from creating a group buy 0.06s # ✓ it allows authenticated user to join an open group buy 0.09s # ✓ it prevents joining a group buy that is already full 0.07s # ✓ it prevents duplicate join to the same group buy 0.06s # ✓ it confirms group buy when minimum participants reached 0.11s # ✓ it does not confirm group buy below minimum participants 0.07s # ✓ it returns paginated group buys as JSON 0.12s # ✓ it requires authentication for API group buy creation 0.04s # # Tests: 11 passed (23 assertions) # Duration: 0.90s ``` 全綠。11 個測試、23 個斷言、不到 1 秒。這就是你的安全網。 ## 小結：有測試的程式碼，才是專業的程式碼這一章我們建立了完整的測試體系： **測試框架：** - Pest 是 Laravel 12 官方一級支援、可在建立專案時直接選用的框架——語法簡潔、讀起來像英文、`expect()` API 直覺好用 - `it()` 描述行為、`expect()` 驗證結果、`uses()` 套用 trait - `php artisan test` 一行指令跑所有測試 **測試類型：** - Feature Test 模擬完整 HTTP 請求，投資報酬率最高 - Unit Test 測試單一 class/method 的純邏輯 - 先寫 Feature Test 覆蓋核心流程，再補 Unit Test 給複雜邏輯 **測試工具：** - `actingAs()` 模擬登入使用者 - `RefreshDatabase` 確保每個測試從乾淨資料庫開始 - `Mail::fake()`、`Queue::fake()`、`Notification::fake()` 攔截副作用 - `Storage::fake()` 建立 in-memory 檔案系統 - Factory States 讓測試資料準備更有表達力 **CI Pipeline：** - GitHub Actions 讓每次 push 自動跑測試 - SQLite in-memory + Composer cache 讓 CI 跑得快 - 測試紅了就修，不要跳過、不要忽視 **揪好買進度：** - ✅ 11 個 Feature Test 涵蓋開團、跟團、成團、API - ✅ Factory States 定義 `confirmed()`、`expired()`、`full()` 等狀態 - ✅ GitHub Actions CI pipeline 設定完成 - ✅ 核心流程全部有測試保護有了測試保護，你就可以放心做任何改動。[下一章](/blog/laravel-guide-deployment-forge-docker/)我們要把揪好買部署上線——從 Production 環境設定、Config Cache、到 Laravel Forge 一鍵部署和 Docker 容器化。從此以後，你的程式碼不只在本機能跑，在全世界都能跑。

後台管理與進階查詢：用 Filament 打造管理介面

Tue, 20 May 2025 00:00:00 GMT

每一個有使用者的平台，遲早都需要一個管理後台。你可以從零開始刻——自己寫列表頁、編輯頁、篩選器、圖表——但說實話，那些重複的 CRUD 介面真的不值得你花好幾天去做。Filament 5 是 Laravel 生態系中最成熟的後台框架，完全開源免費，而且跟 Laravel 的整合度高到像是原生功能一樣。但後台管理不只是有畫面就好。當你的團購平台上有幾千筆開團紀錄、幾萬筆訂單，你會發現頁面開始變慢，資料庫查詢數量爆增。這時候你需要的不是加更多伺服器，而是搞懂 Eloquent 的進階查詢技巧——Eager Loading 解決 N+1 問題、Query Scopes 讓查詢條件可重用、Subqueries 處理複雜的報表需求。這一章我們分兩條線走：前半段用 Filament 5 幫揪好買建立開團主儀表板和站台管理員後台，後半段深入 Eloquent 進階查詢，搭配 Laravel Debugbar 實際觀察效能差異。你會發現，寫出「能跑」的程式碼和寫出「跑得快」的程式碼之間，差距往往就在這些細節裡。 ## 為什麼選 Filament：開源、免費、功能完整 Laravel 生態系有好幾套後台管理方案，最常被拿出來比較的是 Filament、Nova、Backpack。先看一張比較表： | 特性 | Filament 5 | Nova 5 | Backpack v7 | | --------------------- | ------------------- | ----------------- | ------------------- | | **授權** | MIT（完全免費） | 付費（Solo $99/site、Pro $199/site） | 免費核心 + 付費 PRO | | **技術棧** | Livewire + Tailwind | Vue 3 + Inertia | Blade + Bootstrap | | **Panel Builder** | 內建 | 內建 | 內建 | | **Form Builder** | 內建 | 內建 | 內建 | | **Table Builder** | 內建 | 內建 | 內建 | | **Dashboard Widgets** | 內建 | 內建 | 付費 PRO | | **Multi-tenancy** | 內建支援 | 需套件 | 需套件 | | **Plugin 生態** | 活躍（200+） | 豐富 | 中等 | | **學習曲線** | 中等 | 低 | 低 | | **自訂性** | 極高 | 高 | 中 | Nova 是 Laravel 官方出品，品質穩定，但它不是開源的——Nova 5 授權分兩階：Solo（年營收 < $20k 個人開發者）$99/site、Pro $199/site，一次性永久授權含一年更新，而且你看不到原始碼，沒辦法深度客製。Backpack v7 以 Blade 元件（Data Components）為核心，技術棧採 Blade + Bootstrap，穩定度高且持續維護。 Filament 5 的優勢很明確： - **完全開源、MIT 授權**——你可以用在商業專案、修改原始碼、不需要付費 - **跟我們的技術棧一致**——Livewire + Tailwind CSS，跟揪好買的前端技術完全相同 - **功能不打折**——Dashboard widgets、Chart、多租戶、通知系統⋯⋯全部免費 - **社群活躍**——GitHub 上超過 30,000 stars，plugin 生態豐富如果你從 JavaScript 世界來，Filament 的角色類似於 React Admin 或 Refine——但它不需要你寫前端程式碼，全部用 PHP 搞定。 ### 但 Filament 不是無條件的最佳解上面那張表我給 Filament 打的分數偏高，所以這裡得誠實補一段，不然你會以為它沒有缺點。它的優勢和短板其實是同一件事的兩面：**Livewire 的 server-driven 架構**。 - **每次互動都要回伺服器一趟。** 你點篩選器、改一個欄位、翻一頁，背後都是一次 AJAX round-trip 回 PHP 重算畫面。後台在公司內網、操作的人坐在你旁邊，這完全無感；但如果管理員在咖啡廳用 4G、或者你做的是欄位超多的大表單即時連動，那個延遲是會被抱怨的。Nova 之所以用 Vue + Inertia、有人寧可自刻 React/Vue SPA admin，理由就在這——純前端互動不用每動一下都等網路。 - **「全部用 PHP 搞定」有個但書。** 內建 component 覆蓋得到的範圍，確實爽到不行；可是一旦你要做的東西超出內建（自訂互動元件、塞一段客製 JS 行為），你還是得回頭懂 Livewire 和 Alpine.js 的心智模型，不是純後端就能搞定。學習曲線那欄我標「中等」，代價就藏在這裡。 - **Panel 大起來要顧效能。** 一個頁面塞太多 Livewire widget、table 又開一堆即時運算的欄位，元件數量上去之後 server 端負擔和回應時間都會浮現，這時候該做的是精簡 widget、把重查詢丟進快取或非同步，而不是無腦加機器。所以選型不是「Filament 贏者全拿」。後台要極致即時互動或得離線跑 → SPA admin 可能更合適；團隊已經買單 Nova 官方支援、不想碰 Livewire → Nova 很穩；需求簡單到連框架都嫌重 → 自刻幾頁 CRUD 反而最快。我這章選 Filament，是因為它對「Laravel 團隊、後台、開源免費」這個組合的命中率最高，不是因為它打趴所有對手。 ## Filament 5 安裝與 Resource 建立 ### 安裝 Filament ```bash composer require filament/filament ``` 安裝 Panel Builder 並設定管理面板： ```bash php artisan filament:install --panels ``` 這條指令會做幾件事： 1. 建立 `app/Providers/Filament/AdminPanelProvider.php`——管理面板的核心設定 2. 發布相關的 assets 和 config 3. 設定 `/admin` 路由 ### 建立管理員帳號 ```bash php artisan make:filament-user ``` 終端會問你姓名、Email、密碼。填完之後，打開瀏覽器連到 `http://localhost:8000/admin`，登入就能看到空白的管理面板。 > **注意：** Filament 預設使用 `users` table 的帳號，但只有被標記為 Filament 使用者的人才能登入後台。你可以在 `AdminPanelProvider` 裡自訂登入邏輯。 ### 建立第一個 Resource Resource 是 Filament 的核心概念——每個 Resource 對應一個 Eloquent Model，自動生成 CRUD 介面： ```bash php artisan make:filament-resource GroupBuy ``` 這會在 `app/Filament/Resources/` 下建立一整組檔案： ```text app/Filament/Resources/ ├── GroupBuyResource.php # 主要設定檔 └── GroupBuyResource/ └── Pages/ ├── CreateGroupBuy.php # 建立頁面 ├── EditGroupBuy.php # 編輯頁面 └── ListGroupBuys.php # 列表頁面 ``` 一條 Artisan 指令，三個完整的 CRUD 頁面就出來了。接下來只需要在 `GroupBuyResource.php` 裡定義表單欄位和列表欄位。 ## CRUD Panel：自動化的管理介面 `GroupBuyResource.php` 的核心結構由三個方法組成：`form()`、`table()`、`getRelations()`。 ### Form Schema：定義表單 ```php schema([ Forms\Components\Section::make('基本資訊') ->schema([ Forms\Components\TextInput::make('title') ->label('團購標題') ->required() ->maxLength(255), Forms\Components\Textarea::make('description') ->label('說明') ->rows(4) ->columnSpanFull(), Forms\Components\Select::make('organizer_id') ->label('開團主') ->relationship('organizer', 'name') ->searchable() ->preload() ->required(), Forms\Components\Select::make('status') ->label('狀態') ->options([ 'draft' => '草稿', 'open' => '開團中', 'closed' => '已截止', 'confirmed' => '已成團', 'cancelled' => '已取消', ]) ->default('draft') ->required(), ])->columns(2), Forms\Components\Section::make('時間與門檻') ->schema([ Forms\Components\DateTimePicker::make('starts_at') ->label('開始時間') ->required(), Forms\Components\DateTimePicker::make('ends_at') ->label('截止時間') ->required() ->after('starts_at'), Forms\Components\TextInput::make('min_participants') ->label('最低成團人數') ->numeric() ->minValue(1) ->required(), Forms\Components\TextInput::make('max_participants') ->label('人數上限') ->numeric() ->nullable(), ])->columns(2), Forms\Components\Section::make('圖片') ->schema([ Forms\Components\FileUpload::make('image') ->label('封面圖') ->image() ->directory('group-buys') ->maxSize(2048), ]), ]); } ``` 幾個值得注意的設計： - **`Section`** 把表單分成邏輯區塊，管理員不用面對一整片欄位 - **`Select::make()->relationship()`** 自動從關聯 Model 撈資料，還支援搜尋 - **`DateTimePicker::make()->after('starts_at')`** 內建驗證，截止時間必須晚於開始時間 - **`FileUpload`** 直接處理檔案上傳，不用自己寫 storage 邏輯 ### Table Schema：定義列表接續同一個 `GroupBuyResource` class： ```php public static function table(Table $table): Table { return $table ->columns([ Tables\Columns\TextColumn::make('title') ->label('標題') ->searchable() ->sortable() ->limit(30), Tables\Columns\TextColumn::make('organizer.name') ->label('開團主') ->searchable() ->sortable(), Tables\Columns\TextColumn::make('status') ->label('狀態') ->badge() ->color(fn (string $state): string => match ($state) { 'draft' => 'gray', 'open' => 'success', 'closed' => 'warning', 'confirmed' => 'primary', 'cancelled' => 'danger', default => 'gray', }) ->formatStateUsing(fn (string $state): string => match ($state) { 'draft' => '草稿', 'open' => '開團中', 'closed' => '已截止', 'confirmed' => '已成團', 'cancelled' => '已取消', default => $state, }), Tables\Columns\TextColumn::make('participants_count') ->label('參加人數') ->counts('participants') ->sortable(), Tables\Columns\TextColumn::make('ends_at') ->label('截止時間') ->dateTime('Y-m-d H:i') ->sortable(), Tables\Columns\TextColumn::make('created_at') ->label('建立時間') ->dateTime('Y-m-d') ->sortable() ->toggleable(isToggledHiddenByDefault: true), ]) ->filters([ Tables\Filters\SelectFilter::make('status') ->label('狀態') ->options([ 'draft' => '草稿', 'open' => '開團中', 'closed' => '已截止', 'confirmed' => '已成團', 'cancelled' => '已取消', ]), Tables\Filters\Filter::make('active') ->label('進行中') ->query(fn ($query) => $query ->where('status', 'open') ->where('ends_at', '>', now()) ), ]) ->actions([ Tables\Actions\EditAction::make(), Tables\Actions\ViewAction::make(), ]) ->bulkActions([ Tables\Actions\BulkActionGroup::make([ Tables\Actions\DeleteBulkAction::make(), ]), ]) ->defaultSort('created_at', 'desc'); } ``` 這段程式碼產出的效果：一個有搜尋、排序、篩選、分頁的完整列表頁面。狀態欄位用 Badge 顯示彩色標籤，參加人數用 `counts()` 自動計算。如果用手寫的方式做這些功能，至少要花兩三天。 ### 關聯管理接續同一個 `GroupBuyResource` class： ```php public static function getRelations(): array { return [ RelationManagers\OrdersRelationManager::class, RelationManagers\ParticipantsRelationManager::class, ]; } ``` Relation Manager 讓你在團購的編輯頁面直接管理訂單和參加者——不用跳到其他頁面。建立方式： ```bash php artisan make:filament-relation-manager GroupBuyResource orders amount ``` ## Dashboard Widgets：資料視覺化空白的 Dashboard 不太有用。Filament 提供了幾種內建 Widget，讓你快速建立數據儀表板。 ### StatsOverview Widget ```bash php artisan make:filament-widget GroupBuyStatsOverview --stats-overview ``` ```php description('所有團購') ->descriptionIcon('heroicon-m-shopping-bag') ->color('primary'), Stat::make('進行中', GroupBuy::where('status', 'open')->count()) ->description('目前開放中的團購') ->descriptionIcon('heroicon-m-arrow-trending-up') ->color('success'), Stat::make( '本月營收', 'NT$ ' . number_format( Order::whereMonth('created_at', now()->month) ->whereYear('created_at', now()->year) ->sum('amount') / 100 ) ) ->description('本月訂單總額') ->descriptionIcon('heroicon-m-currency-dollar') ->color('warning'), ]; } } ``` 三張統計卡片就出現在 Dashboard 頂端——總團購數、進行中的團購、本月營收。不用寫任何前端 JavaScript。 ### Chart Widget ```bash php artisan make:filament-widget GroupBuyChart --chart ``` ```php map(function ($weeksAgo) { $start = now()->subWeeks($weeksAgo)->startOfWeek(); $end = $start->copy()->endOfWeek(); return [ 'week' => $start->format('m/d'), 'count' => GroupBuy::whereBetween('created_at', [$start, $end])->count(), ]; }); return [ 'datasets' => [ [ 'label' => '新增團購', 'data' => $data->pluck('count')->toArray(), 'borderColor' => '#6366f1', 'backgroundColor' => 'rgba(99, 102, 241, 0.1)', 'fill' => true, ], ], 'labels' => $data->pluck('week')->toArray(), ]; } protected function getType(): string { return 'line'; // 支援 'line', 'bar', 'pie', 'doughnut' 等 } } ``` Widget 預設會出現在 Dashboard 頁面。你也可以用 `$sort` 屬性控制顯示順序——數字越小越上面。 ### 自訂 Widget 範例除了統計和圖表，你也可以做完全自訂的 Widget，例如顯示「最近即將截止的團購」： ```bash php artisan make:filament-widget ExpiringGroupBuys ``` ```php query( GroupBuy::where('status', 'open') ->where('ends_at', '<=', now()->addDays(3)) ->where('ends_at', '>', now()) ->orderBy('ends_at') ) ->columns([ Tables\Columns\TextColumn::make('title') ->label('標題'), Tables\Columns\TextColumn::make('organizer.name') ->label('開團主'), Tables\Columns\TextColumn::make('ends_at') ->label('截止時間') ->dateTime('Y-m-d H:i') ->color('danger'), Tables\Columns\TextColumn::make('participants_count') ->label('目前人數') ->counts('participants'), ]) ->paginated(false); } } ``` 這個 Table Widget 直接在 Dashboard 上顯示一個迷你列表，讓管理員一眼掌握哪些團購快截止了。 ## 進階 Eloquent：Eager Loading 解決 N+1 後台蓋好了，現在來處理效能問題。Eloquent 最常見、也最容易踩到的效能地雷就是 **N+1 查詢問題**。（Eloquent 關聯的基礎用法見[第四章](/blog/laravel-guide-eloquent-orm-models/)） ### 什麼是 N+1 問題假設你要顯示「所有團購 + 每個團購的開團主名稱」： ```php // ❌ 這段程式碼有 N+1 問題 $groupBuys = GroupBuy::all(); // 1 次查詢：SELECT * FROM group_buys foreach ($groupBuys as $groupBuy) { echo $groupBuy->organizer->name; // 每次迴圈都會觸發一次查詢： // SELECT * FROM users WHERE id = ? } ``` 如果有 100 筆團購，這段程式碼會執行 **101 次查詢**（1 次取所有團購 + 100 次取開團主）。這就是 N+1 問題——1 次取清單、N 次取關聯。你可能覺得 101 次查詢也還好？試試看 1000 筆團購——就是 1001 次查詢。再加上每個團購要顯示參加人數，那就是 2001 次。頁面直接從 200ms 變成 5 秒。 ### Eager Loading：一次把關聯資料撈好 ```php // ✅ 用 with() 做 Eager Loading $groupBuys = GroupBuy::with('organizer')->get(); // 只有 2 次查詢： // SELECT * FROM group_buys // SELECT * FROM users WHERE id IN (1, 2, 3, ..., 100) foreach ($groupBuys as $groupBuy) { echo $groupBuy->organizer->name; // 不會再觸發查詢 } ``` `with('organizer')` 會一次把所有需要的 `users` 撈回來，用 `WHERE IN` 而不是一筆一筆查。從 101 次查詢變成 2 次。你可以同時 Eager Load 多個關聯，甚至是巢狀關聯： ```php // 多個關聯 $groupBuys = GroupBuy::with(['organizer', 'participants', 'products'])->get(); // 巢狀關聯：團購 → 訂單 → 訂單項目 $groupBuys = GroupBuy::with('orders.items')->get(); // 限制 Eager Loading 的欄位（節省記憶體） $groupBuys = GroupBuy::with('organizer:id,name,email')->get(); ``` ### withCount：只要數量不要全部資料有時你只需要知道「有幾個」，不需要把整個關聯載入： ```php $groupBuys = GroupBuy::withCount('participants')->get(); foreach ($groupBuys as $groupBuy) { echo $groupBuy->participants_count; // 自動加上 _count 後綴 } // 只有 1 次查詢（用 subquery 計算 count） ``` `withCount` 不會把所有參加者的資料載入記憶體——它只在 SQL 層面用子查詢算出數量。適合用在列表頁只需要顯示數字的場景。若需要一次處理大批量資料，記憶體管理有更多眉角，可參考大量資料的記憶體陷阱。 ### 前後對比 | 情境 | 沒有 Eager Loading | 有 Eager Loading | 改善 | | ---------------------------- | ------------------ | --------------------- | -------------- | | 100 筆團購 + 開團主 | 101 次查詢 | 2 次查詢 | **98% 減少** | | 100 筆團購 + 開團主 + 參加者 | 201 次查詢 | 3 次查詢 | **98.5% 減少** | | 100 筆團購 + 參加人數 | 101 次查詢 | 1 次查詢（withCount） | **99% 減少** | ### 開發模式下禁止 Lazy Loading 為了在開發階段就發現 N+1 問題，可以在 `AppServiceProvider` 裡設定： ```php // app/Providers/AppServiceProvider.php use Illuminate\Database\Eloquent\Model; public function boot(): void { // 開發環境：禁止 Lazy Loading，直接拋出例外 Model::preventLazyLoading(! app()->isProduction()); } ``` 加了這行之後，任何沒有預先 Eager Load 的關聯存取都會直接拋出 `LazyLoadingViolationException`。等於是在開發階段強制你用 `with()` 載入所有需要的關聯。到了正式環境則自動關閉，避免意外中斷服務。 ## Query Scopes：可重用的查詢條件在揪好買裡，你會一直重複寫一些查詢條件：「只要開團中的」、「只要還沒截止的」、「只要某個開團主的」。與其每次都手寫 `where()` 鏈，不如把它們封裝成 Scope。 ### Local Scopes 在 Model 裡定義 `scope` 開頭的方法： ```php where('status', 'open') ->where('ends_at', '>', now()); } /** * 篩選：已截止（超過截止時間或被手動關閉） */ public function scopeExpired(Builder $query): void { $query->where(function ($q) { $q->where('ends_at', '<=', now()) ->orWhere('status', 'closed'); }); } /** * 篩選：特定開團主的團購 */ public function scopeByOrganizer(Builder $query, int $userId): void { $query->where('organizer_id', $userId); } /** * 篩選：已達成團門檻 */ public function scopeReachedMinimum(Builder $query): void { $query->whereColumn( 'participants_count', '>=', 'min_participants' ); } } ``` 使用起來非常乾淨，而且可以鏈式組合： ```php // 取得所有進行中的團購 $openGroupBuys = GroupBuy::open()->get(); // 某個使用者的進行中團購 $myOpenGroupBuys = GroupBuy::open() ->byOrganizer(auth()->id()) ->get(); // 已截止但還沒成團的（可能需要退款） $expiredNotConfirmed = GroupBuy::expired() ->where('status', '!=', 'confirmed') ->get(); // 搭配 Eager Loading $openWithDetails = GroupBuy::open() ->with(['organizer', 'products']) ->withCount('participants') ->latest() ->paginate(20); ``` Scope 的好處是**查詢邏輯只定義一次**。如果哪天「開團中」的定義改了（例如加了「需要通過審核」這個條件），你只需要改 `scopeOpen()` 一個地方，所有使用它的地方自動更新。 ### Global Scopes Global Scope 會自動套用在所有查詢上，最常見的用途是軟刪除（`SoftDeletes` trait 就是透過 Global Scope 實現的）。你也可以自訂： ```php // 自動排除被封鎖的開團主的團購 use Illuminate\Database\Eloquent\Scope; class ExcludeBannedOrganizersScope implements Scope { public function apply(Builder $builder, Model $model): void { $builder->whereHas('organizer', fn ($q) => $q->where('is_banned', false)); } } ``` Global Scope 很強大，但也很容易造成「為什麼查不到那筆資料？」的困惑。建議只在非常確定的情境下使用，大多數時候 Local Scope 就夠了。 ## Subqueries：複雜報表查詢有些報表需求光靠 `with()` 和 `withCount()` 搞不定——例如「每個開團主的累計營收排行」。這時候就需要子查詢。 ### addSelect + Subquery ```php use App\Models\User; use App\Models\Order; use Illuminate\Database\Eloquent\Builder; // 每個開團主的累計營收 $organizers = User::query() ->addSelect([ 'total_revenue' => Order::query() ->selectRaw('SUM(amount)') ->whereColumn('orders.group_buy_id', 'group_buys.id') ->whereIn('orders.group_buy_id', function ($query) { $query->select('id') ->from('group_buys') ->whereColumn('group_buys.organizer_id', 'users.id'); }), ]) ->addSelect([ 'group_buy_count' => GroupBuy::query() ->selectRaw('COUNT(*)') ->whereColumn('group_buys.organizer_id', 'users.id'), ]) ->having('group_buy_count', '>', 0) ->orderByDesc('total_revenue') ->get(); ``` 這段查詢在 SQL 層面就算好了每個開團主的營收和開團數，不需要在 PHP 端做 N 次迴圈計算。 ### 簡化版：用 withSum Laravel 其實提供了更簡潔的語法處理常見的聚合需求： ```php // 每個團購的總訂單金額 $groupBuys = GroupBuy::withSum('orders', 'amount') ->withCount('participants') ->orderByDesc('orders_sum_amount') ->get(); foreach ($groupBuys as $groupBuy) { echo $groupBuy->orders_sum_amount; // 自動命名：{relation}_sum_{column} echo $groupBuy->participants_count; } ``` `withSum()`、`withAvg()`、`withMin()`、`withMax()` 這幾個方法底層都是用子查詢實現的，語法上比手寫 `addSelect()` 簡潔得多。 ### 什麼時候用 Raw SQL Query Builder 能處理 90% 的需求，但偶爾你會遇到非常複雜的報表查詢——多層 JOIN、窗口函數、CTE（Common Table Expression）。這時候不要硬用 Query Builder，直接寫 Raw SQL 反而更清楚： ```php use Illuminate\Support\Facades\DB; // 每週營收趨勢（用窗口函數計算移動平均） $weeklyRevenue = DB::select(" SELECT DATE_FORMAT(created_at, '%Y-%u') AS week, SUM(amount) AS revenue, AVG(SUM(amount)) OVER ( ORDER BY DATE_FORMAT(created_at, '%Y-%u') ROWS BETWEEN 3 PRECEDING AND CURRENT ROW ) AS moving_avg FROM orders WHERE created_at >= ? GROUP BY week ORDER BY week ", [now()->subMonths(3)]); ``` 經驗法則：**如果你花超過 10 分鐘在組 Query Builder 鏈，而且結果還不太對，那就直接寫 SQL。** 可讀性比「全部用 Eloquent」更重要。Raw SQL 的缺點是失去了資料庫引擎抽象（SQLite 和 MySQL 語法不完全相同），但在報表查詢這種場景，你通常只會在一種資料庫上跑。 ## Laravel Debugbar：效能偵測利器前面講了這麼多最佳化技巧，但怎麼確認真的有效？靠感覺不行——你需要實際看到查詢數量和執行時間。Laravel Debugbar 就是幹這個的。 ### 安裝 ```bash composer require fruitcake/laravel-debugbar --dev ``` `--dev` 很重要——Debugbar 只應該在開發環境使用。安裝後它會自動啟用（當 `APP_DEBUG=true` 時），在頁面底部出現一條黑色的工具列。 ### 看什麼 Debugbar 提供的資訊非常豐富，但對效能最佳化來說，最重要的是這幾個 tab： **Queries tab（查詢）：** - 顯示每個頁面執行了多少次 SQL 查詢 - 每次查詢的完整 SQL 語句 - 每次查詢的執行時間 - **重複查詢會被標記出來**——這就是 N+1 問題的最直接證據 **Timeline tab（時間軸）：** - 整個 request 的生命週期，從 boot 到 response - 可以看到時間花在哪裡——是 SQL 慢還是 PHP 慢 **Memory tab（記憶體）：** - 這個 request 使用了多少記憶體 - 如果你用 `all()` 載入了一萬筆資料⋯⋯這裡的數字會告訴你問題有多嚴重 ### 實戰：觀察 N+1 修復效果以一個灌了 50 筆團購的列表頁為例，修復 N+1 前後的 Debugbar 數據會像這樣： **修復前：** - Queries: 52 queries（1 + 50 筆團購 × 1 取開團主） - Time: 320ms - Memory: 14 MB **修復後（加了 `with('organizer')`）：** - Queries: 2 queries - Time: 45ms - Memory: 8 MB 差距一目了然。養成習慣：每次寫完一個頁面，開 Debugbar 看一眼查詢數量。超過 10 次的，八成有 N+1 可以修。 > **提醒：** Debugbar 絕對不能部署到正式環境。它會暴露你的 SQL 查詢、環境變數、路由結構——等於是把所有內部資訊攤開給攻擊者看。`--dev` 裝、`APP_DEBUG=false` 就會自動隱藏，但還是建議在部署前確認一下。 ## 實作：揪好買的開團主與管理員後台到目前為止我們學了 Filament 和進階查詢的個別技巧，現在把它們串起來，為揪好買建立完整的後台系統。 ### 管理員後台：完整 Resource 體系管理員需要管理三個核心資源：團購、訂單、使用者。 ```bash php artisan make:filament-resource GroupBuy --generate php artisan make:filament-resource Order --generate php artisan make:filament-resource User --generate ``` `--generate` flag 會根據 Model 的資料表結構自動產生表單和列表欄位——先自動生成，再手動微調，比從空白開始快得多。管理面板的設定在 `AdminPanelProvider`： ```php default() ->id('admin') ->path('admin') ->login() ->colors([ 'primary' => Color::Indigo, ]) ->discoverResources( in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources' ) ->discoverPages( in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages' ) ->widgets([ GroupBuyStatsOverview::class, GroupBuyChart::class, ExpiringGroupBuys::class, ]) ->middleware([ // ...預設 middleware ]) ->authMiddleware([ // 確保只有管理員能存取 ]); } } ``` ### 開團主儀表板：第二個 Panel 揪好買的開團主不是管理員，但他們需要看到自己的開團統計、管理自己的團購。Filament 5 支援**多 Panel**——你可以為不同角色建立不同的後台。 ```bash php artisan make:filament-panel organizer ``` 這會建立 `app/Providers/Filament/OrganizerPanelProvider.php`： ```php id('organizer') ->path('organizer') // 路由前綴：/organizer ->login() ->colors([ 'primary' => Color::Emerald, // 用不同主色區分 ]) ->discoverResources( in: app_path('Filament/Organizer/Resources'), for: 'App\\Filament\\Organizer\\Resources' ) ->discoverPages( in: app_path('Filament/Organizer/Pages'), for: 'App\\Filament\\Organizer\\Pages' ); } } ``` 接著為開團主建立專屬的 Resource，只顯示自己的資料： ```php byOrganizer(auth()->id()) // 用前面定義的 scope ->withCount('participants') ->withSum('orders', 'amount'); } public static function table(Table $table): Table { return $table ->columns([ Tables\Columns\TextColumn::make('title') ->label('標題') ->searchable(), Tables\Columns\TextColumn::make('status') ->label('狀態') ->badge() ->color(fn (string $state): string => match ($state) { 'draft' => 'gray', 'open' => 'success', 'closed' => 'warning', 'confirmed' => 'primary', default => 'gray', }), Tables\Columns\TextColumn::make('participants_count') ->label('參加人數') ->sortable(), Tables\Columns\TextColumn::make('orders_sum_amount') ->label('訂單總額') ->money('TWD') ->sortable(), Tables\Columns\TextColumn::make('ends_at') ->label('截止時間') ->dateTime('Y-m-d H:i'), ]) ->defaultSort('created_at', 'desc'); } // ...form() 和其他設定 } ``` 注意 `getEloquentQuery()` 的覆寫——這是 Filament 的資料隔離機制。開團主只看得到自己的團購，就算手動改 URL 中的 ID 也拿不到別人的資料。搭配前面定義的 `scopeByOrganizer()`，query 條件清楚又好維護。 ### 自訂 Dashboard 頁面開團主的 Dashboard 跟管理員不同——他們更關心自己的數據。你可以建立自訂頁面： ```bash php artisan make:filament-page OrganizerDashboard --panel=organizer ``` ```php id(); return [ 'totalGroupBuys' => GroupBuy::byOrganizer($userId)->count(), 'activeGroupBuys' => GroupBuy::byOrganizer($userId)->open()->count(), 'totalRevenue' => GroupBuy::byOrganizer($userId) ->withSum('orders', 'amount') ->get() ->sum('orders_sum_amount'), 'recentGroupBuys' => GroupBuy::byOrganizer($userId) ->with('participants') ->withCount('participants') ->latest() ->take(5) ->get(), ]; } } ``` 看到了嗎？`byOrganizer()`、`open()`、`withCount()`、`withSum()`——這一章學的所有技巧全部用上了。Query Scope 讓查詢條件可讀又可重用，Eager Loading 確保不會有 N+1 問題，Subquery 聚合讓報表數據在 SQL 層面就算好。 ## 小結：後台不用從零寫起這一章我們同時搞定了兩件事：用 Filament 5 快速建立後台介面，以及用 Eloquent 進階查詢確保後台跑得快。回顧一下重點： - **Filament 5** 是 Laravel 生態最成熟的開源後台方案——Resource 自動產生 CRUD、Widget 做 Dashboard、多 Panel 支援不同角色 - **Eager Loading**（`with()`）解決 N+1 問題，`withCount()` 和 `withSum()` 處理聚合需求 - **Query Scopes** 把查詢條件封裝成可重用的方法，`scopeOpen()`、`scopeByOrganizer()` 讓程式碼簡潔又好維護 - **Subqueries** 處理複雜報表需求，知道什麼時候該用 Raw SQL 也是一種能力 - **Debugbar** 是開發階段的效能照妖鏡，養成每個頁面都看一眼查詢數量的習慣 - **`preventLazyLoading()`** 在開發環境強制杜絕 N+1，等於是編譯時期就抓到效能問題後台和效能是同一件事的兩面——有了漂亮的管理介面，但背後查詢跑得慢，管理員一樣會抱怨。反過來說，查詢最佳化做得再好，沒有 UI 也沒人看得到。兩條線必須同時顧。下一章我們進入測試。寫到現在，揪好買已經有使用者系統、團購邏輯、付款流程、通知系統、後台管理⋯⋯功能越多，改壞東西的風險就越高。[**第十三章「測試不是選配：用 Pest 寫出有信心的 Laravel 程式」**](/blog/laravel-guide-testing-pest-ci/)會教你用 Pest 為核心流程寫完整測試，搭配 GitHub Actions 讓每次 Push 都自動驗證——從此你可以安心重構，不怕改一處壞三處。

RESTful API 與 Sanctum：讓 LINE Bot 也能開團

Tue, 13 May 2025 00:00:00 GMT

你的網頁應用做得很好，使用者可以開團、跟團、下單。但現實世界不只有瀏覽器。有人想用手機 App 開團，有人想在 LINE 群組裡直接查詢團購狀態，還有合作店家想透過程式自動同步訂單資料。這些需求都指向同一件事：你需要 API。 RESTful API 是讓你的後端從「只服務網頁」進化到「服務所有人」的關鍵。Laravel 這部分該有的都有——API Routes、API Resources、Sanctum Token 認證。你不需要另外架一套 API Server，同一個 Laravel 專案就能同時服務網頁和 API 客戶端。這一章我們要把揪好買的核心功能——開團列表、跟團操作、訂單查詢——全部包裝成 RESTful API，用 Sanctum 做 Token 認證保護端點，設定 Rate Limiting 防止濫用，還會示範 LINE Bot 整合的概念。一套後端程式碼，同時餵給多個前端消費者。 ## 為什麼需要 API：不只是網頁的世界前十章我們做的事情，都是「使用者打開瀏覽器 → 伺服器回傳 HTML」。這在桌面端的體驗很好，但想想這些場景： - **手機 App**：你的合作夥伴想做一個揪好買的 iOS/Android App，它不需要 HTML，它需要 JSON 資料 - **LINE Bot**：台灣人都在用 LINE，如果在群組裡打「@揪好買查團購」就能看到最新團購列表，多方便？ - **第三方整合**：合作店家的 ERP 系統想自動抓訂單資料，它不會開瀏覽器，它用程式 call API - **SPA 前端**：如果你的前端團隊想用 React 或 Vue 重寫介面，它們只需要跟 API 溝通 - **自動化腳本**：你自己想寫一個 cron job 在截止時間自動關閉團購，用 API 最乾淨這些消費者有一個共通點：它們不需要 HTML，它們需要**結構化的資料**。而 JSON 就是這個通用語言。 ``` 瀏覽器使用者 → routes/web.php → 回傳 HTML（Blade view）手機 App → routes/api.php → 回傳 JSON LINE Bot → routes/api.php → 回傳 JSON 第三方系統 → routes/api.php → 回傳 JSON ``` API 不是什麼高深的東西——它就是你的後端用 JSON 格式說話，讓任何程式都能聽懂。 ## API Routes：api.php 與 web.php 的差異 ### 安裝 API 路由重要的一點：**Laravel 12 預設不包含 `routes/api.php`**。這是刻意的設計——不是每個專案都需要 API。要啟用它，跑一行指令： ```bash php artisan install:api ``` 這個指令幫你做了三件事： 1. 建立 `routes/api.php` 檔案 2. 安裝 **Laravel Sanctum**（Token 認證套件） 3. 執行 Sanctum 需要的 migration（`personal_access_tokens` 表）裝完後你會在 `routes/api.php` 裡看到這樣的起始內容： ```php user(); })->middleware('auth:sanctum'); ``` ### web.php vs api.php：兩個世界這兩個路由檔案的差異不只是「放在不同檔案」而已，它們跑在完全不同的 middleware 環境裡： | 特性 | web.php | api.php | |------|---------|---------| | URL 前綴 | 無（`/group-buys`） | `/api`（`/api/group-buys`） | | Session | 有（記住登入狀態） | 無（Stateless） | | CSRF 保護 | 有（`@csrf`） | 無（不需要） | | Cookie | 有 | 無 | | 認證方式 | Session-based（瀏覽器） | Token-based（Sanctum） | | Rate Limiting | 無預設 | `throttle:api`（每分鐘 60 次） | | 回傳格式 | HTML（Blade view） | JSON | 關鍵差異是**stateless**：每個 API request 都是獨立的，伺服器不會「記得」你是誰。每次請求都要帶著 Token 來證明身份。這就像去便利商店——你每次都要出示會員卡，店員不會記得你昨天來過。 ### 定義 API 路由 ```php // routes/api.php use App\Http\Controllers\Api\GroupBuyController; // 公開端點——任何人都能呼叫 Route::get('/group-buys', [GroupBuyController::class, 'index']); Route::get('/group-buys/{groupBuy}', [GroupBuyController::class, 'show']); // 受保護端點——需要 Sanctum Token Route::middleware('auth:sanctum')->group(function () { Route::post('/group-buys', [GroupBuyController::class, 'store']); Route::post('/group-buys/{groupBuy}/join', [GroupBuyController::class, 'join']); Route::get('/my/orders', [GroupBuyController::class, 'myOrders']); }); ``` 注意我把 API Controller 放在 `App\Http\Controllers\Api\` 命名空間下——跟 web Controller 分開，讓結構清楚。 ```bash php artisan make:controller Api/GroupBuyController --api ``` `--api` flag 會生成只有 `index`、`store`、`show`、`update`、`destroy` 五個方法的 Controller（沒有 `create` 和 `edit`，因為 API 不需要「表單頁面」）。 ## API Resource：優雅的 JSON 轉換直接在 Controller 裡 `return $groupBuy;` 可以嗎？技術上可以，但你會把整個 Model——包括 `created_at`、`updated_at`、甚至 `password`——全部暴露出去。API Resource 讓你精準控制「回傳哪些欄位、長什麼格式」。 ### 建立 Resource ```bash php artisan make:resource GroupBuyResource ``` ```php $this->id, 'title' => $this->title, 'description' => $this->description, 'target_amount'=> $this->target_amount, 'current_amount'=> $this->current_amount, 'status' => $this->status->value, 'deadline' => $this->deadline->toIso8601String(), 'organizer' => [ 'id' => $this->user->id, 'name' => $this->user->name, ], 'participants_count' => $this->participants_count, 'created_at' => $this->created_at->toIso8601String(), ]; } } ``` 注意幾件事： - **只暴露需要的欄位**——`user_id` 換成巢狀的 `organizer` 物件，更直覺 - **日期用 ISO 8601 格式**——`2026-08-10T08:00:00+08:00`，前端好 parse - **不暴露 `updated_at`**——API 消費者不需要這個 - **Enum 轉成字串**——`$this->status->value` 而不是整個 Enum 物件 ### 在 Controller 裡使用 ```php use App\Http\Resources\GroupBuyResource; class GroupBuyController extends Controller { public function index() { $groupBuys = GroupBuy::withCount('participants') ->where('status', 'open') ->latest() ->paginate(15); return GroupBuyResource::collection($groupBuys); } public function show(GroupBuy $groupBuy) { $groupBuy->loadCount('participants'); return new GroupBuyResource($groupBuy); } } ``` ### 回傳的 JSON 長這樣單一資源： ```json { "data": { "id": 42, "title": "芒果季團購", "description": "玉井愛文芒果，產地直送", "target_amount": 30, "current_amount": 18, "status": "open", "deadline": "2026-08-15T23:59:59+08:00", "organizer": { "id": 7, "name": "小陳" }, "participants_count": 18, "created_at": "2026-08-01T10:30:00+08:00" } } ``` 列表（搭配 Pagination）： ```json { "data": [ { "id": 42, "title": "芒果季團購", ... }, { "id": 41, "title": "阿里山烏龍茶", ... } ], "links": { "first": "http://localhost/api/group-buys?page=1", "last": "http://localhost/api/group-buys?page=5", "prev": null, "next": "http://localhost/api/group-buys?page=2" }, "meta": { "current_page": 1, "last_page": 5, "per_page": 15, "total": 67 } } ``` Laravel 自動把 `paginate()` 的結果包成帶 `links` 和 `meta` 的結構——前端不用自己算分頁。 ### ResourceCollection：集合層級的客製化如果你想在集合回傳時加額外資訊（比如統計數據），可以建一個 Collection class： ```bash php artisan make:resource GroupBuyCollection ``` ```php class GroupBuyCollection extends ResourceCollection { public function toArray(Request $request): array { return [ 'data' => $this->collection, 'stats' => [ 'total_open' => GroupBuy::where('status', 'open')->count(), ], ]; } } ``` > **安全提醒：** Resource 是你 API 的門面。永遠不要暴露 `password`、`remember_token`、內部的 `pivot` 資料，或任何使用者不該看到的欄位。養成習慣——在 `toArray()` 裡明確列出每一個欄位，而不是用 `parent::toArray()` 全部丟出去。 ## Sanctum Token Authentication [第六章我們用 Session 做瀏覽器的認證](/blog/laravel-guide-auth-breeze-authorization/)。但 API 客戶端（手機 App、LINE Bot、第三方系統）不用瀏覽器，沒有 Cookie 和 Session。它們需要的是 **Token-based 認證**：每次請求都在 Header 帶一個 token，伺服器驗證這個 token 來識別身份。 ### Token 認證的流程 ``` 1. 使用者用帳號密碼呼叫 /api/login 2. 伺服器驗證成功，回傳一個 token 3. 之後的每個請求，在 Header 帶上：Authorization: Bearer 4. 伺服器看到 token，就知道你是誰 5. 登出時，伺服器把 token 刪掉 ``` ### 建立登入端點 ```php // routes/api.php use App\Http\Controllers\Api\AuthController; Route::post('/register', [AuthController::class, 'register']); Route::post('/login', [AuthController::class, 'login']); Route::middleware('auth:sanctum')->group(function () { Route::post('/logout', [AuthController::class, 'logout']); Route::get('/user', [AuthController::class, 'user']); }); ``` ```php validate([ 'name' => 'required|string|max:255', 'email' => 'required|string|email|unique:users', 'password' => 'required|string|min:8|confirmed', ]); $user = User::create([ 'name' => $validated['name'], 'email' => $validated['email'], 'password' => Hash::make($validated['password']), ]); $token = $user->createToken('api-token')->plainTextToken; return response()->json([ 'user' => $user->only('id', 'name', 'email'), 'token' => $token, ], 201); } public function login(Request $request) { $request->validate([ 'email' => 'required|email', 'password' => 'required', ]); $user = User::where('email', $request->email)->first(); if (! $user || ! Hash::check($request->password, $user->password)) { throw ValidationException::withMessages([ 'email' => ['帳號或密碼錯誤。'], ]); } $token = $user->createToken('api-token')->plainTextToken; return response()->json([ 'user' => $user->only('id', 'name', 'email'), 'token' => $token, ]); } public function logout(Request $request) { // 刪除當前使用的 token $request->user()->currentAccessToken()->delete(); return response()->json(['message' => '已登出']); } public function user(Request $request) { return response()->json($request->user()->only('id', 'name', 'email', 'role')); } } ``` `createToken()` 回傳的 `plainTextToken` 長這樣：`1|abc123def456...`，前面的數字是 token ID，後面是實際的 token 值。**這個值只會在建立時出現一次**——資料庫裡存的是 hash 過的版本。告訴你的 API 消費者：拿到 token 就要存好。 ### Token Abilities（權限）不是每個 token 都應該有全部權限。例如，LINE Bot 只需要「讀取」的權限，不該能刪除團購： ```php // 建立有限權限的 token $token = $user->createToken('line-bot', ['group-buys:read']); // 建立完整權限的 token $token = $user->createToken('mobile-app', ['*']); ``` 在路由裡檢查 ability： ```php Route::middleware(['auth:sanctum', 'ability:group-buys:read'])->group(function () { Route::get('/group-buys', [GroupBuyController::class, 'index']); Route::get('/group-buys/{groupBuy}', [GroupBuyController::class, 'show']); }); Route::middleware(['auth:sanctum', 'ability:group-buys:write'])->group(function () { Route::post('/group-buys', [GroupBuyController::class, 'store']); Route::delete('/group-buys/{groupBuy}', [GroupBuyController::class, 'destroy']); }); ``` 需要在 `bootstrap/app.php` 裡註冊 ability middleware： ```php use Laravel\Sanctum\Http\Middleware\CheckAbilities; use Laravel\Sanctum\Http\Middleware\CheckForAnyAbility; ->withMiddleware(function (Middleware $middleware) { $middleware->alias([ 'abilities' => CheckAbilities::class, // 必須擁有「全部」列出的 abilities 'ability' => CheckForAnyAbility::class, // 擁有「其中一個」就通過 ]); }) ``` ### 撤銷 Token ```php // 撤銷當前 token $request->user()->currentAccessToken()->delete(); // 撤銷所有 token（強制所有裝置登出） $request->user()->tokens()->delete(); // 撤銷特定 token $request->user()->tokens()->where('id', $tokenId)->delete(); ``` ### Sanctum vs JWT 你可能聽過 JWT（JSON Web Token）。在 Laravel 生態系裡，Sanctum 和 JWT 的差異是： | 特性 | Sanctum | JWT（tymon/jwt-auth） | |------|---------|----------------------| | 官方維護 | 是（Laravel 團隊） | 否（社群套件） | | Token 儲存 | 資料庫 | 無狀態（Token 自帶資訊） | | 撤銷 Token | 簡單（刪資料庫記錄） | 複雜（需要黑名單機制） | | 適用場景 | SPA、手機 App、第三方 | 微服務間通訊 | | 複雜度 | 低 | 中高 | | 建議 | 90% 的專案用這個 | 除非有跨服務需求 | 除非你在做微服務架構，否則 Sanctum 就是正確的選擇。官方維護、設定簡單、能撤銷 token，沒什麼理由用 JWT。 ## Rate Limiting：保護你的 API 公開的 API 如果沒有速率限制，一個寫壞的爬蟲或惡意攻擊就能把你的伺服器打掛。Rate Limiting 限制每個使用者（或 IP）在一段時間內能發多少請求。 ### 預設設定 `php artisan install:api` 安裝後，`api.php` 的路由自動帶 `throttle:api` middleware。預設限制在 `bootstrap/app.php` 裡： ```php ->withMiddleware(function (Middleware $middleware) { $middleware->throttleApi(); // 等同於 throttle:api，預設 60 次/分鐘 }) ``` ### 自訂 Rate Limiter 在 `AppServiceProvider` 的 `boot()` 方法裡定義： ```php use Illuminate\Cache\RateLimiting\Limit; use Illuminate\Support\Facades\RateLimiter; use Illuminate\Http\Request; public function boot(): void { // 已登入使用者：每分鐘 120 次 // 未登入（靠 IP）：每分鐘 30 次 RateLimiter::for('api', function (Request $request) { return $request->user() ? Limit::perMinute(120)->by($request->user()->id) : Limit::perMinute(30)->by($request->ip()); }); // 登入端點特別嚴格：每分鐘 5 次（防暴力破解） RateLimiter::for('login', function (Request $request) { return Limit::perMinute(5)->by($request->ip()); }); } ``` 套用到路由： ```php Route::post('/login', [AuthController::class, 'login']) ->middleware('throttle:login'); ``` ### Rate Limit Response Headers Laravel 自動在回傳的 HTTP Header 裡告訴客戶端剩餘額度： ``` X-RateLimit-Limit: 120 X-RateLimit-Remaining: 117 Retry-After: 58 ← 超過限制時，告訴你幾秒後可以再試 ``` ### 自訂超過限制時的回應 ```php RateLimiter::for('api', function (Request $request) { return Limit::perMinute(60) ->by($request->user()?->id ?: $request->ip()) ->response(function (Request $request, array $headers) { return response()->json([ 'message' => '請求太頻繁，請稍後再試。', ], 429, $headers); }); }); ``` ## API 版本管理策略 API 一旦發布出去，就有人在用。你改了回傳格式，人家的 App 就壞了。版本管理讓你能安全地升級 API 而不影響現有客戶端。 ### 方法一：URL 前綴（最常見） ```php // routes/api.php // v1 版本 Route::prefix('v1')->group(function () { Route::get('/group-buys', [V1\GroupBuyController::class, 'index']); }); // v2 版本（未來） Route::prefix('v2')->group(function () { Route::get('/group-buys', [V2\GroupBuyController::class, 'index']); }); ``` 呼叫方式：`GET /api/v1/group-buys` ### 方法二：Header 版本控制 ``` GET /api/group-buys Accept: application/vnd.jiuhaomai.v1+json ``` 比較少見，但更「正統」。 ### 務實的建議 **不要過早加版本號**。如果你的 API 還在開發階段、消費者只有自己的團隊，直接用 `/api/group-buys` 就好。等到以下情況才加 versioning： - 有外部第三方在用你的 API - 你需要做 breaking change（欄位改名、移除、格式變更） - 你需要同時維護新舊版本加版本號的成本是真實的：你要維護兩份 Controller、兩份 Resource、兩份文件。YAGNI（You Ain't Gonna Need It）——等需要的時候再加。 ## API 文件化：Scramble 好的 API 沒有文件等於不存在。你的 API 消費者不該來看你的程式碼才知道怎麼呼叫端點。Scramble 是一個能直接從 Laravel 程式碼自動生成 OpenAPI（Swagger）文件的套件——不需要寫任何註解或額外設定。 ### 安裝 ```bash composer require dedoc/scramble ``` 就這樣。打開瀏覽器： ``` http://localhost:8000/docs/api ``` 你會看到一個互動式的 API 文件頁面，自動列出所有端點、參數類型、回傳格式。它是透過分析你的 Route、Controller、FormRequest、Resource 來推斷結構的。 ### 為什麼推薦 Scramble - **零設定**：裝完就能用，不用在程式碼裡寫一堆 annotation - **自動同步**：程式碼改了文件就改了，不會有文件過期的問題 - **OpenAPI 標準**：輸出的是標準的 OpenAPI 3.x spec，可以匯入 Postman、Insomnia - **互動式測試**：在文件頁面直接送請求測試如果你需要更細緻的文件控制（加範例、加說明），也可以搭配 PHPDoc 補充： ```php /** * 取得團購列表 * * 回傳所有進行中的團購，支援分頁。 */ public function index() { // ... } ``` ## CORS 設定：跨域請求處理如果你的 React 或 Vue 前端跑在 `localhost:3000`，API 跑在 `localhost:8000`，瀏覽器會擋住跨域請求。這不是 bug，是瀏覽器的安全機制——**CORS**（Cross-Origin Resource Sharing）。 ### 什麼是 CORS 當瀏覽器從 A 網域發請求到 B 網域時，B 必須在 Response Header 裡明確說「我允許 A 來存取」。如果沒有這些 Header，瀏覽器會直接擋掉回應。 ``` 前端（localhost:3000）→ 請求 → API（localhost:8000） ↓ API 回傳 CORS Header: Access-Control-Allow-Origin: http://localhost:3000 ↓ 瀏覽器檢查 Header → OK → 前端拿到資料 ``` ### Laravel 的 CORS 設定 Laravel 內建 CORS 處理（由全域 middleware 中的 `HandleCors` 自動處理，不發佈設定檔也能運作）。Laravel 12 預設**不會**發佈這個設定檔，需先執行 `php artisan config:publish cors`，才會在 `config/cors.php` 產生它，接著就能編輯： ```php return [ 'paths' => ['api/*'], // 哪些路徑要處理 CORS 'allowed_methods' => ['*'], // GET, POST, PUT, DELETE... 'allowed_origins' => [ 'http://localhost:3000', // 開發環境前端 'https://jiuhaomai.tw', // 正式環境 ], 'allowed_origins_patterns' => [], 'allowed_headers' => ['*'], 'exposed_headers' => [], 'max_age' => 0, // Preflight 快取秒數 'supports_credentials' => false, ]; ``` ### 常見踩坑 1. **`allowed_origins` 設成 `['*']` 很方便但不安全**——正式環境一定要列出明確的 domain 2. **Preflight request（OPTIONS）被 Nginx 擋掉**——確保你的 Nginx/Apache 設定允許 OPTIONS 方法通過 3. **帶 credentials 時不能用 `*`**——如果 `supports_credentials` 是 `true`，`allowed_origins` 不能用萬用字元，必須列明 4. **忘記加 `api/*` 到 paths**——如果你的 API 路由不在 `api/` 底下，CORS 設定不會生效 > **提醒：** CORS 是**瀏覽器**的機制。手機 App 和 server-to-server 的請求不受 CORS 限制。所以你的 LINE Bot 和後端爬蟲不需要擔心 CORS。 ## 實作：揪好買 API 與 LINE Bot 概念整合把前面學的全部串起來。我們要幫揪好買建一組完整的 API 端點。 ### 完整的 API 路由 ```php // routes/api.php use App\Http\Controllers\Api\AuthController; use App\Http\Controllers\Api\GroupBuyController; // 認證端點 Route::post('/register', [AuthController::class, 'register']); Route::post('/login', [AuthController::class, 'login']) ->middleware('throttle:login'); // 公開端點 Route::get('/group-buys', [GroupBuyController::class, 'index']); Route::get('/group-buys/{groupBuy}', [GroupBuyController::class, 'show']); // 受保護端點 Route::middleware('auth:sanctum')->group(function () { // 認證 Route::post('/logout', [AuthController::class, 'logout']); Route::get('/user', [AuthController::class, 'user']); // 團購操作 Route::post('/group-buys', [GroupBuyController::class, 'store']); Route::post('/group-buys/{groupBuy}/join', [GroupBuyController::class, 'join']); // 我的資料 Route::get('/my/orders', [GroupBuyController::class, 'myOrders']); }); ``` ### GroupBuyController（API 版） ```php where('status', 'open') ->when($request->query('search'), function ($query, $search) { $query->where('title', 'like', "%{$search}%"); }) ->latest() ->paginate(15); return GroupBuyResource::collection($groupBuys); } /** * 取得單一團購詳情 */ public function show(GroupBuy $groupBuy) { $groupBuy->loadCount('participants'); $groupBuy->load('user:id,name'); return new GroupBuyResource($groupBuy); } /** * 建立新團購（需要認證） */ public function store(Request $request) { $this->authorize('create', GroupBuy::class); $validated = $request->validate([ 'title' => 'required|string|max:255', 'description' => 'required|string', 'target_amount' => 'required|integer|min:2', 'deadline' => 'required|date|after:now', 'price_per_unit'=> 'required|numeric|min:0', ]); $groupBuy = $request->user()->groupBuys()->create($validated); return (new GroupBuyResource($groupBuy)) ->response() ->setStatusCode(201); } /** * 加入團購 */ public function join(Request $request, GroupBuy $groupBuy) { // 檢查團購是否還開放 if ($groupBuy->status !== 'open') { return response()->json([ 'message' => '此團購已截止或已取消。', ], 422); } // 檢查是否已經加入 if ($groupBuy->participants()->where('user_id', $request->user()->id)->exists()) { return response()->json([ 'message' => '你已經加入這個團購了。', ], 422); } $validated = $request->validate([ 'quantity' => 'required|integer|min:1', ]); $groupBuy->participants()->attach($request->user()->id, [ 'quantity' => $validated['quantity'], ]); return response()->json([ 'message' => '成功加入團購！', ]); } /** * 我的訂單 */ public function myOrders(Request $request) { $orders = $request->user() ->joinedGroupBuys() ->withPivot('quantity') ->withCount('participants') ->latest() ->paginate(15); return GroupBuyResource::collection($orders); } } ``` ### ParticipantResource（跟團者資訊）如果 API 需要回傳參與者列表，也用 Resource 包裝： ```php [ 'id' => $this->id, 'name' => $this->name, ], 'quantity' => $this->pivot->quantity, 'joined_at' => $this->pivot->created_at?->toIso8601String(), ]; } } ``` ### 用 curl 測試 API 不需要瀏覽器就能測試。用 `curl` 或 `httpie` 在終端機直接打： ```bash # 註冊 curl -X POST http://localhost:8000/api/register \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "小陳", "email": "chen@example.com", "password": "password123", "password_confirmation": "password123" }' # 回傳：{"user":{"id":1,"name":"小陳","email":"chen@example.com"},"token":"1|abc123..."} ``` ```bash # 登入 curl -X POST http://localhost:8000/api/login \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"email": "chen@example.com", "password": "password123"}' ``` ```bash # 查看團購列表（不需要 token） curl http://localhost:8000/api/group-buys \ -H "Accept: application/json" ``` ```bash # 加入團購（需要 token） curl -X POST http://localhost:8000/api/group-buys/42/join \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer 1|abc123..." \ -d '{"quantity": 2}' ``` ```bash # 如果你裝了 httpie，語法更簡潔 http POST localhost:8000/api/login email=chen@example.com password=password123 http localhost:8000/api/group-buys Authorization:"Bearer 1|abc123..." ``` > **重要：** 請求 API 時一定要帶 `Accept: application/json` Header。如果不帶，Laravel 在驗證失敗時會嘗試 redirect 到一個 HTML 頁面——在 API 裡這會變成很奇怪的 302 回應。 ### LINE Bot Webhook 概念整合 LINE Bot 的運作邏輯是：使用者在 LINE 群組裡傳訊息 → LINE 平台把訊息轉送到你的 webhook URL → 你的伺服器處理後回覆。 ``` 使用者在 LINE 傳「查團購」 ↓ LINE 平台 → POST /api/line/webhook（你的伺服器） ↓ 伺服器解析訊息，查詢 GroupBuy 資料 ↓ 伺服器透過 LINE Messaging API 回覆結果 ``` webhook 端點的概念實作： ```php // routes/api.php Route::post('/line/webhook', [LineWebhookController::class, 'handle']); ``` ```php input('events', []); foreach ($events as $event) { if ($event['type'] !== 'message') { continue; } $text = $event['message']['text'] ?? ''; $replyToken = $event['replyToken']; if (str_contains($text, '查團購')) { $this->replyGroupBuyList($replyToken); } elseif (str_contains($text, '開團中')) { $this->replyOpenGroupBuys($replyToken); } } return response()->json(['status' => 'ok']); } private function replyGroupBuyList(string $replyToken): void { $groupBuys = GroupBuy::where('status', 'open') ->latest() ->take(5) ->get(); $message = "目前開團中的團購：\n\n"; foreach ($groupBuys as $gb) { $message .= "🛒 {$gb->title}\n"; $message .= " 截止：{$gb->deadline->format('m/d H:i')}\n"; $message .= " 目標：{$gb->current_amount}/{$gb->target_amount} 人\n\n"; } // 實際整合時透過 LINE Messaging API SDK 回覆 // v7 SDK：$messagingApi->replyMessage(new ReplyMessageRequest([ // 'replyToken' => $replyToken, // 'messages' => [new TextMessage(['type' => 'text', 'text' => $message])], // ])); // 舊版 LINEBot::replyText 已淘汰 } private function replyOpenGroupBuys(string $replyToken): void { $count = GroupBuy::where('status', 'open')->count(); $message = "目前有 {$count} 個團購進行中！\n輸入「查團購」看詳細列表。"; // v7 SDK：$messagingApi->replyMessage(new ReplyMessageRequest([...]));（舊版 LINEBot::replyText 已淘汰） } } ``` 這裡只展示概念——實際的 LINE Bot 整合需要安裝 `linecorp/line-bot-sdk`、設定 Channel Access Token 和 Channel Secret、做 Signature 驗證。但核心架構就是這樣：一個 webhook 端點，接收訊息、查詢資料庫、回覆結果。**你的 API 和 LINE Bot 共用同一個資料庫和 Model**，不需要重寫任何商業邏輯。 ### 錯誤回應的統一格式好的 API 在出錯時也要回傳結構化的 JSON，而不是 HTML 錯誤頁面。在 `bootstrap/app.php` 統一處理： ```php use Illuminate\Http\Request; ->withExceptions(function (Exceptions $exceptions) { $exceptions->shouldRenderJsonWhen(function (Request $request) { return $request->is('api/*') || $request->expectsJson(); }); }) ``` 這樣所有 `/api/*` 路由的例外都會以 JSON 格式回傳： ```json { "message": "此團購已截止或已取消。", "errors": {} } ``` 驗證錯誤則會自動回傳 422 和欄位明細： ```json { "message": "The title field is required.", "errors": { "title": ["The title field is required."], "deadline": ["The deadline must be a date after now."] } } ``` ## 小結：一套後端，多個前端這一章我們把揪好買從「只服務瀏覽器」升級成「服務所有人」： **API 基礎：** - `php artisan install:api` 啟用 API 路由和 Sanctum - `routes/api.php` 是 stateless 的——沒有 Session、沒有 CSRF，靠 Token 認證 - API Resource 精準控制 JSON 輸出，搭配 Pagination 自動生成分頁資訊 **認證與安全：** - Sanctum Token 認證——`createToken()` 建立、`Bearer` Header 攜帶、`delete()` 撤銷 - Token Abilities 做細粒度權限控制 - Rate Limiting 防止 API 被濫用——已登入使用者和匿名使用者各自獨立限制 **實務面：** - CORS 設定讓 SPA 前端能跨域存取 - Scramble 自動生成 API 文件，零設定 - LINE Bot webhook 概念——同一個 Laravel 專案服務所有消費者 - API 版本管理 YAGNI——等需要時再加現在揪好買有了完整的 API 端點，手機 App 可以呼叫、LINE Bot 可以整合、第三方系統可以串接。但平台越來越大，開團主需要看統計報表，管理員需要後台管理介面，團購列表開始變慢——下一章，我們要用 **[Filament 3 快速建立管理後台](/blog/laravel-guide-admin-filament-advanced-queries/)**，並深入 Eloquent 進階查詢技巧，解決真實世界的效能問題。

Queue 與 Event：讓耗時任務不阻塞使用者

Tue, 06 May 2025 00:00:00 GMT

[上一章](/blog/laravel-guide-orders-stripe-cashier/)成團收款的瞬間，你需要做一堆事：寄成團確認信給所有跟團者、寄通知給開團主、更新團購狀態、生成訂單明細 PDF、紀錄 analytics 事件。如果這些全部塞在同一個 HTTP request 裡同步執行，使用者按下確認後要等五到十秒才看到回應——這種體驗在 2026 年是不能接受的。 Queue（佇列）就是解決這個問題的：把不需要即時完成的工作丟到背景去跑，使用者的 request 馬上就能回應。但 Queue 只解決了「何時做」的問題。「誰該做什麼」的問題，需要 Event/Listener 模式來處理。當「團購成團」這個事件發生時，可能有五六個不同的動作要觸發——寄信、推播、更新統計、通知倉庫備貨。如果把這些全寫在 Controller 或 Service 裡，程式碼會變成一團義大利麵。 Event/Listener 讓你把「事件」和「反應」解耦：Controller 只要 dispatch 一個 `GroupBuyConfirmed` event，各個 Listener 自己知道該做什麼。新增需求？加一個 Listener 就好，不用動到原本的程式碼。 Laravel 還有一個被低估的利器：Notification。它提供統一的介面來發送通知，不管你要透過 Email、SMS、Slack、站內訊息還是 push notification——同一個 Notification class 搞定所有管道。在「揪好買」裡，我們會把成團通知、出貨通知、截止提醒全部用 Notification 來實作，搭配 Queue 讓它們在背景發送。 ## 為什麼需要 Queue：使用者不該等你寄 Email 想像這個場景：一個團購有 50 個跟團者，成團後你要寄確認信給每個人。每封信透過 SMTP 發送大約需要 0.5 秒，50 封就是 25 秒。如果是同步執行，使用者按下「確認成團」之後，要盯著 loading 轉圈 25 秒才能看到結果。 ```text 同步處理（Synchronous）：使用者按下確認 → 寄信給 A（0.5s）→ 寄信給 B（0.5s）→ ... → 寄信給第 50 人（0.5s）→ 回應使用者總共 25 秒 ⏳ 非同步處理（Asynchronous with Queue）：使用者按下確認 → 把 50 封信丟進 Queue → 回應使用者 ✅（0.1s） ↓ 背景 Worker 慢慢寄，使用者不用等 ``` 這就是 Queue 的核心價值：**把不需要使用者等待的工作延遲到背景執行**。常見的適用場景： - **寄送 Email / SMS / 推播通知**——使用者不需要等你跟 SMTP Server 握手 - **生成 PDF 或 Excel 報表**——耗時的運算不該卡住 request - **呼叫第三方 API**——外部服務的回應時間你控制不了 - **圖片處理**——裁切、壓縮、上傳到 CDN - **資料同步**——把訂單資料推到 ERP 或會計系統不過在你決定全部丟 Queue 之前，先把帳算清楚。Queue 不是免費的：你的系統會從「一個 PHP process 收 request、回 response」變成「還要養一個常駐 worker、設 Supervisor 讓它掛掉自動拉起、加監控、部署時記得 `php artisan queue:restart`」的分散式架構。對流量很小的專案，這個維運成本常常大於「使用者少等三秒」省下來的時間——這時候同步處理加一個 loading 轉圈，反而更簡單、更可靠、半夜也不會出事。而且非同步多了一個很容易忽略的 failure mode：worker 沒在跑的時候，任務不會報錯，它只是安靜地躺在佇列裡不動，通知就默默沒送出去，沒人會發現。同步至少會當場噴錯給你看。所以這章後面我會花篇幅講 Supervisor 跟失敗監控，不是順帶提一下——那是用 Queue 的入場費，不是加分題。如果你用過 Node.js，你可能會想：「JavaScript 本來就是非同步的啊，用 `Promise` 不就好了？」問題在於，PHP 的每個 request 是獨立的 process。request 結束了，process 就結束了，不會有「背景繼續跑」的機會。 Queue 的做法是把任務序列化後存到某個地方（資料庫、Redis、SQS），然後由獨立的 worker process 去取出來執行。概念上類似 Python 的 Celery 或 Node.js 的 Bull/BullMQ。 ## Queue 概念與 Driver 選擇 Laravel 的 Queue 系統支援多種 driver（驅動），讓你根據環境和規模選擇適合的後端： | Driver | 適用場景 | 優點 | 缺點 | | ---------- | ----------------- | ------------------------ | ---------------------- | | `sync` | 本地開發/除錯 | 同步執行，方便 debug | 不是真的 queue，會阻塞 | | `database` | 小型專案/開發環境 | 不需額外服務 | 效能較差，polling 機制 | | `redis` | **正式環境首選** | 快、支援優先級、延遲任務 | 需要 Redis 服務 | | `sqs` | AWS 大規模部署 | 完全託管、自動擴展 | 綁定 AWS | 在「揪好買」的開發環境，我們用 `database` driver 就夠了——不需要額外安裝 Redis，資料庫裡開一張 table 就能跑。正式環境再切到 `redis`，只要改一行 `.env` 設定。 ### 設定 Database Queue Driver ```bash # .env QUEUE_CONNECTION=database ``` 建立 Queue 需要的資料表： ```bash php artisan queue:table php artisan migrate ``` 這會建立一張 `jobs` table，Queue 把待執行的任務序列化後存在這裡。若需要批次處理（Job Batching），另外執行 `php artisan queue:batches-table` 建立 `job_batches` table。另外，我們還需要一張 `failed_jobs` table 來記錄失敗的任務： ```bash php artisan queue:failed-table php artisan migrate ``` > **提示：** Laravel 12 的新專案預設就會幫你建好這些 migration。如果你是從舊版升級，才需要手動執行上面的指令。 ## Job 類別：把任務包裝起來 Queue 裡的每個任務就是一個 Job class。用 Artisan 指令快速生成： ```bash php artisan make:job ProcessGroupBuyConfirmation ``` 這會在 `app/Jobs/` 目錄下建立一個檔案： ```php groupBuy->update(['status' => 'confirmed']); // 生成訂單明細 PDF $pdf = PDF::loadView('pdf.group-buy-summary', [ 'groupBuy' => $this->groupBuy, 'participants' => $this->groupBuy->participants()->with('orders')->get(), ]); Storage::put( "summaries/{$this->groupBuy->id}.pdf", $pdf->output() ); } } ``` 幾個關鍵點： - **`implements ShouldQueue`**——這個 interface 告訴 Laravel：「這個 Job 要丟到 Queue 裡背景執行」。如果拿掉它，Job 會同步執行（跟沒有 Queue 一樣）。 - **`SerializesModels`**——這個 trait 會自動序列化 Eloquent Model 的 ID，然後在 worker 端重新從資料庫取出完整的 Model。避免把整個 Model 物件塞進 Queue（那會很大，而且資料可能過時）。 - **`handle()` 方法**——worker 從 Queue 取出任務後，就是執行這個方法。你的業務邏輯寫在這裡。 ### 分派 Job 在 Controller 或 Service 裡，把 Job 丟進 Queue： ```php // 最常用的方式 ProcessGroupBuyConfirmation::dispatch($groupBuy); // 延遲執行：5 分鐘後才執行 ProcessGroupBuyConfirmation::dispatch($groupBuy) ->delay(now()->addMinutes(5)); // 指定 Queue 名稱（用來區分優先級） ProcessGroupBuyConfirmation::dispatch($groupBuy) ->onQueue('high'); // 用 dispatch helper function dispatch(new ProcessGroupBuyConfirmation($groupBuy)); ``` ### 重試與超時設定 Job 失敗時的行為可以直接在 class 上設定： ```php class ProcessGroupBuyConfirmation implements ShouldQueue { use Dispatchable, InteractsWithQueue, Queueable, SerializesModels; public int $tries = 3; // 最多重試 3 次 public int $timeout = 60; // 超過 60 秒就算超時 public int $maxExceptions = 2; // 最多容忍 2 個例外 // 退避策略：第一次失敗等 10 秒、第二次等 30 秒、第三次等 60 秒 public function backoff(): array { return [10, 30, 60]; } // ... } ``` ### Job Middleware 如果你需要防止同一個 Job 重複執行（例如同一個團購的確認信不該寄兩次），可以用 Job Middleware： ```php use Illuminate\Queue\Middleware\WithoutOverlapping; public function middleware(): array { return [ new WithoutOverlapping($this->groupBuy->id), ]; } ``` `WithoutOverlapping` 會用 lock 機制確保同一個 key 的 Job 不會同時執行。在「揪好買」裡，用團購 ID 當 key 是最直覺的選擇。 ## Event 與 Listener：解耦業務邏輯 Queue 解決了「非同步執行」的問題，但還有另一個問題：**當一個動作需要觸發多個後續動作時，程式碼要怎麼組織？** 不好的寫法是把所有邏輯塞在 Controller： ```php // ❌ 不好：Controller 變成 God Object class GroupBuyController extends Controller { public function confirm(GroupBuy $groupBuy) { $groupBuy->update(['status' => 'confirmed']); // 寄確認信給跟團者 foreach ($groupBuy->participants as $user) { Mail::to($user)->send(new GroupBuyConfirmedMail($groupBuy)); } // 寄摘要給開團主 Mail::to($groupBuy->organizer)->send(new OrganizerSummaryMail($groupBuy)); // 更新統計 $groupBuy->increment('confirmed_count'); // 通知倉庫備貨 Http::post('https://warehouse-api.example.com/prepare', [...]); // 紀錄 analytics Analytics::track('group_buy_confirmed', [...]); return redirect()->route('group-buys.show', $groupBuy); } } ``` 問題在哪？每次新增需求（例如「成團後也要發 LINE 通知」），你都要改這個 Controller。這違反了開放封閉原則（Open/Closed Principle）——**對擴展開放，對修改封閉**。 Event/Listener 模式的做法是：Controller 只做一件事——dispatch 一個 Event。其他的後續動作由各自的 Listener 處理： ```php // ✅ 好：Controller 只 dispatch event class GroupBuyController extends Controller { public function confirm(GroupBuy $groupBuy) { $groupBuy->update(['status' => 'confirmed']); event(new GroupBuyConfirmed($groupBuy)); return redirect()->route('group-buys.show', $groupBuy); } } ``` ### 建立 Event ```bash php artisan make:event GroupBuyConfirmed ``` ```php groupBuy; foreach ($groupBuy->participants as $user) { $user->notify(new GroupBuyConfirmedNotification($groupBuy)); } } } ``` 注意 `implements ShouldQueue`——加上這個 interface，Listener 就會自動在背景執行。不加的話就是同步執行。你可以根據每個 Listener 的特性來決定：寄信要 Queue、更新資料庫統計可以同步。 > **背景化之前先想清楚 debug 怎麼辦** > > 「寄信要 Queue」這句話我得補一個但書。同步寄信失敗時，stack trace 直接打在那個 request 上，使用者當場看到錯誤、你的 log 也立刻有紀錄。一旦丟進 Queue，失敗就搬到另一個 process、另一個時間點發生了——使用者那邊畫面顯示「確認成功」，信其實沒寄出去，而且沒人會知道。這個「使用者以為成功、實際上失敗」的落差會無聲累積，等客訴進來才發現往往已經漏掉一堆。 > > 所以非同步化跟「主動建可觀測性」是綁在一起的，不能只做前者：至少要對 `failed_jobs` 設告警，正式環境上 Horizon 看佇列健康度，例外接到 Sentry。開發期則反過來——把 `QUEUE_CONNECTION` 設成 `sync`，或用 `php artisan queue:work --once` 一次跑一個，讓失敗回到 request 生命週期裡，你才 debug 得動。背景執行很爽，但你是拿「看得見的失敗」去換的，這筆交易要心裡有數。 ```php groupBuy; $groupBuy->update([ 'participant_count' => $groupBuy->participants()->count(), 'total_amount' => $groupBuy->orders()->sum('amount'), 'confirmed_at' => now(), ]); } } ``` ### 註冊 Event 與 Listener Laravel 12 支援**自動發現**——只要 Listener 的 `handle()` 方法有正確的 type hint，Laravel 會自動把它跟 Event 配對。不需要在任何地方手動註冊。如果你需要明確控制（或是自動發現沒生效），可以在 `AppServiceProvider` 的 `boot()` 方法裡手動註冊： ```php use App\Events\GroupBuyConfirmed; use App\Listeners\SendConfirmationToParticipants; use App\Listeners\SendOrganizerSummary; use App\Listeners\UpdateGroupBuyStats; use Illuminate\Support\Facades\Event; public function boot(): void { Event::listen(GroupBuyConfirmed::class, [ SendConfirmationToParticipants::class, SendOrganizerSummary::class, UpdateGroupBuyStats::class, ]); } ``` 要確認所有 Event/Listener 的對應關係，可以用： ```bash php artisan event:list ``` ### 跨框架概念對照如果你從其他語言過來，Event/Listener 的概念不會太陌生： | 框架/語言 | 對應機制 | 差異點 | | ----------------- | ------------------------- | ---------------------------------------------------------------------- | | **Node.js** | `EventEmitter` | Node 的 event 是 in-process、同步觸發；Laravel 可以選擇 Queue 背景執行 | | **Python/Django** | Signals（`post_save` 等） | Django 的 signal 是同步的，沒有內建的非同步機制 | | **React** | Custom Events / Context | 前端的事件系統，概念類似但作用域不同 | | **Spring** | `@EventListener` | 最接近 Laravel 的做法，也支援 async | Laravel 的 Event 系統最大的優勢是它跟 Queue 的深度整合——一個 `implements ShouldQueue` 就能把 Listener 從同步變成非同步，不需要額外的配置。 ## Notification：統一的通知發送介面你可能會想：「寄信直接用 `Mail::send()` 不就好了？幹嘛還要 Notification？」問題是，真實世界的通知不只有 Email。成團通知你可能要同時寄 Email + 存到站內訊息 + 推 LINE 通知。如果分三個地方寫，資料格式不一致，日後加一個管道就要改三個地方。 Notification 的設計理念是：**一個通知類別，多種發送管道**。 ```bash php artisan make:notification GroupBuyConfirmedNotification ``` ```php subject("🎉 團購「{$this->groupBuy->title}」已成團！") ->greeting("Hi {$notifiable->name}，") ->line("好消息！你參加的團購「{$this->groupBuy->title}」已經達到最低人數，正式成團了。") ->line("成團人數：{$this->groupBuy->participant_count} 人") ->line("總金額：NT$ " . number_format($this->groupBuy->total_amount)) ->action('查看團購詳情', route('group-buys.show', $this->groupBuy)) ->line('感謝你的參與，我們會儘快安排出貨！'); } /** * 站內訊息版本（存到 notifications table） */ public function toDatabase(object $notifiable): array { return [ 'group_buy_id' => $this->groupBuy->id, 'group_buy_title' => $this->groupBuy->title, 'message' => "團購「{$this->groupBuy->title}」已成團", 'type' => 'group_buy_confirmed', ]; } } ``` `via()` 方法決定要用哪些管道發送。你甚至可以根據使用者的偏好動態決定： ```php public function via(object $notifiable): array { $channels = ['database']; // 站內訊息一定有 if ($notifiable->email_notifications_enabled) { $channels[] = 'mail'; } if ($notifiable->line_token) { $channels[] = 'line'; // 自訂管道 } return $channels; } ``` ### 發送通知有兩種方式： ```php // 方式一：透過 Notifiable trait（User Model 預設就有） $user->notify(new GroupBuyConfirmedNotification($groupBuy)); // 方式二：透過 Notification Facade（可以一次寄給多人） use Illuminate\Support\Facades\Notification; Notification::send( $groupBuy->participants, // Collection of users new GroupBuyConfirmedNotification($groupBuy) ); ``` 方式二在「揪好買」更常用——成團的時候要一次通知所有跟團者。 ## Mail 通知：寄出成團確認信上面的 `toMail()` 用的是 `MailMessage` builder——它會自動套用 Laravel 內建的 Email 模板。但如果你想要更漂亮、更品牌化的 Email，可以用 Markdown 模板： ```php public function toMail(object $notifiable): MailMessage { return (new MailMessage) ->subject("🎉 團購「{$this->groupBuy->title}」已成團！") ->markdown('emails.group-buy-confirmed', [ 'user' => $notifiable, 'groupBuy' => $this->groupBuy, 'orders' => $this->groupBuy->orders() ->where('user_id', $notifiable->id) ->get(), ]); } ``` 對應的 Markdown 模板 `resources/views/emails/group-buy-confirmed.blade.php`： ```blade # 🎉 {{ $groupBuy->title }} 已成團！ Hi {{ $user->name }}，你參加的團購已經達到最低人數，正式成團了。以下是你的訂購明細： | 品項 | 數量 | 小計 | |:-----|:----:|-----:| @foreach ($orders as $order) | {{ $order->product_name }} | {{ $order->quantity }} | NT$ {{ number_format($order->amount) }} | @endforeach | **合計** | | **NT$ {{ number_format($orders->sum('amount')) }}** | 查看團購詳情感謝你使用揪好買！ {{ config('app.name') }} ``` Laravel 的 Mail Markdown 元件（`x-mail::message`、`x-mail::table`、`x-mail::button`）會自動轉換成漂亮的 HTML Email。 ### 開發環境測試：不要真的寄信在開發階段，你不會想真的寄 Email 出去。在 `.env` 裡設定： ```bash MAIL_MAILER=log ``` 這樣所有「寄出的」Email 都會寫到 `storage/logs/laravel.log`，你可以在 log 裡看到完整的 Email 內容，確認格式正確。另一個好用的選擇是 [Mailpit](https://mailpit.axllent.org/)——一個本地的 Email 測試伺服器，會攔截所有寄出的信，讓你在瀏覽器裡預覽： ```bash MAIL_MAILER=smtp MAIL_HOST=localhost MAIL_PORT=1025 ``` ## Database 通知：站內訊息不是每個人都會看 Email。站內訊息（in-app notification）是另一個重要的通知管道。使用者登入後在右上角看到小鈴鐺和紅色數字——這就是 Database 通知的用途。 ### 設定 Notifications Table ```bash php artisan notifications:table php artisan migrate ``` 這會建立一張 `notifications` table，結構大概是這樣： | 欄位 | 型別 | 說明 | | --------------- | --------- | ----------------------------- | | id | uuid | 通知 ID | | type | string | Notification class 名稱 | | notifiable_type | string | 被通知的 Model（通常是 User） | | notifiable_id | bigint | 被通知的 Model ID | | data | json | `toDatabase()` 回傳的資料 | | read_at | timestamp | 已讀時間（null = 未讀） | | created_at | timestamp | 建立時間 | ### 讀取與標記已讀在 User Model 上（透過 `Notifiable` trait），你可以這樣操作： ```php // 取得所有通知 $user->notifications; // 取得未讀通知 $user->unreadNotifications; // 取得未讀數量 $user->unreadNotifications->count(); // 標記單一通知為已讀 $notification->markAsRead(); // 標記所有通知為已讀 $user->unreadNotifications->markAsRead(); ``` ### 在 Blade 裡顯示通知鈴鐺一個常見的 UI 實作——導覽列上的通知鈴鐺： ```blade {{-- resources/views/components/notification-bell.blade.php --}} @auth

通知

@forelse (auth()->user()->notifications()->latest()->take(10)->get() as $notification)

@empty

暫無通知

@endforelse

@endauth ``` 對應的 Controller 處理「點擊通知 → 標記已讀 → 跳轉」： ```php class NotificationController extends Controller { public function read(string $id) { $notification = auth()->user() ->notifications() ->findOrFail($id); $notification->markAsRead(); // 根據通知類型跳轉到對應頁面 return match ($notification->data['type'] ?? null) { 'group_buy_confirmed' => redirect()->route( 'group-buys.show', $notification->data['group_buy_id'] ), default => redirect()->route('dashboard'), }; } } ``` ## 失敗 Job 處理與重試策略 Queue 不是萬能的——Job 會失敗。SMTP Server 掛了、第三方 API 回應逾時、資料庫連線斷了，這些在分散式系統裡是家常便飯。Laravel 提供了完整的失敗處理機制。 ### failed_jobs Table 前面我們已經建立了 `failed_jobs` table。當 Job 的重試次數耗盡仍然失敗時，它會被記錄到這張 table，包含 Job 的完整資料和錯誤訊息。 ### 在 Job 裡處理失敗你可以在 Job class 裡定義 `failed()` 方法，在 Job 最終失敗時做一些處理： ```php class ProcessGroupBuyConfirmation implements ShouldQueue { // ... public function failed(\Throwable $exception): void { // 通知開發者 Log::critical('團購確認處理失敗', [ 'group_buy_id' => $this->groupBuy->id, 'error' => $exception->getMessage(), ]); // 通知開團主處理異常 $this->groupBuy->organizer->notify( new ProcessingFailedNotification($this->groupBuy, $exception) ); } } ``` ### 重試失敗的 Job ```bash # 查看所有失敗的 Job php artisan queue:failed # 重試特定 Job php artisan queue:retry # 重試所有失敗的 Job php artisan queue:retry all # 刪除特定失敗 Job php artisan queue:forget # 清空所有失敗 Job php artisan queue:flush ``` ### 退避策略的最佳實踐不要用固定的重試間隔。如果 SMTP Server 掛了，每 5 秒重試一次只會浪費資源。用**指數退避**（Exponential Backoff）： ```php public function backoff(): array { return [10, 60, 300]; // 10 秒、1 分鐘、5 分鐘 } ``` 如果 Job 涉及第三方 API 呼叫，加上 Rate Limiting middleware： ```php use Illuminate\Queue\Middleware\RateLimited; public function middleware(): array { return [ new RateLimited('external-api'), ]; } ``` 在 `AppServiceProvider` 裡定義 rate limiter： ```php use Illuminate\Cache\RateLimiting\Limit; use Illuminate\Support\Facades\RateLimiter; public function boot(): void { RateLimiter::for('external-api', function (object $job) { return Limit::perMinute(30); }); } ``` ### Laravel Horizon 簡介當你的 Queue 規模成長到需要監控時，[Laravel Horizon](https://laravel.com/docs/horizon) 是官方提供的 Redis Queue 儀表板。它提供： - 即時監控 Job 的吞吐量和執行時間 - 查看失敗 Job 的詳細錯誤 - 自動調整 worker 數量 - 基於 tag 的 Job 搜尋和過濾安裝很簡單： ```bash composer require laravel/horizon php artisan horizon:install php artisan horizon ``` 然後在瀏覽器開啟 `/horizon` 就能看到漂亮的監控介面。在「揪好買」正式上線後，Horizon 會是你觀察系統健康狀況的重要工具。不過在開發階段，用 `php artisan queue:work` 就夠了。 ## 實作：揪好買的通知系統把前面學到的全部串起來。以下是「揪好買」在團購成團時的完整通知流程： ### 第一步：定義 Event ```php // app/Events/GroupBuyConfirmed.php groupBuy->participants, new GroupBuyConfirmedNotification($event->groupBuy) ); } } ``` **Listener 2：寄摘要報告給開團主** ```php // app/Listeners/SendOrganizerSummary.php groupBuy; $groupBuy->organizer->notify( new OrganizerSummaryNotification($groupBuy) ); } } ``` **Listener 3：更新統計資料（同步）** ```php // app/Listeners/UpdateGroupBuyStats.php groupBuy; $groupBuy->update([ 'participant_count' => $groupBuy->participants()->count(), 'total_amount' => $groupBuy->orders()->sum('amount'), 'confirmed_at' => now(), ]); } } ``` ### 第三步：在 Service 裡觸發 Event ```php // app/Services/GroupBuyService.php canBeConfirmed(), \DomainException::class, '此團購不符合成團條件' ); $groupBuy->update(['status' => 'confirmed']); // 就這一行，所有後續動作都會自動觸發 event(new GroupBuyConfirmed($groupBuy)); } } ``` > **如果這段被包在 transaction 裡，這個 race condition 會咬你** > > 上面的 `confirm()` 沒包 transaction 還算安全，但實務上你很可能會把「更新狀態 + 寫幾張關聯表」一起包進 `DB::transaction()`。問題來了：Listener 用 `SerializesModels` 只存了 model 的 ID，到 worker 端會重新 `find()` 一次回 DB 撈。Redis worker 很快，可能在你的 transaction 還沒 commit 的瞬間就把 job 撈走執行了——這時 DB 裡那筆 `confirmed` 資料還在你這個連線的交易裡，worker 看不到，直接吃 `ModelNotFoundException`。更陰險的是它不一定每次都中，本機跑沒事、上線高併發才偶發，超難重現。 > > 解法是叫 job 等 commit 完再派：dispatch 時接 `->afterCommit()`，或在 `config/queue.php` 對應的 connection 設 `'after_commit' => true` 一勞永逸。`SerializesModels` 幫你省記憶體、避免資料過時，代價就是這個時序陷阱，兩件事是同一個機制的一體兩面，得一起記。整個流程是這樣的： ```text Controller 呼叫 GroupBuyService::confirm() ├── 更新 status = confirmed（同步） └── dispatch GroupBuyConfirmed event ├── SendConfirmationToParticipants（Queue → 寄 Email + 存站內訊息） ├── SendOrganizerSummary（Queue → 寄開團主摘要信） └── UpdateGroupBuyStats（同步 → 更新統計欄位） ``` ### 第四步：截止提醒通知（Scheduled）除了成團通知，「揪好買」還需要在截止前提醒跟團者。這個用 Laravel 的 Scheduler 搭配 Notification： ```php // app/Notifications/GroupBuyDeadlineReminder.php diffInHours($this->groupBuy->deadline, true); // Carbon 3（Laravel 11/12）的 diffInHours 預設回傳帶正負號的 float，第二參數 $absolute=true 取絕對值並 cast int 確保顯示正確小時數 return (new MailMessage) ->subject("⏰ 團購「{$this->groupBuy->title}」即將截止") ->line("你參加的團購還有 {$hoursLeft} 小時就要截止了。") ->line("目前人數：{$this->groupBuy->participants()->count()} / {$this->groupBuy->min_participants}") ->action('查看團購', route('group-buys.show', $this->groupBuy)) ->line('趕快分享給朋友一起揪團吧！'); } public function toDatabase(object $notifiable): array { return [ 'group_buy_id' => $this->groupBuy->id, 'group_buy_title' => $this->groupBuy->title, 'message' => "團購「{$this->groupBuy->title}」即將截止", 'type' => 'deadline_reminder', ]; } } ``` 在 `routes/console.php` 裡設定排程： ```php use App\Models\GroupBuy; use App\Notifications\GroupBuyDeadlineReminder; use Illuminate\Support\Facades\Notification; use Illuminate\Support\Facades\Schedule; Schedule::call(function () { // 找出 24 小時內即將截止的團購 $groupBuys = GroupBuy::where('status', 'open') ->whereBetween('deadline', [now(), now()->addHours(24)]) ->whereNull('reminder_sent_at') ->get(); foreach ($groupBuys as $groupBuy) { Notification::send( $groupBuy->participants, new GroupBuyDeadlineReminder($groupBuy) ); $groupBuy->update(['reminder_sent_at' => now()]); } })->hourly()->name('group-buy-deadline-reminders'); ``` ### 啟動 Worker 所有 Queue 裡的 Job 需要一個 worker process 來處理。開發時直接在終端機執行： ```bash # 啟動 worker php artisan queue:work # 指定處理特定 queue php artisan queue:work --queue=notifications,default # 處理一個 job 後就停止（適合測試） php artisan queue:work --once # 設定記憶體限制和超時 php artisan queue:work --memory=256 --timeout=120 ``` > **注意：** `queue:work` 是長時間執行的 process。在開發時改了 Job 的程式碼，需要重啟 worker 才會載入新的程式碼。可以用 `php artisan queue:restart` 優雅地重啟，或者在開發時用 `queue:listen`——它每次都會重新載入程式碼（但效能較差，僅限開發使用）。在正式環境，你會用 process manager（如 Supervisor）來確保 worker 持續運行： ```ini # /etc/supervisor/conf.d/jiuhaobuy-worker.conf [program:jiuhaobuy-worker] process_name=%(program_name)s_%(process_num)02d command=php /var/www/jiuhaobuy/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600 autostart=true autorestart=true stopasgroup=true killasgroup=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/var/www/jiuhaobuy/storage/logs/worker.log stopwaitsecs=3600 ``` ## 小結：非同步思維讓應用更健壯這一章我們學了三個核心概念，各自解決不同的問題： - **Queue**——解決「何時做」：把耗時任務丟到背景，使用者不用等。Driver 從開發用的 `database` 到正式環境的 `redis`，切換只需改一行 `.env`。 - **Event/Listener**——解決「誰做什麼」：用事件驅動的方式解耦業務邏輯。新增需求只要加 Listener，不用改原本的程式碼。搭配 `ShouldQueue` 就能讓 Listener 在背景執行。 - **Notification**——解決「怎麼通知」：一個 class 搞定 Email、站內訊息、SMS 等多種管道。搭配 Queue 在背景發送，搭配 Database driver 實作站內訊息。在「揪好買」裡，這三者的組合是：Controller 呼叫 Service → Service dispatch Event → Listener 在背景透過 Notification 發送多管道通知。整個流程清晰、解耦、可擴展。現在你的後端已經能優雅地處理背景任務和通知了。但你的系統目前只服務網頁使用者。[下一章](/blog/laravel-guide-api-sanctum-rest/)，我們要把揪好買的核心功能包裝成 RESTful API，用 Sanctum 做 Token 認證，讓手機 App 和 LINE Bot 也能開團、跟團、查詢訂單——同一套後端，服務所有人。

訂單與金流：成團後用 Cashier 串接 Stripe 收款

Tue, 29 Apr 2025 00:00:00 GMT

成團了，然後呢？錢要怎麼收？這是每個電商類專案最讓人緊張的環節。金流處理不像一般的 CRUD，有幾個雷你得事先知道： - **信用卡號不能自己存**——PCI DSS 合規不是鬧著玩的 - **付款失敗要能重試**——使用者的卡可能被拒、餘額不足 - **Webhook 要正確處理**——Stripe 的回呼打來時，你的程式碼必須正確回應 - **訂單狀態要明確流轉**——從「建立 → 付款中 → 已付款 → 已完成」，每個轉換都要受控任何一個環節出錯，輕則使用者體驗差，重則真的會出財務問題。好在 Laravel Cashier 把 Stripe 整合這件事做得非常優雅。它幫你處理了客戶（Customer）建立、Checkout Session 流程、Webhook 驗證與分發、訂閱管理這些繁瑣的底層工作，讓你可以專注在自己的業務邏輯上。你不需要自己去讀 Stripe API 文件的每一頁——Cashier 已經幫你封裝好了最常用的操作。當然，理解底層原理還是很重要的，所以這一章我們會先搞懂金流處理的基本觀念，再一步步把 Cashier 接進來。在「揪好買」裡，金流的觸發時機跟一般電商不一樣——不是使用者按下「購買」就收錢，而是等到成團確認後，才統一向所有跟團者收款。這代表我們需要一個清楚的訂單狀態機，還要處理「成團了但某個人付款失敗」的 edge case。這一章會完整走過這個流程。 ## 金流處理的基本觀念：為什麼 Stripe 不讓你自己存信用卡號讓我先講一個會讓你嚇出冷汗的事實：如果你自己在資料庫裡存信用卡號，你需要通過 **PCI DSS**（Payment Card Industry Data Security Standard）合規認證。這個認證要求包含——但不限於——專用的加密硬體、年度安全稽核、滲透測試、嚴格的存取控制。完整的 Level 1 合規認證每年的費用可以到幾十萬美金。所以答案很簡單：**不要自己存信用卡號**。讓專業的支付處理商（Stripe、綠界 ECPay、藍新 NewebPay）來處理。金流的核心概念是**轉嫁責任**。整個付款流程長這樣： ``` 1. 使用者在你的網站按下「付款」 2. 你的伺服器向 Stripe 建立一個 Checkout Session 3. 使用者被導向到 Stripe 的付款頁面（hosted page） 4. 使用者在 Stripe 的頁面輸入信用卡資訊 5. Stripe 處理付款 6. Stripe 透過 webhook 通知你的伺服器「付款成功了」 7. 你的伺服器更新訂單狀態 ``` 注意：信用卡資訊**從頭到尾都不經過你的伺服器**。使用者是在 Stripe 的頁面上輸入的。你的伺服器只收到「付款成功」或「付款失敗」的通知——不會碰到任何卡號資訊。這就是 Stripe Checkout 的精髓。 ### 跨服務對照 | 概念 | Stripe | 綠界 ECPay | 藍新 NewebPay | | ------------- | ---------------- | ------------------- | ------------------- | | Hosted 付款頁 | Checkout Session | 付款頁（AIO） | MPG 多功能收款 | | 付款結果通知 | Webhook | 付款完成通知 | 背景通知 NotifyURL | | 客戶端套件 | Stripe.js | N/A | N/A | | Laravel 套件 | Laravel Cashier | 自行串接 / 社群套件 | 自行串接 / 社群套件 | > **為什麼選 Stripe？（先講一個會卡死你的前提）** 本章用 Stripe，純粹因為它有官方 Laravel 套件（Cashier）、文件最齊全、測試工具最好用，最適合「學金流概念」。但有件事我必須先講清楚，免得你照做到最後才發現收不到錢：Stripe 目前不支援台灣境內公司直接開戶收款（台灣不在它的支援國家清單內），真要收到台幣帳戶，得繞道去註冊美國公司、辦 EIN 那一整套——對一個只想做台灣團購平台的人來說，這成本不合理。所以請把這章當成「拿 Stripe 學概念」，真要在台灣上線收款，請改用綠界 ECPay 或藍新 NewebPay，它們才支援台灣公司行號跟在地金流（ATM、超商代碼、Line Pay）。好消息是：這裡學到的 webhook 驗證、訂單狀態機、DB transaction 邏輯，換成台灣金流幾乎照搬，所以這章不算白學——只是別把「學習情境」當成「能上線收錢」。 ## Laravel Cashier 與 Stripe 整合 Laravel Cashier 是 Laravel 官方維護的 Stripe 整合套件。它封裝了最常用的 Stripe 操作——建立 Customer、Checkout Session、處理 Webhook——讓你用優雅的 PHP 語法完成金流串接。 ### 安裝 ```bash composer require laravel/cashier ``` ### 執行 Migration Cashier 的 migration 需要先發佈到 `database/migrations/`（Laravel 11+ 起 Cashier 不再自動載入 migration），再執行 migrate，才會在你的 `users` 表加上 Stripe 相關的欄位： ```bash php artisan vendor:publish --tag="cashier-migrations" php artisan migrate ``` 這會新增以下欄位到 `users` 表： | 欄位 | 用途 | | --------------- | --------------------------------------- | | `stripe_id` | 使用者在 Stripe 的 Customer ID | | `pm_type` | 預設付款方式類型（visa, mastercard...） | | `pm_last_four` | 信用卡末四碼 | | `trial_ends_at` | 試用期結束時間（訂閱制用） | ### 設定 Billable Trait 在 User Model 上加入 `Billable` trait： ```php **千萬不要把 Secret key 提交到 Git。** `.env` 已經在 `.gitignore` 裡了，但還是提醒一下——這種 key 外流的事件每個月都在發生。 ### Stripe 測試卡號 Stripe 提供一整套測試用的卡號，讓你不用刷真的信用卡就能測試各種場景： | 卡號 | 行為 | | --------------------- | ---------------------- | | `4242 4242 4242 4242` | 付款成功 | | `4000 0000 0000 3220` | 需要 3D Secure 驗證 | | `4000 0000 0000 0002` | 付款被拒（卡片被拒絕） | | `4000 0000 0000 9995` | 付款失敗（餘額不足） | 到期日填任何未來的日期，CVC 填任意三碼數字。 ### Stripe CLI：本地測試 Webhook Webhook 是 Stripe 打到**你的伺服器**的 HTTP 請求。但開發階段你的電腦通常在 NAT 後面，Stripe 打不到你。Stripe CLI 幫你解決這個問題： ```bash # 安裝（macOS） brew install stripe/stripe-cli/stripe # 登入 stripe login # 把 Stripe 的 webhook 事件轉發到你的本地伺服器 stripe listen --forward-to localhost:8000/stripe/webhook ``` 執行後，CLI 會印出一個 `whsec_...` 的 webhook signing secret，把它填到 `.env` 的 `STRIPE_WEBHOOK_SECRET`。開另一個終端機觸發測試事件： ```bash stripe trigger checkout.session.completed ``` 你會看到 CLI 印出事件轉發的紀錄，而你的 Laravel 應用也會收到對應的 webhook。 ## 訂單 Model 設計：Order 與 OrderItem 在接 Stripe 之前，先把訂單的資料結構搞定。揪好買的訂單跟一般電商略有不同：一個訂單對應一個使用者在一個團購裡的跟團記錄。 ### 建立 Migration 與 Model ```bash php artisan make:model Order -mf php artisan make:model OrderItem -mf ``` ### Order Migration ```php id(); $table->foreignId('user_id')->constrained()->cascadeOnDelete(); $table->foreignId('group_buy_id')->constrained()->cascadeOnDelete(); $table->integer('total'); // 總金額（分） $table->string('status')->default('pending'); // pending, paid, failed, refunded $table->string('stripe_checkout_session_id')->nullable(); $table->string('stripe_payment_intent_id')->nullable(); $table->timestamp('paid_at')->nullable(); $table->timestamps(); $table->unique(['user_id', 'group_buy_id']); // 一個使用者在一個團購只有一筆訂單 }); } public function down(): void { Schema::dropIfExists('orders'); } }; ``` ### OrderItem Migration ```php return new class extends Migration { public function up(): void { Schema::create('order_items', function (Blueprint $table) { $table->id(); $table->foreignId('order_id')->constrained()->cascadeOnDelete(); $table->string('product_name'); $table->integer('quantity'); $table->integer('unit_price'); // 單價（分） $table->integer('subtotal'); // 小計（分）= quantity * unit_price $table->timestamps(); }); } public function down(): void { Schema::dropIfExists('order_items'); } }; ``` ### OrderStatus Enum ```php '待付款', self::Paid => '已付款', self::Failed => '付款失敗', self::Refunded => '已退款', self::Shipping => '出貨中', self::Completed => '已完成', }; } public function color(): string { return match ($this) { self::Pending => 'yellow', self::Paid => 'green', self::Failed => 'red', self::Refunded => 'gray', self::Shipping => 'blue', self::Completed => 'green', }; } } ``` ### Model 定義 ```php OrderStatus::class, 'total' => 'integer', 'paid_at' => 'datetime', ]; } // ── 關聯 ── public function user(): BelongsTo { return $this->belongsTo(User::class); } public function groupBuy(): BelongsTo { return $this->belongsTo(GroupBuy::class); } public function items(): HasMany { return $this->hasMany(OrderItem::class); } } ``` ```php 'integer', 'unit_price' => 'integer', 'subtotal' => 'integer', ]; } public function order(): BelongsTo { return $this->belongsTo(Order::class); } } ``` 在 User Model 加上關聯： ```php // app/Models/User.php public function orders(): HasMany { return $this->hasMany(Order::class); } ``` ### ER 關係圖 ``` users ──────< orders >────── group_buys │ │ └──────< order_items ``` - 一個 user 有多個 orders（一對多） - 一個 group_buy 有多個 orders（一對多） - 一個 order 有多個 order_items（一對多） ## Database Transaction：確保資料一致性建立訂單的時候，你需要同時做好幾件事：建立 Order、建立 OrderItem、扣減庫存（如果有的話）。這些動作必須**全部成功**或**全部失敗**——不能出現「Order 建好了但 OrderItem 沒建」的殘缺狀態。這就是 Database Transaction 的用途。 ### DB::transaction() ```php use Illuminate\Support\Facades\DB; $order = DB::transaction(function () use ($user, $groupBuy, $quantity) { // 建立訂單 $order = Order::create([ 'user_id' => $user->id, 'group_buy_id' => $groupBuy->id, 'total' => $groupBuy->price_per_unit * $quantity, 'status' => 'pending', ]); // 建立訂單項目 $order->items()->create([ 'product_name' => $groupBuy->product_name, 'quantity' => $quantity, 'unit_price' => $groupBuy->price_per_unit, 'subtotal' => $groupBuy->price_per_unit * $quantity, ]); return $order; }); ``` 如果 `DB::transaction()` 裡的任何一步拋出例外，所有資料庫操作都會被**回滾**（rollback）——就像什麼都沒發生過一樣。 ### 失敗場景想像這個情況：`Order::create()` 成功了，但 `$order->items()->create()` 因為某個驗證錯誤失敗了。如果沒有 Transaction： - 資料庫裡有一筆 Order，但沒有對應的 OrderItem - 使用者看到「訂單已建立」但內容是空的 - 你需要手動清理殘餘資料有了 Transaction，整個操作被回滾，資料庫維持乾淨。 ### 跨框架對照 | 框架 | Transaction 語法 | | --------- | ----------------------------------------- | | Laravel | `DB::transaction(fn () => ...)` | | Django | `with transaction.atomic():` | | Sequelize | `sequelize.transaction(async (t) => ...)` | | Prisma | `prisma.$transaction([...])` | > **什麼時候該用 Transaction？** 只要你在一個操作裡有**兩個以上**的資料庫寫入，而且它們必須同時成功或失敗，就該用 Transaction。訂單建立、轉帳、庫存異動——這些都是經典場景。 ## Stripe Checkout Session 流程 Checkout Session 是 Stripe 的 hosted 付款頁面。你在後端建立一個 Session，Stripe 回傳一個 URL，你把使用者導過去——Stripe 處理所有付款流程，完成後把使用者導回你的網站。 ### 建立 Checkout Session ```php authorize('pay', $order); $checkout = $order->user->checkout( // line items：顯示在 Stripe 付款頁上的項目 $order->items->map(fn ($item) => [ 'price_data' => [ 'currency' => 'twd', 'product_data' => [ 'name' => $item->product_name, ], 'unit_amount' => $item->unit_price, // 以「分」為單位（TWD 不需要換算） ], 'quantity' => $item->quantity, ])->toArray(), // session options [ 'success_url' => route('checkout.success', ['order' => $order->id]) . '?session_id={CHECKOUT_SESSION_ID}', 'cancel_url' => route('checkout.cancel', ['order' => $order->id]), 'metadata' => [ 'order_id' => $order->id, // 關鍵：在 webhook 裡用這個找回訂單 ], ] ); // 記錄 Session ID 到訂單 $order->update([ 'stripe_checkout_session_id' => $checkout->id, ]); return redirect($checkout->url); } } ``` 這裡有幾個重點： 1. **`unit_amount` 的單位**：Stripe 用的是貨幣的最小單位。對 USD 來說 `1000` = $10.00（以 cent 為單位）；對 TWD 來說 `1000` 就是 NT$1,000（因為台幣沒有「分」）。如果你的資料庫存的是台幣整數，直接給就好。 2. **`metadata`**：自訂資料，Stripe 會在 webhook 事件裡原封不動回傳給你。我們放了 `order_id`，等收到 webhook 時就能快速找到對應的訂單。 3. **`success_url` 和 `cancel_url`**：使用者付款成功/取消後被導回的網址。`{CHECKOUT_SESSION_ID}` 是 Stripe 的 placeholder，會被替換成真正的 Session ID。 ### 成功與取消頁面 ```php // routes/web.php Route::middleware(['auth'])->group(function () { Route::get('/checkout/{order}', [CheckoutController::class, 'create'])->name('checkout.create'); Route::get('/checkout/{order}/success', [CheckoutController::class, 'success'])->name('checkout.success'); Route::get('/checkout/{order}/cancel', [CheckoutController::class, 'cancel'])->name('checkout.cancel'); }); ``` ```php // CheckoutController.php public function success(Request $request, Order $order) { // 注意：不要在這裡更新訂單狀態！ // 這只是使用者看到的頁面，真正的狀態更新要靠 webhook。 // 使用者可能直接複製這個 URL，不代表真的付款了。 return view('checkout.success', [ 'order' => $order->load('items', 'groupBuy'), ]); } public function cancel(Request $request, Order $order) { return view('checkout.cancel', [ 'order' => $order->load('groupBuy'), ]); } ``` > **非常重要：** 絕對不要在 `success_url` 的 callback 裡直接把訂單標記為已付款。使用者可以自己在瀏覽器裡輸入 success URL 而不需要真的付款。**唯一可信的付款確認來源是 Stripe 的 webhook。** ## Webhook 處理：Stripe 回呼你的伺服器 Webhook 的概念很簡單：當 Stripe 那邊發生了某個事件（付款成功、付款失敗、退款完成），Stripe 會主動發一個 HTTP POST 請求到你事先設定好的 URL。你的伺服器接到這個請求，就能做對應的處理。 ### 為什麼需要 Webhook？你可能會想：「使用者付完款被導回 success URL，我在那裡處理不就好了？」不行。有好幾個原因： 1. **使用者可能關掉瀏覽器**——付完款但沒被導回你的網站。 2. **Success URL 可以被偽造**——任何人都能在瀏覽器裡輸入那個 URL。 3. **延遲付款**——某些付款方式（銀行轉帳、超商繳費）不是即時完成的。 4. **Stripe 保證投遞**——如果你的伺服器暫時掛了，Stripe 會重試。 ### Cashier 的 Webhook 路由 Cashier 已經幫你註冊了一個 webhook 路由： ```php // 自動註冊在 POST /stripe/webhook ``` 你需要在 Stripe Dashboard 裡設定 webhook endpoint，指向你的 `https://your-domain.com/stripe/webhook`。 > **CSRF 豁免：** Stripe 的 webhook 請求不會帶 CSRF token（因為是 Stripe 伺服器發的，不是瀏覽器）。Cashier 已經自動把 `/stripe/webhook` 排除在 CSRF 驗證之外，你不需要手動處理。 ### 監聽 Checkout 完成事件 Cashier 會自動驗證 webhook 的簽名（確認是 Stripe 發的，不是惡意攻擊者偽造的），然後把事件分發出來。你只需要監聽對應的事件： ```php payload['type'] !== 'checkout.session.completed') { return; } $session = $event->payload['data']['object']; $orderId = $session['metadata']['order_id'] ?? null; if (! $orderId) { return; } $order = Order::find($orderId); if (! $order || $order->status !== OrderStatus::Pending) { return; } // 走狀態機，而不是直接 update —— 與前面定義的 markAsPaid() 一致 $order->markAsPaid($session['payment_intent']); } } ``` ### 註冊 Listener 在 `AppServiceProvider` 的 `boot()` 方法裡，或用 `EventServiceProvider`： ```php // app/Providers/AppServiceProvider.php use App\Listeners\HandleCheckoutSessionCompleted; use Illuminate\Support\Facades\Event; use Laravel\Cashier\Events\WebhookReceived; public function boot(): void { Event::listen(WebhookReceived::class, HandleCheckoutSessionCompleted::class); } ``` ### Webhook 簽名驗證 Stripe 在每個 webhook 請求的 header 裡帶了一個簽名（`Stripe-Signature`）。Cashier 會用你 `.env` 裡的 `STRIPE_WEBHOOK_SECRET` 來驗證這個簽名，確保請求真的是 Stripe 發的。如果驗證失敗（簽名不對），Cashier 會回傳 403，webhook 內容不會被處理。這是防止惡意攻擊者偽造 webhook 的關鍵安全機制——沒有這一層，任何人都能假裝 Stripe 打你的 webhook endpoint，偽造「付款成功」的通知。 ## 訂單狀態機：從建立到完成訂單在它的生命週期裡會經歷不同的狀態。重點是：**不是每個狀態都能轉換到任何其他狀態**。你不能把「已退款」的訂單變成「待付款」，也不能把「付款失敗」直接跳到「已完成」。 ### 合法的狀態轉換 ``` pending ──→ paid ──→ shipping ──→ completed │ │ │ └──→ refunded │ └──→ failed ──→ pending（重新付款） ``` ### 在 Order Model 上實作狀態轉換 ```php ['paid', 'failed'], 'paid' => ['shipping', 'refunded'], 'failed' => ['pending'], // 重新付款 'shipping' => ['completed'], 'completed' => [], // 終態 'refunded' => [], // 終態 ]; public function transitionTo(OrderStatus $newStatus): void { $allowed = self::ALLOWED_TRANSITIONS[$this->status->value] ?? []; if (! in_array($newStatus->value, $allowed)) { throw new \InvalidArgumentException( "無法將訂單從「{$this->status->label()}」轉換為「{$newStatus->label()}」" ); } $this->update(['status' => $newStatus]); } public function markAsPaid(string $paymentIntentId): void { $this->transitionTo(OrderStatus::Paid); $this->update([ 'stripe_payment_intent_id' => $paymentIntentId, 'paid_at' => now(), ]); } public function markAsFailed(): void { $this->transitionTo(OrderStatus::Failed); } public function markAsShipping(): void { $this->transitionTo(OrderStatus::Shipping); } public function markAsCompleted(): void { $this->transitionTo(OrderStatus::Completed); } // ── 查詢 ── public function isPaid(): bool { return $this->status === OrderStatus::Paid; } public function canPay(): bool { return $this->status === OrderStatus::Pending || $this->status === OrderStatus::Failed; } } ``` 為什麼要搞這麼「囉嗦」的狀態機？因為**不合法的狀態轉換是訂單系統裡最常見的 bug**。你可能在某個 Controller 裡不小心把已退款的訂單又改成已付款，然後使用者收到錯誤的通知、財務報表數字對不上、客服接到一堆抱怨電話。把合法的轉換規則寫死在 Model 裡，任何不合法的操作都會直接拋例外——bug 在開發階段就被抓到，不會偷偷溜到正式環境。 ## 實作：揪好買成團後收款流程理論講完了，讓我們把所有東西串起來。揪好買的收款流程是這樣的： ``` 1. 成團確認（[上一章的邏輯](/blog/laravel-guide-group-buy-logic-session/)） 2. 為每個跟團者建立 Order（DB::transaction） 3. 寄出付款連結給每個跟團者 4. 跟團者點連結 → 導向 Stripe Checkout 5. 付款完成 → Stripe 打 webhook → 更新訂單狀態 6. 所有人都付款了 → 團購狀態改為 completed ``` ### Step 1：成團後批次建立訂單 ```php status !== 'open') { throw new \RuntimeException('此團購已非開放狀態，無法確認成團'); } // 防呆：人數不夠不能成團 if ($groupBuy->participants()->count() < $groupBuy->min_participants) { throw new \RuntimeException('跟團人數未達最低門檻'); } DB::transaction(function () use ($groupBuy) { // 更新團購狀態 $groupBuy->update(['status' => 'confirmed']); // 為每個跟團者建立訂單 foreach ($groupBuy->participants as $participant) { $quantity = $participant->pivot->quantity; $order = Order::create([ 'user_id' => $participant->id, 'group_buy_id' => $groupBuy->id, 'total' => $groupBuy->price_per_unit * $quantity, 'status' => OrderStatus::Pending, ]); $order->items()->create([ 'product_name' => $groupBuy->product_name, 'quantity' => $quantity, 'unit_price' => $groupBuy->price_per_unit, 'subtotal' => $groupBuy->price_per_unit * $quantity, ]); } }); // 寄出付款通知（下一章用 Queue + Notification，詳見 /blog/laravel-guide-queues-events-notifications/） // event(new GroupBuyConfirmed($groupBuy)); } } ``` 整個操作包在 `DB::transaction()` 裡——如果幫第五個人建立訂單的時候炸了，前四個人的訂單也會被回滾。不會出現「有些人有訂單有些人沒有」的混亂狀態。 ### Step 2：CheckoutController 完整實作 ```php user(); // 確認是自己的訂單 if ($order->user_id !== $user->id) { abort(403, '這不是你的訂單'); } // 確認訂單可以付款 if (! $order->canPay()) { return redirect()->route('orders.show', $order) ->with('error', '此訂單目前無法付款'); } $checkout = $user->checkout( $order->items->map(fn ($item) => [ 'price_data' => [ 'currency' => 'twd', 'product_data' => [ 'name' => $item->product_name, ], 'unit_amount' => $item->unit_price, ], 'quantity' => $item->quantity, ])->toArray(), [ 'success_url' => route('checkout.success', $order) . '?session_id={CHECKOUT_SESSION_ID}', 'cancel_url' => route('checkout.cancel', $order), 'metadata' => [ 'order_id' => $order->id, ], ] ); $order->update([ 'stripe_checkout_session_id' => $checkout->id, ]); return redirect($checkout->url); } /** * 付款成功頁面（僅顯示用，真正的狀態更新靠 webhook） */ public function success(Request $request, Order $order) { return view('checkout.success', [ 'order' => $order->load('items', 'groupBuy'), ]); } /** * 使用者取消付款 */ public function cancel(Request $request, Order $order) { return view('checkout.cancel', [ 'order' => $order->load('groupBuy'), ]); } } ``` ### Step 3：路由設定 ```php // routes/web.php use App\Http\Controllers\CheckoutController; Route::middleware(['auth', 'verified'])->group(function () { // 訂單 Route::get('/orders', [OrderController::class, 'index'])->name('orders.index'); Route::get('/orders/{order}', [OrderController::class, 'show'])->name('orders.show'); // Checkout Route::get('/checkout/{order}', [CheckoutController::class, 'create'])->name('checkout.create'); Route::get('/checkout/{order}/success', [CheckoutController::class, 'success'])->name('checkout.success'); Route::get('/checkout/{order}/cancel', [CheckoutController::class, 'cancel'])->name('checkout.cancel'); }); ``` ### Step 4：訂單頁面 View ```html {{-- resources/views/orders/show.blade.php --}}

訂單 #{{ $order->id }}

團購 {{ $order->groupBuy->title }}

狀態 {{ $order->status->label() }}

@foreach ($order->items as $item)

{{ $item->product_name }} x {{ $item->quantity }} NT$ {{ number_format($item->subtotal) }}

@endforeach

合計 NT$ {{ number_format($order->total) }}

@if ($order->canPay()) 前往付款 @endif @if ($order->isPaid())

已於 {{ $order->paid_at->format('Y/m/d H:i') }} 完成付款

@endif

``` ### Step 5：用 Stripe 測試模式跑完整流程 ```bash # 終端機 1：啟動 Laravel php artisan serve # 終端機 2：啟動 Stripe CLI 轉發 webhook stripe listen --forward-to localhost:8000/stripe/webhook # 終端機 3：用 Tinker 模擬成團 php artisan tinker ``` ```php >>> $groupBuy = GroupBuy::first(); >>> app(GroupBuyService::class)->confirm($groupBuy); >>> Order::where('group_buy_id', $groupBuy->id)->count(); // 應該等於跟團人數 ``` 然後用瀏覽器登入任一跟團者帳號，進入訂單頁面，點「前往付款」。你會被導到 Stripe 的付款頁面——輸入測試卡號 `4242 4242 4242 4242`，填任意到期日和 CVC，按下付款。付款成功後： 1. 瀏覽器被導回 success 頁面 2. Stripe CLI 顯示 `checkout.session.completed` 事件被轉發 3. 訂單狀態從 `pending` 變成 `paid` ```php # 在 Tinker 裡確認 >>> Order::first()->fresh()->status // App\Enums\OrderStatus::Paid ``` ### 處理「某個人付款失敗」團購場景的特殊挑戰：10 個人跟團，9 個付款成功，1 個付款失敗。怎麼辦？幾種策略： ```php // 策略一：給期限，逾期自動取消 // 可以用 Laravel Scheduler（第十二章會教） // 每小時檢查一次，超過 48 小時沒付款的訂單標記為 failed // 策略二：允許部分付款完成，照常出貨 // 適合數量彈性的團購 // 策略三：所有人都付款才出貨 // 適合需要精確數量的團購 ``` 揪好買採用策略一——給 48 小時的付款期限，逾期自動標記為失敗，並釋放名額。具體的排程實作會在第十二章搭配 Scheduler 來做。 ## 小結：讓 Stripe 處理金流，你專注在產品這一章我們走過了金流整合的完整流程： - **PCI DSS 合規**——不要自己存信用卡號，讓 Stripe 處理 - **Laravel Cashier**——`composer require laravel/cashier`，加 `Billable` trait，搞定 - **Stripe 測試模式**——測試卡號 + Stripe CLI，完全在本地測試金流 - **訂單設計**——Order + OrderItem，用 Enum 管理狀態，用 DB Transaction 確保一致性 - **Checkout Session**——建立 Session → 導向 Stripe → 使用者付款 → 回到你的網站 - **Webhook**——Stripe 打你的伺服器通知付款結果，Cashier 驗證簽名確保安全 - **狀態機**——明確定義合法的狀態轉換，避免不合法的操作最關鍵的心法是：**不要在 success URL 的 callback 裡更新訂單狀態**。唯一可信的付款確認來源是 webhook。這不是 Laravel 的規矩，而是所有金流整合的通用原則——不管你用的是 Stripe、ECPay 還是任何其他支付服務。下一章我們要處理成團後的一連串後續動作——寄確認信、推播通知、更新統計。如果這些全部塞在同一個 HTTP request 裡，使用者要等十秒才看到回應。[**Queue 與 Event**](/blog/laravel-guide-queues-events-notifications/) 讓你把這些耗時任務丟到背景去跑，使用者按下按鈕的瞬間就看到回應。

跟團與成團邏輯：用 Laravel Session 打造從「+1」到「成團確認」

Tue, 22 Apr 2025 00:00:00 GMT

團購平台的核心，說穿了就是兩個字：+1。有人開團、有人跟團、湊到最低人數就成團。聽起來簡單，但背後的工程考量比你想像的多： - 使用者還沒登入就想跟團怎麼辦？ - 同時一百個人按下「+1」會不會超賣？ - 截止時間到了但人數不夠要怎麼處理？ - 成團瞬間要同時通知所有跟團者、建立訂單、鎖定庫存，這些動作的順序和原子性都不能出錯。這一章是「揪好買」的心臟。我們要用 Laravel 的 Session 機制處理使用者的暫存狀態，用 Cache 加速熱門團購的讀取，用 Livewire 做即時的跟團人數更新，然後把「成團條件判斷」這個最關鍵的業務邏輯寫得清楚明白。技術選型不是重點——Session driver 用 database 還是 Redis、Cache 用 file 還是 Memcached，這些換一行設定就能改。真正難的是業務邏輯本身：什麼時候該鎖定、什麼時候該釋放、edge case 怎麼處理。老實說，框架教學最容易迴避的就是業務邏輯。因為每個專案不一樣，沒有標準答案。但我認為這才是你真正需要練習的部分——把模糊的需求轉化成明確的程式碼。這一章，我們就來面對它。 ## 跟團前先懂 Session：HTTP 是無狀態的 HTTP 本身是無狀態的（stateless）。每一次請求對 server 來說都是全新的陌生人——server 不知道五秒前那個看了團購列表的人，跟現在要按 +1 的人是不是同一個。這就好像你每次走進便利商店，店員都不認得你。 Web 應用程式怎麼解決這個問題？**Session**。 Session 的運作原理其實很簡單： 1. 使用者第一次造訪網站時，server 產生一個隨機 ID（Session ID） 2. 這個 ID 透過 Cookie 送回瀏覽器 3. 往後每次請求，瀏覽器自動帶上這個 Cookie 4. Server 收到 Cookie，用 Session ID 查找對應的資料 5. 資料存在 server 端（檔案、資料庫、Redis），不在瀏覽器裡所以 Session 就是 server 端的暫存記憶體——你放什麼進去，下一次請求都還在。 ### 跨框架對照 | 概念 | Laravel | Express (Node.js) | Django (Python) | | ------------ | --------------------------- | ------------------------- | -------------------------------- | | Session 套件 | 內建 | `express-session` | 內建 | | 儲存位置設定 | `SESSION_DRIVER` in `.env` | `store` option | `SESSION_ENGINE` | | 讀取 | `session('key')` | `req.session.key` | `request.session['key']` | | 寫入 | `session(['key' => 'val'])` | `req.session.key = 'val'` | `request.session['key'] = 'val'` | | Flash data | `session()->flash()` | `req.flash()` (需套件) | `messages` framework | 如果你從 Express 轉過來，Laravel 的 Session 概念一模一樣，只是 Express 需要你自己裝 `express-session` 然後選 store（memory、redis、mongo），而 Laravel 全部幫你包好了——改一行 `.env` 就切換儲存方式。 ## Laravel Session 機制：Driver 選擇與設定打開 `.env`，找到 `SESSION_DRIVER`： ```bash SESSION_DRIVER=database ``` ### Driver 一覽 | Driver | 說明 | 適合場景 | | ---------- | ---------------------------------- | --------------------------- | | `file` | 存在 `storage/framework/sessions/` | 單機開發、小型站台 | | `database` | 存在 `sessions` 資料表 | Laravel 12 預設，通用且可靠 | | `redis` | 存在 Redis | 高流量正式環境，速度最快 | | `cookie` | 加密後存在 Cookie | 輕量，但有 4KB 大小限制 | | `array` | 存在記憶體（request 結束就消失） | 測試用 | Laravel 12 新建專案預設用 `database`。執行 `php artisan migrate` 時會自動建好 `sessions` 資料表——你不用額外做任何事。 > **生產環境建議：** 如果你的流量大，Session driver 換成 `redis` 是最直接的升級。改一行 `SESSION_DRIVER=redis`，前提是你裝了 Redis server。開發階段用 `database` 就好，不要過早優化。 ### Session 基本操作 ```php // ── 寫入 ── session(['cart_quantity' => 3]); // 或者 session()->put('cart_quantity', 3); // ── 讀取 ── $qty = session('cart_quantity'); // 取得值 $qty = session('cart_quantity', 0); // 預設值（key 不存在時回傳 0） $qty = session()->get('cart_quantity', 0); // 等效寫法 // ── 檢查 ── if (session()->has('cart_quantity')) { // key 存在且不為 null } if (session()->exists('cart_quantity')) { // key 存在（可能為 null） } // ── 刪除 ── session()->forget('cart_quantity'); // 刪除單一 key session()->forget(['cart_quantity', 'selected_group']); // 刪除多個 session()->flush(); // 清空整個 session // ── 所有資料 ── $all = session()->all(); ``` ### Flash Data：一次性訊息 Flash data 是只在「下一次請求」有效的 session 資料，用完即消。最典型的用途是操作成功/失敗的通知訊息： ```php // Controller 裡 session()->flash('success', '成功加入團購！'); return redirect("/group-buys/{$groupBuy->id}"); // 或用 redirect 的語法糖 return redirect("/group-buys/{$groupBuy->id}") ->with('success', '成功加入團購！'); ``` 在 Blade 裡顯示： ```blade @if(session('success'))

@endif @if(session('error'))

@endif ``` 重新整理頁面後，這些訊息就消失了——因為 flash data 只活一次。 ## 跟團邏輯設計：選數量、加入、取消好，技術工具介紹完了。現在進入這一章的核心——跟團邏輯。 ### 需求拆解使用者在團購詳情頁看到一個「+1 跟團」按鈕。點下去之前，他要先選擇數量（跟幾份）。點下去之後： 1. **驗證**——團購還在開團嗎？還沒滿嗎？這個人已經跟過了嗎？ 2. **寫入**——把這個人加到 `group_buy_user` 中間表 3. **回饋**——頁面顯示「成功加入！」，參與人數即時更新取消跟團的邏輯相反：從中間表 detach，人數減少。 ### 驗證規則在寫程式碼之前，先把規則列清楚。這是業務邏輯最重要的步驟——先用人話寫出所有條件，再翻譯成程式碼： 1. 團購 `status` 必須是 `open` 2. 團購 `deadline` 還沒過 3. 使用者必須已登入 4. 使用者不能重複加入同一個團購 5. 如果有 `max_participants`，目前人數不能超過上限 6. 數量必須是正整數 ### Livewire Component：JoinGroupBuy ```bash php artisan make:livewire JoinGroupBuy ``` ```php groupBuy = $groupBuy; if (Auth::check()) { $existing = $groupBuy->participants() ->where('user_id', Auth::id()) ->first(); if ($existing) { $this->hasJoined = true; $this->currentQuantity = $existing->pivot->quantity; } } } public function join(): void { // 1. 必須登入 if (! Auth::check()) { $this->redirect(route('login')); return; } // 2. 驗證數量 $this->validate([ 'quantity' => 'required|integer|min:1|max:10', ]); // 3. 團購還在開團嗎？ if ($this->groupBuy->status !== 'open') { session()->flash('error', '這個團購已經不接受跟團了。'); return; } // 4. 還沒截止嗎？ if ($this->groupBuy->deadline->isPast()) { session()->flash('error', '這個團購已經截止了。'); return; } // 5. 沒有重複加入？ if ($this->hasJoined) { session()->flash('error', '你已經跟過這個團了。'); return; } // 6. 還有名額嗎？ if ($this->groupBuy->max_participants) { $currentCount = $this->groupBuy->participants()->count(); if ($currentCount >= $this->groupBuy->max_participants) { session()->flash('error', '這個團已經滿了。'); return; } } // 7. 一切驗證通過，加入團購 $this->groupBuy->participants()->attach(Auth::id(), [ 'quantity' => $this->quantity, ]); $this->hasJoined = true; $this->currentQuantity = $this->quantity; // 通知其他 Livewire component 更新 $this->dispatch('participant-updated'); session()->flash('success', "成功跟團！你選了 {$this->quantity} 份。"); } public function leave(): void { if (! $this->hasJoined) { return; } // 已成團的不能退出 if ($this->groupBuy->status !== 'open') { session()->flash('error', '團購已成團，無法退出。'); return; } $this->groupBuy->participants()->detach(Auth::id()); $this->hasJoined = false; $this->currentQuantity = 0; $this->dispatch('participant-updated'); session()->flash('success', '你已退出這個團購。'); } public function render() { return view('livewire.join-group-buy'); } } ``` 對應的 Blade 模板： ```blade

@if(session('success'))

@endif @if(session('error'))

@endif @if($hasJoined)

你已跟團 {{ $currentQuantity }} 份

@if($groupBuy->status === 'open') @endif

@else @if($groupBuy->status === 'open' && ! $groupBuy->deadline->isPast())

數量

@else

此團購已截止或不再接受跟團

@endif @endif

``` ### 為什麼用 `attach()` / `detach()`？回顧[第四章的多對多關聯](/blog/laravel-guide-eloquent-orm-models/)——`group_buy_user` 是 pivot table，`attach()` 新增一筆關聯，`detach()` 移除。這比自己手寫 `DB::table('group_buy_user')->insert(...)` 乾淨很多，而且 Eloquent 會自動幫你維護 timestamps。 ## 成團條件判斷：最低人數與截止時間跟團邏輯處理的是個人行為——一個人加入、一個人退出。**成團邏輯**處理的是整個團的狀態轉換。 ### 狀態轉換圖 ``` ┌──────────────┐ │ open │ │ （開團中） │ └──────┬───────┘ │ ┌──────────┴──────────┐ │ │ 人數 >= 最低門檻截止時間到了 (可提前成團) 但人數不夠 │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ confirmed │ │ cancelled │ │ （已成團） │ │ （已取消） │ └──────────────┘ └──────────────┘ ``` 規則很明確： 1. **成團**：參與人數 >= `min_participants`（不管截止時間到了沒，都可以成團） 2. **取消**：截止時間到了，但參與人數 < `min_participants` 3. **開團中**：還沒截止，人數也還不夠不過「人數一夠就提前成團」是我做的產品選擇，不是唯一正解，這裡先講清楚兩件事： - **提前鎖定有代價**：有些團購反而希望跑滿整個截止時間，盡量蒐集人數去衝更低的折扣級距（湊到 50 人比 20 人便宜）。你一達標就 confirm，等於把後面那批人擋在門外，揪團規模反而變小。要不要提前成團，看你的折扣是不是階梯式的——如果是，可能該等截止才結算。 - **`checkAndConfirm()` 要有人叫它**：這個方法不會自己跑。下面你會看到它靠 `join()` 事件或每 5 分鐘的 scheduler 觸發，但等一下的 `JoinGroupBuy::join()` 其實只有 attach 完 dispatch UI 事件、**沒有呼叫 `checkAndConfirm()`**。所以實務上的成團時間點是「下一個人 +1」或「scheduler 下一輪」，最慘可能拖好幾分鐘——明明第 5 個人已經進來了，狀態卻還掛在 open。要避免這種「達標但遲遲沒成團」的尷尬，記得在 `join()` 的 attach 之後補一行 `$this->groupBuy->checkAndConfirm()`，讓達標當下就結算。 ### GroupBuy Model 方法：`checkAndConfirm()` ```php // app/Models/GroupBuy.php use Illuminate\Support\Facades\DB; /** * 檢查並更新成團狀態 * 回傳是否發生狀態變更 */ public function checkAndConfirm(): bool { // 只有 open 狀態才需要檢查 if ($this->status !== 'open') { return false; } $participantCount = $this->participants()->count(); // 情況一：人數夠了 → 成團 if ($participantCount >= $this->min_participants) { return $this->confirmGroup(); } // 情況二：截止了但人數不夠 → 取消 if ($this->deadline->isPast() && $participantCount < $this->min_participants) { return $this->cancelGroup(); } // 情況三：還在進行中 return false; } private function confirmGroup(): bool { return DB::transaction(function () { // 用悲觀鎖鎖住這筆團購，避免 race condition $groupBuy = GroupBuy::lockForUpdate()->find($this->id); // 再次確認狀態（double-check locking） if ($groupBuy->status !== 'open') { return false; } $groupBuy->update(['status' => 'confirmed']); // TODO: 第十章會加入——通知所有參與者、建立訂單 // event(new GroupBuyConfirmed($groupBuy)); return true; }); } private function cancelGroup(): bool { return DB::transaction(function () { $groupBuy = GroupBuy::lockForUpdate()->find($this->id); if ($groupBuy->status !== 'open') { return false; } $groupBuy->update(['status' => 'cancelled']); // TODO: 通知所有參與者團購取消 // event(new GroupBuyCancelled($groupBuy)); return true; }); } ``` 成團後的通知與訂單建立（`GroupBuyConfirmed` 事件、Queue 處理）將在[第十章：Queue、Event 與通知](/blog/laravel-guide-queues-events-notifications/)詳細介紹。 ### 為什麼需要 `DB::transaction()` 和 `lockForUpdate()`？想像這個場景：團購需要 5 人成團，目前已經有 4 個人。第五個人和第六個人幾乎同時按下 +1。 **沒有鎖的情況：** ``` 使用者 A 讀取人數 → 4 人使用者 B 讀取人數 → 4 人使用者 A 加入 → 5 人 → 觸發成團 ✅ 使用者 B 加入 → 6 人 → 又觸發成團？或超過上限？❌ ``` **有鎖的情況：** ``` 使用者 A 取得鎖 → 讀取 4 人 → 加入 → 5 人 → 成團 → 釋放鎖使用者 B 等待鎖 → 取得鎖 → 讀取 5 人 → 已成團，不再處理 → 釋放鎖 ``` `lockForUpdate()` 是資料庫的悲觀鎖（`SELECT ... FOR UPDATE`），確保同一時間只有一個 process 能修改這筆資料。搭配 `DB::transaction()` 保證整組操作的原子性——要嘛全部成功，要嘛全部回滾。 > **悲觀鎖不是萬靈丹，講幾句它的代價。** `FOR UPDATE` 在低併發下很好用，但併發一上來，搶不到鎖的 request 會排隊乾等，連線一個個卡住，連線池滿了就開始噴 error；兩筆交易互相等對方的鎖還會 deadlock。它也綁 DB 引擎——MySQL InnoDB / Postgres 行為正常，SQLite 根本不是那樣鎖，你本機測過了上線可能兩種行為。所以前面說「高流量改用 Redis」跟這裡說「用悲觀鎖」其實有點打架：真高流量時，悲觀鎖本身可能就是瓶頸。 > > 想換做法的話：樂觀鎖（加個 `version` 欄位，update 時帶條件，撞到就重試）、單一原子 `UPDATE ... WHERE status = 'open'`（靠 DB 自己的行鎖，不用顯式 `FOR UPDATE`）、或把成團檢查丟進 queue 用單一 worker 序列化處理，都比硬鎖更耐操。 > > 還有一句更重要的：**真正怕超賣的是「名額/庫存」那一層**，那裡才該下重手防併發。成團狀態從 open 轉 confirmed 只會發生一次、併發量通常很低，這裡用悲觀鎖是「夠用」而非「最佳」——學概念剛好，別把它當成所有 race condition 的標準答案。 ### Scheduled Command：定時檢查過期團購有些團購不會被人手動觸發成團檢查——可能截止時間到了但最後一個人早就加入了，沒有新的 +1 來觸發 `checkAndConfirm()`。所以我們需要一個定時任務來掃描過期的團購。 ```bash php artisan make:command CheckExpiredGroupBuys ``` ```php where('deadline', '<=', now()) ->get(); $confirmed = 0; $cancelled = 0; foreach ($expiredGroups as $groupBuy) { if ($groupBuy->checkAndConfirm()) { if ($groupBuy->fresh()->status === 'confirmed') { $confirmed++; } else { $cancelled++; } } } $this->info("處理完成：{$confirmed} 個成團、{$cancelled} 個取消"); return self::SUCCESS; } } ``` 在 `routes/console.php`（Laravel 12 的排程檔案）裡註冊： ```php // routes/console.php use Illuminate\Support\Facades\Schedule; Schedule::command('group-buys:check-expired')->everyFiveMinutes(); ``` 每五分鐘跑一次，把所有已截止的團購該成團的成團、該取消的取消。生產環境記得啟動 scheduler： ```bash # crontab -e，加入這一行 * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1 ``` ## Cache Facade：快取熱門資料團購列表頁可能有幾十個團購，每一個都要 `$groupBuy->participants()->count()` 去查 pivot table——如果首頁流量大，這些 COUNT 查詢會成為瓶頸。Cache（快取）可以大幅減少資料庫壓力。 ### Cache 基本操作 ```php use Illuminate\Support\Facades\Cache; // ── 存入 ── Cache::put('key', 'value', now()->addMinutes(30)); // 30 分鐘後過期 // ── 讀取 ── $value = Cache::get('key'); // 不存在回傳 null $value = Cache::get('key', 'default'); // 不存在回傳 default // ── remember：不存在就執行 closure 並快取 ── $count = Cache::remember('group_buy_42_count', now()->addMinutes(5), function () { return GroupBuy::find(42)->participants()->count(); }); // 第一次：跑 DB 查詢，結果存入快取 // 之後五分鐘內：直接從快取拿，不碰 DB // ── 刪除 ── Cache::forget('group_buy_42_count'); // ── 永久快取 ── Cache::forever('site_settings', $settings); ``` ### 在揪好買中快取跟團人數 ```php // app/Models/GroupBuy.php public function cachedParticipantCount(): int { return Cache::remember( "group_buy_{$this->id}_participant_count", now()->addMinutes(5), fn () => $this->participants()->count() ); } ``` 在 JoinGroupBuy component 的 `join()` 和 `leave()` 方法裡，加入 cache 失效： ```php // 加入或退出後，清除快取 Cache::forget("group_buy_{$this->groupBuy->id}_participant_count"); ``` ### Cache Driver 選擇 ```bash # .env CACHE_STORE=database # Laravel 12 預設 ``` | Driver | 特點 | 適合場景 | | ---------- | --------------- | -------------- | | `file` | 零設定 | 開發、小站 | | `database` | 可靠，預設 | 一般用途 | | `redis` | 最快，支援 tags | 高流量正式環境 | | `array` | 不持久化 | 測試 | 跟 Session driver 一樣的故事——開發用 `database`，流量大了再換 `redis`。程式碼完全不用改。 ## 登入前後狀態合併策略這是很容易被忽略的 UX 問題：使用者還沒登入就開始瀏覽團購，甚至把某個團購加到「想跟」清單。登入之後，這些行為不應該消失——要把 session 裡的暫存資料合併到資料庫裡。 ### 場景 1. 訪客 A 瀏覽團購 #42，把它加入「收藏清單」（存在 session） 2. 訪客 A 按下「+1 跟團」→ 被導向登入頁 3. A 登入成功 → 回到團購 #42 → 收藏清單裡應該還有 #42 ### 實作：合併 Session 資料 Laravel 在使用者登入時會觸發 `Login` event。我們可以監聽這個 event，在登入後把 session 資料合併到資料庫： ```php user; // 合併收藏清單 $sessionFavorites = session()->pull('guest_favorites', []); if (! empty($sessionFavorites)) { // 把 session 裡的收藏寫到 user 的資料庫記錄 foreach ($sessionFavorites as $groupBuyId) { $user->favorites()->syncWithoutDetaching([$groupBuyId]); } } // 如果訪客有「想跟團」的意圖，導向那個團購頁 $pendingJoin = session()->pull('pending_join_group_buy'); if ($pendingJoin) { session()->flash('info', '你可以繼續完成跟團了！'); // Livewire 或 Controller 可以根據這個 flash 做導向 } } } ``` 在 `EventServiceProvider` 或 `AppServiceProvider` 裡註冊： ```php // app/Providers/AppServiceProvider.php use App\Listeners\MergeSessionDataAfterLogin; use Illuminate\Auth\Events\Login; use Illuminate\Support\Facades\Event; public function boot(): void { Event::listen(Login::class, MergeSessionDataAfterLogin::class); } ``` 而在 JoinGroupBuy component 的 `join()` 方法裡，如果使用者未登入，先記住意圖： ```php public function join(): void { if (! Auth::check()) { // 記住使用者想跟哪個團 session()->put('pending_join_group_buy', $this->groupBuy->id); $this->redirect(route('login')); return; } // ...後續驗證和加入邏輯 } ``` 登入成功後，使用者會被導回原頁面，看到一條 flash 訊息提醒他繼續完成跟團。 > **Session 的妙用：** 很多人以為 session 只是「登入狀態」，其實它是通用的暫存工具。訪客瀏覽行為、購物車、表單草稿、多步驟流程的中間狀態——都可以用 session 暫存，登入後再合併到資料庫。 ## Livewire 即時更新跟團人數團購詳情頁除了 JoinGroupBuy component，還需要顯示「目前幾人跟團」。這個數字要在有人加入/退出時即時更新——前面的 JoinGroupBuy 會 dispatch `participant-updated` 事件，我們可以做一個 component 來監聽它。 ### ParticipantCounter Component ```php groupBuy = $groupBuy; $this->refreshCount(); } #[On('participant-updated')] public function refreshCount(): void { $this->count = $this->groupBuy->participants()->count(); $this->totalQuantity = (int) $this->groupBuy ->participants() ->sum('group_buy_user.quantity'); } public function render() { $progress = $this->groupBuy->min_participants > 0 ? min(100, round(($this->count / $this->groupBuy->min_participants) * 100)) : 0; return view('livewire.participant-counter', [ 'progress' => $progress, ]); } } ``` ```blade

{{ $count }} / {{ $groupBuy->min_participants }} 人 @if($groupBuy->max_participants) （上限 {{ $groupBuy->max_participants }} 人） @endif

共 {{ $totalQuantity }} 份 @if($progress >= 100) 已達成團門檻！ @else ，還差 {{ $groupBuy->min_participants - $count }} 人成團 @endif

``` ### 關鍵設計 - **`#[On('participant-updated')]`**：PHP 8 Attribute 語法，告訴 Livewire「當收到 `participant-updated` 事件時，執行這個方法」。JoinGroupBuy 在加入/退出後 dispatch 這個事件，ParticipantCounter 就會即時更新——同一頁面上的跨 component 通訊。 - **`wire:poll.30s`**：每 30 秒自動跟 server 同步一次。這是為了處理「別人在其他瀏覽器跟團」的情況——你不會收到 Livewire 事件，但 poll 會定時拉最新數字。 - **進度條**：視覺化呈現成團進度，用百分比計算寬度。CSS `transition-all` 讓寬度變化有動畫。 > **wire:poll 的代價：** 每 30 秒一次 AJAX 請求。如果頁面上有很多使用者同時瀏覽，這會產生不少請求。正式環境如果流量真的很大，可以考慮用 Laravel Echo + WebSocket 做真正的即時推播。但對揪好買的規模來說，30 秒 poll 完全夠用。 ## 倒數計時：團購截止提醒截止時間的倒數計時是純前端的事——每秒更新一次，不需要打 server。用 Alpine.js 就對了。 ```blade

``` Alpine.js 的 countdown 函式放在全域 JS 裡： ```javascript // resources/js/countdown.js document.addEventListener('alpine:init', () => { Alpine.data('countdown', (deadline) => ({ days: '00', hours: '00', minutes: '00', seconds: '00', expired: false, interval: null, start() { this.update(); this.interval = setInterval(() => this.update(), 1000); }, update() { const now = new Date().getTime(); const target = new Date(deadline).getTime(); const diff = target - now; if (diff <= 0) { this.expired = true; clearInterval(this.interval); // 截止了，重新整理頁面讓 server 更新狀態 setTimeout(() => window.location.reload(), 2000); return; } this.days = String(Math.floor(diff / (1000 * 60 * 60 * 24))).padStart(2, '0'); this.hours = String(Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60))).padStart( 2, '0' ); this.minutes = String(Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60))).padStart(2, '0'); this.seconds = String(Math.floor((diff % (1000 * 60)) / 1000)).padStart(2, '0'); }, destroy() { clearInterval(this.interval); }, })); }); ``` 在 `resources/js/app.js` 引入： ```javascript import './countdown.js'; ``` ### 為什麼倒數計時用 Alpine.js 而不是 Livewire？因為倒數計時需要**每秒**更新。如果用 `wire:poll.1s`，每秒都要跑一趟 AJAX 到 server——這完全沒必要，截止時間又不會變。純前端的 `setInterval` 搭配 Alpine.js，零 server 負擔，體驗也更流暢。這是 Livewire + Alpine.js 分工的經典案例： - **需要 server 資料（人數、狀態）** → Livewire - **純 UI 計算（倒數、動畫）** → Alpine.js ## 實作：揪好買的跟團完整流程把前面所有元件串起來，做一個完整的團購詳情頁。 ### 路由 ```php // routes/web.php Route::get('/group-buys/{groupBuy}', function (GroupBuy $groupBuy) { return view('group-buys.show', compact('groupBuy')); })->name('group-buys.show'); ``` ### 團購詳情頁 ```blade

{{ match($groupBuy->status) { 'open' => '開團中', 'confirmed' => '已成團', 'cancelled' => '已取消', default => $groupBuy->status, } }}

開團者：{{ $groupBuy->organizer->name }} ・{{ $groupBuy->created_at->diffForHumans() }}

@if($groupBuy->image) image) }}" alt="{{ $groupBuy->product_name }}" class="w-full rounded-xl" /> @endif

${{ number_format($groupBuy->price_per_unit / 100) }} / 份

跟團者

@forelse($groupBuy->participants as $participant)

{{ $participant->name }} {{ $participant->pivot->quantity }} 份 @if($participant->pivot->note) ・{{ $participant->pivot->note }} @endif

@empty

還沒有人跟團，成為第一個吧！

@endforelse

{{-- 倒數計時 --}} @if($groupBuy->status === 'open') @include('partials.countdown', ['deadline' => $groupBuy->deadline]) @endif {{-- 跟團人數 --}}

跟團進度

``` ### 流程測試 ```bash # 重建資料庫和測試資料 php artisan migrate:fresh --seed # 啟動開發 server php artisan serve & npm run dev & ``` 開兩個瀏覽器（或一個開無痕模式），用不同帳號登入： 1. **瀏覽器 A**：進入某個團購頁，看到「0 / 5 人」 2. **瀏覽器 A**：選 2 份，按 +1 跟團 → 成功，顯示「1 / 5 人」 3. **瀏覽器 B**：登入另一個帳號，進入同一個團購 4. **瀏覽器 B**：看到「1 / 5 人」（wire:poll 會同步） 5. **瀏覽器 B**：按 +1 跟團 → 成功，顯示「2 / 5 人」 6. **瀏覽器 A**：等 30 秒或重新整理 → 看到「2 / 5 人」再測邊界情況： - 嘗試重複加入 → 看到「你已經跟過這個團了」 - 在團購截止後按 +1 → 看到「這個團購已經截止了」 - 退出團購 → 人數減少，按鈕恢復成「+1 跟團」 ### Tinker 測試成團 ```bash php artisan tinker >>> $gb = GroupBuy::where('status', 'open')->first() >>> $gb->min_participants # 假設是 3 >>> $gb->participants()->count() # 假設已經有 3 人 >>> $gb->checkAndConfirm() # true >>> $gb->fresh()->status # "confirmed" ``` 也可以手動跑定時任務： ```bash php artisan group-buys:check-expired # 處理完成：1 個成團、2 個取消 ``` ## 小結：業務邏輯才是最難的部分回顧這一章的技術點： - **Session**——server 端的暫存記憶體，`put()` / `get()` / `flash()` 三板斧 - **Cache**——`Cache::remember()` 快取熱門查詢結果，減少 DB 壓力 - **DB Transaction + lockForUpdate()**——保護成團判斷的原子性，避免 race condition - **Scheduled Command**——定時檢查過期團購，`php artisan schedule:run` - **Livewire Events**——`$this->dispatch()` + `#[On()]` 做跨 component 通訊 - **Alpine.js**——純前端倒數計時，不打 server - **Login Event Listener**——登入後合併 session 資料但老實說，這些技術點都不是這一章最難的部分。最難的是**業務邏輯的設計**： - 什麼時候成團？什麼時候取消？什麼時候保持開放？ - 誰能加入？加入的條件是什麼？退出的限制呢？ - Race condition 怎麼處理？狀態轉換的原子性怎麼保證？ - 登入前後的使用者體驗怎麼銜接？框架給你工具，但不會告訴你「最低成團人數應該設在哪裡檢查」或「截止時間到了但人數不夠要不要寬限十分鐘」。這些是業務決策，只有跟產品經理（或者自己兼任產品經理的你）討論清楚之後，才能轉化成明確的 `if-else`。我的建議：**先用人話把所有規則列出來，再寫程式碼**。本章的驗證清單就是這個做法——六條規則寫清楚了，程式碼幾乎是自動翻譯出來的。最怕的是邊寫邊想、邊改邊加，最後程式碼變成一堆互相矛盾的條件分支，連自己都看不懂。下一章，我們要面對成團之後最關鍵的問題——收錢。訂單怎麼建立？Stripe 怎麼串接？[Laravel Cashier](/blog/laravel-guide-orders-stripe-cashier/) 能幫我們做到什麼？團購的收款跟一般電商不一樣——不是「買了就付」，而是「成團了才收」。這個時序差異會影響整個金流架構的設計。

表單驗證與檔案上傳：讓使用者好好提交資料

Tue, 15 Apr 2025 00:00:00 GMT

使用者輸入的資料，永遠不能信任。這不是偏執，是血淚教訓。前端驗證擋得了手滑的一般使用者，擋不了： - 開 DevTools 直接改掉 HTML 的人 - 用 `curl` 繞過瀏覽器直打你 API 的人 - 自動化攻擊腳本後端驗證是最後一道防線，也是唯一可靠的防線。 Laravel 的驗證系統大概是我用過最舒服的——內建超過 90 條驗證規則，從 `required`、`email`、`max` 到 `exists:users,id` 這種直接查資料庫的都有，而且錯誤訊息自動對應、自動回填表單，開發體驗好到讓你不想偷懶跳過驗證。除了文字資料，表單常常還要處理檔案上傳——大頭照、商品圖片、附件。Laravel 的 Storage facade 把檔案操作抽象化，不管你底層用的是本地硬碟、Amazon S3 還是其他雲端儲存，程式碼寫法都一樣。搭配 Form Request 把驗證邏輯從 Controller 搬出去，你的 Controller 就能保持精簡，每個 method 不超過十行。在「揪好買」團購平台裡，開團主建立團購時要填寫商品名稱、描述、最低成團人數、截止時間，還要上傳商品圖片。這一章我們會完整實作這張「開團」表單——從驗證規則、錯誤處理、圖片上傳到縮圖生成，每一步都用 Laravel 最佳實踐來做。 ## 為什麼需要後端驗證：前端擋不住的事你可能會想：「我前端已經用 JavaScript 做了驗證，使用者填錯會即時提示，應該夠了吧？」讓我示範一下為什麼不夠。假設你的「開團」表單前端限制了標題必須填寫、價格必須是正數。但攻擊者完全可以繞過瀏覽器，直接用 curl 送請求： ```bash # 繞過前端，直接打後端 API curl -X POST http://localhost:8000/group-buys \ -H "Content-Type: application/json" \ -d '{"title": "", "price_per_unit": -100, "deadline": "1999-01-01"}' ``` 前端驗證完全沒機會攔截這個請求。標題是空的、價格是負數、截止時間在 25 年前——如果後端照單全收，你的資料庫就被塞了一筆垃圾資料。後端驗證攔的就是這種「形狀壞掉」的資料：空標題、負數價格、過去的截止日。前端的 `required` 和 `minLength` 一個 `curl` 就繞過了，所以這道把關只能放在後端。所以原則很簡單：**前端驗證是為了使用者體驗（即時反饋），後端驗證是為了把關資料的正確性。兩者缺一不可，但如果只能選一個，一定是後端。** 不過我要先講清楚一件事，免得你誤會：validation 不是萬靈丹。`required|string|max:2000` 這種規則管的是「資料長什麼樣、符不符合業務規則」，它不會幫你擋 SQL injection，也不會擋 stored XSS。那是另外兩層的事： - **防 SQL injection** 靠的是 Eloquent / Query Builder 的參數化綁定。只要你不去手動拼 raw SQL 字串，注入這條路本來就被堵住了，跟你有沒有寫 validation 無關。 - **防 XSS** 靠的是輸出端——Blade 的 `{{ }}` 預設會做 HTML escape。所以 description 就算真的被塞了 `