속도 제한

업데이트됨

번역일: 2026년 6월 20일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 20일

속도 제한

소개
- 캐시 설정
기본 사용법
- 시도 횟수 직접 증가시키기
- 시도 횟수 초기화

소개

Laravel은 간편하게 사용할 수 있는 속도 제한(Rate Limiting) 추상화를 제공합니다. 애플리케이션의 캐시와 함께 사용하면 특정 시간 내에 임의의 동작이 실행되는 횟수를 손쉽게 제한할 수 있습니다.

NOTE

들어오는 HTTP 요청에 대한 속도 제한이 필요하다면 라우팅의 속도 제한 미들웨어 문서를 참고하세요.

캐시 설정

속도 제한기는 기본적으로 cache 설정 파일의 default 키에 정의된 캐시 드라이버를 사용합니다. 속도 제한기가 사용할 캐시 드라이버를 별도로 지정하려면 cache 설정 파일에 limiter 키를 추가하면 됩니다.

'default' => env('CACHE_STORE', 'database'),

'limiter' => 'redis', //

속도 제한 카운터를 자주 갱신하는 특성상, Redis처럼 읽기/쓰기가 빠른 드라이버를 limiter로 지정하는 것이 성능상 유리합니다.

기본 사용법

Illuminate\Support\Facades\RateLimiter 파사드를 통해 속도 제한기를 사용할 수 있습니다. 가장 간단한 방법은 attempt 메서드입니다. 이 메서드는 지정한 초 동안 콜백의 실행 횟수를 제한합니다.

남은 시도 횟수가 없으면 false를 반환합니다.
시도 가능한 상태라면 콜백을 실행하고, 콜백의 반환값(없으면 true)을 돌려줍니다.

첫 번째 인자는 속도 제한 "키"로, 제한하려는 동작을 구분하는 임의의 문자열입니다. 보통 사용자 ID 등을 포함해 고유하게 만듭니다.

use Illuminate\Support\Facades\RateLimiter;

$executed = RateLimiter::attempt(
    'send-message:'.$user->id,
    $perMinute = 5,
    function() {
        // 메시지 전송...
    }
);

if (! $executed) {
    return '메시지를 너무 많이 전송했습니다!';
}

네 번째 인자로 "감쇠 시간(decay rate)"을 초 단위로 지정할 수 있습니다. 예를 들어, 2분에 5회로 제한하려면 다음과 같이 작성합니다.

$executed = RateLimiter::attempt(
    'send-message:'.$user->id,
    $perTwoMinutes = 5,
    function() {
        // 메시지 전송...
    },
    $decayRate = 120,
);

시도 횟수 직접 증가시키기

속도 제한기를 세밀하게 제어하고 싶을 때는 다양한 메서드를 개별적으로 활용할 수 있습니다.

tooManyAttempts 메서드는 특정 키의 시도 횟수가 허용 최대치를 초과했는지 확인합니다.

use Illuminate\Support\Facades\RateLimiter;

if (RateLimiter::tooManyAttempts('send-message:'.$user->id, $perMinute = 5)) {
    return '시도 횟수를 초과했습니다!';
}

RateLimiter::increment('send-message:'.$user->id);

// 메시지 전송...

동시에 많은 요청이 몰릴 수 있는 엔드포인트라면 tooManyAttempts와 increment를 따로 호출하는 대신, increment의 반환값을 직접 확인하는 방식을 권장합니다. redis, memcached, database 캐시 드라이버를 사용할 경우 카운터가 원자적(atomic)으로 증가하므로, 동시 요청이 들어와도 각각 고유한 카운트를 받을 수 있습니다.

use Illuminate\Support\Facades\RateLimiter;

$perMinute = 5;

if (RateLimiter::increment('send-message:'.$user->id) > $perMinute) {
    return '시도 횟수를 초과했습니다!';
}

// 메시지 전송...

또는 remaining 메서드로 특정 키의 남은 시도 횟수를 확인한 뒤, 횟수가 남아 있을 때만 increment를 호출할 수도 있습니다.

use Illuminate\Support\Facades\RateLimiter;

if (RateLimiter::remaining('send-message:'.$user->id, $perMinute = 5)) {
    RateLimiter::increment('send-message:'.$user->id);

    // 메시지 전송...
}

한 번에 1 이상의 값으로 증가시키려면 increment 메서드에 원하는 증가량을 전달합니다.

RateLimiter::increment('send-message:'.$user->id, amount: 5);

재시도 가능 시간 확인

특정 키의 시도 횟수가 모두 소진된 경우, availableIn 메서드를 사용해 다음 시도까지 남은 시간(초)을 가져올 수 있습니다. 이를 통해 사용자에게 얼마 뒤에 재시도할 수 있는지 안내할 수 있습니다.

use Illuminate\Support\Facades\RateLimiter;

if (RateLimiter::tooManyAttempts('send-message:'.$user->id, $perMinute = 5)) {
    $seconds = RateLimiter::availableIn('send-message:'.$user->id);

    return $seconds.'초 후에 다시 시도하세요.';
}

RateLimiter::increment('send-message:'.$user->id);

// 메시지 전송...

시도 횟수 초기화

clear 메서드를 사용하면 특정 키의 시도 횟수를 즉시 초기화할 수 있습니다. 예를 들어, 수신자가 메시지를 읽었을 때 해당 사용자의 전송 횟수를 리셋할 수 있습니다.

use App\Models\Message;
use Illuminate\Support\Facades\RateLimiter;

/**
 * 메시지를 읽음으로 표시합니다.
 */
public function read(Message $message): Message
{
    $message->markAsRead();

    RateLimiter::clear('send-message:'.$message->user_id);

    return $message;
}