# 还在每个项目里复制粘贴接口日志切面？我把它做成了零配置的 Spring Boot Starter

> 前置链采集 → 限流 → 后置链统计，AOP 只 proceed 一次；本地/Redis 两种限流、令牌桶/滑动窗口两种算法、SpEL 按参数限流、钉钉/企微/飞书告警、Micrometer 指标桥接——引入一个依赖，什么都不配就生效。

## 一、从一个大家都写过的类说起

先看一段你大概率写过的代码：

```java
@Aspect
@Component
public class ApiLogAspect {
    @Around("execution(* com.example..controller..*(..))")
    public Object around(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            Object result = pjp.proceed();
            log.info("[API] {} 耗时 {}ms", pjp.getSignature(), System.currentTimeMillis() - start);
            return result;
        } catch (Throwable e) {
            log.error("[API] {} 失败", pjp.getSignature(), e);
            throw e;
        }
    }
}
```

每个项目都有一份，长得还不太一样：有的统计了耗时没统计成功率，有的日志打了但接口一多没法看，想限流的时候再加一个切面、想上报 Prometheus 再加一个——**切面越叠越多，`pjp.proceed()` 被调了四五次，出了问题没人说得清执行顺序**。

我更烦的是另一件事：换一家公司，这套东西要从零再写一遍。

所以我把这几年重复写的部分抽成了一个 Starter：**api-governance-spring-boot-starter**。这篇文章先给你 30 秒能跑起来的效果，然后重点讲它背后的设计取舍——尤其是分布式限流里那些文档不告诉你的坑。

## 二、30 秒上手：什么都不配就生效

引入依赖：

```xml
<dependency>
    <groupId>io.github.biglv666</groupId>
    <artifactId>api-governance-spring-boot-starter</artifactId>
    <version>0.5.0</version>
</dependency>
```

然后写一个普通的 Controller，**不加任何注解、不改任何代码**：

```java
@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User get(@PathVariable Long id) {
        return userService.findById(id);
    }
}
```

每个请求会自动输出：

```
[API] GET /api/users/{id} - com.x.UserController#get - 成功 - 耗时: 12ms
```

同时管理接口 `GET /api-governance/metrics` 已经能查到这个接口的调用次数、成功率、慢方法明细。想要限流、关闭某接口日志，也只加三个注解：

```java
@RateLimit(limit = 100)                 // 类级默认限流
@RateLimit(limit = 5, window = 60, key = "#request.username")  // 按参数独立配额
@NoLog                                  // 关日志，统计仍保留
@Skip                                   // 完全放行（健康检查之类）
```

到这里是"能用"。下面是这篇文章真正想聊的：它内部是怎么设计的，以及分布式限流这个看似简单的功能里藏了多少坑。

## 三、核心设计：切面只做一次，其余全是管道

多数"日志切面 + 限流切面 + 指标切面"的方案，本质是多个 AOP 切面叠在同一个方法上，执行顺序靠 `@Order` 猜。这个 Starter 的做法是**只有一个切面**，切面内部把一次请求的完整生命周期拆成两条过滤器链：

```
前置链：信息采集(1) → 流量统计(100) → 限流判断(200) → 自定义
                              ↓ 任一过滤器返回 false 即短路，业务方法不执行
业务方法（pjp.proceed() 有且仅有一次）
                              ↓
后置链：耗时统计(400) → 日志记录(500) → 自定义
```

这样带来三个直接好处：

1. **语义清晰**：限流发生在统计之前，被拒绝的请求不会污染耗时指标（Micrometer Timer 只记真正执行的请求）；
2. **可插拔**：实现一个 `PreFilter` / `PostFilter` Bean 就自动进管道，`@Order` 排序，返回 `false` 即短路拒绝（可以自定义 400/429/503）：

```java
@Component
@Order(300)
public class ParamCheckFilter implements PreFilter {
    @Override
    public boolean doFilter(FilterContext ctx) {
        if (ctx.getArgs() == null || ctx.getArgs().length == 0) {
            ctx.setRejectStatus(400);
            ctx.setRejectReason("参数缺失");
            return false;
        }
        return true;
    }
}
```

3. **内置过滤器可关可换**：5 个内置过滤器都能通过 `api.governance.filters.*` 开关，注册同类型 Bean 即覆盖，不用改源码。

自定义过滤器还能直接拿到真实请求上下文：`getRequestUri()`（路径变量实际值）、`getClientIp()`（`X-Forwarded-For` → `X-Real-IP` → `remoteAddr`），不用自己去解 `RequestContextHolder`。
![architecture.png](https://developer.qcloudimg.com/http-save/yehe-12788779/06488c3e20389bae683b1da2fdce5426.png)
## 四、分布式限流：三个文档不会告诉你的坑

本地限流没什么好讲的，`ConcurrentHashMap` + 惰性过期就够。有意思的是 Redis 分布式限流，我踩了三个坑。

### 坑一：窗口判定不能用客户端时间

滑动窗口最直觉的实现：Lua 脚本里用 `ARGV` 传入应用服务器的时间戳，`ZREMRANGEBYSCORE` 清理窗口外的 member，再 `ZCARD` 计数。

问题在于**多实例时钟漂移**：A 机器快 200ms，B 机器慢 200ms，同一时刻两台机器对"当前时间"的判断差了 400ms，窗口边界上的计数就不准了——而分布式限流恰恰是为了多实例一致才存在的，用客户端时间等于自废武功。

正确做法是在 Lua 脚本里用 `TIME` 命令取 **Redis 服务器时间**，窗口判定和令牌补充都基于它。但 `TIME` 是非确定性命令，Redis 4.x 及之前的逐字复制模式下，主从复制的是整段脚本而不是效果，从库重放时会产生不同的结果。

所以脚本开头必须显式调用：

```lua
redis.replicate_commands()  -- 切换为效果复制，Redis 3.2~4.x 可用
local t = redis.call('TIME')
local now = t[1] + t[2] / 1000000
```

Redis 5+ 默认就是效果复制，这个调用幂等无害。这一行，很多 Redisson 之外的手写限流实现都漏了。

### 坑二：同毫秒并发，ZSET 的 member 会互相覆盖

滑动窗口用 Sorted Set 计数时，member 得保证唯一。我最开始用「毫秒时间戳 + 线程 ID」，结果写测试时发现计数偏松——**同一毫秒内、线程池复用导致的同线程两次请求，member 完全相同，后一次 ZADD 把前一次覆盖了**。换成 UUID 才彻底消除。

### 坑三：Redis 挂了，限流器该放行还是拒绝？

这是个纯架构决策题，没有标准答案，但必须显式回答：

- `fail-open`（放行）：可用性优先，Redis 故障时退化为不限流，但业务不受影响；
- `fail-close`（拒绝）：配额优先，Redis 故障时全部返回 503——注意是 **503 而不是 429**，429 语义是"你请求太快"，503 语义是"我这边限流组件故障"，运维看监控能一眼区分，而不是把系统故障误判成用户刷接口。

无论哪种策略，故障都会触发 `RATE_LIMITER_FAILURE` 告警（可以直接推钉钉群）。

## 五、SpEL 按参数限流：好用，但有个安全边界你必须知道

`@RateLimit(key = "#id")` 一个注解就能按参数值独立配额：

```java
@GetMapping("/users/{id}")
@RateLimit(limit = 10, key = "#id")
public User get(@PathVariable Long id) { ... }
```

实现上用的是受限的 `SimpleEvaluationContext`：不允许类型引用、构造器调用和 Bean 引用，表达式解析失败自动回退接口级限流，只打 warn 不影响业务。这套防御是为了杜绝 SpEL 注入——`StandardEvaluationContext` 加上客户端可控输入，是可以直接打出 RCE 的。

但这里有一个更隐蔽的问题，值得单独说：**当表达式结果由客户端可控输入派生时（用户名、IP、任意 ID），每个新取值都从满配额开始**。攻击者只要遍历一万个不同的 `id`，就等于拥有一万个独立的 10 次配额。所以：

- 「按参数限流」的正确用途是**租户间公平性**（防止一个租户耗尽共享配额）；
- 它**不能**作为防爆破等安全边界使用；
- 防爆破场景应该叠加接口级总配额，或者实现 `RateLimitKeyResolver` Bean 组合 IP 等低基数维度。

另外高基数 key 还有内存风险，本机限流器的键数量上限（`max-entries`）就是为这个准备的，键超限会淘汰。

## 六、指标、告警、可观测性：治理不只是拦请求

- **Micrometer 桥接**：`api.governance.requests`（Counter，outcome 分 success/error/reject）、`api.governance.request.duration`（Timer）、`api.governance.apis.tracked`（Gauge）。`api` 标签是 `全限定类名#方法名`，基数上限就是 Controller 方法数，不会标签膨胀。容器里有 `MeterRegistry` 就自动注册，对接 Prometheus/Grafana 零配置。
- **告警**：慢方法 / 限流拒绝 / 限流器故障 / 异步任务被拒四类事件，内置 Webhook 通知器基于 JDK HttpClient（零第三方依赖），钉钉支持加签（HMAC-SHA256）。同一个 `(类型, apiKey)` 默认 10 秒内只发一次，防告警风暴把群刷爆。
- **内存指标防膨胀**：每个 API 的最近记录是有界滑动窗口（条数 + 时长双上限），全局 API 数量 LRU 淘汰。内存型指标组件不做这个，运行久了就是一个 OOM 定时炸弹。
- **异步钩子**（0.5.0）：`@AsyncAction` + `@AsyncHandler` 可以给任意 Spring Bean 方法挂四阶段旁路任务（写日志、发通知之类），带启动期校验——Handler 引用了不存在的 action 直接启动失败，拼写错误不再静默失效。

## 七、写在最后

完整代码和文档（中文注释、升级指南、最小可运行示例工程都在）：

👉 **https://github.com/BIGLV666/api-governance-spring-boot-starter**

Maven Central 可直接引入，坐标见文首。欢迎提 issue 和 PR。

最后留两个问题，评论区聊聊：

1. 你们线上的限流故障策略是 fail-open 还是 fail-close？有没有因为选错吃过亏？
2. 接口治理（日志/指标/限流）在你司是框架组统一做，还是每个业务组自己写切面？

下一篇计划拆 **SpEL 限流键的完整安全模型**（含一个可复现的绕过案例），感兴趣的关注一下不迷路。

---

前置链采集 → 限流 → 后置链统计，AOP 只 proceed 一次；本地/Redis 两种限流、令牌桶/滑动窗口两种算法、SpEL 按参数限流、钉钉/企微/飞书告警、Micrometer 指标桥接——引入一个依赖，什么都不配就生效。

一个注解不用写，给你的 Spring Boot 接口加上限流、日志、指标和钉钉告警

开发工具

后端

编程语言

api-governance-spring-boot-starter零配置接入SpringBoot，单AOP切面整合日志、限流与指标。支持Redis/本地限流、滑动窗口/令牌桶算法、SpEL参数限流，含钉钉/企微告警及Micrometer桥接。解决分布式限流时钟漂移、member覆盖、故障策略等痛点，引入即用。

代码解释

服务器

容器

Redis

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

一个注解不用写，给你的 Spring Boot 接口加上限流、日志、指标和钉钉告警-腾讯云开发者社区-腾讯云

一个注解不用写，给你的 Spring Boot 接口加上限流、日志、指标和钉钉告警

一个注解不用写，给你的 Spring Boot 接口加上限流、日志、指标和钉钉告警

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐