Lottery 類別

什麼是 Lottery 類別

Illuminate\Support\Lottery 是可將機率式操作以流暢 API 表達的工具類別。可以簡潔地寫出如「每 100 個請求執行 1 次處理」、「僅對部分請求記錄詳細日誌」等模式。

實作位於 src/Illuminate/Support/Lottery.php。Laravel 亦於 Session GC、Cache Lock 的 prune 等框架內部活用此類別。

基本用法

以整數比例指定機率

以 Lottery::odds($chances, $outOf) 指定「

outOf 次中

chances 次中選」的機率。

use Illuminate\Support\Lottery;

Lottery::odds(1, 100)           // 每 100 次 1 次
    ->winner(fn () => $this->runMaintenance())
    ->loser(fn () => null)
    ->choose();

以小數指定機率

省略 $outOf 並傳入 0.0〜1.0 的小數，則會直接作為機率使用。

Lottery::odds(0.01)             // 1% 的機率
    ->winner(fn () => $this->sample())
    ->choose();

小數指定時，值若超過 1.0 會拋出 RuntimeException。

不帶 callback 回傳布林值

若未設定 winner / loser，choose() 中選時回傳 true，未中時回傳 false。

$shouldSample = Lottery::odds(1, 50)->choose(); // bool

執行多次

若對 choose($times) 傳入次數，會回傳結果的陣列。

$results = Lottery::odds(1, 2)
    ->winner(fn () => 'win')
    ->loser(fn () => 'lose')
    ->choose(10);

// 例：['win', 'lose', 'win', 'win', 'lose', ...]

作為 Callable 傳入

Lottery 實例實作了 __invoke，可直接傳入接受 callable 的 API。

// 作為 DB::whenQueryingForLongerThan 的第 2 個引數傳入的範例
DB::whenQueryingForLongerThan(
    Interval::seconds(5),
    Lottery::odds(1, 5)->winner(function ($connection) {
        // 偵測到慢查詢時以 1/5 機率送出警示
        Alert::send("Slow query on {$connection->getName()}");
    })
);

實務使用情境

1. Cache 的 prune（每 100 次僅執行 1 次）

適合刪除過期記錄等無需每次執行的維護處理。

Lottery::odds(1, 100)
    ->winner(fn () => Cache::store('database')->flush())
    ->choose();

2. 遙測、取樣（僅部分請求記錄詳細日誌）

若將所有請求都記錄成本過高，可用於取樣。

Lottery::odds(1, 20)
    ->winner(function () use ($request) {
        Log::channel('telemetry')->info('Request sampled', [
            'url'      => $request->url(),
            'duration' => microtime(true) - LARAVEL_START,
            'memory'   => memory_get_peak_usage(true),
        ]);
    })
    ->choose();

3. 類似 A/B 測試的行為

以機率將使用者分派至 2 條程式碼路徑。

$result = Lottery::odds(1, 2)
    ->winner(fn ($user) => $this->newCheckoutFlow($user))
    ->loser(fn ($user) => $this->legacyCheckoutFlow($user))
    ->choose();

4. 作為 Scheduler 的輔助，隨機執行定期任務

當希望在多台伺服器上避免重複執行且隨機執行某任務時可用。

// app/Console/Kernel.php
$schedule->call(function () {
    Lottery::odds(1, 3)
        ->winner(fn () => Artisan::call('cache:prune-stale-tags'))
        ->choose();
})->everyMinute();

Laravel 框架內的機率模式

Laravel 也於框架內部廣泛使用機率式維護處理。部分實作因為在 Lottery 類別新增之前撰寫，直接使用 random_int()，但思維相同。

Session：垃圾回收

Illuminate\Session\Middleware\StartSession::configHitsLottery() 使用 config/session.php 的 lottery 設定，以 random_int 進行機率判定並執行 GC。

// config/session.php
'lottery' => [2, 100], // 每 100 個請求 2 次

// StartSession 內部（直接使用 random_int）
protected function configHitsLottery(array $config): bool
{
    return random_int(1, $config['lottery'][1]) <= $config['lottery'][0];
}

DatabaseLock：過期 Lock 的 prune

Illuminate\Cache\DatabaseLock::acquire() 於每次取得 Lock 時以相同比例模式刪除過期 Lock。

// config/cache.php（database driver）
'lock_lottery' => [2, 100], // 每 100 次執行 2 次 prune

// DatabaseLock::acquire() 內部（直接使用 random_int）
if (random_int(1, $this->lottery[1]) <= $this->lottery[0]) {
    $this->pruneExpiredLocks();
}

DB::whenQueryingForLongerThan — 傳入 Lottery 類別的範例

因 Lottery 實例可作為 callable 傳入，可直接用於慢查詢偵測的 callback。

DB::whenQueryingForLongerThan(
    Interval::seconds(5),
    Lottery::odds(1, 5)->winner(function ($connection) {
        Log::warning("Slow query on {$connection->getName()}");
    })
);

Session 與 DatabaseLock 直接使用 random_int()，而使用 Lottery 類別的優點是可透過 alwaysWin() / alwaysLose() / fix() 於測試中控制結果。套件開發選擇 Lottery 類別可提升可測試性。

測試時的使用

具備隨機性的程式碼測試中，可使用 Lottery 提供的測試 API。

`Lottery::alwaysWin()` — 恆使中選

public function test_maintenance_runs_on_win(): void
{
    $ranMaintenance = false;

    Lottery::alwaysWin(function () use (&$ranMaintenance) {
        Lottery::odds(1, 100)
            ->winner(function () use (&$ranMaintenance) {
                $ranMaintenance = true;
            })
            ->choose();
    });

    $this->assertTrue($ranMaintenance);
}

`Lottery::alwaysLose()` — 恆使未中

public function test_maintenance_skipped_on_lose(): void
{
    $ranMaintenance = false;

    Lottery::alwaysLose(function () use (&$ranMaintenance) {
        Lottery::odds(1, 100)
            ->winner(function () use (&$ranMaintenance) {
                $ranMaintenance = true;
            })
            ->choose();
    });

    $this->assertFalse($ranMaintenance);
}

`Lottery::fix()` — 以序列固定結果

可以 true/false 的陣列控制多次呼叫的結果。

public function test_alternating_results(): void
{
    Lottery::fix([true, false, true, false]);

    $results = Lottery::odds(1, 100)
        ->winner(fn () => 'winner')
        ->loser(fn () => 'loser')
        ->choose(4);

    $this->assertSame(['winner', 'loser', 'winner', 'loser'], $results);

    Lottery::determineResultNormally(); // 測試後務必還原
}

alwaysWin() / alwaysLose() / fix() 會變更全域靜態屬性。請務必於測試的 tearDown() 呼叫 Lottery::determineResultNormally()。

protected function tearDown(): void
{
    Lottery::determineResultNormally();

    parent::tearDown();
}

`Lottery::setResultFactory()` — 注入自訂 factory

若需更精細的控制，可使用自訂 factory。

Lottery::setResultFactory(function ($chances, $outOf) {
    // 恆使中選的自訂邏輯
    return true;
});

// 測試後重置
Lottery::determineResultNormally();

套件開發的活用

於服務提供者註冊

若於套件的服務提供者中組入維護處理，可透過 Lottery 分散負載。

use Illuminate\Support\Lottery;
use Illuminate\Support\ServiceProvider;

class AcmeServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->app->booted(function () {
            Lottery::odds(1, 100)
                ->winner(fn () => $this->pruneExpiredRecords())
                ->choose();
        });
    }

    protected function pruneExpiredRecords(): void
    {
        $this->app['db']->table('acme_logs')
            ->where('expires_at', '<', now())
            ->delete();
    }
}

從設定值讀取 odds

若允許使用者從設定檔變更機率，會更方便調整。

$lottery = config('acme.prune_lottery', [1, 100]);

Lottery::odds(...$lottery)
    ->winner(fn () => $this->pruneExpiredRecords())
    ->choose();

// config/acme.php
return [
    // [中選數, 嘗試數] = 每 100 個請求執行 1 次 prune
    'prune_lottery' => [1, 100],
];

於 Middleware 進行取樣

use Illuminate\Support\Lottery;

class SampleTelemetryMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);

        Lottery::odds(1, 50)
            ->winner(fn () => $this->recordTelemetry($request, $response))
            ->choose();

        return $response;
    }
}

API 參考

方法	說明
`Lottery::odds($chances, $outOf)`	產生 Lottery 實例的靜態 factory
`->winner(callable $callback)`	設定中選時的 callback
`->loser(callable $callback)`	設定未中時的 callback
`->choose($times = null)`	執行 Lottery。指定 `$times` 則回傳陣列
`Lottery::alwaysWin($callback)`	測試用：恆使中選
`Lottery::alwaysLose($callback)`	測試用：恆使未中
`Lottery::fix($sequence)`	測試用：以序列固定結果
`Lottery::determineResultNormally()`	重置測試用固定
`Lottery::setResultFactory(callable)`	注入自訂判定邏輯

Macroable trait

學習為既有類別新增方法的擴充模式。

Conditionable trait

學習透過 when() / unless() 設計條件分支鏈。

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

什麼是 Lottery 類別

基本用法

以整數比例指定機率

以小數指定機率

不帶 callback 回傳布林值

執行多次

作為 Callable 傳入

實務使用情境

1. Cache 的 prune（每 100 次僅執行 1 次）

2. 遙測、取樣（僅部分請求記錄詳細日誌）

3. 類似 A/B 測試的行為

4. 作為 Scheduler 的輔助，隨機執行定期任務

Laravel 框架內的機率模式

測試時的使用

`Lottery::alwaysWin()` — 恆使中選

`Lottery::alwaysLose()` — 恆使未中

`Lottery::fix()` — 以序列固定結果

`Lottery::setResultFactory()` — 注入自訂 factory

套件開發的活用

於服務提供者註冊

從設定值讀取 odds

於 Middleware 進行取樣

API 參考

相關頁面

Macroable trait

Conditionable trait

​什麼是 Lottery 類別

​基本用法

​以整數比例指定機率

​以小數指定機率

​不帶 callback 回傳布林值

​執行多次

​作為 Callable 傳入

​實務使用情境

​1. Cache 的 prune（每 100 次僅執行 1 次）

​2. 遙測、取樣（僅部分請求記錄詳細日誌）

​3. 類似 A/B 測試的行為

​4. 作為 Scheduler 的輔助，隨機執行定期任務

​Laravel 框架內的機率模式

​測試時的使用

​Lottery::alwaysWin() — 恆使中選

​Lottery::alwaysLose() — 恆使未中

​Lottery::fix() — 以序列固定結果

​Lottery::setResultFactory() — 注入自訂 factory

​套件開發的活用

​於服務提供者註冊

​從設定值讀取 odds

​於 Middleware 進行取樣

​API 參考

​相關頁面

Macroable trait

Conditionable trait

什麼是 Lottery 類別

基本用法

以整數比例指定機率

以小數指定機率

不帶 callback 回傳布林值

執行多次

作為 Callable 傳入

實務使用情境

1. Cache 的 prune（每 100 次僅執行 1 次）

2. 遙測、取樣（僅部分請求記錄詳細日誌）

3. 類似 A/B 測試的行為

4. 作為 Scheduler 的輔助，隨機執行定期任務

Laravel 框架內的機率模式

測試時的使用

`Lottery::alwaysWin()` — 恆使中選

`Lottery::alwaysLose()` — 恆使未中

`Lottery::fix()` — 以序列固定結果

`Lottery::setResultFactory()` — 注入自訂 factory

套件開發的活用

於服務提供者註冊

從設定值讀取 odds

於 Middleware 進行取樣

API 參考

相關頁面