diff --git a/docs/.vitepress/src/en/sidebars.ts b/docs/.vitepress/src/en/sidebars.ts
index d0e1033f1..4f0abf961 100644
--- a/docs/.vitepress/src/en/sidebars.ts
+++ b/docs/.vitepress/src/en/sidebars.ts
@@ -149,6 +149,10 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Purifier',
                     link: '/en/components/purifier.md'
                 },
+                {
+                    text: 'Rate Limit',
+                    link: '/en/components/rate-limit.md'
+                },
                 {
                     text: 'Recaptcha',
                     link: '/en/components/recaptcha.md'
diff --git a/docs/.vitepress/src/zh-cn/sidebars.ts b/docs/.vitepress/src/zh-cn/sidebars.ts
index 8a474b958..16c1dc3a1 100644
--- a/docs/.vitepress/src/zh-cn/sidebars.ts
+++ b/docs/.vitepress/src/zh-cn/sidebars.ts
@@ -162,6 +162,10 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Purifier',
                     link: '/zh-cn/components/purifier.md'
                 },
+                {
+                    text: 'Rate Limit',
+                    link: '/zh-cn/components/rate-limit.md'
+                },
                 {
                     text: 'Recaptcha',
                     link: '/zh-cn/components/recaptcha.md'
diff --git a/docs/.vitepress/src/zh-hk/sidebars.ts b/docs/.vitepress/src/zh-hk/sidebars.ts
index 1be4c9620..393d02389 100644
--- a/docs/.vitepress/src/zh-hk/sidebars.ts
+++ b/docs/.vitepress/src/zh-hk/sidebars.ts
@@ -162,6 +162,10 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Purifier',
                     link: '/zh-hk/components/purifier.md'
                 },
+                {
+                    text: 'Rate Limit',
+                    link: '/zh-hk/components/rate-limit.md'
+                },
                 {
                     text: 'Recaptcha',
                     link: '/zh-hk/components/recaptcha.md'
diff --git a/docs/.vitepress/src/zh-tw/sidebars.ts b/docs/.vitepress/src/zh-tw/sidebars.ts
index 5e9faf0e2..3825f87a0 100644
--- a/docs/.vitepress/src/zh-tw/sidebars.ts
+++ b/docs/.vitepress/src/zh-tw/sidebars.ts
@@ -162,6 +162,10 @@ const sidebar:DefaultTheme.Sidebar = {
                     text: 'Purifier',
                     link: '/zh-tw/components/purifier.md'
                 },
+                {
+                    text: 'Rate Limit',
+                    link: '/zh-tw/components/rate-limit.md'
+                },
                 {
                     text: 'Recaptcha',
                     link: '/zh-tw/components/recaptcha.md'
diff --git a/docs/en/components/rate-limit.md b/docs/en/components/rate-limit.md
new file mode 100644
index 000000000..4a45dbe7e
--- /dev/null
+++ b/docs/en/components/rate-limit.md
@@ -0,0 +1,466 @@
+# Rate Limit
+
+Hyperf's rate limiting component, supporting multiple algorithms (fixed window, sliding window, token bucket, leaky bucket).
+
+## Installation
+
+```bash
+composer require friendsofhyperf/rate-limit
+```
+
+## Requirements
+
+- Hyperf ~3.1.0
+- Redis
+
+## Features
+
+- **Multiple Rate Limiting Algorithms**
+  - Fixed Window
+  - Sliding Window
+  - Token Bucket
+  - Leaky Bucket
+- **Flexible Usage**
+  - Annotation-based rate limiting (via aspect)
+  - Custom middleware support
+- **Smart Multi-Annotation Sorting**
+  - Automatically sorts multiple RateLimit annotations by priority
+  - Intelligent sorting based on strictness (maxAttempts/decay ratio)
+  - Stricter limits checked first for better performance
+- **Flexible Key Generation**
+  - Default method/class-based keys
+  - Support for custom keys and placeholders
+  - Support for array keys
+  - Support for callable keys
+- **Custom Responses**
+  - Custom response messages
+  - Custom HTTP response codes
+- **Multiple Redis Connection Pool Support**
+
+## Usage
+
+### Method 1: Using Annotations
+
+The simplest way is to use the `#[RateLimit]` attribute:
+
+```php
+<?php
+
+namespace App\Controller;
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Algorithm;
+
+class UserController
+{
+    /**
+     * Basic rate limit: max 60 requests in 60 seconds
+     */
+    #[RateLimit(maxAttempts: 60, decay: 60)]
+    public function index()
+    {
+        // Your code
+    }
+
+    /**
+     * Using sliding window algorithm
+     */
+    #[RateLimit(
+        maxAttempts: 100,
+        decay: 60,
+        algorithm: Algorithm::SLIDING_WINDOW
+    )]
+    public function api()
+    {
+        // Your code
+    }
+
+    /**
+     * Custom key with user ID placeholder
+     */
+    #[RateLimit(
+        key: 'user:{userId}:action',
+        maxAttempts: 10,
+        decay: 3600
+    )]
+    public function create($userId)
+    {
+        // Your code
+    }
+
+    /**
+     * Using array key
+     */
+    #[RateLimit(
+        key: ['user', '{userId}', 'create'],
+        maxAttempts: 5,
+        decay: 60
+    )]
+    public function update($userId)
+    {
+        // Your code
+    }
+
+    /**
+     * Custom response message and status code
+     */
+    #[RateLimit(
+        maxAttempts: 5,
+        decay: 60,
+        response: 'Too many requests, please try again later.',
+        responseCode: 429
+    )]
+    public function login()
+    {
+        // Your code
+    }
+
+    /**
+     * Using specified Redis connection pool
+     */
+    #[RateLimit(
+        maxAttempts: 60,
+        decay: 60,
+        pool: 'rate_limit'
+    )]
+    public function heavyOperation()
+    {
+        // Your code
+    }
+}
+```
+
+### Annotation Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `key` | `string\|array` | `''` | Rate limit key. Supports: 'user:{user_id}', ['user', '{user_id}'], or callable functions |
+| `maxAttempts` | `int` | `60` | Maximum number of allowed requests |
+| `decay` | `int` | `60` | Time window in seconds |
+| `algorithm` | `Algorithm` | `Algorithm::FIXED_WINDOW` | Algorithm: fixed_window, sliding_window, token_bucket, leaky_bucket |
+| `pool` | `?string` | `null` | Redis connection pool to use |
+| `response` | `string` | `'Too Many Attempts, Please try again in %d seconds.'` | Custom response when rate limit is exceeded |
+| `responseCode` | `int` | `429` | HTTP status code when rate limit is exceeded |
+
+### Using AutoSort for Smart Multi-Rate-Limit Rule Sorting
+
+When a single method requires multiple rate limiting rules (e.g., per-minute and per-hour limits), use the `AutoSort` annotation for automatic sorting by strictness:
+
+```php
+<?php
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Annotation\AutoSort;
+
+class ApiController
+{
+    /**
+     * Smart sorting of multiple rate limit rules
+     * Stricter limits (smaller maxAttempts/decay ratio) are checked first
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 10, decay: 60)]      // 10 per minute - checked first
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 100 per hour - checked second
+    public function expensiveOperation()
+    {
+        // Your code
+    }
+
+    /**
+     * Without AutoSort, checks in declaration order
+     */
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // Checked first
+    #[RateLimit(maxAttempts: 10, decay: 60)]       // Checked second
+    public function anotherOperation()
+    {
+        // Your code
+    }
+}
+```
+
+**AutoSort Advantages:**
+
+- **Performance**: Stricter limits checked first, avoiding unnecessary checks of looser limits
+- **Intelligent**: Automatically calculates priority based on limit strictness (maxAttempts/decay ratio)
+- **Optional**: Only takes effect on methods explicitly using `AutoSort`
+- **Backward Compatible**: Existing code continues to work without modification
+
+### Key Placeholders
+
+The `key` parameter supports dynamic placeholders that are replaced with method parameters:
+
+```php
+// Named placeholders
+#[RateLimit(key: 'user:{userId}:{action}')]
+public function action($userId, $action)
+
+// Array format (automatically joined with ':')
+#[RateLimit(key: ['user', '{userId}', '{action}'])]
+public function action($userId, $action)
+```
+
+### Method 2: Using Middleware
+
+For HTTP requests, you can create custom middleware extending `RateLimitMiddleware`:
+
+```php
+<?php
+
+namespace App\Middleware;
+
+use FriendsOfHyperf\RateLimit\Middleware\RateLimitMiddleware;
+use FriendsOfHyperf\RateLimit\Algorithm;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+class ApiRateLimitMiddleware extends RateLimitMiddleware
+{
+    // Override default properties
+    protected int $maxAttempts = 100;
+    protected int $decay = 60;
+    protected Algorithm $algorithm = Algorithm::SLIDING_WINDOW;
+    protected string $responseMessage = 'API rate limit exceeded';
+    protected int $responseCode = 429;
+
+    // Or customize key resolution
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'api:' . $this->getClientIp();
+    }
+}
+```
+
+Then register the middleware in configuration:
+
+```php
+// config/autoload/middlewares.php
+return [
+    'http' => [
+        App\Middleware\ApiRateLimitMiddleware::class,
+    ],
+];
+```
+
+## Rate Limiting Algorithms
+
+### Fixed Window (Default)
+
+The simplest algorithm, counting requests within a fixed time window.
+
+```php
+#[RateLimit(algorithm: Algorithm::FIXED_WINDOW)]
+```
+
+**Advantages**: Simple, memory efficient  
+**Disadvantages**: May allow burst requests at window boundaries
+
+### Sliding Window
+
+More accurate than fixed window, distributing requests evenly.
+
+```php
+#[RateLimit(algorithm: Algorithm::SLIDING_WINDOW)]
+```
+
+**Advantages**: Smooths burst traffic, more accurate  
+**Disadvantages**: Slightly more complex
+
+### Token Bucket
+
+Allows burst traffic while maintaining average rate.
+
+```php
+#[RateLimit(algorithm: Algorithm::TOKEN_BUCKET)]
+```
+
+**Advantages**: Allows burst traffic, flexible  
+**Disadvantages**: Requires more configuration
+
+### Leaky Bucket
+
+Processes requests at a constant rate, queuing burst traffic.
+
+```php
+#[RateLimit(algorithm: Algorithm::LEAKY_BUCKET)]
+```
+
+**Advantages**: Smooth output rate, prevents bursts  
+**Disadvantages**: May delay requests
+
+## Custom Rate Limiter
+
+You can implement your own rate limiter by implementing `RateLimiterInterface`:
+
+```php
+<?php
+
+namespace App\RateLimit;
+
+use FriendsOfHyperf\RateLimit\Contract\RateLimiterInterface;
+
+class CustomRateLimiter implements RateLimiterInterface
+{
+    public function tooManyAttempts(string $key, int $maxAttempts, int $decay): bool
+    {
+        // Your implementation
+    }
+
+    public function availableIn(string $key): int
+    {
+        // Your implementation
+    }
+
+    public function remaining(string $key, int $maxAttempts): int
+    {
+        // Your implementation
+    }
+}
+```
+
+## Exception Handling
+
+When rate limit is exceeded, a `RateLimitException` is thrown:
+
+```php
+<?php
+
+try {
+    $userController->index();
+} catch (FriendsOfHyperf\RateLimit\Exception\RateLimitException $e) {
+    // Rate limit exceeded
+    $message = $e->getMessage();  // "Too Many Attempts. Please try again in X seconds."
+    $code = $e->getCode();        // 429
+}
+```
+
+## Configuration
+
+The component uses Hyperf's Redis configuration. You can specify the Redis connection pool to use in annotations or middleware:
+
+```php
+// Use specific Redis connection pool
+#[RateLimit(pool: 'rate_limit')]
+```
+
+Ensure Redis connection pools are configured in `config/autoload/redis.php`:
+
+```php
+return [
+    'default' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 0,
+        'pool' => [
+            'min_connections' => 1,
+            'max_connections' => 30,
+        ],
+    ],
+    'rate_limit' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 1,
+        'pool' => [
+            'min_connections' => 5,
+            'max_connections' => 50,
+        ],
+    ],
+];
+```
+
+## Examples
+
+### Example 1: Login Rate Limiting
+
+Limit login attempts to prevent brute force attacks:
+
+```php
+#[RateLimit(
+    key: 'login:{email}',
+    maxAttempts: 5,
+    decay: 300, // 5 minutes
+    response: 'Too many login attempts. Please try again after 5 minutes.',
+    responseCode: 429
+)]
+public function login(string $email, string $password)
+{
+    // Login logic
+}
+```
+
+### Example 2: API Endpoint Rate Limiting
+
+Set different rate limits for different API endpoints:
+
+```php
+class ApiController
+{
+    // Public API: 100 requests per minute
+    #[RateLimit(maxAttempts: 100, decay: 60)]
+    public function public()
+    {
+        // Public endpoint
+    }
+
+    // Premium API: 1000 requests per minute
+    #[RateLimit(maxAttempts: 1000, decay: 60)]
+    public function premium()
+    {
+        // Premium endpoint
+    }
+}
+```
+
+### Example 3: User-Based Rate Limiting
+
+Rate limit by user:
+
+```php
+#[RateLimit(
+    key: ['user', '{userId}', 'action'],
+    maxAttempts: 10,
+    decay: 3600 // 1 hour
+)]
+public function performAction(int $userId)
+{
+    // Action logic
+}
+```
+
+### Example 4: IP-Based Rate Limiting
+
+Rate limit by IP address using middleware:
+
+```php
+class IpRateLimitMiddleware extends RateLimitMiddleware
+{
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'ip:' . $this->getClientIp();
+    }
+}
+```
+
+### Example 5: Multi-Level Rate Limiting with AutoSort
+
+Efficiently handle multi-level rate limiting for expensive operations using AutoSort:
+
+```php
+class ReportController
+{
+    /**
+     * Expensive report generation with multi-level protection
+     * AutoSort ensures stricter limits are checked first for better performance
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 5, decay: 60, response: 'Too many requests. Max 5 per minute')]       // Emergency brake
+    #[RateLimit(maxAttempts: 30, decay: 3600, response: 'Hourly limit exceeded. Max 30 per hour')] // Sustained load
+    #[RateLimit(maxAttempts: 100, decay: 86400, response: 'Daily limit exceeded. Max 100 per day')] // Daily cap
+    public function generateReport($reportType)
+    {
+        // Expensive report generation logic
+    }
+}
+```
\ No newline at end of file
diff --git a/docs/zh-cn/components/rate-limit.md b/docs/zh-cn/components/rate-limit.md
new file mode 100644
index 000000000..5b8d654ef
--- /dev/null
+++ b/docs/zh-cn/components/rate-limit.md
@@ -0,0 +1,466 @@
+# Rate Limit
+
+Hyperf 的限流组件，支持多种算法（固定窗口、滑动窗口、令牌桶、漏桶）。
+
+## 安装
+
+```bash
+composer require friendsofhyperf/rate-limit
+```
+
+## 环境要求
+
+- Hyperf ~3.1.0
+- Redis
+
+## 特性
+
+- **多种限流算法**
+  - 固定窗口
+  - 滑动窗口
+  - 令牌桶
+  - 漏桶
+- **灵活的使用方式**
+  - 基于注解的限流（通过切面实现）
+  - 自定义中间件支持
+- **多注解智能排序**
+  - 自动对多个 RateLimit 注解进行优先级排序
+  - 根据严格程度智能排序（maxAttempts/decay 比率）
+  - 更严格的限制优先检查，提升性能
+- **灵活的键生成**
+  - 默认基于方法/类的键
+  - 支持自定义键和占位符
+  - 支持数组键
+  - 支持可调用键
+- **自定义响应**
+  - 自定义响应消息
+  - 自定义 HTTP 响应码
+- **多 Redis 连接池支持**
+
+## 使用方式
+
+### 方式一：使用注解
+
+最简单的方式是使用 `#[RateLimit]` 属性：
+
+```php
+<?php
+
+namespace App\Controller;
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Algorithm;
+
+class UserController
+{
+    /**
+     * 基础限流：60 秒内最多 60 次请求
+     */
+    #[RateLimit(maxAttempts: 60, decay: 60)]
+    public function index()
+    {
+        // 你的代码
+    }
+
+    /**
+     * 使用滑动窗口算法
+     */
+    #[RateLimit(
+        maxAttempts: 100,
+        decay: 60,
+        algorithm: Algorithm::SLIDING_WINDOW
+    )]
+    public function api()
+    {
+        // 你的代码
+    }
+
+    /**
+     * 自定义键，支持用户 ID 占位符
+     */
+    #[RateLimit(
+        key: 'user:{userId}:action',
+        maxAttempts: 10,
+        decay: 3600
+    )]
+    public function create($userId)
+    {
+        // 你的代码
+    }
+
+    /**
+     * 使用数组键
+     */
+    #[RateLimit(
+        key: ['user', '{userId}', 'create'],
+        maxAttempts: 5,
+        decay: 60
+    )]
+    public function update($userId)
+    {
+        // 你的代码
+    }
+
+    /**
+     * 自定义响应消息和状态码
+     */
+    #[RateLimit(
+        maxAttempts: 5,
+        decay: 60,
+        response: 'Too many requests, please try again later.',
+        responseCode: 429
+    )]
+    public function login()
+    {
+        // 你的代码
+    }
+
+    /**
+     * 使用指定的 Redis 连接池
+     */
+    #[RateLimit(
+        maxAttempts: 60,
+        decay: 60,
+        pool: 'rate_limit'
+    )]
+    public function heavyOperation()
+    {
+        // 你的代码
+    }
+}
+```
+
+### 注解参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `key` | `string\|array` | `''` | 限流键。支持：'user:{user_id}', ['user', '{user_id}'], 或可调用函数 |
+| `maxAttempts` | `int` | `60` | 允许的最大请求次数 |
+| `decay` | `int` | `60` | 时间窗口（秒） |
+| `algorithm` | `Algorithm` | `Algorithm::FIXED_WINDOW` | 算法：fixed_window, sliding_window, token_bucket, leaky_bucket |
+| `pool` | `?string` | `null` | 使用的 Redis 连接池 |
+| `response` | `string` | `'Too Many Attempts, Please try again in %d seconds.'` | 超出限流时的自定义响应 |
+| `responseCode` | `int` | `429` | 超出限流时的 HTTP 状态码 |
+
+### 使用 AutoSort 实现多限流规则智能排序
+
+当同一个方法需要多个限流规则时（例如每分钟和每小时的限制），可以使用 `AutoSort` 注解自动按严格程度排序：
+
+```php
+<?php
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Annotation\AutoSort;
+
+class ApiController
+{
+    /**
+     * 多个限流规则智能排序
+     * 更严格的限制（maxAttempts/decay 比率更小）优先检查
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 10, decay: 60)]      // 每分钟 10 次 - 优先检查
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 每小时 100 次 - 其次检查
+    public function expensiveOperation()
+    {
+        // 你的代码
+    }
+
+    /**
+     * 不使用 AutoSort 时，按声明顺序检查
+     */
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 优先检查
+    #[RateLimit(maxAttempts: 10, decay: 60)]       // 其次检查
+    public function anotherOperation()
+    {
+        // 你的代码
+    }
+}
+```
+
+**AutoSort 的优势：**
+
+- **性能**：严格的限制优先检查，避免不必要的宽松限制检查
+- **智能**：自动根据限制严格程度（maxAttempts/decay 比率）计算优先级
+- **可选**：仅在显式使用 `AutoSort` 的方法上生效
+- **向后兼容**：现有代码无需修改即可继续工作
+
+### 键占位符
+
+`key` 参数支持动态占位符，会被方法参数替换：
+
+```php
+// 命名占位符
+#[RateLimit(key: 'user:{userId}:{action}')]
+public function action($userId, $action)
+
+// 数组格式（自动用 ':' 连接）
+#[RateLimit(key: ['user', '{userId}', '{action}'])]
+public function action($userId, $action)
+```
+
+### 方式二：使用中间件
+
+对于 HTTP 请求，可以创建继承 `RateLimitMiddleware` 的自定义中间件：
+
+```php
+<?php
+
+namespace App\Middleware;
+
+use FriendsOfHyperf\RateLimit\Middleware\RateLimitMiddleware;
+use FriendsOfHyperf\RateLimit\Algorithm;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+class ApiRateLimitMiddleware extends RateLimitMiddleware
+{
+    // 重写默认属性
+    protected int $maxAttempts = 100;
+    protected int $decay = 60;
+    protected Algorithm $algorithm = Algorithm::SLIDING_WINDOW;
+    protected string $responseMessage = 'API rate limit exceeded';
+    protected int $responseCode = 429;
+
+    // 或自定义键解析
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'api:' . $this->getClientIp();
+    }
+}
+```
+
+然后在配置中注册中间件：
+
+```php
+// config/autoload/middlewares.php
+return [
+    'http' => [
+        App\Middleware\ApiRateLimitMiddleware::class,
+    ],
+];
+```
+
+## 限流算法
+
+### 固定窗口（默认）
+
+最简单的算法，在固定时间窗口内计数请求。
+
+```php
+#[RateLimit(algorithm: Algorithm::FIXED_WINDOW)]
+```
+
+**优点**：简单，内存高效  
+**缺点**：可能在窗口边界处允许突发请求
+
+### 滑动窗口
+
+比固定窗口更准确，均匀分布请求。
+
+```php
+#[RateLimit(algorithm: Algorithm::SLIDING_WINDOW)]
+```
+
+**优点**：平滑突发流量，更准确  
+**缺点**：稍微复杂一些
+
+### 令牌桶
+
+允许突发流量，同时保持平均速率。
+
+```php
+#[RateLimit(algorithm: Algorithm::TOKEN_BUCKET)]
+```
+
+**优点**：允许突发流量，灵活  
+**缺点**：需要更多配置
+
+### 漏桶
+
+以恒定速率处理请求，排队突发流量。
+
+```php
+#[RateLimit(algorithm: Algorithm::LEAKY_BUCKET)]
+```
+
+**优点**：平滑输出速率，防止突发  
+**缺点**：可能延迟请求
+
+## 自定义限流器
+
+你可以通过实现 `RateLimiterInterface` 来实现自己的限流器：
+
+```php
+<?php
+
+namespace App\RateLimit;
+
+use FriendsOfHyperf\RateLimit\Contract\RateLimiterInterface;
+
+class CustomRateLimiter implements RateLimiterInterface
+{
+    public function tooManyAttempts(string $key, int $maxAttempts, int $decay): bool
+    {
+        // 你的实现
+    }
+
+    public function availableIn(string $key): int
+    {
+        // 你的实现
+    }
+
+    public function remaining(string $key, int $maxAttempts): int
+    {
+        // 你的实现
+    }
+}
+```
+
+## 异常处理
+
+当超出限流时，会抛出 `RateLimitException`：
+
+```php
+<?php
+
+try {
+    $userController->index();
+} catch (FriendsOfHyperf\RateLimit\Exception\RateLimitException $e) {
+    // 超出限流
+    $message = $e->getMessage();  // "Too Many Attempts. Please try again in X seconds."
+    $code = $e->getCode();        // 429
+}
+```
+
+## 配置
+
+组件使用 Hyperf 的 Redis 配置。你可以在注解或中间件中指定使用的 Redis 连接池：
+
+```php
+// 使用特定的 Redis 连接池
+#[RateLimit(pool: 'rate_limit')]
+```
+
+确保在 `config/autoload/redis.php` 中配置 Redis 连接池：
+
+```php
+return [
+    'default' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 0,
+        'pool' => [
+            'min_connections' => 1,
+            'max_connections' => 30,
+        ],
+    ],
+    'rate_limit' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 1,
+        'pool' => [
+            'min_connections' => 5,
+            'max_connections' => 50,
+        ],
+    ],
+];
+```
+
+## 示例
+
+### 示例 1：登录限流
+
+限制登录尝试以防止暴力破解：
+
+```php
+#[RateLimit(
+    key: 'login:{email}',
+    maxAttempts: 5,
+    decay: 300, // 5 分钟
+    response: 'Too many login attempts. Please try again after 5 minutes.',
+    responseCode: 429
+)]
+public function login(string $email, string $password)
+{
+    // 登录逻辑
+}
+```
+
+### 示例 2：API 端点限流
+
+为不同的 API 端点设置不同的限流：
+
+```php
+class ApiController
+{
+    // 公共 API：每分钟 100 次请求
+    #[RateLimit(maxAttempts: 100, decay: 60)]
+    public function public()
+    {
+        // 公共端点
+    }
+
+    // 高级 API：每分钟 1000 次请求
+    #[RateLimit(maxAttempts: 1000, decay: 60)]
+    public function premium()
+    {
+        // 高级端点
+    }
+}
+```
+
+### 示例 3：基于用户的限流
+
+按用户限流：
+
+```php
+#[RateLimit(
+    key: ['user', '{userId}', 'action'],
+    maxAttempts: 10,
+    decay: 3600 // 1 小时
+)]
+public function performAction(int $userId)
+{
+    // 操作逻辑
+}
+```
+
+### 示例 4：基于 IP 的限流
+
+使用中间件按 IP 地址限流：
+
+```php
+class IpRateLimitMiddleware extends RateLimitMiddleware
+{
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'ip:' . $this->getClientIp();
+    }
+}
+```
+
+### 示例 5：使用 AutoSort 的多级限流
+
+使用 AutoSort 高效处理昂贵操作的多级限流：
+
+```php
+class ReportController
+{
+    /**
+     * 昂贵的报告生成，多级保护
+     * AutoSort 确保优先检查严格的限制，提升性能
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 5, decay: 60, response: 'Too many requests. Max 5 per minute')]       // 紧急制动
+    #[RateLimit(maxAttempts: 30, decay: 3600, response: 'Hourly limit exceeded. Max 30 per hour')] // 持续负载
+    #[RateLimit(maxAttempts: 100, decay: 86400, response: 'Daily limit exceeded. Max 100 per day')] // 每日上限
+    public function generateReport($reportType)
+    {
+        // 昂贵的报告生成逻辑
+    }
+}
+```
diff --git a/docs/zh-hk/components/rate-limit.md b/docs/zh-hk/components/rate-limit.md
new file mode 100644
index 000000000..c87bf7016
--- /dev/null
+++ b/docs/zh-hk/components/rate-limit.md
@@ -0,0 +1,466 @@
+# Rate Limit
+
+Hyperf 的限流組件，支持多種算法（固定窗口、滑動窗口、令牌桶、漏桶）。
+
+## 安裝
+
+```bash
+composer require friendsofhyperf/rate-limit
+```
+
+## 環境要求
+
+- Hyperf ~3.1.0
+- Redis
+
+## 特性
+
+- **多種限流算法**
+  - 固定窗口
+  - 滑動窗口
+  - 令牌桶
+  - 漏桶
+- **靈活的使用方式**
+  - 基於註解的限流（通過切面實現）
+  - 自定義中間件支持
+- **多註解智能排序**
+  - 自動對多個 RateLimit 註解進行優先級排序
+  - 根據嚴格程度智能排序（maxAttempts/decay 比率）
+  - 更嚴格的限制優先檢查，提升性能
+- **靈活的鍵生成**
+  - 默認基於方法/類的鍵
+  - 支持自定義鍵和佔位符
+  - 支持數組鍵
+  - 支持可調用鍵
+- **自定義響應**
+  - 自定義響應消息
+  - 自定義 HTTP 響應碼
+- **多 Redis 連接池支持**
+
+## 使用方式
+
+### 方式一：使用註解
+
+最簡單的方式是使用 `#[RateLimit]` 屬性：
+
+```php
+<?php
+
+namespace App\Controller;
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Algorithm;
+
+class UserController
+{
+    /**
+     * 基礎限流：60 秒內最多 60 次請求
+     */
+    #[RateLimit(maxAttempts: 60, decay: 60)]
+    public function index()
+    {
+        // 你的代碼
+    }
+
+    /**
+     * 使用滑動窗口算法
+     */
+    #[RateLimit(
+        maxAttempts: 100,
+        decay: 60,
+        algorithm: Algorithm::SLIDING_WINDOW
+    )]
+    public function api()
+    {
+        // 你的代碼
+    }
+
+    /**
+     * 自定義鍵，支持用户 ID 佔位符
+     */
+    #[RateLimit(
+        key: 'user:{userId}:action',
+        maxAttempts: 10,
+        decay: 3600
+    )]
+    public function create($userId)
+    {
+        // 你的代碼
+    }
+
+    /**
+     * 使用數組鍵
+     */
+    #[RateLimit(
+        key: ['user', '{userId}', 'create'],
+        maxAttempts: 5,
+        decay: 60
+    )]
+    public function update($userId)
+    {
+        // 你的代碼
+    }
+
+    /**
+     * 自定義響應消息和狀態碼
+     */
+    #[RateLimit(
+        maxAttempts: 5,
+        decay: 60,
+        response: 'Too many requests, please try again later.',
+        responseCode: 429
+    )]
+    public function login()
+    {
+        // 你的代碼
+    }
+
+    /**
+     * 使用指定的 Redis 連接池
+     */
+    #[RateLimit(
+        maxAttempts: 60,
+        decay: 60,
+        pool: 'rate_limit'
+    )]
+    public function heavyOperation()
+    {
+        // 你的代碼
+    }
+}
+```
+
+### 註解參數
+
+| 參數 | 類型 | 默認值 | 説明 |
+|-----------|------|---------|-------------|
+| `key` | `string\|array` | `''` | 限流鍵。支持：'user:{user_id}', ['user', '{user_id}'], 或可調用函數 |
+| `maxAttempts` | `int` | `60` | 允許的最大請求次數 |
+| `decay` | `int` | `60` | 時間窗口（秒） |
+| `algorithm` | `Algorithm` | `Algorithm::FIXED_WINDOW` | 算法：fixed_window, sliding_window, token_bucket, leaky_bucket |
+| `pool` | `?string` | `null` | 使用的 Redis 連接池 |
+| `response` | `string` | `'Too Many Attempts, Please try again in %d seconds.'` | 超出限流時的自定義響應 |
+| `responseCode` | `int` | `429` | 超出限流時的 HTTP 狀態碼 |
+
+### 使用 AutoSort 實現多限流規則智能排序
+
+當同一個方法需要多個限流規則時（例如每分鐘和每小時的限制），可以使用 `AutoSort` 註解自動按嚴格程度排序：
+
+```php
+<?php
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Annotation\AutoSort;
+
+class ApiController
+{
+    /**
+     * 多個限流規則智能排序
+     * 更嚴格的限制（maxAttempts/decay 比率更小）優先檢查
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 10, decay: 60)]      // 每分鐘 10 次 - 優先檢查
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 每小時 100 次 - 其次檢查
+    public function expensiveOperation()
+    {
+        // 你的代碼
+    }
+
+    /**
+     * 不使用 AutoSort 時，按聲明順序檢查
+     */
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 優先檢查
+    #[RateLimit(maxAttempts: 10, decay: 60)]       // 其次檢查
+    public function anotherOperation()
+    {
+        // 你的代碼
+    }
+}
+```
+
+**AutoSort 的優勢：**
+
+- **性能**：嚴格的限制優先檢查，避免不必要的寬鬆限制檢查
+- **智能**：自動根據限制嚴格程度（maxAttempts/decay 比率）計算優先級
+- **可選**：僅在顯式使用 `AutoSort` 的方法上生效
+- **向後兼容**：現有代碼無需修改即可繼續工作
+
+### 鍵佔位符
+
+`key` 參數支持動態佔位符，會被方法參數替換：
+
+```php
+// 命名佔位符
+#[RateLimit(key: 'user:{userId}:{action}')]
+public function action($userId, $action)
+
+// 數組格式（自動用 ':' 連接）
+#[RateLimit(key: ['user', '{userId}', '{action}'])]
+public function action($userId, $action)
+```
+
+### 方式二：使用中間件
+
+對於 HTTP 請求，可以創建繼承 `RateLimitMiddleware` 的自定義中間件：
+
+```php
+<?php
+
+namespace App\Middleware;
+
+use FriendsOfHyperf\RateLimit\Middleware\RateLimitMiddleware;
+use FriendsOfHyperf\RateLimit\Algorithm;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+class ApiRateLimitMiddleware extends RateLimitMiddleware
+{
+    // 重寫默認屬性
+    protected int $maxAttempts = 100;
+    protected int $decay = 60;
+    protected Algorithm $algorithm = Algorithm::SLIDING_WINDOW;
+    protected string $responseMessage = 'API rate limit exceeded';
+    protected int $responseCode = 429;
+
+    // 或自定義鍵解析
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'api:' . $this->getClientIp();
+    }
+}
+```
+
+然後在配置中註冊中間件：
+
+```php
+// config/autoload/middlewares.php
+return [
+    'http' => [
+        App\Middleware\ApiRateLimitMiddleware::class,
+    ],
+];
+```
+
+## 限流算法
+
+### 固定窗口（默認）
+
+最簡單的算法，在固定時間窗口內計數請求。
+
+```php
+#[RateLimit(algorithm: Algorithm::FIXED_WINDOW)]
+```
+
+**優點**：簡單，內存高效  
+**缺點**：可能在窗口邊界處允許突發請求
+
+### 滑動窗口
+
+比固定窗口更準確，均勻分佈請求。
+
+```php
+#[RateLimit(algorithm: Algorithm::SLIDING_WINDOW)]
+```
+
+**優點**：平滑突發流量，更準確  
+**缺點**：稍微複雜一些
+
+### 令牌桶
+
+允許突發流量，同時保持平均速率。
+
+```php
+#[RateLimit(algorithm: Algorithm::TOKEN_BUCKET)]
+```
+
+**優點**：允許突發流量，靈活  
+**缺點**：需要更多配置
+
+### 漏桶
+
+以恆定速率處理請求，排隊突發流量。
+
+```php
+#[RateLimit(algorithm: Algorithm::LEAKY_BUCKET)]
+```
+
+**優點**：平滑輸出速率，防止突發  
+**缺點**：可能延遲請求
+
+## 自定義限流器
+
+你可以通過實現 `RateLimiterInterface` 來實現自己的限流器：
+
+```php
+<?php
+
+namespace App\RateLimit;
+
+use FriendsOfHyperf\RateLimit\Contract\RateLimiterInterface;
+
+class CustomRateLimiter implements RateLimiterInterface
+{
+    public function tooManyAttempts(string $key, int $maxAttempts, int $decay): bool
+    {
+        // 你的實現
+    }
+
+    public function availableIn(string $key): int
+    {
+        // 你的實現
+    }
+
+    public function remaining(string $key, int $maxAttempts): int
+    {
+        // 你的實現
+    }
+}
+```
+
+## 異常處理
+
+當超出限流時，會拋出 `RateLimitException`：
+
+```php
+<?php
+
+try {
+    $userController->index();
+} catch (FriendsOfHyperf\RateLimit\Exception\RateLimitException $e) {
+    // 超出限流
+    $message = $e->getMessage();  // "Too Many Attempts. Please try again in X seconds."
+    $code = $e->getCode();        // 429
+}
+```
+
+## 配置
+
+組件使用 Hyperf 的 Redis 配置。你可以在註解或中間件中指定使用的 Redis 連接池：
+
+```php
+// 使用特定的 Redis 連接池
+#[RateLimit(pool: 'rate_limit')]
+```
+
+確保在 `config/autoload/redis.php` 中配置 Redis 連接池：
+
+```php
+return [
+    'default' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 0,
+        'pool' => [
+            'min_connections' => 1,
+            'max_connections' => 30,
+        ],
+    ],
+    'rate_limit' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 1,
+        'pool' => [
+            'min_connections' => 5,
+            'max_connections' => 50,
+        ],
+    ],
+];
+```
+
+## 示例
+
+### 示例 1：登錄限流
+
+限制登錄嘗試以防止暴力破解：
+
+```php
+#[RateLimit(
+    key: 'login:{email}',
+    maxAttempts: 5,
+    decay: 300, // 5 分鐘
+    response: 'Too many login attempts. Please try again after 5 minutes.',
+    responseCode: 429
+)]
+public function login(string $email, string $password)
+{
+    // 登錄邏輯
+}
+```
+
+### 示例 2：API 端點限流
+
+為不同的 API 端點設置不同的限流：
+
+```php
+class ApiController
+{
+    // 公共 API：每分鐘 100 次請求
+    #[RateLimit(maxAttempts: 100, decay: 60)]
+    public function public()
+    {
+        // 公共端點
+    }
+
+    // 高級 API：每分鐘 1000 次請求
+    #[RateLimit(maxAttempts: 1000, decay: 60)]
+    public function premium()
+    {
+        // 高級端點
+    }
+}
+```
+
+### 示例 3：基於用户的限流
+
+按用户限流：
+
+```php
+#[RateLimit(
+    key: ['user', '{userId}', 'action'],
+    maxAttempts: 10,
+    decay: 3600 // 1 小時
+)]
+public function performAction(int $userId)
+{
+    // 操作邏輯
+}
+```
+
+### 示例 4：基於 IP 的限流
+
+使用中間件按 IP 地址限流：
+
+```php
+class IpRateLimitMiddleware extends RateLimitMiddleware
+{
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'ip:' . $this->getClientIp();
+    }
+}
+```
+
+### 示例 5：使用 AutoSort 的多級限流
+
+使用 AutoSort 高效處理昂貴操作的多級限流：
+
+```php
+class ReportController
+{
+    /**
+     * 昂貴的報告生成，多級保護
+     * AutoSort 確保優先檢查嚴格的限制，提升性能
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 5, decay: 60, response: 'Too many requests. Max 5 per minute')]       // 緊急制動
+    #[RateLimit(maxAttempts: 30, decay: 3600, response: 'Hourly limit exceeded. Max 30 per hour')] // 持續負載
+    #[RateLimit(maxAttempts: 100, decay: 86400, response: 'Daily limit exceeded. Max 100 per day')] // 每日上限
+    public function generateReport($reportType)
+    {
+        // 昂貴的報告生成邏輯
+    }
+}
+```
diff --git a/docs/zh-tw/components/rate-limit.md b/docs/zh-tw/components/rate-limit.md
new file mode 100644
index 000000000..ecf3c1e2b
--- /dev/null
+++ b/docs/zh-tw/components/rate-limit.md
@@ -0,0 +1,466 @@
+# Rate Limit
+
+Hyperf 的限流元件，支援多種演算法（固定視窗、滑動視窗、令牌桶、漏桶）。
+
+## 安裝
+
+```bash
+composer require friendsofhyperf/rate-limit
+```
+
+## 環境要求
+
+- Hyperf ~3.1.0
+- Redis
+
+## 特性
+
+- **多種限流演算法**
+  - 固定視窗
+  - 滑動視窗
+  - 令牌桶
+  - 漏桶
+- **靈活的使用方式**
+  - 基於註解的限流（透過切面實現）
+  - 自定義中介軟體支援
+- **多註解智慧排序**
+  - 自動對多個 RateLimit 註解進行優先順序排序
+  - 根據嚴格程度智慧排序（maxAttempts/decay 比率）
+  - 更嚴格的限制優先檢查，提升效能
+- **靈活的鍵生成**
+  - 預設基於方法/類的鍵
+  - 支援自定義鍵和佔位符
+  - 支援陣列鍵
+  - 支援可呼叫鍵
+- **自定義響應**
+  - 自定義響應訊息
+  - 自定義 HTTP 響應碼
+- **多 Redis 連線池支援**
+
+## 使用方式
+
+### 方式一：使用註解
+
+最簡單的方式是使用 `#[RateLimit]` 屬性：
+
+```php
+<?php
+
+namespace App\Controller;
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Algorithm;
+
+class UserController
+{
+    /**
+     * 基礎限流：60 秒內最多 60 次請求
+     */
+    #[RateLimit(maxAttempts: 60, decay: 60)]
+    public function index()
+    {
+        // 你的程式碼
+    }
+
+    /**
+     * 使用滑動視窗演算法
+     */
+    #[RateLimit(
+        maxAttempts: 100,
+        decay: 60,
+        algorithm: Algorithm::SLIDING_WINDOW
+    )]
+    public function api()
+    {
+        // 你的程式碼
+    }
+
+    /**
+     * 自定義鍵，支援使用者 ID 佔位符
+     */
+    #[RateLimit(
+        key: 'user:{userId}:action',
+        maxAttempts: 10,
+        decay: 3600
+    )]
+    public function create($userId)
+    {
+        // 你的程式碼
+    }
+
+    /**
+     * 使用陣列鍵
+     */
+    #[RateLimit(
+        key: ['user', '{userId}', 'create'],
+        maxAttempts: 5,
+        decay: 60
+    )]
+    public function update($userId)
+    {
+        // 你的程式碼
+    }
+
+    /**
+     * 自定義響應訊息和狀態碼
+     */
+    #[RateLimit(
+        maxAttempts: 5,
+        decay: 60,
+        response: 'Too many requests, please try again later.',
+        responseCode: 429
+    )]
+    public function login()
+    {
+        // 你的程式碼
+    }
+
+    /**
+     * 使用指定的 Redis 連線池
+     */
+    #[RateLimit(
+        maxAttempts: 60,
+        decay: 60,
+        pool: 'rate_limit'
+    )]
+    public function heavyOperation()
+    {
+        // 你的程式碼
+    }
+}
+```
+
+### 註解引數
+
+| 引數 | 型別 | 預設值 | 說明 |
+|-----------|------|---------|-------------|
+| `key` | `string\|array` | `''` | 限流鍵。支援：'user:{user_id}', ['user', '{user_id}'], 或可呼叫函式 |
+| `maxAttempts` | `int` | `60` | 允許的最大請求次數 |
+| `decay` | `int` | `60` | 時間視窗（秒） |
+| `algorithm` | `Algorithm` | `Algorithm::FIXED_WINDOW` | 演算法：fixed_window, sliding_window, token_bucket, leaky_bucket |
+| `pool` | `?string` | `null` | 使用的 Redis 連線池 |
+| `response` | `string` | `'Too Many Attempts, Please try again in %d seconds.'` | 超出限流時的自定義響應 |
+| `responseCode` | `int` | `429` | 超出限流時的 HTTP 狀態碼 |
+
+### 使用 AutoSort 實現多限流規則智慧排序
+
+當同一個方法需要多個限流規則時（例如每分鐘和每小時的限制），可以使用 `AutoSort` 註解自動按嚴格程度排序：
+
+```php
+<?php
+
+use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
+use FriendsOfHyperf\RateLimit\Annotation\AutoSort;
+
+class ApiController
+{
+    /**
+     * 多個限流規則智慧排序
+     * 更嚴格的限制（maxAttempts/decay 比率更小）優先檢查
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 10, decay: 60)]      // 每分鐘 10 次 - 優先檢查
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 每小時 100 次 - 其次檢查
+    public function expensiveOperation()
+    {
+        // 你的程式碼
+    }
+
+    /**
+     * 不使用 AutoSort 時，按宣告順序檢查
+     */
+    #[RateLimit(maxAttempts: 100, decay: 3600)]    // 優先檢查
+    #[RateLimit(maxAttempts: 10, decay: 60)]       // 其次檢查
+    public function anotherOperation()
+    {
+        // 你的程式碼
+    }
+}
+```
+
+**AutoSort 的優勢：**
+
+- **效能**：嚴格的限制優先檢查，避免不必要的寬鬆限制檢查
+- **智慧**：自動根據限制嚴格程度（maxAttempts/decay 比率）計算優先順序
+- **可選**：僅在顯式使用 `AutoSort` 的方法上生效
+- **向後相容**：現有程式碼無需修改即可繼續工作
+
+### 鍵佔位符
+
+`key` 引數支援動態佔位符，會被方法引數替換：
+
+```php
+// 命名佔位符
+#[RateLimit(key: 'user:{userId}:{action}')]
+public function action($userId, $action)
+
+// 陣列格式（自動用 ':' 連線）
+#[RateLimit(key: ['user', '{userId}', '{action}'])]
+public function action($userId, $action)
+```
+
+### 方式二：使用中介軟體
+
+對於 HTTP 請求，可以建立繼承 `RateLimitMiddleware` 的自定義中介軟體：
+
+```php
+<?php
+
+namespace App\Middleware;
+
+use FriendsOfHyperf\RateLimit\Middleware\RateLimitMiddleware;
+use FriendsOfHyperf\RateLimit\Algorithm;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+class ApiRateLimitMiddleware extends RateLimitMiddleware
+{
+    // 重寫預設屬性
+    protected int $maxAttempts = 100;
+    protected int $decay = 60;
+    protected Algorithm $algorithm = Algorithm::SLIDING_WINDOW;
+    protected string $responseMessage = 'API rate limit exceeded';
+    protected int $responseCode = 429;
+
+    // 或自定義鍵解析
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'api:' . $this->getClientIp();
+    }
+}
+```
+
+然後在配置中註冊中介軟體：
+
+```php
+// config/autoload/middlewares.php
+return [
+    'http' => [
+        App\Middleware\ApiRateLimitMiddleware::class,
+    ],
+];
+```
+
+## 限流演算法
+
+### 固定視窗（預設）
+
+最簡單的演算法，在固定時間視窗內計數請求。
+
+```php
+#[RateLimit(algorithm: Algorithm::FIXED_WINDOW)]
+```
+
+**優點**：簡單，記憶體高效  
+**缺點**：可能在視窗邊界處允許突發請求
+
+### 滑動視窗
+
+比固定視窗更準確，均勻分佈請求。
+
+```php
+#[RateLimit(algorithm: Algorithm::SLIDING_WINDOW)]
+```
+
+**優點**：平滑突發流量，更準確  
+**缺點**：稍微複雜一些
+
+### 令牌桶
+
+允許突發流量，同時保持平均速率。
+
+```php
+#[RateLimit(algorithm: Algorithm::TOKEN_BUCKET)]
+```
+
+**優點**：允許突發流量，靈活  
+**缺點**：需要更多配置
+
+### 漏桶
+
+以恆定速率處理請求，排隊突發流量。
+
+```php
+#[RateLimit(algorithm: Algorithm::LEAKY_BUCKET)]
+```
+
+**優點**：平滑輸出速率，防止突發  
+**缺點**：可能延遲請求
+
+## 自定義限流器
+
+你可以透過實現 `RateLimiterInterface` 來實現自己的限流器：
+
+```php
+<?php
+
+namespace App\RateLimit;
+
+use FriendsOfHyperf\RateLimit\Contract\RateLimiterInterface;
+
+class CustomRateLimiter implements RateLimiterInterface
+{
+    public function tooManyAttempts(string $key, int $maxAttempts, int $decay): bool
+    {
+        // 你的實現
+    }
+
+    public function availableIn(string $key): int
+    {
+        // 你的實現
+    }
+
+    public function remaining(string $key, int $maxAttempts): int
+    {
+        // 你的實現
+    }
+}
+```
+
+## 異常處理
+
+當超出限流時，會丟擲 `RateLimitException`：
+
+```php
+<?php
+
+try {
+    $userController->index();
+} catch (FriendsOfHyperf\RateLimit\Exception\RateLimitException $e) {
+    // 超出限流
+    $message = $e->getMessage();  // "Too Many Attempts. Please try again in X seconds."
+    $code = $e->getCode();        // 429
+}
+```
+
+## 配置
+
+元件使用 Hyperf 的 Redis 配置。你可以在註解或中介軟體中指定使用的 Redis 連線池：
+
+```php
+// 使用特定的 Redis 連線池
+#[RateLimit(pool: 'rate_limit')]
+```
+
+確保在 `config/autoload/redis.php` 中配置 Redis 連線池：
+
+```php
+return [
+    'default' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 0,
+        'pool' => [
+            'min_connections' => 1,
+            'max_connections' => 30,
+        ],
+    ],
+    'rate_limit' => [
+        'host' => env('REDIS_HOST', 'localhost'),
+        'port' => env('REDIS_PORT', 6379),
+        'auth' => env('REDIS_AUTH', null),
+        'db' => 1,
+        'pool' => [
+            'min_connections' => 5,
+            'max_connections' => 50,
+        ],
+    ],
+];
+```
+
+## 示例
+
+### 示例 1：登入限流
+
+限制登入嘗試以防止暴力破解：
+
+```php
+#[RateLimit(
+    key: 'login:{email}',
+    maxAttempts: 5,
+    decay: 300, // 5 分鐘
+    response: 'Too many login attempts. Please try again after 5 minutes.',
+    responseCode: 429
+)]
+public function login(string $email, string $password)
+{
+    // 登入邏輯
+}
+```
+
+### 示例 2：API 端點限流
+
+為不同的 API 端點設定不同的限流：
+
+```php
+class ApiController
+{
+    // 公共 API：每分鐘 100 次請求
+    #[RateLimit(maxAttempts: 100, decay: 60)]
+    public function public()
+    {
+        // 公共端點
+    }
+
+    // 高階 API：每分鐘 1000 次請求
+    #[RateLimit(maxAttempts: 1000, decay: 60)]
+    public function premium()
+    {
+        // 高階端點
+    }
+}
+```
+
+### 示例 3：基於使用者的限流
+
+按使用者限流：
+
+```php
+#[RateLimit(
+    key: ['user', '{userId}', 'action'],
+    maxAttempts: 10,
+    decay: 3600 // 1 小時
+)]
+public function performAction(int $userId)
+{
+    // 操作邏輯
+}
+```
+
+### 示例 4：基於 IP 的限流
+
+使用中介軟體按 IP 地址限流：
+
+```php
+class IpRateLimitMiddleware extends RateLimitMiddleware
+{
+    protected function resolveKey(ServerRequestInterface $request): string
+    {
+        return 'ip:' . $this->getClientIp();
+    }
+}
+```
+
+### 示例 5：使用 AutoSort 的多級限流
+
+使用 AutoSort 高效處理昂貴操作的多級限流：
+
+```php
+class ReportController
+{
+    /**
+     * 昂貴的報告生成，多級保護
+     * AutoSort 確保優先檢查嚴格的限制，提升效能
+     */
+    #[AutoSort]
+    #[RateLimit(maxAttempts: 5, decay: 60, response: 'Too many requests. Max 5 per minute')]       // 緊急制動
+    #[RateLimit(maxAttempts: 30, decay: 3600, response: 'Hourly limit exceeded. Max 30 per hour')] // 持續負載
+    #[RateLimit(maxAttempts: 100, decay: 86400, response: 'Daily limit exceeded. Max 100 per day')] // 每日上限
+    public function generateReport($reportType)
+    {
+        // 昂貴的報告生成邏輯
+    }
+}
+```