Sa-Token鉴权学习：Vue结合SpringBoot实现角色权限控制

2026-01-03

要实现 Vue 框架结合 Sa-Token 按不同身份（角色/权限）展示不同功能板块，核心是前后端协同：

后端：基于 Sa-Token 完成登录认证、角色/权限的校验与管理；
前端：通过 Sa-Token 返回的 Token 维持登录状态，结合路由守卫、权限指令控制功能板块的显示/隐藏。

以下是完整的实现方案（涵盖 Vue2/Vue3，以 Vue3 + Pinia 为例，Vue2 仅需替换状态管理为 Vuex 即可）。

一、核心原理

端	核心职责
后端	1. 登录时生成 Sa-Token，绑定用户角色/权限； 2. 接口层通过 Sa-Token 注解（@SaCheckRole/@SaCheckPermission）校验权限； 3. 提供接口返回当前用户的角色/权限列表。
前端 Vue	1. 登录后存储 Token 和用户角色/权限； 2. 路由守卫拦截无权限路由； 3. 自定义指令/工具函数控制页面内功能板块的显示； 4. 请求拦截器携带 Token 完成鉴权。

二、后端实现（Spring Boot + Sa-Token）

先完成后端的 Sa-Token 配置和鉴权逻辑，为前端提供支撑。

1. 依赖引入（Maven）


<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.38.0</version>
</dependency>

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-dao-redis-jackson</artifactId>
    <version>1.38.0</version>
</dependency>

2. Sa-Token 基础配置（application.yml）

sa-token:
  # Token 名称（前端请求头中携带的名称）
  token-name: satoken
  # Token 有效期（7天，单位：秒）
  timeout: 604800
  # 无感刷新时间（3天，单位：秒）
  active-timeout: 259200
  # 是否允许同一账号多地登录
  is-concurrent: true
  # Token 风格（JWT 格式）
  token-style: jwt
  # 输出日志
  is-log: true

3. 核心业务实现

（1）用户实体与权限枚举

// 角色枚举
public enum RoleEnum {
    ADMIN("admin", "超级管理员"),
    USER("user", "普通用户"),
    OPERATOR("operator", "运营人员");

    private final String code;
    private final String desc;
    // 构造器、getter 略
}

// 权限枚举
public enum PermEnum {
    USER_ADD("user:add", "添加用户"),
    USER_DEL("user:del", "删除用户"),
    ORDER_VIEW("order:view", "查看订单");

    private final String code;
    private final String desc;
    // 构造器、getter 略
}

// 用户DTO（返回给前端）
@Data
public class UserInfoDTO {
    private Long id;
    private String username;
    private String avatar;
    // 用户角色列表（如 ["admin", "user"]）
    private List<String> roles;
    // 用户权限列表（如 ["user:add", "order:view"]）
    private List<String> permissions;
}

（2）登录接口（核心）

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @Autowired
    private UserService userService;

    /**
     * 登录接口
     */
    @PostMapping("/login")
    public Result<UserInfoDTO> login(@RequestBody LoginDTO loginDTO) {
        // 1. 校验账号密码（业务逻辑，自行实现）
        User user = userService.verifyUser(loginDTO.getUsername(), loginDTO.getPassword());
        if (user == null) {
            return Result.error("账号或密码错误");
        }

        // 2. Sa-Token 登录：将用户ID作为登录标识
        StpUtil.login(user.getId());
        // 3. 绑定角色和权限（可存储到 Sa-Token 上下文，也可返回给前端）
        List<String> roles = userService.getRolesByUserId(user.getId());
        List<String> permissions = userService.getPermissionsByUserId(user.getId());
        
        // 4. 构造返回给前端的用户信息
        UserInfoDTO userInfo = new UserInfoDTO();
        userInfo.setId(user.getId());
        userInfo.setUsername(user.getUsername());
        userInfo.setRoles(roles);
        userInfo.setPermissions(permissions);

        return Result.success(userInfo);
    }

    /**
     * 获取当前登录用户信息（前端刷新页面时调用）
     */
    @GetMapping("/current-user")
    // Sa-Token 注解：校验是否登录，未登录自动抛出异常
    @SaCheckLogin
    public Result<UserInfoDTO> getCurrentUser() {
        // 获取当前登录用户ID
        Long userId = StpUtil.getLoginIdAsLong();
        UserInfoDTO userInfo = userService.getUserInfoById(userId);
        return Result.success(userInfo);
    }

    /**
     * 退出登录
     */
    @PostMapping("/logout")
    @SaCheckLogin
    public Result<Void> logout() {
        StpUtil.logout();
        return Result.success("退出成功");
    }
}

（3）权限拦截接口（示例）

@RestController
@RequestMapping("/api/user")
public class UserController {

    /**
     * 添加用户：仅管理员可访问
     */
    @PostMapping("/add")
    @SaCheckRole("admin") // 校验角色为admin
    public Result<Void> addUser() {
        // 业务逻辑
        return Result.success("添加用户成功");
    }

    /**
     * 查看订单：需要 order:view 权限
     */
    @GetMapping("/order")
    @SaCheckPermission("order:view") // 校验权限
    public Result<List<OrderDTO>> getOrder() {
        // 业务逻辑
        return Result.success(Collections.emptyList());
    }
}

三、前端 Vue 实现

基于 Vue3 + Pinia + 之前封装的 request.js 实现，核心是状态管理、路由鉴权、组件级权限控制。

1. 环境准备

（1）封装的 request.js 中添加 Token 携带逻辑（已在之前的封装中包含，补充适配 Sa-Token）：

// request.js 中的请求拦截器部分
service.interceptors.request.use(
  (config) => {
    // 从Pinia获取Token，添加到请求头（Sa-Token默认名称为satoken）
    const userStore = useUserStore();
    if (userStore.token) {
      config.headers.satoken = userStore.token; // 关键：匹配后端sa-token的token-name
    }
    // 其他逻辑（重复请求、loading等）不变
    return config;
  },
  (error) => Promise.reject(error)
);

（2）创建 Pinia 状态管理（存储 Token 和用户权限）：

// src/stores/user.js
import { defineStore } from 'pinia';
import { get, post } from '@/utils/request';

export const useUserStore = defineStore('user', {
  state: () => ({
    token: localStorage.getItem('satoken') || '', // 持久化存储Token
    userInfo: {
      id: '',
      username: '',
      roles: [], // 角色列表
      permissions: [] // 权限列表
    }
  }),
  actions: {
    // 登录：存储Token和用户信息
    async login(loginForm) {
      const res = await post('/api/auth/login', loginForm);
      this.token = res.data.satoken; // 后端返回的Token（或从响应头取）
      this.userInfo = res.data;
      // 持久化Token，防止页面刷新丢失
      localStorage.setItem('satoken', this.token);
    },

    // 获取当前用户信息（刷新页面时调用）
    async getCurrentUser() {
      const res = await get('/api/auth/current-user');
      this.userInfo = res.data;
    },

    // 退出登录
    async logout() {
      await post('/api/auth/logout');
      // 清空状态和本地存储
      this.token = '';
      this.userInfo = { id: '', username: '', roles: [], permissions: [] };
      localStorage.removeItem('satoken');
    },

    // 检查是否有指定角色
    hasRole(role) {
      return this.userInfo.roles.includes(role);
    },

    // 检查是否有指定权限
    hasPermission(permission) {
      return this.userInfo.permissions.includes(permission);
    }
  }
});

2. 路由鉴权（核心：控制页面级访问）

（1）路由配置（添加 meta 元信息，声明角色/权限要求）：

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router';
import { useUserStore } from '@/stores/user';
import Layout from '@/layout/Layout.vue';

const routes = [
  {
    path: '/login',
    name: 'Login',
    component: () => import('@/views/Login.vue'),
    meta: { requiresAuth: false } // 无需登录即可访问
  },
  {
    path: '/',
    component: Layout,
    meta: { requiresAuth: true }, // 需要登录
    children: [
      // 首页：所有登录用户可访问
      {
        path: 'home',
        name: 'Home',
        component: () => import('@/views/Home.vue'),
        meta: { title: '首页' }
      },
      // 用户管理：仅admin角色可访问
      {
        path: 'user',
        name: 'User',
        component: () => import('@/views/User.vue'),
        meta: { title: '用户管理', roles: ['admin'] }
      },
      // 订单管理：需要 order:view 权限
      {
        path: 'order',
        name: 'Order',
        component: () => import('@/views/Order.vue'),
        meta: { title: '订单管理', permissions: ['order:view'] }
      },
      // 运营面板：仅operator角色可访问
      {
        path: 'operator',
        name: 'Operator',
        component: () => import('@/views/Operator.vue'),
        meta: { title: '运营面板', roles: ['operator'] }
      }
    ]
  },
  { path: '/:pathMatch(.*)*', redirect: '/home' }
];

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
});

// 全局前置守卫：鉴权核心
router.beforeEach(async (to, from, next) => {
  const userStore = useUserStore();
  const isLogin = !!userStore.token;

  // 1. 未登录：跳登录页（除了登录页本身）
  if (to.meta.requiresAuth && !isLogin) {
    next({ path: '/login', query: { redirect: to.fullPath } });
    return;
  }

  // 2. 已登录：刷新用户信息（首次进入/刷新页面）
  if (isLogin && !userStore.userInfo.username) {
    await userStore.getCurrentUser();
  }

  // 3. 权限校验：检查角色/权限
  if (to.meta.roles) {
    // 校验角色：只要有一个匹配即可
    const hasRole = to.meta.roles.some(role => userStore.hasRole(role));
    if (!hasRole) {
      ElMessage.error('无访问权限，请联系管理员');
      next({ path: '/home' });
      return;
    }
  }
  if (to.meta.permissions) {
    // 校验权限：只要有一个匹配即可
    const hasPermission = to.meta.permissions.some(perm => userStore.hasPermission(perm));
    if (!hasPermission) {
      ElMessage.error('无操作权限，请联系管理员');
      next({ path: '/home' });
      return;
    }
  }

  // 4. 全部通过，放行
  next();
});

export default router;

3. 组件级权限控制（控制功能板块/按钮显示）

通过自定义指令实现细粒度的权限控制（如按钮、功能板块的显示/隐藏）。

（1）创建权限指令：

// src/directives/permission.js
import { useUserStore } from '@/stores/user';

/**
 * 角色指令：v-role="['admin']"
 */
export const roleDirective = {
  mounted(el, binding) {
    const userStore = useUserStore();
    const requiredRoles = binding.value;
    if (!Array.isArray(requiredRoles)) return;

    // 无匹配角色则隐藏元素
    const hasRole = requiredRoles.some(role => userStore.hasRole(role));
    if (!hasRole) {
      el.style.display = 'none';
      // 彻底移除（可选）：el.parentNode?.removeChild(el);
    }
  }
};

/**
 * 权限指令：v-permission="['user:add']"
 */
export const permissionDirective = {
  mounted(el, binding) {
    const userStore = useUserStore();
    const requiredPerms = binding.value;
    if (!Array.isArray(requiredPerms)) return;

    // 无匹配权限则隐藏元素
    const hasPerm = requiredPerms.some(perm => userStore.hasPermission(perm));
    if (!hasPerm) {
      el.style.display = 'none';
    }
  }
};

（2）注册全局指令（main.js）：

// src/main.js
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { createPinia } from 'pinia';
import { roleDirective, permissionDirective } from '@/directives/permission';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';

const app = createApp(App);
app.use(createPinia());
app.use(router);
app.use(ElementPlus);

// 注册权限指令
app.directive('role', roleDirective);
app.directive('permission', permissionDirective);

app.mount('#app');

（3）组件中使用（控制功能板块/按钮）：


<template>
  <div class="user-page">
    
    <el-button 
      type="primary" 
      v-permission="['user:add']"
      @click="addUser"
    >
      添加用户
    </el-button>
    
    <div v-role="['operator']" class="operator-panel">
      <h3>运营数据统计</h3>
      
    </div>
    
    <el-button 
      type="danger" 
      v-if="userStore.hasPermission('user:del')"
      @click="delUser"
    >
      删除用户
    </el-button>
  </div>
</template>
<script setup>
import { useUserStore } from '@/stores/user';
const userStore = useUserStore();

const addUser = () => { /* 业务逻辑 */ };
const delUser = () => { /* 业务逻辑 */ };
</script>

4. 登录/退出逻辑（页面示例）


<template>
  <el-form :model="loginForm" @submit.prevent="handleLogin">
    <el-form-item label="用户名" prop="username">
      <el-input v-model="loginForm.username" />
    </el-form-item>
    <el-form-item label="密码" prop="password">
      <el-input v-model="loginForm.password" type="password" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" native-type="submit">登录</el-button>
    </el-form-item>
  </el-form>
</template>
<script setup>
import { ref } from 'vue';
import { useUserStore } from '@/stores/user';
import { useRouter } from 'vue-router';
import { ElMessage } from 'element-plus';

const loginForm = ref({ username: '', password: '' });
const userStore = useUserStore();
const router = useRouter();

const handleLogin = async () => {
  try {
    await userStore.login(loginForm.value);
    // 跳转到之前的页面（或首页）
    const redirect = router.currentRoute.query.redirect || '/home';
    router.push(redirect);
    ElMessage.success('登录成功');
  } catch (error) {
    ElMessage.error('登录失败，请检查账号密码');
  }
};
</script>

四、效果演示

用户角色	可访问页面	可操作功能
admin	首页、用户管理、订单管理	添加用户、删除用户、查看订单
user	首页、订单管理	仅查看订单
operator	首页、运营面板	仅查看运营数据

五、关键注意事项

Token 持久化：前端需将 Token 存储到 localStorage/sessionStorage，防止页面刷新丢失；
无感刷新 Token：结合 Sa-Token 的 active-timeout，前端可在 Token 过期前调用 StpUtil.renewTimeout() 刷新有效期（后端提供刷新接口）；
权限缓存：用户角色/权限可缓存到前端，无需每次请求接口都校验；
后端兜底校验：前端权限控制仅为“展示层面”，核心权限校验必须在后端通过 @SaCheckRole/@SaCheckPermission 实现，防止前端篡改；
Vue2 适配：将 Pinia 替换为 Vuex，指令注册方式改为 Vue.directive，路由守卫逻辑一致。

六、扩展优化

动态路由：若权限配置从后端动态获取，可在登录后通过 router.addRoute 动态添加路由，进一步细化权限；
按钮级别禁用：除了隐藏，还可通过指令禁用按钮（el.disabled = true），提升用户体验；
权限缓存刷新：当用户权限变更时，主动刷新前端缓存的权限列表；
多标签页适配：通过 localStorage 监听，实现多标签页登录状态同步。

通过以上方案，即可完整实现 Vue 框架基于 Sa-Token 的“不同身份展示不同功能板块”，兼顾安全性和易用性。