SpringBoot 使用 Sa-Token 完成註解鑑權功能

註解鑑權 —— 優雅的將鑑權與業務程式碼分離。本篇我們將介紹在 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();
	}
	
}

當我們存取這個介面時，瀏覽器會強制彈出一個表單：

當我們輸入賬號密碼後 （sa / 123456），才可以繼續存取資料：

八、服務禁用性校驗

@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

SpringBoot 使用 Sa-Token 完成註解鑑權功能

一、Sa-Token 鑑權註解一覽

二、登入認證

三、許可權認證 & 角色認證

四、設定校驗模式

五、角色許可權雙重 「or校驗」

六、二級認證

七、HttpBasic認證：

八、服務禁用性校驗

九、忽略認證

十、在業務邏輯層使用註解鑑權

參考資料

五、角色許可權雙重「or校驗」