谈谈 HZero 微服务权限体系：一个 @Permission 注解的前世今生

一、 微服务下的权限难题

在传统的单体架构中，权限控制往往非常直接——写个拦截器或在 Spring Security 里配几条规则就行。但在包含几十上百个微服务的大型企业中台中：

• 接口成千上万，谁公开？谁需登录？谁必须具备特定角色？
  
• 新写了一个微服务上线，难道每次都要运维手动去改网关配置、重启网关吗？
  
• 业务开发如果还要在每个接口手写各种权限校验，代码侵入性太大。
  

HZero 是如何优雅解决这个问题的？答案就是：一个 @Permission 注解 + 一套自动化治理体系。

二、 四个“核心角色”

在探讨这个注解之前，我们需要先认识这套体系中的 4 位“关键成员”：

1. 业务微服务：接口的提供者（比如你的订单服务、用户服务）。
   
2. hzero-admin（平台治理中心）：微服务集群的**“总协调官”**，负责监控服务上下线、协调下发路由与权限。
   
3. hzero-iam（权限中心）：“户籍管理局”，负责记录所有的 API 接口、角色、菜单与权限关系（RBAC 核心）。
   
4. hzero-gateway（API 网关）：“大门保安”，所有外部请求的统一入口，负责根据规则进行安检与拦截。
   

三、 @Permission 注解的四种形态

你在 Controller 接口上打下的 @Permission，本质上是在给接口贴“访问策略标签”：

@Permission(level = ResourceLevel.SITE, permissionLogin = true)
@PostMapping("/v1/orders")
public ResponseEntity<?> createOrder() { ... }

这个标签主要告诉平台 4 件事：

• 公开接口（permissionPublic = true）：任何人（包括游客）都能调，免密免检（如验证码、公开注册）。
  
• 登录即可访问（permissionLogin = true）：只要登录拿到 Token 就能调，不需要中台分配角色（如查个人信息、修改密码）。
  
• 微服务内部专享（permissionWithin = true）：绝不对外，只能内网服务之间调（如 Feign），网关一律阻断外部访问。
  
• 默认受控接口（全为 false）：普通业务接口，必须在中台给角色分配了对应权限集后，才能访问。
  

四、 核心：一个新接口的“生命周期四步走”

从你在代码里敲下 @Permission，到线上用户成功调用，整个过程非常丝滑：

[开发阶段] 代码贴上 @Permission 标签，借助 Swagger 生成接口元数据
   │
   ▼
[上线阶段] 服务向注册中心注册，平台治理 (admin) 自动协调打通路由与接口入库
   │
   ▼
[编排阶段] 管理员在中台把接口挂到“权限集”，赋给角色
   │
   ▼
[运行阶段] 用户请求到达网关，网关流水线“读标签”逐级安检拦截

第一步：出生与建档（业务服务本地）

• 为什么这个注解在 swagger 包下？因为 HZero 巧妙复用了 Swagger 的扫描机制。
  
• 服务启动时，Swagger 会扫描所有接口；HZero 顺便把 @Permission 的信息打包成元数据，塞进了本服务的 API 文档中（/v2/choerodon/api-docs），完全没有增加多余的性能开销。
  

第二步：上线与通报（平台治理 admin 的协调艺术）

• 业务微服务启动并注册到注册中心（Nacos/Eureka）。
  
• hzero-admin（总协调官） 监测到有新服务上线，立刻发起一波“自动化协调三连击”：      

• 协调网关路由：解析该服务的路径规则（如 /order/**），写入 Redis 并通知网关：“有新路由来了，快更新！”（无需重启网关）。
  
• 协调接口入库：通知 hzero-iam 拉取该服务的 API 文档，把新接口的路径、方法、权限标签存入数据库（iam_permission 表），并写入 Redis 缓存。
  
• 协调文档聚合：将接口文档合并进全平台的 API 统一展示中心。
  

第三步：中台权限编排（给角色授权）

• 此时接口已经记录在案，但如果是受控接口，没有任何普通用户能访问它。
  
• 管理员登录 HZero 前端中台页面，做经典的 RBAC 授权：      

• 接口挂载：在【菜单管理】里，把新接口勾选绑定到某个权限集（按钮级权限）。
  
• 角色授权：把该权限集分配给指定的角色（如“订单管理员”）。
  
• 授权变更实时同步到 Redis 缓存。
  

第四步：运行时网关安检（逐层过滤）

用户在前端发起请求到达 hzero-gateway 网关，网关像安检通道一样逐层审查：

1. 查路由：根据 URL 找到目标微服务。
   
2. 读标签：根据接口的 URL + 请求方式，从 Redis 查出当初 @Permission 声明的标签：      

1. 标签是 within = true？直接 403 阻断！（内部接口禁止公网访问）。
   
2. 标签是 public = true？直接放行！（公开接口免密）。
   
3. 解析用户 Token，拿到用户身份；标签是 login = true？直接放行！
   

3. 查角色：对于普通的受控接口，查 Redis 判断当前用户的角色是否包含该权限：      

1. 包含 →\to→ 放行，转发给后端微服务执行。
   
2. 不包含 →\to→ 403 Forbidden 拦截，提示没有权限。
   

五、 架构设计的精妙思考

1. 零侵入与避免重复造轮子：借助已有 Swagger 的扫描插件机制提取权限元数据，业务开发只需要专注一个注解，不需要写任何拦截器。
   
2. 全自动热装配（控制面与数据面分离）：利用 hzero-admin 作为协调者，实现了微服务即插即用——服务上线后路由自动打通、权限自动收集，网关秒级热更新，彻底告别停机维护。
   
3. 安全前置，解耦业务：所有的鉴权逻辑全部被拦截在网关层，非法请求根本摸不到内网微服务，业务代码完全不用关心权限校验，保持了纯粹的业务逻辑。
   

本文章参考 Hzero 开源框架进行分享

Hzero 开源框架地址：https://github.com/open-hand/hzero