《优化接口设计的思路》系列：第四篇—接口的权限控制

前言

大家好！我是sum墨，一个一线的底层码农，平时喜欢研究和思考一些技术相关的问题并整理成文，限于本人水平，如果文章和代码有表述不当之处，还请不吝赐教。

作为一名从业已达六年的老码农，我的工作主要是开发后端Java业务系统，包括各种管理后台和小程序等。在这些项目中，我设计过单/多租户体系系统，对接过许多开放平台，也搞过消息中心这类较为复杂的应用，但幸运的是，我至今还没有遇到过线上系统由于代码崩溃导致资损的情况。这其中的原因有三点：一是业务系统本身并不复杂；二是我一直遵循某大厂代码规约，在开发过程中尽可能按规约编写代码；三是经过多年的开发经验积累，我成为了一名熟练工，掌握了一些实用的技巧。

我们在做系统的时候，只要这个系统里面存在角色和权限相关的业务需求，那么接口的权限控制肯定必不可少。但是大家一搜接口权限相关的资料，出来的就是整合Shrio、Spring Security等各种框架，然后下面一顿贴配置和代码，看得人云里雾里。实际上接口的权限控制是整个系统权限控制里面很小的一环，没有设计好底层数据结构，是无法做好接口的权限控制的。那么怎么做一个系统的权限控制呢？我认为有以下几步：

那么接下来我就按这个流程一一给大家说明权限是怎么做出来的。(注：只需要SpringBoot和Redis，不需要额外权限框架。)

本文参考项目源码地址：summo-springboot-interface-demo

一、权限底层表结构设计

第一，只要一个系统是给人用的，那么这个系统就一定会有一张用户表；第二，只要有人的地方，就一定会有角色权限的划分，最简单的就是超级管理员、普通用户；第三，如此常见的设计，会有一套相对规范的设计标准。
而权限底层表结构设计的标准就是：RBAC模型

1. RBAC模型简介

RBAC（Role-Based Access Control）权限模型的概念，即：基于角色的权限控制。通过角色关联用户，角色关联权限的方式间接赋予用户权限。

回到业务需求上来，应该是下面这样的要求：

用表结构展示的话就是这样，一共5张表，3张实体表，2张关联表

2. 建表语句

(1) t_user

DROP TABLE IF EXISTS `t_user`;
CREATE TABLE `t_user` (
  `user_id` bigint(20) unsigned zerofill NOT NULL AUTO_INCREMENT COMMENT '用户ID',
  `user_name` varchar(32) DEFAULT NULL COMMENT '用户名称',
  `gmt_create` datetime DEFAULT NULL COMMENT '创建时间',
  `gmt_modified` datetime DEFAULT NULL COMMENT '更新时间',
  `creator_id` bigint DEFAULT NULL COMMENT '创建人ID',
  `modifier_id` bigint DEFAULT NULL COMMENT '更新人ID',
  PRIMARY KEY (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ;

(2) t_role

DROP TABLE IF EXISTS `t_role`;
CREATE TABLE `t_role` (
  `role_id` bigint(20) unsigned zerofill NOT NULL AUTO_INCREMENT COMMENT '角色ID',
  `role_name` varchar(32) CHARACTER SET utf8mb4   DEFAULT NULL COMMENT '角色名称',
  `role_code` varchar(32) CHARACTER SET utf8mb4   DEFAULT NULL COMMENT '角色code',
  `gmt_create` datetime DEFAULT NULL COMMENT '创建时间',
  `gmt_modified` datetime DEFAULT NULL COMMENT '更新时间',
  `creator_id` bigint DEFAULT NULL COMMENT '创建人ID',
  `modifier_id` bigint DEFAULT NULL COMMENT '更新人ID',
  PRIMARY KEY (`role_id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4;

(3) t_auth

DROP TABLE IF EXISTS `t_auth`;
CREATE TABLE `t_auth` (
  `auth_id` bigint(20) unsigned zerofill NOT NULL AUTO_INCREMENT COMMENT '权限ID',
  `auth_code` varchar(32) DEFAULT NULL COMMENT '权限code',
  `auth_name` varchar(32) CHARACTER SET utf8mb4  DEFAULT NULL COMMENT '权限名称',
  `gmt_create` datetime DEFAULT NULL COMMENT '创建时间',
  `gmt_modified` datetime DEFAULT NULL COMMENT '更新时间',
  `creator_id` bigint DEFAULT NULL COMMENT '创建人ID',
  `modifier_id` bigint DEFAULT NULL COMMENT '更新人ID',
  PRIMARY KEY (`auth_id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4;

(4) t_user_role

DROP TABLE IF EXISTS `t_user_role`;
CREATE TABLE `t_user_role` (
  `id` bigint(20) unsigned zerofill NOT NULL AUTO_INCREMENT COMMENT '物理ID',
  `user_id` bigint NOT NULL COMMENT '用户ID',
  `role_id` bigint NOT NULL COMMENT '角色ID',
  `gmt_create` datetime DEFAULT NULL COMMENT '创建时间',
  `gmt_modified` datetime DEFAULT NULL COMMENT '更新时间',
  `creator_id` bigint DEFAULT NULL COMMENT '创建人ID',
  `modifier_id` bigint DEFAULT NULL COMMENT '更新人ID',
   PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

(5) t_role_auth

DROP TABLE IF EXISTS `t_role_auth`;
CREATE TABLE `t_role_auth` (
 `id` bigint(20) unsigned zerofill NOT NULL AUTO_INCREMENT COMMENT '物理ID',
  `role_id` bigint DEFAULT NULL COMMENT '角色ID',
  `auth_id` bigint DEFAULT NULL COMMENT '权限ID',
  `gmt_create` datetime DEFAULT NULL COMMENT '创建时间',
  `gmt_modified` datetime DEFAULT NULL COMMENT '更新时间',
  `creator_id` bigint DEFAULT NULL COMMENT '创建人ID',
  `modifier_id` bigint DEFAULT NULL COMMENT '更新人ID',
   PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

二、用户身份认证和授权

上面已经把表设计好了，接下来就是代码开发了。不过，在开发之前我们要搞清楚认证和授权这两个词是啥意思。

• 什么是认证？
  认证是确认一个用户的身份，确保用户是其所声称的人。它通过验证用户的身份信息，例如用户名和密码，来确认用户的身份。
• 什么是授权？
  授权是根据用户的身份和权限，给予用户特定的访问权限或使用某些资源的权力。它确定用户可以执行的操作，并限制他们不能执行的操作。授权确保用户只能访问他们被允许的内容和功能。

光看定义也很难懂，这里我举个例子配合说明。

接下来且看如何实现

1. 初始化数据

t_user表数据

INSERT INTO `t_user` (`user_id`, `user_name`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, '小A', '2023-09-21 09:48:14', '2023-09-21 09:48:19', -1, -1);
INSERT INTO `t_user` (`user_id`, `user_name`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (2, '小B', '2023-09-21 09:48:14', '2023-09-21 09:48:19', -1, -1);

t_role表数据

INSERT INTO `t_role` (`role_id`, `role_name`, `role_code`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, '管理员', 'admin', '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_role` (`role_id`, `role_name`, `role_code`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (2, '普通用户', 'normal', '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);

t_auth表数据

INSERT INTO `t_auth` (`auth_id`, `auth_code`, `auth_name`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, 'add', '新增', '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_auth` (`auth_id`, `auth_code`, `auth_name`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (2, 'delete', '删除', '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_auth` (`auth_id`, `auth_code`, `auth_name`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (3, 'query', '查询', '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_auth` (`auth_id`, `auth_code`, `auth_name`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (4, 'update', '更新', '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);

t_user_role表数据

INSERT INTO `t_user_role` (`user_id`, `role_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, 1, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_user_role` (`user_id`, `role_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (2, 2, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);

t_role_auth表数据

INSERT INTO `t_role_auth` (`role_id`, `auth_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, 2, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_role_auth` (`role_id`, `auth_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, 1, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_role_auth` (`role_id`, `auth_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, 3, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_role_auth` (`role_id`, `auth_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (1, 4, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);
INSERT INTO `t_role_auth` (`role_id`, `auth_id`, `gmt_create`, `gmt_modified`, `creator_id`, `modifier_id`) VALUES (2, 3, '2023-09-21 09:52:45', '2023-09-21 09:52:47', -1, -1);

2、新增/user/login接口模拟登录

接口代码如下

@GetMapping("/login")
public ResponseEntity<String> userLogin(@RequestParam(required = true) String userName,
        HttpServletRequest httpServletRequest,
        HttpServletResponse httpServletResponse) {
  return userService.login(userName, httpServletRequest, httpServletResponse);
}

业务代码如下

@Override
public ResponseEntity<String> login(String userName, HttpServletRequest httpServletRequest,
        HttpServletResponse httpServletResponse) {
  //根据名称查询用户信息
  UserDO userDO = userMapper.selectOne(new QueryWrapper<UserDO>().lambda().eq(UserDO::getUserName, userName));
  if (Objects.isNull(userDO)) {
    return ResponseEntity.ok("未查询到用户");
  }
  //查询当前用户的角色信息
  List<UserRoleDO> userRoleDOList = userRoleMapper.selectList(
            new QueryWrapper<UserRoleDO>().lambda().eq(UserRoleDO::getUserId, userDO.getUserId()));
  if (CollectionUtils.isEmpty(userRoleDOList)) {
    return ResponseEntity.ok("当前用户没有角色");
  }
  //查询当前用户的权限
  List<RoleAuthDO> roleAuthDOS = roleAuthMapper.selectList(new QueryWrapper<RoleAuthDO>().lambda()
            .in(RoleAuthDO::getRoleId, userRoleDOList.stream().map(UserRoleDO::getRoleId).collect(
                Collectors.toList())));
  if (CollectionUtils.isEmpty(roleAuthDOS)) {
    return ResponseEntity.ok("当前角色没有对应权限");
  }
  //查询权限code
  List<AuthDO> authDOS = authMapper.selectList(new QueryWrapper<AuthDO>().lambda()
            .in(AuthDO::getAuthId, roleAuthDOS.stream().map(RoleAuthDO::getAuthId).collect(
                Collectors.toList())));

  //生成唯一token
  String token = UUID.randomUUID().toString();
  //缓存用户信息
  redisUtil.set(token, JSONObject.toJSONString(userDO), tokenTimeout);
  //缓存用户权限信息
  redisUtil.set("auth_" + userDO.getUserId(),
            JSONObject.toJSONString(authDOS.stream().map(AuthDO::getAuthCode).collect(Collectors.toList())),
            tokenTimeout);
  //向localhost中添加Cookie
  Cookie cookie = new Cookie("token", token);
  cookie.setDomain("localhost");
  cookie.setPath("/");
  cookie.setMaxAge(tokenTimeout.intValue());
  httpServletResponse.addCookie(cookie);
  //返回登录成功
  return ResponseEntity.ok(JSONObject.toJSONString(userDO));
}

上面代码用流程图表示如下

3. 调用登录接口

小A登录：http://localhost:8080/user/login?userName=小A
小B登录：http://localhost:8080/user/login?userName=小B

（没画前端界面，大家将就看下哈）

小A登录调用返回如下

小B登录调用返回如下

三、用户权限验证逻辑

通过第二步，用户已经进行了认证、授权的操作，那么接下来就是用户验权：即验证用户是否有调用接口的权限。

1. 定义接口权限注解

前面定义了4个权限：新增/删除/修改/查询，分别对应着4个接口。这里我们使用注解进行一一对应。
注解定义如下：
RequiresPermissions.java

package com.summo.demo.config.permissions;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequiresPermissions {
    /**
     * 权限列表
     * @return
     */
    String[] value();

    /**
     * 权限控制方式，且或者和
     * @return
     */
    Logical logical() default Logical.AND;

}

注解处理代码逻辑如下：
RequiresPermissionsHandler.java

package com.summo.demo.config.permissions;

import java.lang.reflect.Method;
import java.text.MessageFormat;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.Set;
import java.util.stream.Collectors;

import com.alibaba.fastjson.JSONObject;

import com.summo.demo.config.context.GlobalUserContext;
import com.summo.demo.config.context.UserContext;
import com.summo.demo.config.manager.UserManager;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class RequiresPermissionsHandler {

    @Autowired
    private UserManager userManager;

    @Pointcut("@annotation(com.summo.demo.config.permissions.RequiresPermissions)")
    public void pointcut() {
        // do nothing
    }

    @Around("pointcut()")
    public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
        //获取用户上下文
        UserContext userContext = GlobalUserContext.getUserContext();
        if (Objects.isNull(userContext)) {
            throw new RuntimeException("用户认证失败，请检查是否登录");
        }
        //获取注解
        MethodSignature signature = (MethodSignature)joinPoint.getSignature();
        Method method = signature.getMethod();
        RequiresPermissions requiresPermissions = method.getAnnotation(RequiresPermissions.class);
        //获取当前接口上数据权限
        String[] permissions = requiresPermissions.value();
        if (Objects.isNull(permissions) && permissions.length == 0) {
            throw new RuntimeException("用户认证失败，请检查该接口是否添加了数据权限");
        }
        //判断当前是and还是or
        String[] notHasPermissions;
        switch (requiresPermissions.logical()) {
            case AND:
                //当逻辑为and时，所有的数据权限必须存在
                notHasPermissions = checkPermissionsByAnd(userContext.getUserId(), permissions);
                if (Objects.nonNull(notHasPermissions) && notHasPermissions.length > 0) {
                    throw new RuntimeException(
                        MessageFormat.format("用户权限不足，缺失以下权限:[{0}]", JSONObject.toJSONString(notHasPermissions)));
                }
                break;
            case OR:
                //当逻辑为and时，所有的数据权限必须存在
                notHasPermissions = checkPermissionsByOr(userContext.getUserId(), permissions);
                if (Objects.nonNull(notHasPermissions) && notHasPermissions.length > 0) {
                    throw new RuntimeException(
                        MessageFormat.format("用户权限不足，缺失以下权限:[{0}]", JSONObject.toJSONString(notHasPermissions)));
                }
                break;
            default:
                //默认为and
        }
        return joinPoint.proceed();
    }

    /**
     * 当数据权限为or时，进行判断
     *
     * @param userId      用户ID
     * @param permissions 权限组
     * @return 没有授予的权限
     */
    private String[] checkPermissionsByOr(Long userId, String[] permissions) {
        // 获取用户权限集
        Set<String> permissionSet = userManager.queryAuthByUserId(userId);
        if (permissionSet.isEmpty()) {
            return permissions;
        }
        //一一比对
        List<String> tempPermissions = new ArrayList<>();
        for (String permission1 : permissions) {
            permissionSet.forEach(permission -> {
                if (permission1.equals(permission)) {
                    tempPermissions.add(permission);
                }
            });
        }
        if (Objects.nonNull(tempPermissions) && tempPermissions.size() > 0) {
            return null;
        }
        return permissions;
    }

    /**
     * 当数据权限为and时，进行判断
     *
     * @param userId      用户ID
     * @param permissions 权限组
     * @return 没有授予的权限
     */
    private String[] checkPermissionsByAnd(Long userId, String[] permissions) {
        // 获取用户权限集
        Set<String> permissionSet = userManager.queryAuthByUserId(userId);
        if (permissionSet.isEmpty()) {
            return permissions;
        }
        //如果permissions大小为1，可以单独处理一下
        if (permissionSet.size() == 1 && permissionSet.contains(permissions[0])) {
            return null;
        }
        if (permissionSet.size() == 1 && !permissionSet.contains(permissions[0])) {
            return permissions;
        }
        //一一比对
        List<String> tempPermissions = new ArrayList<>();
        for (String permission1 : permissions) {
            permissionSet.forEach(permission -> {
                if (permission1.equals(permission)) {
                    tempPermissions.add(permission);
                }
            });
        }
        //如果tempPermissions的长度与permissions相同，那么说明权限吻合
        if (permissions.length == tempPermissions.size()) {
            return null;
        }
        //否则取出当前用户没有的权限，并返回用作提示
        List<String> notHasPermissions = Arrays.stream(permissions).filter(
            permission -> !tempPermissions.contains(permission)).collect(Collectors.toList());
        return notHasPermissions.toArray(new String[notHasPermissions.size()]);
    }

}

2. 注解使用方式

使用比较简单，直接放到接口的方法上

@GetMapping("/add")
@RequiresPermissions(value = "add", logical = Logical.OR)
public ResponseEntity<String> add(@RequestBody AddReq addReq) {
  return userService.add(addReq);
}

@GetMapping("/delete")
@RequiresPermissions(value = "delete", logical = Logical.OR)
public ResponseEntity<String> delete(@RequestParam Long userId) {
  return userService.delete(userId);
}

@GetMapping("/query")
@RequiresPermissions(value = "query", logical = Logical.OR)
public ResponseEntity<String> query(@RequestParam String userName) {
  return userService.query(userName);
}

@GetMapping("/update")
@RequiresPermissions(value = "update", logical = Logical.OR)
public ResponseEntity<String> update(@RequestBody UpdateReq updateReq) {
  return userService.update(updateReq);
}

3. 接口验权的流程

四、用户权限变动后的状态刷新

其实前面三步完成后，正向流已经完成了，但用户的权限是变化的，比如：

还记得登录的时候，我有缓存两个信息吗

对应代码中的

//缓存用户信息
redisUtil.set(token, JSONObject.toJSONString(userDO), tokenTimeout);
//缓存用户权限信息
redisUtil.set("auth_" + userDO.getUserId(),JSONObject.toJSONString(authDOS.stream().map(AuthDO::getAuthCode).collect(Collectors.toList())),tokenTimeout);

不过，这个地方有一个争议的点
用户权限发生变更的时候，是更新权限缓存呢？还是直接删除用户的权限缓存呢？

我的建议是：删除权限缓存。原因有三

• 用户权限缓存并不是一直存在，存在连缓存都没有的情况。
• 缓存更新只适用于单个用户权限的更新，但是我要把角色和权限的关联变动了呢？
• 直接把权限缓存删除，用户会不会报错？我查询权限缓存的方式是：先查询缓存，缓存没有在查询数据库，所以并不会出现缓存被删除就报错的情况。

五、认证失败或无权限等异常情况处理

出现由于权限不足或认证失败的问题，常见的做法有重定向到登录页、通知用户刷新界面等，具体怎么处理还要看产品是怎么要求的。
关于网站的异常有很多，权限相关的状态码是401、服务器错误的状态码是500，除此之外还会有自定义的错误码，我打算放在接口优化系列的后面用专篇说明，敬请期待哦~

写在最后