API 金鑰之亂終結者：Laravel + JWT 深度實戰，打造無狀態認證的現代化後端！

嘿，我是浪花科技的資深工程師 Eric。最近接了幾個案子，前端都吵著要 API，還指定要用 JWT 認證。這讓我想起以前剛開始做前後端分離專案時，還傻傻地想把傳統網站的 Session/Cookie 那套搬過來用，結果搞得自己灰頭土臉。如果你也正在開發 SPA (Single Page Application)、手機 App，或是任何需要與後端 API 溝通的應用，那你遲早會遇到這個問題：驗證機制該怎麼做？

今天，就讓我這個踩過無數坑的工程師，帶你徹底搞懂為什麼在現代化的架構下，JWT (JSON Web Tokens) 會是你最好的朋友，以及如何在 PHP 框架的優等生——Laravel 中，優雅地實現它。別再把 API 當作網站的附屬品了，它可是現代應用程式的心臟啊！

為什麼你的 API 需要 JWT？告別 Session 的歷史包袱

在我們動手寫 Code 之前，身為一個囉嗦的工程師，我必須先讓你搞懂「為什麼」。很多人會問：「我用 PHP 的 `$_SESSION` 不是好好的嗎？為什麼要搞一個這麼複雜的東西？」問得好，這就牽涉到「有狀態」與「無狀態」兩種驗證模式的根本差異。

有狀態 (Stateful) vs. 無狀態 (Stateless) 的戰爭

• 有狀態 (Stateful) 驗證：這就是我們熟悉的 Session 機制。當使用者登入後，伺服器會創建一個 Session 檔案或紀錄來儲存使用者狀態（例如登入中、購物車內容），然後回傳一個 Session ID 的 Cookie 給瀏覽器。之後的每次請求，瀏覽器都會帶著這個 Session ID，伺服器再根據 ID 找到對應的 Session 檔案來驗證身份。
• 無狀態 (Stateless) 驗證：JWT 就是這種模式的代表。使用者登入後，伺服器會產生一個加密過的「令牌 (Token)」給使用者。這個 Token 本身就包含了所有驗證需要的資訊（例如使用者 ID、權限、過期時間）。之後的每次請求，使用者都必須自己帶著這個 Token，伺服器收到後只需驗證 Token 的合法性，完全不需要在自己家裡（伺服器端）儲存任何 Session 資訊。

聽起來好像差不多？魔鬼藏在細節裡。當你的網站流量變大，需要多台伺服器做負載平衡 (Load Balancing) 時，有狀態的 Session 就會是個大麻煩。使用者的第一次請求可能送到 A 伺服器，第二次卻送到 B 伺服器，但 B 伺服器上沒有這個使用者的 Session 資料，於是使用者就被強制登出了。為了解決這個問題，你得搞「Sticky Session」（讓同一個使用者黏在同一台伺服器）或是共用 Session 儲存（例如用 Redis），增加了架構的複雜度。但無狀態的 JWT 就沒這個問題，不管請求送到哪台伺服器，只要 Token 是合法的，伺服器就能認得你，這讓系統的水平擴展變得非常簡單。

JWT (JSON Web Token) 結構大解密

JWT 本質上就是一個長長的字串，由三個部分用點 `.` 隔開，分別是：Header (標頭)、Payload (酬載)、Signature (簽章)。

一個典型的 JWT 長這樣：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

• Header (標頭): 通常由兩部分組成：令牌的類型（`typ`），也就是 JWT，以及所使用的簽名演算法（`alg`），例如 `HS256`。這部分會經過 Base64Url 編碼。
• Payload (酬載): 存放「聲明 (Claims)」的地方，也就是你想傳遞的資料。例如使用者 ID (`sub`)、簽發時間 (`iat`)、過期時間 (`exp`) 等。你也可以放自訂的資料，像是使用者角色 (`role`)。這部分同樣會經過 Base64Url 編碼。
• Signature (簽章): 這是 JWT 最關鍵的部分。它會將編碼後的 Header、編碼後的 Payload，加上一個只有伺服器知道的密鑰 (Secret)，再用 Header 中指定的演算法進行加密。這個簽章的目的是為了驗證訊息在傳輸過程中沒有被竄改。

囉嗦一下：千萬別在 Payload 裡放敏感資料像密碼啊！ 這玩意只是 Base64 編碼，不是加密，網路上隨便找個解碼工具就能看光光。簽章（Signature）才是保證它沒被竄改的關鍵，就像是數位世界的火漆印一樣，確保這封信是你發的，而且中途沒被拆開過。

Laravel API 開發實戰：從零到一打造 JWT 認證

好了，理論講完了，我們來動手吧！這裡我們將使用目前 Laravel 社群中最受歡迎的 JWT 套件 `tymon/jwt-auth` 來實作。

步驟一：環境準備與安裝 JWT 認證套件

首先，假設你已經有一個全新的 Laravel 專案。打開你的終端機，進入專案目錄，然後執行以下指令安裝套件：

composer require tymon/jwt-auth

安裝完成後，我們需要發佈套件的設定檔，這樣才能客製化我們的 JWT 設定：

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

最後，產生一個 JWT 簽章用的密鑰。這個密鑰會被加到你的 `.env` 檔案中，非常重要，絕對不要外洩！

php artisan jwt:secret

步驟二：設定 User Model 與 Auth Guard

接下來，我們要告訴 Laravel 的 `User` 模型，它現在需要支援 JWT。我們需要讓 `User` 模型實作 `JWTSubject` 介面。

打開 `app/Models/User.php`，加入 `use TymonJWTAuthContractsJWTSubject;` 並修改 class 定義：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;
use Tymon\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    use HasApiTokens, HasFactory, Notifiable;

    // ... 原本的程式碼 ...

    /**
     * Get the identifier that will be stored in the subject claim of the JWT.
     *
     * @return mixed
     */
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    /**
     * Return a key value array, containing any custom claims to be added to the JWT.
     *
     * @return array
     */
    public function getJWTCustomClaims()
    {
        return [];
    }
}

然後，我們要設定認證的「守衛 (Guard)」。打開 `config/auth.php`，將 `api` guard 的 `driver` 從 `token` (或 `sanctum`) 改成 `jwt`。

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'jwt', // 把這裡改成 jwt
        'provider' => 'users',
    ],
],

步驟三：打造你的認證控制器 (AuthController)

接著，我們來建立一個專門處理 API 認證邏輯的控制器。

php artisan make:controller API/AuthController

打開 `app/Http/Controllers/API/AuthController.php`，並加入登入、登出、刷新 Token 和取得使用者資訊的方法：

<?php

namespace App\Http\Controllers\API;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class AuthController extends Controller
{
    public function __construct()
    {
        // 除了 login，其他都需要 auth 中介層驗證
        $this->middleware('auth:api', ['except' => ['login']]);
    }

    public function login(Request $request)
    {
        $credentials = $request->only('email', 'password');

        if (! $token = Auth::guard('api')->attempt($credentials)) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        return $this->respondWithToken($token);
    }

    public function me()
    {
        return response()->json(Auth::guard('api')->user());
    }

    public function logout()
    {
        Auth::guard('api')->logout();
        return response()->json(['message' => 'Successfully logged out']);
    }

    public function refresh()
    {
        return $this->respondWithToken(Auth::guard('api')->refresh());
    }

    protected function respondWithToken($token)
    {
        return response()->json([
            'access_token' => $token,
            'token_type' => 'bearer',
            'expires_in' => Auth::guard('api')->factory()->getTTL() * 60
        ]);
    }
}

這裡的 `respondWithToken` 是一個我很喜歡用的小技巧，把回傳 Token 的格式統一封裝起來，控制器裡的程式碼會乾淨很多，以後要改格式也只要改一個地方就好，這就是工程師的浪漫啊！

步驟四：設定 API 路由與 Middleware 保護

最後一步，我們要設定 API 的路由。打開 `routes/api.php`，加入我們剛剛建立的 `AuthController` 的路由規則。

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\API\AuthController;

Route::group([
    'middleware' => 'api',
    'prefix' => 'auth'
], function ($router) {
    Route::post('login', [AuthController::class, 'login']);
    Route::post('logout', [AuthController::class, 'logout']);
    Route::post('refresh', [AuthController::class, 'refresh']);
    Route::post('me', [AuthController::class, 'me']);
});

注意到我們在 `AuthController` 的 `__construct` 方法裡使用了 `middleware(‘auth:api’)` 嗎？這就是 Laravel 的中介層 (Middleware) 機制，它像是一個個檢查站，所有指向 `logout`, `refresh`, `me` 這幾個方法的請求，都必須先通過 `auth:api` 這個檢查站。檢查站會驗證請求是否帶有合法的 JWT，如果沒有，請求就會直接被擋下，回傳 `401 Unauthorized` 錯誤，根本到不了控制器本人。

用 Postman 測試你的 API：眼見為憑

寫完程式，沒測試就跟做白工一樣。打開你愛用的 API 測試工具（例如 Postman），我們來實際跑跑看：

1. 登入取得 Token:
   • 方法: `POST`
   • URL: `http://你的網域/api/auth/login`
   • Body (選擇 `form-data` 或 `x-www-form-urlencoded`): 填入你資料庫中已存在的用戶 `email` 和 `password`。
   • 送出請求，你應該會收到一個包含 `access_token` 的 JSON 回應。
2. 取得使用者資訊:
   • 方法: `POST`
   • URL: `http://你的網域/api/auth/me`
   • Authorization (授權) 頁籤:
     • Type: 選擇 `Bearer Token`。
     • Token: 貼上你從第一步拿到的 `access_token` 字串。
   • 送出請求，如果 Token 有效，你就會看到該使用者的詳細資料。如果沒帶 Token 或是 Token 錯誤，就會收到 `401` 錯誤。

看到成功的回應時，恭喜你！你已經成功打造了一個受 JWT 保護的 Laravel API！

總結：不只是寫 Code，更是架構思維的轉變

從傳統的 Session 到現代的 JWT，這不僅僅是換了一種驗證工具，更代表著一種架構思維的轉變。搞懂 JWT 之後，你會發現前後端分離的開發變得順暢多了。後端專心提供穩定、安全的 API，前端專心打造華麗、流暢的使用者體驗，大家各司其職，不用再為了一點 Session 問題吵半天。這就是所謂的「關注點分離」，也是寫出好維護、可擴展程式碼的關鍵啦。

當然，JWT 還有很多進階議題，例如 Refresh Token 的無痛刷新機制、如何處理 Token 黑名單來強制登出、在客戶端如何安全地儲存 Token 等等。但今天，你已經踏出了最關鍵的第一步，未來在面對各種複雜的應用場景時，你已經有了最穩固的基礎。

延伸閱讀

• 前後端分離還是大一統？Laravel + Vue / React 整合全攻略，資深工程師帶你選對路
• Laravel 門神不好當？從自訂驗證到 Middleware，打造滴水不漏的 API 防線
• 你的 Controller 還在身兼多職？導入 Service Layer，打造可維護、高彈性的 Laravel Admin 後台架構！

如果你在打造自己的 Laravel API 或 WordPress 系統時遇到了瓶頸，或是希望為你的企業導入更現代化、更穩健的技術架構，都歡迎隨時與我們浪花科技的團隊聊聊。我們專注於解決各種複雜的技術問題，讓科技真正成為你業務成長的引擎。

👉 立即聯繫浪花科技，打造你的專屬高效能系統！