统一白名单服务治理组件

服务治理组件：统一白名单控制

一、背景与问题

在微服务架构下，白名单控制几乎是必需能力：

• 接口级访问控制（IP / 应用 / 用户）
• 灰度、内测、运营活动限制
• 风控与安全兜底
• 临时封禁、应急止血

但现实中常见问题是：

• 白名单逻辑散落在各个服务、Controller、网关
• 配置方式不统一（DB / Redis / Nacos / 配置文件）
• 修改不实时，需要发版
• 没有审计、没有版本

👉 结论：必须抽成一个统一的服务治理组件。

二、设计目标

三、整体架构

┌──────────────┐ │ 管理后台 │ └──────┬───────┘ │ ┌──────▼───────┐ │ 配置中心 │ (Nacos / Apollo) └──────┬───────┘ │ 推送 ┌─────────▼─────────┐ │ 白名单治理组件 │ │ (Starter) │ └──────┬───────┬───┘ │ │ ┌──────▼───┐ ┌─▼────────┐ │ Gateway │ │ 业务服务 │ └──────────┘ └──────────┘

四、白名单模型设计

4.1 核心数据结构

publicclassWhiteListRule{privateStringbizCode;// 业务标识privateRuleTyperuleType;// IP / USER / APPprivateSet<String>values;// 白名单值privatebooleanenabled;}

publicenumRuleType{IP,USER_ID,APP_ID}

五、组件使用方式（重点）

5.1 注解定义

@Target({ElementType.METHOD,ElementType.TYPE})@Retention(RetentionPolicy.RUNTIME)public@interfaceWhiteList{StringbizCode();booleanenabled()defaulttrue;}

5.2 使用示例

@WhiteList(bizCode="ORDER_CREATE")@PostMapping("/order/create")publicOrderDTOcreateOrder(){returnorderService.create();}

⚠️Controller / Service 都可用，低侵入

六、核心拦截逻辑

6.1 AOP 拦截

@Around("@annotation(whiteList)")publicObjectaround(ProceedingJoinPointpjp,WhiteListwhiteList)throwsThrowable{WhiteListRulerule=whiteListManager.getRule(whiteList.bizCode());if(rule==null||!rule.isEnabled()){returnpjp.proceed();}booleanpass=ruleMatcher.match(rule);if(!pass){thrownewBizException("无白名单权限");}returnpjp.proceed();}

七、匹配策略设计

7.1 策略接口

publicinterfaceWhiteListMatchStrategy{booleanmatch(WhiteListRulerule);}

7.2 IP 示例

publicclassIpMatchStrategyimplementsWhiteListMatchStrategy{@Overridepublicbooleanmatch(WhiteListRulerule){Stringip=RequestContext.getClientIp();returnrule.getValues().contains(ip);}}

👉典型策略模式

八、配置动态更新

8.1 配置中心

• Nacos / Apollo
• JSON 结构存储
• 支持推送

{"ORDER_CREATE":{"ruleType":"IP","values":["10.1.1.1","10.1.1.2"],"enabled":true}}

8.2 本地缓存

ConcurrentHashMap<String,WhiteListRule>LOCAL_CACHE;

• 启动加载
• 监听变更
• 原子替换

九、高并发优化点

👉2W+ QPS 无压力

十、网关层 vs 服务层

10.1 网关层

• IP 黑白名单
• 全局流量挡板

10.2 服务层（推荐）

• 业务语义清晰
• 可精细到方法级
• 不依赖网关

👉最佳实践：两层都要

十一、审计与治理

• 操作人
• 操作时间
• 变更前 / 后
• 变更原因

建议独立表：whitelist_audit_log

十二、常见坑

1. 白名单写死在代码里 ❌
2. 修改必须发版 ❌
3. DB 实时查 ❌
4. 无兜底开关 ❌

十三、总结一句话

统一白名单治理 = 注解 + AOP + 策略模式 + 本地缓存 + 配置中心