[上一篇](https://cloud.tencent.com/developer/article/2751717)把接口治理做成了「一个切面 + 两条过滤器链」，开头立了个 flag：**一切皆插件**。实现一个 `PreFilter` / `PostFilter` 注册成 Bean 就自动入链。

先交代一个背景：这个 Starter 已经接进我自己维护的一个真实项目里跑了，下面这些"关"不是理论推演，是照着它踩出来的。

但「能写出一个能跑的过滤器」和「敢上生产的过滤器」之间差着好几道关。这篇把我自己踩过的地方整理成一份实战记录：先五分钟入门，再讲 `FilterContext` 到底给了你什么，最后写一个两个过滤器配合的生产级例子。

## 一、五分钟入门版

需求：所有接口的参数不能为 null（真实需求比这复杂，先简化）：

```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;
    }
}
```

`return false` 就是短路：后续前置过滤器不跑，业务方法不执行，调用方收到 400。就这么简单——但简单也意味着，**契约全靠自觉**。下面把它变生产级。

## 二、FilterContext 能力清单：管道里流通的唯一数据载体

自定义过滤器能做什么、不能做什么，全看 `FilterContext` 给了什么。它按功能分成六组：

| 分组 | 方法 | 说明 |
|------|------|------|
| **基础信息** | `getApiKey()` / `getMethod()` / `getTargetClass()` / `getArgs()` | API 标识（`全限定类名#方法名`）、反射 Method、目标类、入参数组 |
| | `getHttpMethod()` / `getRequestUri()` / `getPath()` / `getClientIp()` | 真实 HTTP 信息：URI 含路径变量实际值，IP 按 `X-Forwarded-For` → `X-Real-IP` → `remoteAddr` 解析 |
| | `getElapsedTime()` | 从上下文创建到当前时刻的耗时（毫秒），后置过滤器用它做性能记录 |
| **限流配置** | `getRateLimit()` / `getWindow()` / `setRateLimit()` 等 | `@RateLimit` 解析结果，前置链在（100）~（200）之间消费 |
| **日志开关** | `isLogEnabled()` / `setLogEnabled()` | `@NoLog` 的运行时形态，你的过滤器也能尊重它 |
| **拒绝信息** | `setRejected()` / `setRejectStatus()` / `setRejectReason()` | 短路三件套：状态码默认 429，可改 400/403/503 |
| **结果与异常** | `getResult()` / `getError()` | 后置过滤器专用：业务返回值或异常，配合 `getElapsedTime()` 做审计 |
| **扩展属性** | `setAttribute()` / `getAttribute()` | 过滤器之间传数据的自由映射，本文第三节的例子就靠它 |

这张表背后有个设计决策值得注意：**上下文不区分读写角色**。前置过滤器能读 `args`，后置过滤器也能读；没有「前置只写、后置只读」的类型约束，靠的是 order 区间约定。这是取舍——类型安全换来的是简单，我选简单，因为管道总共就两条链。

## 三、生产级过滤器的四道关

### 第一道：顺序契约——你的过滤器插在哪

`Filter` 接口继承了 Spring 的 `Ordered`，内置过滤器占了这些号段，自定义过滤器要对号入座：

| 号段 | 归属 |
|------|------|
| 1 ~ 99 | 信息采集、元数据收集 |
| 100 ~ 199 | 流量统计 |
| 200 ~ 299 | 限流判断 |
| **300 ~ 399** | **参数校验等业务前置（自定义过滤器的自留地）** |
| 400 ~ 499 | 慢方法/指标统计 |
| 500+ | 日志记录（建议最后） |

选错号段是真实的 bug 来源：我见过把参数校验写在 `@Order(50)` 的——它跑在流量统计**之前**，被它拒绝的请求永远进不了统计，监控上的 QPS 看起来比实际低。**校验类放 300~399，别越界。**

另外两个 `Filter` 接口自带的方法，写生产级插件时都用得上：

- `getName()`：默认返回类名，会出现在过滤器链调试日志和管理接口的 `/filters` 端点里，给它一个人类可读的名字；
- `isEnabled()`：运行时开关，默认 `true`。需要灰度/秒级熔断自定义过滤器时，从配置中心读一个开关返回即可，不用改代码发版。

### 第二道：短路语义——后置链会知道吗

这是整个管道最容易被误解的行为，我第一次也没答对：**前置过滤器短路拒绝后，后置链不会执行**。

设计理由：后置链的职责是「处理业务结果」（耗时统计、日志记录），被拒绝的请求没有业务结果，让它跑一遍没有意义，还省了一次无谓的开销。上一篇说的「拒绝请求不污染耗时指标」，根源就在这里。

对你的设计意味着两件事：

1. **别把「无论成败都要执行」的逻辑放进 `PostFilter`**——被拒绝的请求走不到那里。这类清理逻辑要么放业务层 `finally`，要么想想它是不是真的属于这条管道；
2. **`PostFilter.doFilter` 返回 `void`**，你没有拒绝权。业务已经执行完了，此时说什么都晚了——想要「对返回值不满意就拒绝」的能力，那是前置过滤器的活（提前校验），不是后置的。

### 第三道：异常隔离——谁给你的错误兜底

内置链对过滤器抛出的异常有兜底：前置过滤器抛异常按 500 处理、error 日志记录过滤器名和 API 标识，不会把异常原样炸给业务。但「不炸给业务」不等于「没发生」——你的过滤器每次请求抛异常，等于全站 500。

所以两条纪律：**过滤器里不做慢 IO**（通知器这类慢操作自行异步化）；**依赖的数据源挂了要降级**——比如你的黑名单在 Redis 里，Redis 超时时应该放行并记 warn，而不是把异常抛上去把 503 扫射全站。

还有一个埋在 `FilterContext` 里的陷阱要专门点名：`getJoinPoint()` 是公开的，**但你永远不要在过滤器里调 `proceed()`**。整个管道的契约建立在「proceed 有且仅有一次，由切面调用」上，过滤器碰了它，执行模型直接崩塌。切面作者把它暴露给你是给你读元数据的，不是给你调的。

### 第四道：数据边界——你能看到一切，所以要克制

`getArgs()` 给你的是**真实入参的引用**。这意味着两个红线：

1. **不要修改数组元素**。改了，业务方法收到的就是改过的——你不知不觉从「观察者」变成了「参与者」，这类 bug 排查起来极其痛苦；
2. **不要把 `args` 原样打日志**。手机号、身份证、token 就在入参里。治理框架默认不打印入参（`log-request-params` 默认 false）就是这个原因——你的自定义 Filter 继承同样的责任。

说到这儿，正好引出这篇的正餐：一个和「入参里有敏感数据」正面交手的例子。

## 四、正餐：两个过滤器配合的脱敏审计管道

**需求**：等保审计要求记录每个请求的完整入参，但日志里不能出现手机号和身份证号。

**为什么不能一个过滤器搞定**：脱敏不能改 `args`（第三道关的红线 1），审计日志又必须在业务执行后输出（不然没有完整的请求上下文）。所以拆成一对，用 `attributes` 传数据：

**过滤器 A（PreFilter，order=350）**：业务执行前，对入参做一份**深拷贝并脱敏**的快照，放进 `attributes`——不动原始入参一根汗毛：

```java
@Component
@Order(350)
public class SensitiveArgsSnapshotFilter implements PreFilter {

    private static final String KEY = "AUDIT_MASKED_ARGS";
    private static final Pattern PHONE = Pattern.compile("(1[3-9]\\d)\\d{4}(\\d{4})");
    private static final Pattern ID_CARD = Pattern.compile("(\\d{6})\\d{8}(\\w{4})");
    private static final ObjectMapper MAPPER = new ObjectMapper();
    @Override
    public boolean doFilter(FilterContext ctx) {
        if (ctx.getArgs() == null || ctx.getArgs().length == 0) {
            return true;
        }
        List<String> snapshot = new ArrayList<>();
       for (Object arg : ctx.getArgs()) {
            try {
                // JSON 序列化即天然深拷贝，改快照永不影响业务入参
                String json = MAPPER.writeValueAsString(arg);
                snapshot.add(PHONE.matcher(json).replaceAll("$1****$2")
                        .transform(s -> ID_CARD.matcher(s).replaceAll("$1********$3")));
            } catch (JsonProcessingException e) {
                snapshot.add(String.valueOf(arg));   // 不可序列化的参数降级为 toString
            }
        }
        ctx.setAttribute(KEY, snapshot);
        return true;
    }
}
```

**过滤器 B（PostFilter，order=600）**：业务执行后，从 `attributes` 取快照，连同结果元数据写成审计日志：

```java
@Component
@Order(600)
public class AuditLogFilter implements PostFilter {

    private static final Logger log = LoggerFactory.getLogger("AUDIT");

    @Override
    public void doFilter(FilterContext ctx) {
        List<String> maskedArgs = ctx.getAttribute("AUDIT_MASKED_ARGS",
                Collections.emptyList());
        log.info("api={} uri={} ip={} elapsed={}ms ok={} args={}",
                ctx.getApiKey(),
                ctx.getRequestUri(),
                ctx.getClientIp(),
                ctx.getElapsedTime(),
                ctx.getError() == null,
                maskedArgs);
    }
}
```

拆成两个的意义，恰恰是上一篇讲的管道语义在起作用：

- **A 在（350）短路时，B 自动不执行**——被参数校验拒绝的请求没有业务结果，本来就不该出现在审计里，管道结构替你保证了这件事，一行代码没写；
- **A 和 B 之间没有代码耦合**——它们唯一的约定是一个 attribute 键名。哪天审计要换存储（写 Kafka），只换 B；哪天脱敏规则要更新（多一类证件号），只换 A；
- **`clientIp` 打进审计日志没问题，但别拿它做安全决策**——它可能被 `X-Forwarded-For` 伪造，框架文档里也这么提醒。

三个注解、两个类、零框架改动，审计需求就接进来了——这就是「一切皆插件」的全部含义。

## 五、写在最后

把四道关压缩成一张自查清单，写完过滤器过一遍再上生产：

1. Order 对号入座了吗？（校验 300~399，日志类 500+）
2. 有没有在 `PostFilter` 里放「短路时也要执行」的逻辑？
3. 慢 IO 异步化了吗？数据源挂了是降级还是抛异常？
4. 有没有碰 `proceed()`？有没有改 `getArgs()` 里的元素？日志里有没有裸奔的敏感字段？

完整代码和文档：👉 **https://github.com/BIGLV666/api-governance-spring-boot-starter**

评论区聊聊：你的项目里有哪些逻辑现在长在切面里、其实更适合做成管道插件？下一篇打算拆**限流键解析器（RateLimitKeyResolver）**——按用户、按 IP、按租户限流的那套玩法，关注不迷路。

---

上一篇把接口治理做成了「一个切面 + 两条过滤器链」，开头立了个 flag：一切皆插件。实现一个 PreFilter / PostFilter 注册成 Bean 就自动入链。

「一切皆插件」不是口号：手写一个敢上生产的治理管道过滤器

编程语言

开发工具

后端

一个Spring Boot Starter实战指南，通过“一个切面+两条过滤器链”实现接口治理。文章深入解析FilterContext六大功能，揭示生产级过滤器四道关键关：顺序契约、短路语义、异常隔离、数据边界。通过脱敏审计管道实例，展示如何用两个过滤器协作实现敏感数据保护，附完整代码和自查清单。

代码解释

敏感数据

Redis

Kafka

JSON

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

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

「一切皆插件」不是口号：手写一个敢上生产的治理管道过滤器-腾讯云开发者社区-腾讯云

「一切皆插件」不是口号：手写一个敢上生产的治理管道过滤器

「一切皆插件」不是口号：手写一个敢上生产的治理管道过滤器

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐