服务治理组件：统一白名单控制
一、背景与问题
在微服务架构下，白名单控制几乎是必需能力：
- 接口级访问控制（IP / 应用 / 用户）
- 灰度、内测、运营活动限制
- 风控与安全兜底
- 临时封禁、应急止血
但现实中常见问题是：
- 白名单逻辑散落在各个服务、Controller、网关
- 配置方式不统一（DB / Redis / Nacos / 配置文件）
- 修改不实时，需要发版
- 没有审计、没有版本
👉 结论：必须抽成一个统一的服务治理组件。
二、设计目标
| 目标 | 说明 |
|---|---|
| 统一入口 | 所有白名单能力一个组件解决 |
| 动态生效 | 修改配置秒级生效 |
| 多维度 | 支持 IP / 用户 / 应用 / Token |
| 低侵入 | 一个注解即可接入 |
| 高性能 | 高 QPS 场景无感知 |
| 可审计 | 操作可追溯 |
三、整体架构
┌──────────────┐ │ 管理后台 │ └──────┬───────┘ │ ┌──────▼───────┐ │ 配置中心 │ (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;- 启动加载
- 监听变更
- 原子替换
九、高并发优化点
| 点 | 方案 |
|---|---|
| 读取 | 纯内存 |
| 锁 | 无锁设计 |
| 热点 | 本地缓存 |
| 性能 | 单次判断 < 0.1ms |
👉2W+ QPS 无压力
十、网关层 vs 服务层
10.1 网关层
- IP 黑白名单
- 全局流量挡板
10.2 服务层（推荐）
- 业务语义清晰
- 可精细到方法级
- 不依赖网关
👉最佳实践：两层都要
十一、审计与治理
- 操作人
- 操作时间
- 变更前 / 后
- 变更原因
建议独立表：whitelist_audit_log
十二、常见坑
- 白名单写死在代码里 ❌
- 修改必须发版 ❌
- DB 实时查 ❌
- 无兜底开关 ❌
十三、总结一句话
统一白名单治理 = 注解 + AOP + 策略模式 + 本地缓存 + 配置中心
