一个注解保护你的接口:skrstop-components @AccessLimit限流与@ServiceLock并发锁完全教程
一个注解保护你的接口: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 的核心逻辑:
- 以
lockId(未指定时用方法签名 MD5)为 key,在ConcurrentHashMap中维护一把ReentrantLock(true)公平可重入锁; - 先
tryLock(timeoutMs)尝试获取锁——拿到立即执行方法,执行完finally中释放; fastFail = true且抢锁失败 → 抛出 BUSY 业务异常,接口秒拒;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. 使用注意事项与最佳实践 ✅
limit要给余量:令牌桶是"匀速发放",突发流量会瞬间排队失败。若接口 P99 耗时较长,limit建议参考单机实际吞吐的 70% 左右设置。@ServiceLock的lockId要按业务隔离:不同业务务必使用不同lockId,否则会互相阻塞;想让多个方法互斥(如"提交"和"取消"共享状态),则让它们使用相同的lockId。- 锁内方法尽量短:排队模式下,锁持有时间越长,后续请求等待越久,建议将耗时操作异步化。
- 单进程语义:默认的限流与锁都作用于当前 JVM 进程。集群多实例部署时,可通过实现
AccessLimitRule/ServiceLockRule接入 Redis 等分布式方案,注解使用方式不变。 - 自定义提示文案:
message参数直接决定用户看到的文案,建议写得友好具体(如"验证码发送过快,请 60 秒后重试")。
7. 总结
skrstop-components 用两个注解就把「接口限流」和「并发互斥」这两件高频痛点覆盖了:
@AccessLimit(limit = x):令牌桶限流,超限秒拒,保护接口不被打爆;@ServiceLock(lockId = "..."):公平可重入锁,支持排队与快速失败两种模式,杜绝重复提交;- 两者均预留
AccessLimitRule/ServiceLockRule扩展点,可平滑演进到 Redis 集群限流、分布式锁等方案; - 配合项目的通用响应、通用异常体系,异常信息会自动以标准结构返回给前端。
一行注解,接口从此"身披铠甲"。如果你正在寻找 SpringBoot 限流方案或方法级并发锁教程,这套开箱即用的组合值得一试。