配置微调，代码结构调整

hongweipeng · hongweipeng · commit dcc8f0fd605d · 2025-05-05T20:39:55.000+08:00
diff --git a/README.md b/README.md
@@ -27,18 +27,19 @@ return [
     'key' => true,
     // 要被限制的请求类型, eg: GET POST PUT DELETE HEAD
     'visit_method' => ['GET'],
-    // 设置访问频率，例如 '10/m' 指的是允许每分钟请求10次。值 null 表示不限制， eg: null 10/m  20/h  300/d 200/300
+    // 设置访问频率，例如 '10/m' 指的是允许每分钟请求10次;'10/60'指允许每60秒请求10次。空字符串表示不限制， eg: '', '10/m', '20/h', '300/d', '200/300'
     'visit_rate' => '100/m',
     // 访问受限时返回的响应
     'visit_fail_response' => function (Throttle $throttle, Request $request, int $wait_seconds) {
-        return Response::create('Too many requests, try again after ' . $wait_seconds . ' seconds.')->code(429);
+        $content = str_replace('__WAIT__', (string)$wait_seconds, $throttle->getFailMessage());
+        return Response::create($content)->code(429);
     },
 ];
 ```
 
 当配置项满足以下条件任何一个时，不会限制访问频率：
-1. `key` 值为 `false` 或 `null`；
-2. `visit_rate` 值为 `null`。
+1. `key` 值为 `false` 或 `''`；
+2. `visit_rate` 值为 `''`。
 
 其中 `key` 用来设置缓存键的；而 `visit_rate` 用来设置访问频率，单位可以是秒，分，时，天，例如：`1/s`, `10/m`, `98/h`, `100/d` , 也可以是 `100/600` （600 秒内最多 100 次请求）。
 
@@ -81,20 +82,62 @@ Route::group(function() {
     'key' => '__CONTROLLER__/__ACTION__/__IP__',
 ]);
 ```
+
+示例五：使用注解配置（3.0.x版本支持）
+需要开启路由中间件，它有多种启用方式，这里以全局路由中间件为例，在 `config/route.php` 配置文件中添加: 
+```
+'middleware'    =>    [
+    \think\middleware\Throttle::class,
+],
+```
+控制器中使用：
+```
+<?php
+
+namespace app\controller;
+
+use app\BaseController;
+use think\middleware\annotation\RateLimit;
+
+class User extends BaseController
+{
+
+    #[RateLimit(rate: "10/m")]
+    public function index(): string
+    {
+        // 默认为IP限流，默认单位时间为1秒
+        return '每个ip每秒最多10个请求';
+    }
+
+    #[RateLimit(rate: "1/d", key: RateLimit::SESSION, message: '每个用户每天只能领取一次优惠券')]
+    #[RateLimit(rate: '100/d', key: 'coupon', message: '今天的优惠券已经发完，请明天再来')]
+    public function coupon(): string
+    {
+        return '优惠券发送成功';
+    }
+
+}
+```
 ## 版本与 TP 适配关系
 ```
+3.0.x -> thinkphp 8.0
 2.0.x -> thinkphp 8.0
 1.x.x -> thinkphp 6.0/6.1
 0.5.x -> thinkphp 5.1
 ```
 
 ## 更新日志
+版本 3.0.x 配置微调，不支持无缝升级；
+
 版本 2.0.x 的可从 1.x 无缝升级；
 
 版本 1.3.x 的配置形式完全兼容版本 1.2.x 内容，可以无缝升级；
 
 版本 1.2.x 的配置形式完全兼容版本 1.1.x 内容，可以无缝升级；
 
+### 3.0.x 更新
+- 支持注解方式；
+
 ### 2.0.x 更新
 - 适配 thinkphp 8.0；
 - 所有 `php` 文件都采用 `declare(strict_types=1);` 强类型约束；
diff --git a/src/Throttle.php b/src/Throttle.php
@@ -16,6 +16,7 @@
 use think\middleware\throttle\ThrottleAbstract;
 use think\Request;
 use think\Response;
+use think\Session;
 use TypeError;
 use function sprintf;
 
@@ -37,7 +38,7 @@ class Throttle
         'visit_rate' => '',                         // 节流频率, 空字符串表示不限制 eg: '', '10/m', '20/h', '300/d'
         'visit_enable_show_rate_limit' => true,     // 在响应体中设置速率限制的头部信息
         'visit_fail_code' => 429,                   // 访问受限时返回的 http 状态码，当没有 visit_fail_response 时生效
-        'visit_fail_text' => 'Too Many Requests',   // 访问受限时访问的文本信息，当没有 visit_fail_response 时生效
+        'visit_fail_text' => 'Too many requests, try again after __WAIT__ seconds.',   // 访问受限时访问的文本信息
         'visit_fail_response' => null,              // 访问受限时的响应信息闭包回调
         'driver_name' => CounterFixed::class,       // 限流算法驱动
     ];
@@ -55,6 +56,7 @@ class Throttle
      */
     protected CacheInterface $cache;
     protected App $app;
+    protected Session $session;
 
     /**
      * 配置参数
@@ -74,12 +76,13 @@ class Throttle
      * @param Cache $cache
      * @param Config $config
      */
-    public function __construct(Cache $cache, Config $config, App $app)
+    public function __construct(Cache $cache, Config $config, App $app, Session $session)
     {
         $this->cache = $cache;
         $this->config = array_merge(static::$default_config, $config->get('throttle', []));
         $this->app = $app;
         $this->config_instance = $config;
+        $this->session = $session;
     }
 
     /**
@@ -95,7 +98,7 @@ public function handle(Request $request, Closure $next, array $params = []): Res
             $this->config = array_merge($this->config, $params);
         }
 
-        $allow = $this->allowRequestByConfig($request) && $this->allowRequestByAnnotation($request);
+        $allow = $this->allowRequestByAnnotation($request) && $this->allowRequestByConfig($request);
         if (!$allow) {
             // 访问受限
             throw $this->buildLimitException($this->wait_seconds, $request);
@@ -113,43 +116,73 @@ public function handle(Request $request, Closure $next, array $params = []): Res
     }
 
     /**
-     * 根据**配置**信息是否允许请求通过
+     * 根据**注解**信息是否允许请求通过
      * @param Request $request
      * @return bool
      */
-    protected function allowRequestByConfig(Request $request): bool
+    protected function allowRequestByAnnotation(Request $request): bool
     {
-        // 若请求类型不在限制内
-        if (!in_array($request->method(), $this->config['visit_method'])) {
-            return true;
+        // 处理注解
+        $controller = $this->getFullController($request);
+        if ($controller) {
+            $action = $request->action();
+            if (method_exists($controller, $action)) {
+                $reflectionMethod = new ReflectionMethod($controller, $action);
+                $attributes = $reflectionMethod->getAttributes(RateLimitAnnotation::class);
+                foreach ($attributes as $attribute) {
+                    $annotation = $attribute->newInstance();
+                    $key = $this->getCacheKey($request, $annotation->key, $annotation->driver, true);
+                    if (!$this->allowRequest($key, $annotation->rate, $annotation->driver)) {
+                        $this->config['visit_fail_text'] = $annotation->message;
+                        return false;
+                    }
+                }
+            }
         }
-        $driver = $this->config['driver_name'];
-        $key = $this->getCacheKey($request, $this->config['key'], $driver);
-        return $this->allowRequest($key, $this->config['visit_rate'], $driver);
+        return true;
+    }
+
+    private function getFullController(Request $request): string
+    {
+        $controller = $request->controller();
+        if (empty($controller)) {
+            return '';
+        }
+        $suffix = $this->config_instance->get('route.controller_suffix') ? 'Controller' : '';
+        $layer = $this->config_instance->get('route.controller_layer') ?: 'controller';
+        $controllerClassName = $this->app->parseClass($layer, $controller . $suffix);
+        return $controllerClassName;
     }
 
     /**
      * 生成缓存的 key
      * @param Request $request
-     * @param string|bool|Closure|null $key
+     * @param string|bool|Closure $key
      * @param string $driver
      * @return string
      */
-    protected function getCacheKey(Request $request, string|bool|Closure|null $key, string $driver): string
+    protected function getCacheKey(Request $request, string|bool|Closure $key, string $driver, bool $annotation = false): string
     {
         if ($key instanceof Closure) {
             $key = Container::getInstance()->invokeFunction($key, [$this, $request]);
         }
 
-        if ($key === null || $key === false) {
-            // 关闭当前限制
+        if ($key === false || $key === '') {
+            // 不做限制
             return '';
         }
 
         if ($key === true) {
             $key = $request->ip();
         } elseif (is_string($key) && str_contains($key, '__')) {
-            $key = str_replace(['__CONTROLLER__', '__ACTION__', '__IP__'], [$request->controller(), $request->action(), $request->ip()], $key);
+            $key = str_replace(['__CONTROLLER__', '__ACTION__', '__IP__', '__SESSION__'],
+                [$request->controller(), $request->action(), $request->ip(), $this->session->getId()],
+                $key);
+        }
+
+        if ($annotation) {
+            // 注解需要以实际方法作为前缀
+            $key = $request->controller() . $request->action() . $key;
         }
 
         return md5($this->config['prefix'] . $key . $driver);
@@ -206,44 +239,19 @@ protected function parseRate(string $rate): array
     }
 
     /**
-     * 根据**注解**信息是否允许请求通过
+     * 根据**配置**信息是否允许请求通过
      * @param Request $request
      * @return bool
      */
-    protected function allowRequestByAnnotation(Request $request): bool
-    {
-        // 处理注解
-        $controller = $this->getFullController($request);
-        if ($controller) {
-            $action = $request->action();
-            if (method_exists($controller, $action)) {
-                $reflectionMethod = new ReflectionMethod($controller, $action);
-                $attributes = $reflectionMethod->getAttributes(RateLimitAnnotation::class);
-                foreach ($attributes as $attribute) {
-                    $annotation = $attribute->newInstance();
-                    $key = $this->getCacheKey($request, $annotation->key, $annotation->driver);
-                    $key = $controller . $action . $key; // 注解需要以实际方法作为前缀
-
-                    if (!$this->allowRequest($key, $annotation->rate, $annotation->driver)) {
-                        $this->config['visit_fail_text'] = $annotation->message;
-                        return false;
-                    }
-                }
-            }
-        }
-        return true;
-    }
-
-    private function getFullController(Request $request): string
+    protected function allowRequestByConfig(Request $request): bool
     {
-        $controller = $request->controller();
-        if (empty($controller)) {
-            return '';
+        // 若请求类型不在限制内
+        if (!in_array($request->method(), $this->config['visit_method'])) {
+            return true;
         }
-        $suffix = $this->config_instance->get('route.controller_suffix') ? 'Controller' : '';
-        $layer = $this->config_instance->get('route.controller_layer') ?: 'controller';
-        $controllerClassName = $this->app->parseClass($layer, $controller . $suffix);
-        return $controllerClassName;
+        $driver = $this->config['driver_name'];
+        $key = $this->getCacheKey($request, $this->config['key'], $driver);
+        return $this->allowRequest($key, $this->config['visit_rate'], $driver);
     }
 
     /**
@@ -261,7 +269,7 @@ public function buildLimitException(int $wait_seconds, Request $request): HttpRe
                 throw new TypeError(sprintf('The closure must return %s instance', Response::class));
             }
         } else {
-            $content = str_replace('__WAIT__', (string)$wait_seconds, $this->config['visit_fail_text']);
+            $content = str_replace('__WAIT__', (string)$wait_seconds, $this->getFailMessage());
             $response = Response::create($content)->code($this->config['visit_fail_code']);
         }
         if ($this->config['visit_enable_show_rate_limit']) {
@@ -270,6 +278,15 @@ public function buildLimitException(int $wait_seconds, Request $request): HttpRe
         return new HttpResponseException($response);
     }
 
+    /**
+     * 获取受限时的信息
+     * @return string
+     */
+    public function getFailMessage(): string
+    {
+        return $this->config['visit_fail_text'];
+    }
+
     /**
      * 设置速率
      * @param string $rate '10/m'  '20/300'
diff --git a/src/annotation/RateLimit.php b/src/annotation/RateLimit.php
@@ -12,11 +12,12 @@ class RateLimit
 {
     const AUTO = true;
     const IP = '__IP__';
+    const SESSION = '__SESSION__';
 
-    public function __construct(public string                   $rate,
-                                public string|bool|Closure|null $key = RateLimit::AUTO,
-                                public string                   $driver = CounterFixed::class,
-                                public string                   $message = 'Too Many Requests')
+    public function __construct(public string              $rate,
+                                public string|bool|Closure $key = RateLimit::AUTO,
+                                public string              $driver = CounterFixed::class,
+                                public string              $message = 'Too Many Requests')
     {
 
     }
diff --git a/src/config.php b/src/config.php
@@ -10,11 +10,11 @@
 return [
     // 缓存键前缀，防止键值与其他应用冲突
     'prefix' => 'throttle_',
-    // 缓存的键，true 表示使用来源ip
+    // 缓存的键，true 表示使用来源 ip
     'key' => true,
     // 要被限制的请求类型, eg: GET POST PUT DELETE HEAD 等
     'visit_method' => ['GET', 'HEAD'],
-    // 设置访问频率，例如 '10/m' 指的是允许每分钟请求10次;'10/60'指允许每60秒请求10次。空值表示不限制， eg: '', '10/m', '20/h', '300/d', '200/300'
+    // 设置访问频率，例如 '10/m' 指的是允许每分钟请求10次;'10/60'指允许每60秒请求10次。空字符串表示不限制， eg: '', '10/m', '20/h', '300/d', '200/300'
     'visit_rate' => '100/m',
     /*
      * 设置节流算法，组件提供了四种算法：
@@ -28,6 +28,7 @@
     'visit_enable_show_rate_limit' => true,
     // 访问受限时返回的响应
     'visit_fail_response' => function (Throttle $throttle, Request $request, int $wait_seconds) {
-        return Response::create('Too many requests, try again after ' . $wait_seconds . ' seconds.')->code(429);
+        $content = str_replace('__WAIT__', (string)$wait_seconds, $throttle->getFailMessage());
+        return Response::create($content)->code(429);
     },
 ];
diff --git a/tests/Base.php b/tests/Base.php
@@ -107,10 +107,10 @@ function set_throttle_config(array $config): void
         $this->throttle_config = $config;
     }
 
-    protected function tearDown(): void
+    protected function setUp(): void
     {
-        parent::tearDown();
-        // 每次测试完毕都需要清理 runtime cache 目录，避免影响其他单元测试
+        parent::setUp();
+        // 每次单元测试都需要清理 runtime cache 目录，避免影响其他单元测试
         $cache_dir = GCApp::RUNTIME_PATH . "cache";
         $dirs = glob($cache_dir . '/*', GLOB_ONLYDIR);
         foreach ($dirs as $dir) {
@@ -125,7 +125,6 @@ protected function tearDown(): void
         }
         unset($cache_dir);
         unset($dirs);
-        gc_collect_cycles();    // 进行垃圾回收
     }
 
 }
diff --git a/tests/app/controller/User.php b/tests/app/controller/User.php
@@ -34,4 +34,11 @@ public function coupon(): string
         return '优惠券发送成功';
     }
 
+    #[RateLimit(rate: "1/d", key: RateLimit::SESSION, message: '每个用户每天只能领取一次优惠券')]
+    #[RateLimit(rate: '100/d', key: 'coupon', message: '今天的优惠券已经发完，请明天再来')]
+    public function coupon2(): string
+    {
+        return '优惠券发送成功';
+    }
+
 }
diff --git a/tests/config/throttle.php b/tests/config/throttle.php
@@ -10,11 +10,11 @@
 return [
     // 缓存键前缀，防止键值与其他应用冲突
     'prefix' => 'throttle_',
-    // 缓存的键，true 表示使用来源ip
+    // 缓存的键，true 表示使用来源 ip
     'key' => true,
     // 要被限制的请求类型, eg: GET POST PUT DELETE HEAD 等
     'visit_method' => ['GET', 'HEAD'],
-    // 设置访问频率，例如 '10/m' 指的是允许每分钟请求10次;'10/60'指允许每60秒请求10次。值 null 表示不限制， eg: null 10/m  20/h  300/d 200/300
+    // 设置访问频率，例如 '10/m' 指的是允许每分钟请求10次;'10/60'指允许每60秒请求10次。空值表示不限制， eg: '', '10/m', '20/h', '300/d', '200/300'
     'visit_rate' => '100/m',
     /*
      * 设置节流算法，组件提供了四种算法：
@@ -28,6 +28,7 @@
     'visit_enable_show_rate_limit' => true,
     // 访问受限时返回的响应
     'visit_fail_response' => function (Throttle $throttle, Request $request, int $wait_seconds) {
-        return Response::create('Too many requests, try again after ' . $wait_seconds . ' seconds.')->code(429);
+        $content = str_replace('__WAIT__', (string)$wait_seconds, $throttle->getFailMessage());
+        return Response::create($content)->code(429);
     },
 ];
diff --git a/tests/controller/User.php b/tests/controller/User.php
diff --git a/tests/gc/GCApp.php b/tests/gc/GCApp.php
diff --git a/tests/public/index.php b/tests/public/index.php

Original file line number	Diff line number	Diff line change
`@@ -12,11 +12,12 @@ class RateLimit`
`12`	`12`	`{`
`13`	`13`	`const AUTO = true;`
`14`	`14`	`const IP = '__IP__';`
	`15`	`+ const SESSION = '__SESSION__';`
`15`	`16`
`16`		`- public function __construct(public string $rate,`
`17`		`- public string\|bool\|Closure\|null $key = RateLimit::AUTO,`
`18`		`- public string $driver = CounterFixed::class,`
`19`		`- public string $message = 'Too Many Requests')`
	`17`	`+ public function __construct(public string $rate,`
	`18`	`+ public string\|bool\|Closure $key = RateLimit::AUTO,`
	`19`	`+ public string $driver = CounterFixed::class,`
	`20`	`+ public string $message = 'Too Many Requests')`
`20`	`21`	`{`
`21`	`22`
`22`	`23`	`}`
Original file line number	Diff line number	Diff line change
`@@ -107,10 +107,10 @@ function set_throttle_config(array $config): void`
`107`	`107`	`$this->throttle_config = $config;`
`108`	`108`	`}`
`109`	`109`
`110`		`- protected function tearDown(): void`
	`110`	`+ protected function setUp(): void`
`111`	`111`	`{`
`112`		`- parent::tearDown();`
`113`		`- // 每次测试完毕都需要清理 runtime cache 目录，避免影响其他单元测试`
	`112`	`+ parent::setUp();`
	`113`	`+ // 每次单元测试都需要清理 runtime cache 目录，避免影响其他单元测试`
`114`	`114`	`$cache_dir = GCApp::RUNTIME_PATH . "cache";`
`115`	`115`	`$dirs = glob($cache_dir . '/*', GLOB_ONLYDIR);`
`116`	`116`	`foreach ($dirs as $dir) {`
`@@ -125,7 +125,6 @@ protected function tearDown(): void`
`125`	`125`	`}`
`126`	`126`	`unset($cache_dir);`
`127`	`127`	`unset($dirs);`
`128`		`- gc_collect_cycles(); // 进行垃圾回收`
`129`	`128`	`}`
`130`	`129`
`131`	`130`	`}`
Original file line number	Diff line number	Diff line change
`@@ -34,4 +34,11 @@ public function coupon(): string`
`34`	`34`	`return '优惠券发送成功';`
`35`	`35`	`}`
`36`	`36`
	`37`	`+ #[RateLimit(rate: "1/d", key: RateLimit::SESSION, message: '每个用户每天只能领取一次优惠券')]`
	`38`	`+ #[RateLimit(rate: '100/d', key: 'coupon', message: '今天的优惠券已经发完，请明天再来')]`
	`39`	`+ public function coupon2(): string`
	`40`	`+ {`
	`41`	`+ return '优惠券发送成功';`
	`42`	`+ }`
	`43`	`+`
`37`	`44`	`}`