SpringBoot 專案使用 Sa-Token 完成登入認證

一、設計思路

對於一些登入之後才能存取的介面（例如：查詢我的賬號資料），我們通常的做法是增加一層介面校驗：

• 如果校驗通過，則：正常返回資料。
• 如果校驗未通過，則：丟擲異常，告知其需要先進行登入。

那麼，判斷對談是否登入的依據是什麼？我們先來簡單分析一下登入存取流程：

1. 使用者提交 name + password 引數，呼叫登入介面。
2. 登入成功，返回這個使用者的 Token 對談憑證。
3. 使用者後續的每次請求，都攜帶上這個 Token。
4. 伺服器根據 Token 判斷此對談是否登入成功。

所謂登入認證，指的就是伺服器校驗賬號密碼，為使用者頒發 Token 對談憑證的過程，這個 Token 也是我們後續判斷對談是否登入的關鍵所在。

動態圖演示：

接下來，我們將介紹在 SpringBoot 中如何使用 Sa-Token 完成登入認證操作。

Sa-Token 是一個 java 許可權認證框架，主要解決登入認證、許可權認證、單點登入、OAuth2、微服務閘道器鑑權 等一系列許可權相關問題。
Gitee 開源地址：https://gitee.com/dromara/sa-token

首先在專案中引入 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 即可。

二、登入與登出

根據以上思路，我們需要一個對談登入的函數：

// 對談登入：引數填寫要登入的賬號id，建議的資料型別：long | int | String， 不可以傳入複雜型別，如：User、Admin 等等
StpUtil.login(Object id);	 

只此一句程式碼，便可以使對談登入成功，實際上，Sa-Token 在背後做了大量的工作，包括但不限於：

1. 檢查此賬號是否之前已有登入
2. 為賬號生成 Token 憑證與 Session 對談
3. 通知全域性偵聽器，xx 賬號登入成功
4. 將 Token 注入到請求上下文
5. 等等其它工作……

你暫時不需要完整的瞭解整個登入過程，你只需要記住關鍵一點：Sa-Token 為這個賬號建立了一個Token憑證，且通過 Cookie 上下文返回給了前端。

所以一般情況下，我們的登入介面程式碼，會大致類似如下：

// 對談登入介面 
@RequestMapping("doLogin")
public SaResult doLogin(String name, String pwd) {
	// 第一步：比對前端提交的賬號名稱、密碼
	if("zhang".equals(name) && "123456".equals(pwd)) {
		// 第二步：根據賬號id，進行登入 
		StpUtil.login(10001);
		return SaResult.ok("登入成功");
	}
	return SaResult.error("登入失敗");
}

如果你對以上程式碼閱讀沒有壓力，你可能會注意到略顯奇怪的一點：此處僅僅做了對談登入，但並沒有主動向前端返回 Token 資訊。
是因為不需要嗎？嚴格來講是需要的，只不過 StpUtil.login(id) 方法利用了 Cookie 自動注入的特性，省略了你手寫返回 Token 的程式碼。

如果你對 Cookie 功能還不太瞭解，也不用擔心，我們會在之後的 [ 前後端分離 ] 章節中詳細的闡述 Cookie 功能，現在你只需要瞭解最基本的兩點：

• Cookie 可以從後端控制往瀏覽器中寫入 Token 值。
• Cookie 會在前端每次發起請求時自動提交 Token 值。

因此，在 Cookie 功能的加持下，我們可以僅靠 StpUtil.login(id) 一句程式碼就完成登入認證。

除了登入方法，我們還需要：

// 當前對談登出登入
StpUtil.logout();

// 獲取當前對談是否已經登入，返回true=已登入，false=未登入
StpUtil.isLogin();

// 檢驗當前對談是否已經登入, 如果未登入，則丟擲異常：`NotLoginException`
StpUtil.checkLogin();

異常 NotLoginException 代表當前對談暫未登入，可能的原因有很多：
前端沒有提交 Token、前端提交的 Token 是無效的、前端提交的 Token 已經過期 …… 等等。

Sa-Token 未登入場景值參照表：

場景值	對應常數	含義說明
-1	NotLoginException.NOT_TOKEN	未能從請求中讀取到 Token
-2	NotLoginException.INVALID_TOKEN	已讀取到 Token，但是 Token無效
-3	NotLoginException.TOKEN_TIMEOUT	已讀取到 Token，但是 Token已經過期
-4	NotLoginException.BE_REPLACED	已讀取到 Token，但是 Token 已被頂下線
-5	NotLoginException.KICK_OUT	已讀取到 Token，但是 Token 已被踢下線

那麼，如何獲取場景值呢？廢話少說直接上程式碼：

// 全域性異常攔截（攔截專案中的NotLoginException異常）
@ExceptionHandler(NotLoginException.class)
public SaResult handlerNotLoginException(NotLoginException nle)
		throws Exception {

	// 列印堆疊，以供偵錯
	nle.printStackTrace(); 
	
	// 判斷場景值，客製化化異常資訊 
	String message = "";
	if(nle.getType().equals(NotLoginException.NOT_TOKEN)) {
		message = "未提供token";
	}
	else if(nle.getType().equals(NotLoginException.INVALID_TOKEN)) {
		message = "token無效";
	}
	else if(nle.getType().equals(NotLoginException.TOKEN_TIMEOUT)) {
		message = "token已過期";
	}
	else if(nle.getType().equals(NotLoginException.BE_REPLACED)) {
		message = "token已被頂下線";
	}
	else if(nle.getType().equals(NotLoginException.KICK_OUT)) {
		message = "token已被踢下線";
	}
	else {
		message = "當前對談未登入";
	}
	
	// 返回給前端
	return SaResult.error(message);
}

注意：以上程式碼並非處理邏輯的最佳方式，只為以最簡單的程式碼演示出場景值的獲取與應用，大家可以根據自己的專案需求來客製化化處理

三、對談查詢

// 獲取當前對談賬號id, 如果未登入，則丟擲異常：`NotLoginException`
StpUtil.getLoginId();

// 類似查詢API還有：
StpUtil.getLoginIdAsString();    // 獲取當前對談賬號id, 並轉化為`String`型別
StpUtil.getLoginIdAsInt();       // 獲取當前對談賬號id, 並轉化為`int`型別
StpUtil.getLoginIdAsLong();      // 獲取當前對談賬號id, 並轉化為`long`型別

// ---------- 指定未登入情形下返回的預設值 ----------

// 獲取當前對談賬號id, 如果未登入，則返回null 
StpUtil.getLoginIdDefaultNull();

// 獲取當前對談賬號id, 如果未登入，則返回預設值 （`defaultValue`可以為任意型別）
StpUtil.getLoginId(T defaultValue);

四、Token 查詢

// 獲取當前對談的token值
StpUtil.getTokenValue();

// 獲取當前`StpLogic`的token名稱
StpUtil.getTokenName();

// 獲取指定token對應的賬號id，如果未登入，則返回 null
StpUtil.getLoginIdByToken(String tokenValue);

// 獲取當前對談剩餘有效期（單位：s，返回-1代表永久有效）
StpUtil.getTokenTimeout();

// 獲取當前對談的token資訊引數
StpUtil.getTokenInfo();

TokenInfo 是 Token 資訊 Model，用來描述一個 Token 的常用引數：

{
	"tokenName": "satoken",           // token名稱
	"tokenValue": "e67b99f1-3d7a-4a8d-bb2f-e888a0805633",      // token值
	"isLogin": true,                  // 此token是否已經登入
	"loginId": "10001",               // 此token對應的LoginId，未登入時為null
	"loginType": "login",              // 賬號型別標識
	"tokenTimeout": 2591977,          // token剩餘有效期 (單位: 秒)
	"sessionTimeout": 2591977,        // User-Session剩餘有效時間 (單位: 秒)
	"tokenSessionTimeout": -2,        // Token-Session剩餘有效時間 (單位: 秒) (-2表示系統中不存在這個快取)
	"tokenActivityTimeout": -1,       // token剩餘無操作有效時間 (單位: 秒)
	"loginDevice": "default-device"   // 登入裝置型別 
}

五、來個小測試，加深一下理解

新建 LoginAuthController，複製以下程式碼

package com.pj.cases.use;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import cn.dev33.satoken.stp.SaTokenInfo;
import cn.dev33.satoken.stp.StpUtil;
import cn.dev33.satoken.util.SaResult;

/**
 * Sa-Token 登入認證範例 
 * 
 * @author kong
 * @since 2022-10-13
 */
@RestController
@RequestMapping("/acc/")
public class LoginAuthController {

	// 對談登入介面  ---- http://localhost:8081/acc/doLogin?name=zhang&pwd=123456
	@RequestMapping("doLogin")
	public SaResult doLogin(String name, String pwd) {
		
		// 第一步：比對前端提交的 賬號名稱 & 密碼 是否正確，比對成功後開始登入 
		// 		此處僅作模擬範例，真實專案需要從資料庫中查詢資料進行比對 
		if("zhang".equals(name) && "123456".equals(pwd)) {
			
			// 第二步：根據賬號id，進行登入 
			// 		此處填入的引數應該保持使用者表唯一，比如使用者id，不可以直接填入整個 User 物件 
			StpUtil.login(10001);
			
			// SaResult 是 Sa-Token 中對返回結果的簡單封裝，下面的範例將不再贅述 
			return SaResult.ok("登入成功");
		}
		
		return SaResult.error("登入失敗");
	}

	// 查詢當前登入狀態  ---- http://localhost:8081/acc/isLogin
	@RequestMapping("isLogin")
	public SaResult isLogin() {
		// StpUtil.isLogin() 查詢當前使用者端是否登入，返回 true 或 false 
		boolean isLogin = StpUtil.isLogin();
		return SaResult.ok("當前使用者端是否登入：" + isLogin);
	}

	// 校驗當前登入狀態  ---- http://localhost:8081/acc/checkLogin
	@RequestMapping("checkLogin")
	public SaResult checkLogin() {
		// 檢驗當前對談是否已經登入, 如果未登入，則丟擲異常：`NotLoginException`
		StpUtil.checkLogin();

		// 丟擲異常後，程式碼將走入全域性例外處理（GlobalException.java），如果沒有丟擲異常，則代表通過了登入校驗，返回下面資訊 
		return SaResult.ok("校驗登入成功，這行字串是隻有登入後才會返回的資訊");
	}

	// 獲取當前登入的賬號是誰  ---- http://localhost:8081/acc/getLoginId
	@RequestMapping("getLoginId")
	public SaResult getLoginId() {
		// 需要注意的是，StpUtil.getLoginId() 自帶登入校驗效果
		// 也就是說如果在未登入的情況下呼叫這句程式碼，框架就會丟擲 `NotLoginException` 異常，效果和 StpUtil.checkLogin() 是一樣的 
		Object userId = StpUtil.getLoginId();
		System.out.println("當前登入的賬號id是：" + userId);
		
		// 如果不希望 StpUtil.getLoginId() 觸發登入校驗效果，可以填入一個預設值
		// 如果對談未登入，則返回這個預設值，如果對談已登入，將正常返回登入的賬號id 
		Object userId2 = StpUtil.getLoginId(0);
		System.out.println("當前登入的賬號id是：" + userId2);
		
		// 或者使其在未登入的時候返回 null 
		Object userId3 = StpUtil.getLoginIdDefaultNull();
		System.out.println("當前登入的賬號id是：" + userId3);
		
		// 型別轉換：
		// StpUtil.getLoginId() 返回的是 Object 型別，你可以使用以下方法指定其返回的型別 
		int userId4 = StpUtil.getLoginIdAsInt();  // 將返回值轉換為 int 型別 
		long userId5 = StpUtil.getLoginIdAsLong();  // 將返回值轉換為 long 型別 
		String userId6 = StpUtil.getLoginIdAsString();  // 將返回值轉換為 String 型別 
		
		// 疑問：資料基本型別不是有八個嗎，為什麼只封裝以上三種型別的轉換？
		// 因為大多數專案都是拿 int、long 或 String 宣告 UserId 的型別的，實在沒見過哪個專案用 double、float、boolean 之類來宣告 UserId 
		System.out.println("當前登入的賬號id是：" + userId4 + " --- " + userId5 + " --- " + userId6);
		
		// 返回給前端 
		return SaResult.ok("當前使用者端登入的賬號id是：" + userId);
	}

	// 查詢 Token 資訊  ---- http://localhost:8081/acc/tokenInfo
	@RequestMapping("tokenInfo")
	public SaResult tokenInfo() {
		// TokenName 是 Token 名稱的意思，此值也決定了前端提交 Token 時應該使用的引數名稱 
		String tokenName = StpUtil.getTokenName();
		System.out.println("前端提交 Token 時應該使用的引數名稱：" + tokenName);
		
		// 使用 StpUtil.getTokenValue() 獲取前端提交的 Token 值 
		// 框架預設前端可以從以下三個途徑中提交 Token：
		// 		Cookie 		（瀏覽器自動提交）
		// 		Header頭	（程式碼手動提交）
		// 		Query 引數	（程式碼手動提交） 例如： /user/getInfo?satoken=xxxx-xxxx-xxxx-xxxx 
		// 讀取順序為： Query 引數 --> Header頭 -- > Cookie 
		// 以上三個地方都讀取不到 Token 資訊的話，則視為前端沒有提交 Token 
		String tokenValue = StpUtil.getTokenValue();
		System.out.println("前端提交的Token值為：" + tokenValue);
		
		// TokenInfo 包含了此 Token 的大多數資訊 
		SaTokenInfo info = StpUtil.getTokenInfo();
		System.out.println("Token 名稱：" + info.getTokenName());
		System.out.println("Token 值：" + info.getTokenValue());
		System.out.println("當前是否登入：" + info.getIsLogin());
		System.out.println("當前登入的賬號id：" + info.getLoginId());
		System.out.println("當前登入賬號的型別：" + info.getLoginType());
		System.out.println("當前登入使用者端的裝置型別：" + info.getLoginDevice());
		System.out.println("當前 Token 的剩餘有效期：" + info.getTokenTimeout()); // 單位：秒，-1代表永久有效，-2代表值不存在
		System.out.println("當前 Token 的剩餘臨時有效期：" + info.getTokenActivityTimeout()); // 單位：秒，-1代表永久有效，-2代表值不存在
		System.out.println("當前 User-Session 的剩餘有效期" + info.getSessionTimeout()); // 單位：秒，-1代表永久有效，-2代表值不存在
		System.out.println("當前 Token-Session 的剩餘有效期" + info.getTokenSessionTimeout()); // 單位：秒，-1代表永久有效，-2代表值不存在
		
		// 返回給前端 
		return SaResult.data(StpUtil.getTokenInfo());
	}
	
	// 對談登出  ---- http://localhost:8081/acc/logout
	@RequestMapping("logout")
	public SaResult logout() {
		// 退出登入會清除三個地方的資料：
		// 		1、Redis中儲存的 Token 資訊
		// 		2、當前請求上下文中儲存的 Token 資訊 
		// 		3、Cookie 中儲存的 Token 資訊（如果未使用Cookie模式則不會清除）
		StpUtil.logout();
		
		// StpUtil.logout() 在未登入時也是可以呼叫成功的，
		// 也就是說，無論使用者端有沒有登入，執行完 StpUtil.logout() 後，都會處於未登入狀態 
		System.out.println("當前是否處於登入狀態：" + StpUtil.isLogin());
		
		// 返回給前端 
		return SaResult.ok("退出登入成功");
	}
	
}

程式碼註釋已針對每一步操作做出詳細解釋，大家可根據可參照註釋中的存取連結進行逐步測試。

本範例程式碼已上傳至 Gitee，可參考：
Sa-Token 登入認證範例

---

參考資料

• Gitee 倉庫地址：https://gitee.com/dromara/sa-token
• GitHub 倉庫地址：https://github.com/dromara/sa-token
• Sa-Token 線上檔案：https://sa-token.dev33.cn/