속도 제한

번역일: 2026년 6월 20일

속도 제한

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

소개

Laravel은 애플리케이션의 캐시와 연동하여 특정 시간 창(window) 내에서 임의의 동작에 횟수 제한을 걸 수 있는 간결한 속도 제한(Rate Limiting) 추상화를 제공합니다.

NOTE

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

캐시 설정

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

'default' => 'memcached',

'limiter' => 'redis',

기본 사용법

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

허용 횟수를 모두 소진한 경우 false를 반환합니다.
실행에 성공한 경우 콜백의 반환값, 또는 반환값이 없으면 true를 반환합니다.

첫 번째 인수는 속도 제한 키(key)로, 제한할 동작을 식별하는 임의의 문자열입니다. 보통 사용자 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);

// 메시지 전송 처리...

remaining 메서드로 남은 시도 횟수를 확인할 수도 있습니다. 횟수가 남아 있다면 increment로 카운트를 증가시킵니다.

use Illuminate\Support\Facades\RateLimiter;

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

    // 메시지 전송 처리...
}

한 번에 카운트를 두 개 이상 증가시키려면 increment의 amount 인수를 사용합니다.

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;
}