一个注解保护你的接口:skrstop-components @AccessLimit限流与@ServiceLock并发锁完全教程

原创2026-10-16 09:10:511,767 阅读

一个注解保护你的接口:skrstop-components @AccessLimit限流与@ServiceLock并发锁完全教程

还在为接口被恶意刷爆、并发下数据被重复提交而头疼吗?skrstop-components 是面向 SpringBoot 的常用功能封装组件库,其中的 @AccessLimit 限流注解和 @ServiceLock 并发锁注解,只需一行代码就能为你的接口加上一道安全护栏,免去各种限流配置,开箱即用。本文带你从零上手这两个注解,并讲透背后的限流原理与自定义规则扩展方法。

1. 为什么接口需要「限流」和「锁」?🛡️

在动手之前,先理解两个高频场景,它们也是这两个注解要解决的问题:

场景 风险 解决思路 对应注解
秒杀、短信验证码接口被刷 瞬时流量打垮服务 每秒只放行固定数量的请求,其余快速拒绝 @AccessLimit(限流)
同一个任务/扣减操作被并发触发 重复扣款、状态错乱 同一时刻只允许一个线程进入方法,其余排队或直接失败 @ServiceLock(并发锁)

两者的区别可以一句话概括:

限流是「流量闸门」——控制单位时间内的请求数量;锁是「串行通道」——控制同一资源的并发访问。

skrstop-components 把这两个能力都封装成了方法级注解,底层通过 Spring AOP 的 MethodInterceptor 实现,配合 DynamicAnnotationAdvisor 动态织入,全程无需手写拦截器或过滤器。

2. 快速开始:Maven 引入依赖

@AccessLimit 与 @ServiceLock 都位于通用自定义注解模块 components-starter-annotation 中。项目已上传 Maven,在 pom 中按需引入即可:

<dependency>
    <groupId>com.skrstop.framework</groupId>
    <artifactId>components-starter-annotation</artifactId>
    <version>${skrstop.version}</version>
</dependency>

自动装配类 AnnotationAutoConfiguration.java 已经为两个注解注册好了对应的 Advisor 和拦截器,SpringBoot 应用启动后自动生效,零配置即可使用(支持 JDK8+、JDK17+)。

3. @AccessLimit 限流注解:一键保护高频接口 ⏱️

3.1 基本用法

@AccessLimit 的定义见 AccessLimit.java,可标注在方法或类上。给一个查询接口限制为每秒 10 次请求:

@RestController
public class OrderController {

    /**
     * 限流注解:该接口每秒最多放行 10 个请求
     */
    @AccessLimit(limit = 10, message = "查询太频繁,请稍后再试")
    @GetMapping("/orders/query")
    public Result queryOrder() {
        // 业务逻辑
    }
}

完整示例可参考项目中的 ExampleAnnotationController.java:

@AccessLimit(limit = 1)
@GetMapping("/exampleAnnotationAccessLimit")
public void exampleAnnotationAccessLimit() {
}

3.2 参数说明

参数 默认值 说明
limit 1000.0 每秒限流数(QPS),支持小数
message 访问过于频繁,请稍后再试 触发限流时返回的提示信息
beanName "" 按 Bean 名称查找自定义限流规则,优先级高于 beanClass
beanClass void.class 按类型查找自定义限流规则,需保证全局唯一实例
defaultRule DefaultAccessLimitRule.class 未指定 Bean 时使用的默认规则实现

当请求超过 limit 阈值时,拦截器 AccessLimitAnnotationInterceptor.java 会抛出 AccessLimitException,异常码为 server.limit.access(见 WebAnnotationExceptionCode.java),前端会收到你自定义的 message 提示。

3.3 限流原理:Guava 令牌桶 🪣

默认规则 DefaultAccessLimitRule.java 内部使用 Guava RateLimiter 令牌桶算法:

  • 每个方法单独维护一个 RateLimiter(按方法签名 MD5 作为 key,缓存在 ConcurrentHashMap 中);
  • 桶内按 limit 速率每秒放入固定数量令牌,请求到来时调用 tryAcquire() 尝试取令牌;
  • 取到令牌 → 放行执行方法;取不到 → 立即拒绝,不阻塞、不排队;
  • 属于单进程服务内的限流,适合单体服务或已按实例均摊流量的场景。

💡 提示:limit 在运行期变化时(例如通过配置刷新),DefaultAccessLimitRule 会自动重建对应的 RateLimiter,无需重启服务。

3.4 自定义限流规则:接入 Redis 等外部方案

如果需要基于 IP 限流、集群维度限流(如接入 Redis 令牌桶),只需实现 AccessLimitRule 接口并注册为 Bean,然后在注解上指向它:

public interface AccessLimitRule {
    /** 是否可以继续执行 */
    boolean canContinue(MethodInvocation invocation, double limitNum);
}

项目中给出了完整示例 AccessLimitConfiguration.java:

@Configuration
public class AccessLimitConfiguration {

    @Bean
    public AccessLimitRule accessLimitRule1() {
        return new DefaultAccessLimitRule();
    }
}

三种指定方式(优先级从高到低):

// 方式一:按 beanName 指定
@AccessLimit(limit = 5, message = "自定义限流提示", beanName = "accessLimitRule1")

// 方式二:按 beanClass 指定(全局需唯一实例)
@AccessLimit(limit = 5, beanClass = CustomAccessLimitRule.class)

// 方式三:直接指定 defaultRule 类(反射实例化,不依赖 Spring 容器)
@AccessLimit(limit = 5, defaultRule = CustomAccessLimitRule.class)

4. @ServiceLock 并发锁注解:方法级互斥互锁 🔒

4.1 基本用法

@ServiceLock 的定义见 ServiceLock.java,用于给方法加公平可重入锁,确保同一时刻只有一个线程能进入:

@ServiceLock(lockId = "serviceLock")
@GetMapping("/exampleAnnotationServiceLock")
public void exampleAnnotationServiceLock() throws InterruptedException {
    TimeUnit.SECONDS.sleep(10); // 10 秒内,其他请求被拦截/排队
}

示例同样来自 ExampleAnnotationController.java。

4.2 参数说明

参数 默认值 说明
lockId ""(按方法区分) 锁 ID,相同 lockId 的多个方法共享同一把锁,可实现跨方法互斥
fastFail false 是否快速失败。true 时拿不到锁立即抛业务异常(BUSY),false 时排队等待
timeoutMs 0(无限等待) 仅在 fastFail = true 时生效,等待超时时间(毫秒)
message 访问过于频繁,请稍后再试 提示信息
beanName / beanClass / defaultRule 同 @AccessLimit 自定义锁规则扩展点

两种典型写法:

// 排队模式:拿不到锁就一直等,直到进入方法(防重复提交常用)
@ServiceLock(lockId = "createOrder")

// 快速失败模式:最多等 1 秒,拿不到锁立即返回"忙"
@ServiceLock(lockId = "createOrder", fastFail = true, timeoutMs = 1000)

4.3 锁是怎么实现的?🔍

默认规则 DefaultServiceLockRule.java 的核心逻辑:

  1. 以 lockId(未指定时用方法签名 MD5)为 key,在 ConcurrentHashMap 中维护一把 ReentrantLock(true) 公平可重入锁;
  2. 先 tryLock(timeoutMs) 尝试获取锁——拿到立即执行方法,执行完 finally 中释放;
  3. fastFail = true 且抢锁失败 → 抛出 BUSY 业务异常,接口秒拒;
  4. fastFail = false → 转入 lock() 阻塞排队,按 FIFO 公平顺序依次执行。

典型应用:库存扣减、账户余额操作、防重复提交、单机定时任务防重入——凡是"同一资源不能被两个线程同时操作"的地方都适用。

5. 限流 vs 锁:一张表看懂选型 📊

对比项 @AccessLimit 限流 @ServiceLock 并发锁
解决的问题 流量过多(QPS 超限) 并发冲突(重复执行)
默认算法 Guava RateLimiter 令牌桶 ReentrantLock 公平锁
超限行为 直接拒绝(不排队) 排队等待 或 快速失败
核心参数 limit(每秒放行数) lockId / fastFail / timeoutMs
规则扩展接口 AccessLimitRule ServiceLockRule
触发异常 AccessLimitException BUSY 业务异常(快速失败时)
适用场景 短信验证码、查询接口、对外 API 下单扣减、防重复提交、资源独占操作

💡 组合使用也很常见:对外接口先挂 @AccessLimit 挡住洪峰,内部核心方法再挂 @ServiceLock 保证串行正确性。两个注解均可标注在方法或类上,类上标注时对该类所有方法生效(默认仅拦截 public 方法,可用配置项 skrstop.annotation.config 下的 allowedPublicOnly 调整,见 AnnotationProperties.java)。

6. 使用注意事项与最佳实践 ✅

  1. limit 要给余量:令牌桶是"匀速发放",突发流量会瞬间排队失败。若接口 P99 耗时较长,limit 建议参考单机实际吞吐的 70% 左右设置。
  2. @ServiceLock 的 lockId 要按业务隔离:不同业务务必使用不同 lockId,否则会互相阻塞;想让多个方法互斥(如"提交"和"取消"共享状态),则让它们使用相同的 lockId。
  3. 锁内方法尽量短:排队模式下,锁持有时间越长,后续请求等待越久,建议将耗时操作异步化。
  4. 单进程语义:默认的限流与锁都作用于当前 JVM 进程。集群多实例部署时,可通过实现 AccessLimitRule / ServiceLockRule 接入 Redis 等分布式方案,注解使用方式不变。
  5. 自定义提示文案:message 参数直接决定用户看到的文案,建议写得友好具体(如"验证码发送过快,请 60 秒后重试")。

7. 总结

skrstop-components 用两个注解就把「接口限流」和「并发互斥」这两件高频痛点覆盖了:

  • @AccessLimit(limit = x):令牌桶限流,超限秒拒,保护接口不被打爆;
  • @ServiceLock(lockId = "..."):公平可重入锁,支持排队与快速失败两种模式,杜绝重复提交;
  • 两者均预留 AccessLimitRule / ServiceLockRule 扩展点,可平滑演进到 Redis 集群限流、分布式锁等方案;
  • 配合项目的通用响应、通用异常体系,异常信息会自动以标准结构返回给前端。

一行注解,接口从此"身披铠甲"。如果你正在寻找 SpringBoot 限流方案或方法级并发锁教程,这套开箱即用的组合值得一试。

登录后查看全文
skrstop-components