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

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

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

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

一、五分钟入门版

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

@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 给了什么。它按功能分成六组：

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

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

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

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

选错号段是真实的 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——不动原始入参一根汗毛：

@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 取快照，连同结果元数据写成审计日志：

@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、按租户限流的那套玩法，关注不迷路。