如何构建统一API授权中间件

构建统一API授权中间件，听上去像是个纯技术命题，但真正落地时你会发现，它其实是在跟整个团队的开发习惯“较劲”。很多项目早期为了快速上线，授权逻辑散布在各业务控制器里：订单模块自己写一段if判断，用户模块再写一段角色校验，到了数据导出接口又重复造轮子。这种拼凑式的做法，到了系统复杂起来之后，维护成本会直线上升，而且很难保证一致性——比如订单详情接口校验了租户，但列表导出接口忘了加，越权就出现了。

为什么非要“统一”不可？

授权检查的分散，本质上是把安全决策的责任压在了每个开发人员的肩膀上。而人总会疲劳、会遗忘、会在赶工期时忽略边界。统一中间件的核心价值，不是重新发明一套权限模型，而是把“在什么条件下允许操作”这个规则集中管理。这样当业务调整安全策略时，只需要改动中间件代码，不需要去翻几十个API文件。

有人觉得把所有的权限校验逻辑都塞进一个Filter或Middleware就万事大吉。但实际上，统一不等于大泥球。下面几个问题会让你付出的努力白费：

• 粒度不匹配：中间件只检查了“是否登录”和“角色是否匹配”，但没处理对象归属。比如一个中间件验证了JWT，却对DELETE /api/projects/123不做归属判断，这等于没做。
• 上下文获取乱：授权中间件需要知道当前用户、当前资源ID、当前租户。如果这些参数来自请求Body、URL路径、Header甚至Cookie，且格式不统一，中间件就得写一堆解析逻辑，反而比分散更复杂。
• 忽视异常路径：批量操作接口、异步回调、GraphQL查询往往不走常规路由，统一中间件可能覆盖不到。需要预留扩展点，让非标准接口也能利用同一套规则。

落地方案：从三层结构开始

一个成熟的统一授权中间件，建议拆成三个层次：

这一层不做授权判断，只负责把请求转化为标准上下文：解析Token、提取用户ID、角色、租户ID，并填充到当前请求的Context或ThreadLocal中。要禁止业务代码再自行解析Header或Token。

用声明式的方式描述每个API的资源类型（例如Order、Project）、操作（读、写、删、导出）以及授权规则。规则可以是表达式（如resource.ownerId == currentUser.id || hasRole('admin')），也可以是调用外部权限服务。把所有规则放在一个集中存储（数据库、配置文件或代码注册中心），避免硬编码。

中间件在请求到达控制器之前，从上下文拿到资源类型和操作，然后加载对应的策略进行校验。校验失败直接返回403或404（推荐404以隐藏资源存在性）。同时要在执行前后记录日志：请求者、请求资源、操作、结果。日志可以用于后续的自动化测试验证——把历史请求回放一遍，看授权逻辑是否覆盖了所有场景。

工程中容易忽略的两个点

• 资源ID的获取方式要统一：如果有的接口把订单ID放在路径参数/api/orders/{id}，有的放在查询参数?orderId=123，中间件要能自动识别。最好的做法是约定所有敏感资源ID都通过路径占位符传递，并且中间件能识别占位符含义。
• 覆盖非CRUD操作：比如“提交审核”、“撤回”、“重新分配”，这些操作本质上是修改资源状态，但也需要对象级授权。不要只盯着增删改查，要把业务动词也纳入策略。

说了这么多，其实构建统一授权中间件的难点不在于技术，而在于团队能否达成一致：是否愿意把路由定义、资源标识、上下文提取规范统一起来。技术方案本身不复杂，复杂的是让这套机制成为所有开发人员写代码前的默认假设。