1. 项目概述：为什么我们需要一个内嵌的API防火墙？

如果你正在维护一个基于SpringBoot的微服务，或者一个单体应用，那么对API接口的安全防护一定是你绕不开的话题。传统的做法是什么？大概率是在网络边界部署一个WAF（Web应用防火墙），或者使用API网关自带的安全策略。这些方案当然有效，但它们通常意味着额外的硬件成本、复杂的网络配置，以及一个独立的、需要专门维护的管理系统。对于很多中小型项目、快速迭代的业务，或者对部署简洁性有极致要求的场景来说，这种“重量级”的防护显得有些“杀鸡用牛刀”。

这就是我决定动手自研一个“轻量级API防火墙”的初衷。它的核心目标非常明确：作为一个组件，直接内嵌到SpringBoot应用内部，与应用同生共死，不依赖任何外部服务或复杂配置。想象一下，你的应用就像一个自带免疫系统的生物体，而不是一个需要穿着厚重盔甲上战场的士兵。这个“免疫系统”能在请求抵达你的业务控制器（Controller）之前，就完成身份校验、流量整形、恶意攻击识别等基础防护工作。

更关键的是，它支持在线配置。这意味着你不需要为了修改一个IP黑名单或者调整某个限流阈值而重启整个JVM服务。在微服务架构下，频繁重启带来的服务抖动和用户体验下降是不可接受的。通过一个简单的管理端点（比如一个HTTP接口或集成到Actuator），运维人员或开发者可以实时地查看、更新防护规则，动态生效。这极大地提升了运维效率和系统的灵活性。

这个项目不是要替代专业的WAF，而是在特定场景下（如内部系统、对延迟敏感的服务、资源受限的环境）提供一个成本更低、耦合更紧、响应更快的安全解决方案。它处理的是应用层的逻辑安全，比如防刷、防重放、基础的数据格式校验等，是安全防御体系中贴近业务的那一层。

2. 核心设计思路与架构拆解

2.1 轻量级与内嵌式的实现哲学

“轻量级”和“内嵌式”是这个项目的灵魂，它们直接决定了技术选型和架构设计。

首先，“内嵌”意味着它必须是SpringBoot生态的原生公民。最自然的实现方式就是利用Spring的过滤器（Filter）或拦截器（Interceptor）。我选择了过滤器链（FilterChain）作为请求的第一道关卡。原因在于，过滤器的生命周期更早，在Spring MVC的DispatcherServlet接收到请求之前就能介入，可以拦截到更广泛的请求（包括静态资源，如果需要的话），并且其执行效率通常也更高。我们将防火墙逻辑包装成一个自定义的OncePerRequestFilter，确保在一次请求中只执行一次。

“轻量级”则体现在以下几个方面：

1. 无外部依赖：核心防护逻辑不强制依赖Redis、数据库等外部中间件。所有规则可以存储在内存中，并通过在线配置接口更新。当然，我们也提供了可扩展的接口，允许你将规则持久化到数据库或配置中心，但这不再是强制选项。
2. 功能聚焦：不做大而全的安全套件，而是聚焦于最常见的、最急需的几种API威胁。我们首批实现的功能模块包括：IP黑白名单、请求频率限流、SQL注入/XXS简单模式匹配、请求签名校验等。每个模块都是可插拔的，你可以通过配置决定启用哪些。
3. 性能开销最小化：所有匹配逻辑需要高效。例如，IP检查使用HashSet实现O(1)查找；正则表达式模式匹配进行预编译；限流算法在单机环境下选择高性能的**令牌桶（Token Bucket）或滑动窗口（Sliding Window）**算法，避免使用重量级的原子类操作造成瓶颈。

整个架构可以抽象为“可插拔的责任链”。一个HTTP请求进入防火墙过滤器后，会依次通过多个“处理器（Handler）”，如IP检查处理器、限流处理器、攻击检测处理器等。每个处理器独立负责一项安全检查，如果检查不通过，则直接中断链，返回错误响应；如果通过，则传递给下一个处理器。这种设计保证了功能模块的高内聚、低耦合，未来新增一个“JSON Schema校验处理器”也会非常容易。

2.2 在线配置的动态性考量

在线配置是提升运维体验的关键。我们需要解决两个核心问题：配置如何存储与变更如何生效。

对于存储，最简单的方式是使用一个内存中的ConcurrentHashMap来存放所有规则。但这样一旦应用重启，规则就丢失了。因此，我们设计了一个分层的配置源（Configuration Source）结构：

• 第一层：内存配置。最高优先级，存放当前生效的动态规则。
• 第二层：本地文件备份。当通过在线接口更新内存规则时，同步将规则快照写入一个本地配置文件（如YAML格式）。这样在应用冷启动时，可以从文件加载最后一次持久化的规则，避免“从零开始”。
• 第三层：默认应用配置。作为兜底，可以从application.yml中读取一些初始的、不常变更的规则。

为了实现动态生效，我们利用了观察者模式。每个规则管理器（如IpRuleManager、RateLimitRuleManager）都是一个被观察的主题（Subject）。当在线配置接口接收到更新请求时，它会解析新规则，并调用对应管理器的更新方法。管理器在更新完内存数据后，会通知所有注册的观察者（通常是具体的规则匹配器）。这里的关键是，规则匹配器内部持有的规则引用需要是线程安全且可见的。我采用了AtomicReference来包装规则对象，或者使用CopyOnWriteArrayList这类线程安全的集合。当规则更新时，直接替换AtomicReference中的引用，新的请求立刻就能使用新规则，而正在处理的请求仍使用旧规则引用，完美避免了并发修改异常。

在线配置接口本身通过一个独立的@RestController暴露，但必须施加严格的安全控制，例如通过Spring Security集成，只允许特定的管理角色访问，或者通过内网IP限制，避免成为新的攻击面。

3. 核心模块实现与实操要点

3.1 防火墙过滤器的骨架搭建

一切始于一个自定义的过滤器。这里我选择继承OncePerRequestFilter，它保证了在单个请求生命周期内过滤器逻辑只执行一次，避免了在Forward/Include等场景下的重复执行。

@Component @Order(Ordered.HIGHEST_PRECIPRIORITY) // 设置最高优先级，确保最先执行 public class ApiFirewallFilter extends OncePerRequestFilter { @Autowired private FirewallRuleChain ruleChain; // 规则责任链 @Autowired private FirewallConfig firewallConfig; // 全局配置 @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // 1. 检查是否启用防火墙 if (!firewallConfig.isEnabled()) { filterChain.doFilter(request, response); return; } // 2. 构建防火墙上下文，封装请求信息 FirewallContext context = new FirewallContext(request, response); // 3. 执行规则链检查 FirewallResult result = ruleChain.doFilter(context); // 4. 根据结果决定是放行还是拦截 if (result.isPass()) { // 放行，请求继续向下传递（到达DispatcherServlet） filterChain.doFilter(request, response); } else { // 拦截，直接使用Response返回错误信息 response.setStatus(result.getBlockHttpStatus()); response.setContentType("application/json;charset=UTF-8"); response.getWriter().write(result.getBlockMessage()); // 注意：这里不能调用filterChain.doFilter，否则会继续处理 } } }

关键点解析：

• @Order(Ordered.HIGHEST_PRECIPRIORITY)：这个注解至关重要。它确保了我们的防火墙过滤器在Spring Boot应用中注册的所有过滤器里最先执行。安全检查必须在任何业务逻辑（包括Session处理、权限认证）之前进行，这样才能有效拦截最原始的恶意请求。
• FirewallContext：这是一个包装类，它封装了HttpServletRequest和HttpServletResponse，并可能附加一些解析后的信息，如请求体（Body）的字符串（注意，读取Body后流会关闭，需要小心处理），或者从Header中提取的客户端标识。它为后续的规则处理器提供了统一的上下文数据。
• FirewallResult：一个标准的结果对象，包含是否通过（isPass）、拦截时的HTTP状态码和提示信息。这有利于标准化输出，也便于后续扩展审计日志。

注意：关于读取Request Body的坑在过滤器中读取HttpServletRequest的InputStream获取请求体后，这个流就被消费了。如果后续的过滤器或Controller还需要读取Body，就会报错。常见的解决方案是使用ContentCachingRequestWrapper对原Request进行包装。但需要注意，它默认只缓存小于一定阈值（如2KB）的Body。对于大请求体，需要自定义Wrapper或采用其他策略。在我们的防火墙场景下，如果规则检查不需要分析Body（如仅做IP限流），则应避免读取，以提升性能。如果必须读取（如检查JSON参数），则一定要使用Wrapper，并在规则链执行完毕后，将包装后的Request对象传递给filterChain.doFilter。

3.2 规则责任链的设计与实现

责任链模式是这里的设计核心。我们定义一个RuleHandler接口和一条RuleChain。

public interface RuleHandler { /** * 处理防火墙规则 * @param context 防火墙上下文 * @return 处理结果，如果结果为不通过，则链终止 */ FirewallResult handle(FirewallContext context); } @Component public class FirewallRuleChain { @Autowired private List<RuleHandler> handlers; // Spring会自动注入所有实现RuleHandler的Bean public FirewallResult doFilter(FirewallContext context) { for (RuleHandler handler : handlers) { FirewallResult result = handler.handle(context); if (!result.isPass()) { // 任何一个处理器拦截，立即返回拦截结果 return result; } } return FirewallResult.pass(); // 全部通过 } }

然后，我们实现具体的处理器，例如IP黑白名单处理器：

@Component @Order(1) // 定义处理器执行顺序，IP检查通常在最前面 public class IpBlackWhiteListHandler implements RuleHandler { private final AtomicReference<IpRuleSet> ruleSetRef = new AtomicReference<>(); @PostConstruct public void init() { // 初始化时从配置文件加载默认规则 ruleSetRef.set(loadRulesFromConfig()); } @Override public FirewallResult handle(FirewallContext context) { String clientIp = context.getClientIp(); // 需要从request中正确获取IP（考虑代理） IpRuleSet currentRuleSet = ruleSetRef.get(); // 检查白名单（如果启用且非空） if (currentRuleSet.isWhiteListEnabled() && !currentRuleSet.getWhiteList().isEmpty()) { if (!currentRuleSet.getWhiteList().contains(clientIp)) { return FirewallResult.block("IP not in whitelist", HttpStatus.FORBIDDEN.value()); } // 在白名单中，直接放行，无需检查黑名单 return FirewallResult.pass(); } // 检查黑名单 if (currentRuleSet.getBlackList().contains(clientIp)) { return FirewallResult.block("IP is in blacklist", HttpStatus.FORBIDDEN.value()); } return FirewallResult.pass(); } // 供在线配置接口调用的更新方法 public void updateRuleSet(IpRuleSet newRuleSet) { this.ruleSetRef.set(newRuleSet); // 可以在这里触发持久化到本地文件 persistToLocalFile(newRuleSet); } }

实操心得：获取真实客户端IP这是一个非常容易出错的地方。在真实的网络环境中，请求可能经过Nginx、HAProxy、CDN等多层代理。request.getRemoteAddr()拿到的是最后一层代理的IP，而非用户真实IP。正确的做法是依次检查以下HTTP头：X-Forwarded-For,X-Real-IP,Proxy-Client-IP,WL-Proxy-Client-IP。通常，X-Forwarded-For的第一个IP（当有多个时）是原始客户端IP。你需要一个可靠的工具方法来提取它，并且在网关/代理层确保这些头信息被正确设置和信任。

3.3 单机限流器的算法选择与实现

限流是API防火墙的另一个核心功能。单机限流意味着我们不需要依赖Redis等分布式组件，算法和数据都存储在JVM内存中。这要求算法既要准确，又要高效。

令牌桶算法 vs. 滑动窗口算法

• 令牌桶（Token Bucket）：一个固定容量的桶，以恒定速率放入令牌。请求到来时取走令牌，取到则通过，否则被限流。优点是允许一定程度的突发流量（桶内有令牌时），平滑度高。
• 滑动窗口（Sliding Window）：将时间线划分为多个小格子（窗口），统计最近N个格子内的请求数。相比固定窗口，能更好地应对窗口边界处的流量突增，更精确，但内存占用稍高。

对于API限流这种需要精确控制“每秒多少次”的场景，我更喜欢使用滑动窗口算法。这里我们实现一个基于ConcurrentHashMap和AtomicLong的简易滑动窗口。

@Component public class RateLimitHandler implements RuleHandler { // Key: 限流键（如“用户ID:接口路径”）， Value: 滑动窗口计数器 private final ConcurrentHashMap<String, SlidingWindowCounter> counters = new ConcurrentHashMap<>(); @Override public FirewallResult handle(FirewallContext context) { // 1. 根据规则判断该请求是否需要限流，并获取限流Key和阈值 RateLimitRule rule = matchRule(context); if (rule == null) { return FirewallResult.pass(); // 无匹配规则，不限流 } String key = buildKey(context, rule); // 例如 “192.168.1.1:/api/v1/user” int limit = rule.getLimit(); // 例如 100 int windowSizeInSeconds = rule.getWindow(); // 例如 60秒 // 2. 获取或创建计数器 SlidingWindowCounter counter = counters.computeIfAbsent(key, k -> new SlidingWindowCounter(windowSizeInSeconds)); // 3. 尝试增加计数并检查 if (counter.tryIncrementAndCheck(limit)) { return FirewallResult.pass(); } else { return FirewallResult.block("Rate limit exceeded", HttpStatus.TOO_MANY_REQUESTS.value()); } } // 滑动窗口计数器内部类 private static class SlidingWindowCounter { private final int windowSize; // 窗口大小（秒） private final AtomicLong[] slots; // 时间槽数组 private final AtomicLong lastRotateTime = new AtomicLong(System.currentTimeMillis()); private volatile int currentIndex = 0; public SlidingWindowCounter(int windowSize) { this.windowSize = windowSize; this.slots = new AtomicLong[windowSize]; // 每秒一个槽 for (int i = 0; i < windowSize; i++) { slots[i] = new AtomicLong(0); } } public synchronized boolean tryIncrementAndCheck(long limit) { rotateIfNeeded(); // 检查并滑动窗口 long total = 0; for (AtomicLong slot : slots) { total += slot.get(); } if (total >= limit) { return false; } // 总数未超限，增加当前秒的计数 slots[currentIndex].incrementAndGet(); return true; } private void rotateIfNeeded() { long now = System.currentTimeMillis(); long last = lastRotateTime.get(); int secondsPassed = (int) ((now - last) / 1000); if (secondsPassed > 0) { // 需要滑动窗口 synchronized (this) { // 再次检查，防止并发问题 long currentLast = lastRotateTime.get(); int secs = (int) ((now - currentLast) / 1000); if (secs > 0) { int steps = Math.min(secs, windowSize); for (int i = 1; i <= steps; i++) { int indexToClear = (currentIndex + i) % windowSize; slots[indexToClear].set(0); // 清空过期的槽 } currentIndex = (currentIndex + steps) % windowSize; lastRotateTime.set(now); } } } } } }

性能与内存考量：这个实现为了清晰展示了滑动窗口的原理，但在高并发下，synchronized关键字和遍历整个数组求和可能会成为瓶颈。生产环境可以考虑更优化的数据结构，比如使用LongAdder替代AtomicLong来减少CAS竞争，或者使用环形队列。同时，ConcurrentHashMap中的计数器对象不会自动清理，长期运行可能导致内存泄漏（Key过多）。需要配套一个后台任务，定期清理长时间没有活动的Key（例如最近30分钟无请求）。

3.4 基础攻击检测：正则匹配的陷阱与优化

防御SQL注入和XSS攻击是Web安全的基础。一种简单的方法是使用正则表达式对请求参数（QueryString, Body）进行模式匹配。但这里坑非常多。

首先，不要试图写出匹配所有攻击的正则表达式，这是不可能的，且极易误伤正常请求。我们应该采用“负面清单”策略，只匹配那些极大概率是恶意攻击的、在正常业务参数中几乎不可能出现的字符序列。例如，匹配union select、sleep(、<script>、javascript:等关键字片段。

@Component public class SimpleInjectionDetectionHandler implements RuleHandler { private List<Pattern> maliciousPatterns; @PostConstruct public void init() { // 初始化预编译的正则表达式，避免在请求处理中重复编译 maliciousPatterns = new ArrayList<>(); maliciousPatterns.add(Pattern.compile("(?i)(union\\s+select|sleep\\s*\\(|drop\\s+table)")); maliciousPatterns.add(Pattern.compile("<script[^>]*>.*?</script>", Pattern.CASE_INSENSITIVE | Pattern.DOTALL)); // ... 添加其他简单规则 } @Override public FirewallResult handle(FirewallContext context) { // 检查URL参数 String queryString = context.getRequest().getQueryString(); if (queryString != null && containsMaliciousPattern(queryString)) { return FirewallResult.block("Malicious pattern detected in query", HttpStatus.BAD_REQUEST.value()); } // 检查POST Body (需要确保Body可重复读) String body = context.getCachedBody(); if (body != null && containsMaliciousPattern(body)) { return FirewallResult.block("Malicious pattern detected in body", HttpStatus.BAD_REQUEST.value()); } // 检查Header (某些攻击可能藏在Header里) Enumeration<String> headerNames = context.getRequest().getHeaderNames(); while (headerNames.hasMoreElements()) { String headerName = headerNames.nextElement(); String headerValue = context.getRequest().getHeader(headerName); if (containsMaliciousPattern(headerValue)) { return FirewallResult.block("Malicious pattern detected in header: " + headerName, HttpStatus.BAD_REQUEST.value()); } } return FirewallResult.pass(); } private boolean containsMaliciousPattern(String input) { if (input == null || input.isEmpty()) { return false; } for (Pattern pattern : maliciousPatterns) { if (pattern.matcher(input).find()) { // 使用find()而不是matches() return true; } } return false; } }

重要警告与优化建议：

1. 性能：正则匹配非常消耗CPU。一定要在初始化时预编译（Pattern.compile）好所有正则表达式，避免在每次请求处理时编译。
2. 误报：这是最大的问题。比如，一个博客系统允许用户输入代码片段，里面很可能包含<script>字样。粗暴的拦截会严重影响业务。因此，这个模块默认应该是关闭的，或者仅用于对输入格式有严格约束的接口（如纯数字ID查询）。更安全的做法是依赖参数化查询（防SQL注入）和输出编码（防XSS），而非请求过滤。
3. 局限性：这种方式只能防御最“懒”的攻击者。稍微编码一下（如%3Cscript%3E）就能绕过。因此，它绝不能作为唯一的安全防线，只能作为一个补充的、初步的过滤层。

4. 在线配置管理与动态生效

4.1 配置接口的设计与安全

在线配置需要一个独立的、受保护的HTTP端点。我们创建一个FirewallAdminController。

@RestController @RequestMapping("/api/firewall/admin") @ConditionalOnProperty(name = "firewall.admin.enabled", havingValue = "true") // 可通过配置完全关闭管理端点 public class FirewallAdminController { @Autowired private IpBlackWhiteListHandler ipHandler; @Autowired private RateLimitRuleManager rateLimitManager; // ... 注入其他规则管理器 @PostMapping("/ip-rules") public ResponseEntity<String> updateIpRules(@RequestBody @Valid IpRuleUpdateDto dto) { // 1. 权限校验（集成Spring Security或简单IP白名单） if (!hasAdminPermission()) { return ResponseEntity.status(HttpStatus.FORBIDDEN).body("Access denied"); } // 2. 业务校验 if (dto.getBlackList().size() > 1000) { // 示例：限制黑名单大小 return ResponseEntity.badRequest().body("Blacklist size exceeds limit"); } // 3. 更新处理器中的规则 IpRuleSet newRuleSet = convertDtoToRuleSet(dto); ipHandler.updateRuleSet(newRuleSet); // 4. 返回成功 return ResponseEntity.ok("IP rules updated successfully"); } @GetMapping("/ip-rules") public ResponseEntity<IpRuleSet> getIpRules() { if (!hasAdminPermission()) { return ResponseEntity.status(HttpStatus.FORBIDDEN).build(); } IpRuleSet currentRuleSet = ipHandler.getCurrentRuleSet(); // 需要在Handler中暴露getter方法 return ResponseEntity.ok(currentRuleSet); } // 类似地，提供限流规则、攻击检测规则等的增删改查接口 @PostMapping("/rate-limit-rules") public ResponseEntity<String> updateRateLimitRules(@RequestBody List<RateLimitRuleDto> dtos) { // ... 校验逻辑 rateLimitManager.updateAllRules(dtos); return ResponseEntity.ok("Rate limit rules updated"); } private boolean hasAdminPermission() { // 简单实现：检查请求IP是否在管理白名单内（配置在application.yml） // 复杂实现：集成Spring Security，检查角色或权限 String clientIp = // ... 获取真实IP return adminIpWhitelist.contains(clientIp); } }

安全是重中之重：

• 必须禁用生产环境的管理端点，或者将其部署在严格的内网环境中。可以通过配置firewall.admin.enabled=false来彻底关闭。
• 至少实施IP白名单限制。管理接口绝不允许公网任意访问。
• 考虑添加二次认证，比如一个动态令牌或简单的API Key。
• 所有操作必须记录审计日志，谁在什么时间修改了什么规则。

4.2 配置的持久化与容灾

内存中的配置是易失的。我们采用“内存为主，文件备份”的策略。当通过管理接口更新规则时，除了更新内存中的AtomicReference，同时将完整的规则集序列化（如转为JSON）并写入应用工作目录下的一个文件，例如firewall-rules-backup.json。

@Service public class RulePersistenceService { @Value("${firewall.persistence.file-path:./config/firewall-rules.json}") private String backupFilePath; public void saveRulesToFile(FirewallAllRules allRules) throws IOException { ObjectMapper mapper = new ObjectMapper(); // Jackson mapper.enable(SerializationFeature.INDENT_OUTPUT); String json = mapper.writeValueAsString(allRules); Path path = Paths.get(backupFilePath); Files.createDirectories(path.getParent()); // 创建目录 Files.write(path, json.getBytes(StandardCharsets.UTF_8)); } public FirewallAllRules loadRulesFromFile() throws IOException { Path path = Paths.get(backupFilePath); if (!Files.exists(path)) { return null; } String json = new String(Files.readAllBytes(path), StandardCharsets.UTF_8); ObjectMapper mapper = new ObjectMapper(); return mapper.readValue(json, FirewallAllRules.class); } }

在应用启动时（@PostConstruct或实现ApplicationRunner），尝试从备份文件加载规则。如果文件存在且内容有效，则用其初始化各个规则处理器；如果不存在或损坏，则回退到application.yml中的默认配置。这样，即使应用重启，也能恢复到上一次手动配置的状态，实现了基本的容灾。

5. 集成、测试与生产部署要点

5.1 如何集成到你的SpringBoot项目

将这个自研防火墙集成到现有项目非常简单，因为它本身就是一个标准的Spring Boot Starter。

1. 打包为Starter：将上述所有核心类（过滤器、处理器、管理器、控制器）组织在一个独立的模块中，并创建META-INF/spring.factories文件，通过@Configuration类自动配置。这样，其他项目只需要引入这个Starter的依赖。
2. 引入依赖：在目标项目的pom.xml或build.gradle中添加对该Starter的依赖。
3. 基础配置：在application.yml中开启防火墙并设置一些基本参数。

# application.yml firewall: enabled: true admin: enabled: false # 生产环境建议关闭 ip-whitelist: 192.168.1.100,127.0.0.1 # 管理端IP白名单 default-block-message: "Request blocked by API Firewall" rules: ip: white-list-enabled: false black-list: - 10.0.0.100 - 192.168.34.1 rate-limit: enabled: true default-limit: 100 # 全局默认每秒100次 rules: - pattern: "/api/order/**" # 支持Ant风格路径 limit: 10 window: 60 - pattern: "/api/auth/login" limit: 5 window: 300

4. 自定义与扩展：如果你需要添加自定义的规则处理器，只需实现RuleHandler接口并加上@Component注解，它就会被自动加入到责任链中。你可以通过@Order注解控制其执行顺序。

5.2 测试策略：确保防护有效且无误报

测试是确保防火墙可靠性的关键。需要从两个维度进行：

1. 单元测试（Unit Test）：针对每个规则处理器进行独立测试。

• IpBlackWhiteListHandlerTest：模拟不同IP的请求，验证黑白名单逻辑是否正确。
• RateLimitHandlerTest：使用@SpringBootTest或模拟时间，在短时间内发送大量请求，验证限流是否精确触发。
• SimpleInjectionDetectionHandlerTest：提供包含恶意片段和正常片段的字符串，验证匹配的准确性和误报率。

2. 集成测试（Integration Test）：使用MockMvc或TestRestTemplate模拟完整的HTTP请求，测试过滤器链的整体行为。

• 测试一个被黑名单IP访问的接口，是否收到403状态码和正确的拦截信息。
• 测试快速连续调用一个限流接口，第N+1次请求是否收到429（Too Many Requests）状态码。
• 至关重要：准备一批正常的业务请求用例，确保防火墙不会拦截它们（零误报）。这包括各种复杂的查询参数、JSON请求体等。

5.3 生产环境部署的注意事项与监控

将自研组件部署到生产环境，需要格外小心。

1. 性能压测：使用JMeter或Gatling对开启了防火墙的应用进行压测，与关闭防火墙的情况进行对比。重点关注**平均响应时间（RT）和吞吐量（QPS）**的下降是否在可接受范围内（通常要求损耗<5%）。特别要关注正则匹配和限流计算密集型的处理器。
2. 灰度发布：首次上线时，可以先在application.yml中将firewall.enabled设为false。然后通过管理接口（确保安全），对单个或少数非核心服务节点动态开启防火墙，观察日志和监控指标，确认无误后再全量开启。
3. 详尽的日志：防火墙的拦截日志是排查问题的黄金信息。务必记录清晰的日志，包括：拦截时间、客户端IP、请求URL、拦截规则类型、匹配到的具体值等。建议使用MDC（Mapped Diagnostic Context）将请求ID贯穿到防火墙日志中，便于追踪。

   log.warn("[API-FIREWALL-BLOCK] ip={}, uri={}, ruleType=IP_BLACKLIST, matchValue={}, requestId={}", context.getClientIp(), context.getRequest().getRequestURI(), ip, requestId);

4. 监控与告警：将拦截日志接入ELK或类似日志平台，并设置关键告警。
   • 告警一：拦截频率异常升高。如果某个IP或某个接口突然被大量拦截，可能是遭受攻击，也可能是业务逻辑变更导致的误报，需要立即查看。
   • 告警二：管理接口被调用。任何对在线配置接口的调用都应产生日志告警，通知运维人员核查。
5. 规则维护：建立规则维护流程。禁止直接在生产环境盲目添加IP黑名单。应先分析日志，确认是攻击行为后，再通过管理接口添加。定期审计和清理过期的、无效的规则。

6. 常见问题排查与性能调优实录

在实际使用中，你可能会遇到以下典型问题：

问题1：防火墙拦截了正常的健康检查或监控请求。

• 排查：检查这些请求的来源IP（如K8s的Pod IP、云监控的IP）是否被误加入了黑名单，或者其请求频率是否触发了限流。
• 解决：将健康检查路径（如/actuator/health）和监控系统IP加入防火墙的白名单（或豁免列表）。可以在责任链最前面加一个WhitelistHandler，匹配特定路径直接放行。

问题2：应用响应时间明显变慢，CPU使用率升高。

• 排查：使用Arthas或Async-Profiler等工具进行线上诊断，查看CPU热点是否在防火墙的某个处理器上，特别是正则匹配或复杂的限流计算。
• 解决：
  • 优化正则：检查正则表达式是否过于复杂，尝试简化或禁用部分低效的规则。
  • 限流算法：如果滑动窗口计算开销大，可以切换到性能更好的令牌桶算法，或者使用Guava的RateLimiter（单机场景下非常高效）。
  • 采样检查：对于攻击检测这类高开销操作，可以改为采样执行，例如只对1%的请求进行全量正则匹配。

问题3：规则更新后，部分节点似乎没有立即生效。

• 排查：确认是否在多实例部署环境中。我们的防火墙是单机内嵌的，规则更新只对当前JVM实例生效。如果你有10个服务实例，通过负载均衡器调用管理接口，可能只更新到了其中一个实例。
• 解决：需要实现规则的“广播”机制。管理接口在接收到更新后，应通过消息队列（如Kafka）、配置中心（如Nacos、Apollo）或简单的HTTP调用，将新规则同步到所有其他实例。这超出了单机防火墙的范畴，属于分布式配置管理。

问题4：如何防御慢速攻击（Slowloris）或大请求体攻击？

• 分析：这类攻击在TCP/HTTP协议层消耗服务器连接资源，我们的应用层防火墙可能难以有效防御。因为恶意请求可能还没到达我们的过滤器，Tomcat的连接池就已经被耗尽了。
• 建议：对于这类网络层/传输层攻击，应在更前置的网络边界解决，如使用Nginx的client_max_body_size、client_body_timeout等指令，或者使用云服务商提供的DDoS防护。

性能调优小技巧：

• 懒加载与缓存：对于从数据库或远程配置中心加载的规则，使用缓存并设置合理的过期时间，避免每次请求都触发远程调用。
• 使用布隆过滤器（Bloom Filter）进行IP黑名单初步判断：如果IP黑名单非常大（例如上百万条），使用HashSet内存占用会很高。可以引入一个布隆过滤器进行快速预判。如果布隆过滤器说“不在集合中”，那一定不在；如果它说“可能在集合中”，则再去查精确的HashSet。这能在极小的误判率下，大幅减少内存占用和查询时间。
• 关闭不必要的处理器：通过配置精细控制每个接口（URL Pattern）启用的处理器。例如，对纯静态资源接口，可以关闭所有安全检测；对内部系统接口，只开启IP白名单。这能最大程度减少性能开销。