Spring Cloud Tencent Rate Limit 使用文档

模块简介

服务限流是最常见的一种服务自我保护措施之一，防止流量洪峰打垮服务。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 代码请参考：polaris-ratelimit-example

第一步：准备 Polaris 服务端

搭建北极星服务请参考 Polaris Getting Started

腾讯云提供了免运维的北极星云服务，基于云服务可以快速开通生产级高可用北极星集群 了解更多

第二步：引入 Spring Cloud Tencent Rate Limit 依赖

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

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

2. 引入 Spring Cloud Tencent Rate Limit Starter

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

第三步：增加 Spring Cloud Tencent Rate Limit Starter 的配置文件

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. 按要求填写规则内容。其中，单机限流可以设置限流效果为快速失败或者匀速排队（匀速排队可点击此处了解详情），分布式限流目前仅支持快速失败。

4.2.1 使用分布式限流

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 自定义响应内容，详细参考配置列表。

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

配置列表

配置项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 状态码