속도 제한

번역일: 2026년 6월 20일

속도 제한

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

소개

Laravel은 애플리케이션의 캐시를 활용하여 특정 작업의 실행 횟수를 일정 시간 내로 제한할 수 있는 속도 제한 기능을 제공합니다. 사용법이 간단하면서도 유연하게 다양한 상황에 적용할 수 있습니다.

NOTE

HTTP 요청에 대한 속도 제한(API 요청 제한 등)이 필요하다면, 라우트 미들웨어 문서를 참고하세요. 이 페이지에서는 코드 레벨에서 직접 속도 제한을 다루는 방법을 설명합니다.

캐시 설정

속도 제한 기능은 기본적으로 config/cache.php의 default 키에 지정된 캐시 드라이버를 사용합니다. 속도 제한에만 별도의 캐시 드라이버를 사용하고 싶다면, cache 설정 파일에 limiter 키를 추가하세요.

예를 들어 기본 캐시는 database로 유지하되, 속도 제한에는 더 빠른 redis를 사용하고 싶다면 다음과 같이 설정합니다:

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

'limiter' => 'redis', //

기본 사용법

속도 제한 기능은 Illuminate\Support\Facades\RateLimiter 파사드를 통해 사용합니다. 가장 간편한 방법은 attempt 메서드로, 지정한 콜백을 특정 횟수만큼만 실행되도록 제한합니다.

시도 가능한 횟수가 남아 있으면 콜백을 실행하고 그 결과(또는 true)를 반환합니다.
횟수를 초과했으면 콜백을 실행하지 않고 false를 반환합니다.

첫 번째 인수는 속도 제한의 "키"로, 어떤 동작을 제한하는지 구분하는 고유한 문자열입니다. 보통 사용자 ID 등을 포함시켜 사용자별로 분리합니다:

use Illuminate\Support\Facades\RateLimiter;

$executed = RateLimiter::attempt(
    'send-message:'.$user->id, // 사용자별 고유 키
    $perMinute = 5,            // 분당 최대 5회
    function() {
        // 메시지 전송 처리...
    }
);

if (! $executed) {
    return '메시지를 너무 많이 보냈습니다. 잠시 후 다시 시도해 주세요.';
}

네 번째 인수로 "감소 시간(decay rate)"을 초 단위로 지정할 수 있습니다. 이 값은 시도 횟수가 초기화될 때까지의 시간입니다. 예를 들어 2분에 5회로 제한하려면 다음과 같이 작성합니다:

$executed = RateLimiter::attempt(
    'send-message:'.$user->id,
    $perTwoMinutes = 5,
    function() {
        // 메시지 전송 처리...
    },
    $decayRate = 120, // 120초(2분) 후 횟수 초기화
);

시도 횟수 수동 증가

attempt 외에도 속도 제한을 더 세밀하게 제어할 수 있는 메서드들이 있습니다.

tooManyAttempts 메서드로 특정 키의 시도 횟수가 한도를 초과했는지 먼저 확인한 뒤, 초과하지 않았다면 increment로 횟수를 직접 증가시킬 수 있습니다:

use Illuminate\Support\Facades\RateLimiter;

if (RateLimiter::tooManyAttempts('send-message:'.$user->id, $perMinute = 5)) {
    return '요청이 너무 많습니다. 잠시 후 다시 시도해 주세요.';
}

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

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

또는 remaining 메서드로 남은 시도 횟수를 확인하는 방식도 사용할 수 있습니다:

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