架构与系统设计 / 系统课时
功能授权校验
功能授权校验
本课实现一套可复用的功能授权校验:先读取租户当前生效的订阅,再判断目标功能是否包含在套餐权益中,并在接口入口与业务方法执行前统一拒绝未授权访问,避免只隐藏前端菜单却仍能调用后端能力。
学习目标
- 区分登录认证、角色权限与套餐功能授权
- 设计统一的功能编码和授权校验入口
- 在接口层与业务层形成双重保护
为什么需要独立的功能授权
用户已经登录,只能说明身份有效;拥有某个角色,只能说明组织内部允许操作;订阅功能授权回答的是“租户是否购买了这项能力”。三者解决的问题不同,不能用角色权限替代套餐校验。
例如,管理员角色可能有“导出报表”权限,但租户当前套餐不包含报表模块。此时前端应隐藏入口,后端也必须返回明确的未授权结果,不能依赖页面控制保证安全。
授权判定链路
一次功能访问通常经历“识别租户、读取有效订阅、解析套餐权益、判断功能编码、放行或拒绝”五步。授权结果可以缓存,但缓存键必须包含租户标识,订阅变更后还要主动失效。

功能编码应保持稳定,例如 REPORT_EXPORT、ADVANCED_AUDIT。不要直接使用菜单名称,因为菜单文案可能变化,而且同一功能可能被 API、定时任务和后台操作共同调用。
实现统一校验器
下面的完整 Java 示例用内存集合模拟套餐权益。真实项目中,可将 Subscription 替换为数据库查询或缓存结果,但校验器的调用方式保持不变。
import java.util.EnumSet;
import java.util.Set;
public class FeatureAuthorizationDemo {
enum Feature {
BASIC_ORDER,
REPORT_EXPORT,
ADVANCED_AUDIT
}
record Subscription(String tenantId, boolean active, Set<Feature> features) {
}
static final class FeatureNotEnabledException extends RuntimeException {
FeatureNotEnabledException(String tenantId, Feature feature) {
super("Tenant " + tenantId + " has not enabled feature " + feature);
}
}
static final class FeatureGuard {
void check(Subscription subscription, Feature requiredFeature) {
if (subscription == null || !subscription.active()) {
throw new IllegalStateException("No active subscription");
}
if (!subscription.features().contains(requiredFeature)) {
throw new FeatureNotEnabledException(
subscription.tenantId(), requiredFeature);
}
}
}
public static void main(String[] args) {
Subscription subscription = new Subscription(
"tenant-1001",
true,
EnumSet.of(Feature.BASIC_ORDER, Feature.REPORT_EXPORT)
);
FeatureGuard guard = new FeatureGuard();
guard.check(subscription, Feature.REPORT_EXPORT);
System.out.println("REPORT_EXPORT allowed");
try {
guard.check(subscription, Feature.ADVANCED_AUDIT);
} catch (FeatureNotEnabledException ex) {
System.out.println(ex.getMessage());
}
}
}预期输出:
REPORT_EXPORT allowed
Tenant tenant-1001 has not enabled feature ADVANCED_AUDIT接口层可在进入控制器时校验,尽早返回错误;业务层应在真正执行核心操作前再次校验,防止内部调用、消息消费或定时任务绕过 HTTP 入口。两层应复用同一个 FeatureGuard,不要各自维护一套规则。
缓存与订阅变更
功能集合适合按租户缓存,例如使用 tenantId 作为键、功能编码集合作为值。缓存只能提升读取速度,不能成为唯一事实来源;续费、升级、降级、停用或到期时必须删除对应缓存。
对于高风险功能,可以在缓存中保存订阅版本号。业务请求携带或读取版本后再校验,能够避免套餐刚降级时旧缓存继续放行。普通功能则可采用较短过期时间并配合事件主动失效。
提示:前端隐藏功能入口属于体验优化,后端授权校验才是安全边界。
错误返回与验证
未开通功能应返回稳定的业务错误码,例如 FEATURE_NOT_ENABLED,并附带目标功能编码。不要统一返回“无权限”,否则运营和租户无法判断是角色不足、套餐未购买还是订阅已失效。
验证时至少覆盖三个场景:套餐包含目标功能时正常放行;套餐不包含时拒绝;订阅过期或停用时拒绝。还应直接调用业务方法,确认绕过接口层后仍然会被拦截。
本课总结
- 功能授权与身份认证、角色权限是三条独立控制线
- 接口层负责尽早拒绝,业务层负责守住最终执行边界
- 功能编码、缓存失效和稳定错误码共同决定授权机制是否可靠
下一课预告
下一课将把套餐权益扩展到可计量资源,控制用户数、门店数、存储量和接口调用量,并处理并发占用与配额回收。