注解鑒權 —— 優雅的將鑒權與業務代碼分離。本篇我們將介紹在 Sa-Token 中如何通過注解完成權限校驗。

Sa-Token 是一個輕量級 java 權限認證框架，主要解決登錄認證、權限認證、單點登錄、OAuth2、微服務網關鑒權 等一系列權限相關問題。
Gitee 開源地址：https://gitee.com/dromara/sa-token

一、Sa-Token 鑒權注解一覽

Sa-Token 為我們提供的鑒權注解包括但不限于以下：

• @SaCheckLogin: 登錄校驗 —— 只有登錄之后才能進入該方法。
• @SaCheckRole("admin"): 角色校驗 —— 必須具有指定角色標識才能進入該方法。
• @SaCheckPermission("user:add"): 權限校驗 —— 必須具有指定權限才能進入該方法。
• @SaCheckSafe: 二級認證校驗 —— 必須二級認證之后才能進入該方法。
• @SaCheckBasic: HttpBasic校驗 —— 只有通過 Basic 認證后才能進入該方法。
• @SaCheckDisable("comment")：賬號服務封禁校驗 —— 校驗當前賬號指定服務是否被封禁。
• @SaIgnore：忽略校驗 —— 表示被修飾的方法或類無需進行注解鑒權和路由攔截器鑒權。

首先在項目中引入 Sa-Token 依賴：

<!-- Sa-Token 權限認證 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.34.0</version>
</dependency>

注：如果你使用的是 SpringBoot 3.x，只需要將 sa-token-spring-boot-starter 修改為 sa-token-spring-boot3-starter 即可。

二、登錄認證

Sa-Token 使用全局攔截器完成注解鑒權功能，為了不為項目帶來不必要的性能負擔，攔截器默認處于關閉狀態

因此，為了使用注解鑒權，你必須手動將 Sa-Token 的全局攔截器注冊到你項目中。

以SpringBoot2.0為例，新建配置類SaTokenConfigure.java

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    // 注冊 Sa-Token 攔截器，打開注解式鑒權功能 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注冊 Sa-Token 攔截器，打開注解式鑒權功能 
        registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");    
    }
}

保證此類被springboot啟動類掃描到即可。

新建 LoginController，添加以下代碼：

/**
 * 登錄認證注解測試
 */
@RestController
public class LoginController {

    // 訪問 home 頁，登錄后才能訪問  ---- http://localhost:8081/home
    @SaCheckLogin
    @RequestMapping("home")
    public SaResult home() {
        return SaResult.ok("訪問成功，此處為登錄后才能看到的信息");
    }

    // 登錄接口  ---- http://localhost:8081/doLogin?name=zhang&pwd=123456
    @RequestMapping("doLogin")
    public SaResult doLogin(String name, String pwd) {
        // 此處僅作模擬示例，真實項目需要從數據庫中查詢數據進行比對
        if("zhang".equals(name) && "123456".equals(pwd)) {
            StpUtil.login(10001);
            return SaResult.ok("登錄成功");
        }
        return SaResult.error("登錄失敗");
    }

}

啟動項目，首次訪問資源接口：

http://localhost:8081/home

返回如下：

{
    "code": 500,
    "msg": "未能讀取到有效Token",
    "data": null
}

會話尚未登錄，因此無法訪問資源。

現在我們再去訪問一下登錄接口：

http://localhost:8081/doLogin?name=zhang&pwd=123456

返回如下：

{
    "code": 200,
    "msg": "登錄成功",
    "data": null
}

登錄成功，我們再去訪問資源接口：

http://localhost:8081/home

返回如下：

{
    "code": 200,
    "msg": "訪問成功，此處為登錄后才能看到的信息",
    "data": null
}

通過登錄認證校驗，成功獲取到信息！

三、權限認證 & 角色認證

首先我們需要實現 StpInterface 接口，告訴框架指定賬號擁有哪些權限碼。

/**
 * 自定義權限認證接口擴展，Sa-Token 將從此實現類獲取每個賬號擁有的權限碼 
 * 
 * @author kong
 * @since 2022-10-13
 */
@Component  // 打開此注解，保證此類被springboot掃描，即可完成sa-token的自定義權限驗證擴展 
public class StpInterfaceImpl implements StpInterface {

    /**
     * 返回一個賬號所擁有的權限碼集合 
     */
    @Override
    public List<String> getPermissionList(Object loginId, String loginType) {
        // 本list僅做模擬，實際項目中要根據具體業務邏輯來查詢權限
        List<String> list = new ArrayList<String>();    
        list.add("101");
        list.add("user.add");
        list.add("user.update");
        list.add("user.get");
        // list.add("user.delete");
        list.add("art.*");
        return list;
    }

    /**
     * 返回一個賬號所擁有的角色標識集合 
     */
    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        // 本list僅做模擬，實際項目中要根據具體業務邏輯來查詢角色
        List<String> list = new ArrayList<String>();    
        list.add("admin");
        list.add("super-admin");
        return list;
    }

}

使用以下兩個注解完成校驗：

• @SaCheckPermission("user.add")：校驗當前會話是否具有某個權限。
• @SaCheckRole("super-admin")：校驗當前會話是否具有某個角色。

/**
 * Sa-Token 注解鑒權示例 
 * 
 * @author kong
 * @since 2022-10-13
 */
@RestController
@RequestMapping("/at-check/")
public class AtCheckController {

    /*
     * 前提1：首先調用登錄接口進行登錄
     *      ---- http://localhost:8081/doLogin?name=zhang&pwd=123456
     * 
     * 前提2：項目在配置類中注冊攔截器 SaInterceptor ，此攔截器將打開注解鑒權功能 
     * 
     * 前提3：項目實現了 StpInterface 接口，此接口會告訴框架指定賬號擁有哪些權限碼
     * 
     * 然后我們就可以使用以下示例中的代碼進行注解鑒權了 
     */
    
    // 權限校驗   ---- http://localhost:8081/at-check/checkPermission
    //      只有具有 user.add 權限的賬號才可以進入方法 
    @SaCheckPermission("user.add")
    @RequestMapping("checkPermission")
    public SaResult checkPermission() {
        // ... 
        return SaResult.ok();
    }

    // 角色校驗   ---- http://localhost:8081/at-check/checkRole
    //      只有具有 super-admin 角色的賬號才可以進入方法 
    @SaCheckRole("super-admin")
    @RequestMapping("checkRole")
    public SaResult checkRole() {
        // ... 
        return SaResult.ok();
    }
    
}

可根據代碼注釋提供的鏈接進行測試訪問。

四、設定校驗模式

@SaCheckRole與@SaCheckPermission注解可設置校驗模式，例如：

// 注解式鑒權：只要具有其中一個權限即可通過校驗 
@RequestMapping("atJurOr")
@SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)       
public SaResult atJurOr() {
    return SaResult.data("用戶信息");
}

mode有兩種取值：

• SaMode.AND, 標注一組權限，會話必須全部具有才可通過校驗。
• SaMode.OR, 標注一組權限，會話只要具有其一即可通過校驗。

五、角色權限雙重 “or校驗”

假設有以下業務場景：一個接口在具有權限 user.add 或角色 admin 時可以調通。怎么寫？

// 角色權限雙重 “or校驗”：具備指定權限或者指定角色即可通過校驗
@RequestMapping("userAdd")
@SaCheckPermission(value = "user.add", orRole = "admin")        
public SaResult userAdd() {
    return SaResult.data("用戶信息");
}

orRole 字段代表權限認證未通過時的次要選擇，兩者只要其一認證成功即可通過校驗，其有三種寫法：

• 寫法一：orRole = "admin"，代表需要擁有角色 admin 。
• 寫法二：orRole = {"admin", "manager", "staff"}，代表具有三個角色其一即可。
• 寫法三：orRole = {"admin, manager, staff"}，代表必須同時具有三個角色。

六、二級認證

@RestController
@RequestMapping("/at/")
public class AtController {

    // 在當前會話完成二級認證  ---- http://localhost:8081/at/openSafe 
    @RequestMapping("openSafe")
    public SaResult openSafe() {
        StpUtil.openSafe(200); // 打開二級認證，有效期為200秒
        return SaResult.ok();
    }
    
    // 通過二級認證后，才可以進入  ---- http://localhost:8081/at/checkSafe 
    @SaCheckSafe
    @RequestMapping("checkSafe")
    public SaResult checkSafe() {
        return SaResult.ok();
    }

}

必須先經過 StpUtil.openSafe(1200) 打開二級認證（參數為指定認證有效期，單位：秒），才可以通過 @SaCheckSafe 的檢查。

七、HttpBasic認證：

@RestController
@RequestMapping("/at/")
public class AtController {

    // 通過Basic認證后才可以進入  ---- http://localhost:8081/at/checkBasic 
    @SaCheckBasic(account = "sa:123456")
    @RequestMapping("checkBasic")
    public SaResult checkBasic() {
        return SaResult.ok();
    }
    
}

當我們訪問這個接口時，瀏覽器會強制彈出一個表單：

1.png

當我們輸入賬號密碼后 （sa / 123456），才可以繼續訪問數據：

2.png

八、服務禁用性校驗

@RestController
@RequestMapping("/at/")
public class AtController {

    // 只有當前服務沒有禁用 comment 服務時，才能夠進入方法  ---- http://localhost:8081/at/comment 
    @SaCheckDisable("comment")
    @RequestMapping("comment")
    public SaResult comment() {
        return SaResult.ok();
    }

}

@SaCheckDisable 注解的作用是檢測當前賬號是否被禁用了指定服務，如果已被禁用則無法進入指定方法，
在之后的章節我們會詳細講述服務禁用的相關代碼，此處先稍作了解即可。

九、忽略認證

使用 @SaIgnore 可表示一個接口忽略認證：

@SaCheckLogin
@RestController
public class TestController {
    
    // ... 其它方法 
    
    // 此接口加上了 @SaIgnore 可以游客訪問 
    @SaIgnore
    @RequestMapping("getList")
    public SaResult getList() {
        // ... 
        return SaResult.ok(); 
    }
}

如上代碼表示：TestController 中的所有方法都需要登錄后才可以訪問，但是 getList 接口可以匿名游客訪問。

• @SaIgnore 修飾方法時代表這個方法可以被游客訪問，修飾類時代表這個類中的所有接口都可以游客訪問。
• @SaIgnore 具有最高優先級，當 @SaIgnore 和其它鑒權注解一起出現時，其它鑒權注解都將被忽略。
• @SaIgnore 同樣可以忽略掉 Sa-Token 攔截器中的路由鑒權，在下面的 [路由攔截鑒權] 章節中我們會講到。

十、在業務邏輯層使用注解鑒權

疑問：我能否將注解寫在其它架構層呢，比如業務邏輯層？

使用攔截器模式，只能在Controller層進行注解鑒權，如需在任意層級使用注解鑒權，可使用 AOP注解鑒權 插件。

<!-- Sa-Token 整合 SpringAOP 實現注解鑒權 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-aop</artifactId>
    <version>1.34.0</version>
</dependency>

集成此插件后，便可以在任意層使用 Sa-Token 的注解鑒權了（例如業務邏輯層），不過需要注意的是：

• 攔截器模式和AOP模式不可同時集成，否則會在 Controller 層發生一個注解校驗兩次的bug。

參考資料

• Sa-Token 文檔：https://sa-token.cc
• Gitee 倉庫地址：https://gitee.com/dromara/sa-token
• GitHub 倉庫地址：https://github.com/dromara/sa-token