Spring Cloud Tencent Rate Limit 使用文档

目录

• 模块简介
• 快速入门
  • 第一步：引入 Polaris 服务端
  • 第二步：引入服务限流依赖
  • 第三步：增加相关配置文件
  • 第四步：配置限流规则
  • 第五步：启动应用
• 拓展使用
  • Actuator Endpoint
  • 配置列表

模块简介

服务限流是最常见的一种服务自我保护措施之一，防止流量洪峰打垮服务。Spring Cloud Tencent Rate Limit 模块内置了针对 Spring Web 和 Spring WebFlux 场景的限流 Filter，结合 Polaris 的限流功能帮忙业务快速接入限流能力。

支持的限流场景包括：

1. 服务级限流
2. 根据 path 限流
3. 根据 Request 中的 QueryParam、Header 等参数细粒度限流

如果您对源码感兴趣，可以查看核心限流 Filter 实现类 RateLimitFilter

快速入门

本章节将介绍如何在 Spring Cloud 项目中使用 Spring Cloud Tencent RateLimit 的功能。 完整的 Example 代码请参考：quickstart-example

第一步：引入 Polaris 服务端

请参考 安装北极星服务端

第二步：引入服务限流依赖

1. 参考 Spring Cloud Tencent 版本管理 文档获取最新的版本号，引入 Spring Cloud Tencent Bom。

注意： Spring Cloud 、 Spring Boot 、 Spring Framework 之间有严格的版本对应关系，在 Spring Cloud Tencent 版本管理 文档中有详细罗列版本兼容性关系。请您在引入 Spring Cloud Tencent 版本时，根据项目 Spring Boot 和 Spring Framework 的版本，选择合适的 Spring Cloud Tencent 版本。

例如：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.cloud</groupId>
            <artifactId>spring-cloud-tencent-dependencies</artifactId>
            <version>1.8.2-Hoxton.SR9</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

2. 引入 Spring Cloud Tencent Rate Limit Starter

方式一：只引入spring-cloud-starter-tencent-polaris-ratelimit

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-polaris-ratelimit</artifactId>
</dependency>

方式二：通过 spring-cloud-starter-tencent-all 引入 sct 所有 starters

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-all</artifactId>
</dependency>

如果使用 Spring Cloud 2021 版本，还需要添加如下依赖：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

第三步：增加相关配置文件

1. 在您的 bootstrap.yml 配置文件中加入以下配置内容

spring:
  application:
    name: ${application.name}
  cloud:
    polaris:
      address: grpc://${修改为第一步部署的 Polaris 服务地址}:8091
      namespace: default

第四步：配置限流规则

您可以在北极星控制台动态配置限流规则。

4.1 创建服务

如果您没有使用 Spring Cloud Tencent Discovery 能力，则需要在控制台手工创建服务信息。如下图所示：

4.2 创建限流规则

1. 点击服务名进入服务主页
2. 切换到 服务限流 tab
3. 创建规则
4. 按要求填写规则内容。其中，单机限流可以设置限流效果为快速失败或者匀速排队（匀速排队限流可点击此处了解详情），分布式限流目前仅支持快速失败。

表达式标签，自动解析 Query、Header、Cookie 里的参数

把 Http 请求里的某些字段作为流量标签，并且只针对带有某些标签的请求进行限流。例如 Query Param 有一个 uid 字段，期望只对某些 uid 限流。

场景一：SCT 版本 < 1.8.1，Polaris 版本 < 1.11.0

老版本的 SCT 和 Polaris 为了支持这种场景，我们定义了一套标签规则表达式，例如 ${http.query.uid} 表示请求 Query Param 里的 uid 字段，如下图所示，表示 uid=1000 的用户。

当前支持的标签规则表达式如下：

• ${http.query.xxx}
  • 表示查询请求的参数
• ${http.header.xxx}
  • 表示请求头里的参数
• ${http.cookie.xxx}
  • 表示 cookie 里的参数
• ${http.method}
  • 表示请求的方法，GET、POST、PUT 等
• ${http.uri}
  • 表示请求的 Path，注意 / 开头，例如：/user

场景二：SCT 版本 < 1.8.1，Polaris 版本 >= 1.11.0

北极星从 1.11.0 之后，支持了页面选择 Header、Query 等参数表单，但是格式有所不同，例如 $header.user,所以低版本的 SCT 解析不了这种格式。

1.8.1 版本之后，兼容了 $header.user 格式。所以如果您的 SCT 版本低于 1.8.1 可通过自定义标签来实现，表达式格式和上一节一致，如下图所示：

场景三：1.8.1 <= SCT 版本 < 1.11.0

SCT 支持 Header、Query、Cookie 等参数进行限流。

场景四：1.11.0 <= SCT 版本

SCT 支持 主调IP（caller_ip） 参数进行限流。

对 Path 中带有参数的请求限流

按照 Restful 规范，Path 中经常带有请求参数，例如以下 GET 请求 /users/{userId}/orders 表达的含义是获取特定用户的订单列表。通过正则表达式即可实现这类接口的限流 /users/.*/orders ，如下图所示：

合并计算阈值

默认情况下，/users/1000/orders 和 /user/1001/orders 独立计算 QPS。如果打开合并计算阈值开关，则以 /users/.*/orders 为计算单位，所有满足正则表达式的接口共享 QPS。

使用分布式限流

1. 页面创建限流规则时，选择 分布式限流 规则
2. 额外部署限流 Server （分布式限流需要依赖额外中心限流集群来协调多节点）
3. 客户端默认情况下，无需任何配置，使用默认值即可

如需使用分布式限流，则需要部署限流 Server，并把限流 Server 注册到北极星（限流 Server 部署参考文档），限流客户端通过北极星获取限流 Server 的服务地址。限流 Server 默认服务名为 polaris.limiter 并注册到 Polaris 命名空间下。如自定义限流 Server 服务名，则需要在 resources/polaris.yml 配置限流 Server 服务名，如下所示：

provider:
  # 限流配置
  rateLimit:
    # 限流服务的命名空间
    limiterNamespace: Polaris
    # 限流服务名，改为自定义服务名
    limiterService: polaris.limiter

第五步：启动应用

应用启动成功后，访问应用的 http 接口，测试限流是否生效。如果请求被限流将会返回以下内容：

The request is deny by rate limit because the throttling threshold is reached

HttpCode 默认为 429

被限流时，可通过 spring.cloud.polaris.ratelimit.rejectRequestTips 自定义响应内容，详细参考配置列表。

至此即已完成限流的接入。

拓展使用

自定义限流行为（SCT 版本 >= 1.10.0）

Spring Cloud Tencent 提供了 PolarisRateLimiterLimitedFallback 接口以方便开发者自定义限流行为，可以参考example使用：spring-cloud-tencent-examples/polaris-ratelimit-example/ratelimit-callee-service/src/main/java/com/tencent/cloud/ratelimit/example/service/callee/JsonPolarisRateLimiterLimitedFallback.java。

Actuator Endpoint

Spring Cloud Tencent 扩展了 Spring Boot 标准的 Actuator 能力，通过 Actuator 接口，可以实时查询当前运行实例内存里限流规则，便于排查问题。详细可以参考: Actuator Endpoint 扩展

配置列表

配置项Key	默认值	是否必填	配置项说明
spring.cloud.polaris.ratelimit.enabled	true	否	是否开启服务限流
spring.cloud.polaris.ratelimit.rejectRequestTips		否	自定义拒绝请求响应的文本内容
spring.cloud.polaris.ratelimit.rejectRequestTipsFilePath		否	自定义拒绝请求响应内容的文件地址，常用于返回 html 文件内容等。目前仅支持 classpath 下的文件，放在 resources 目录。
spring.cloud.polaris.ratelimit.rejectHttpCode	429(Too Many Request)	否	自定义拒绝请求响应的 Http 状态码
spring.cloud.polaris.ratelimit.maxQueuingTime	1000	否	匀速排队限流最大排队时间