SpringBootはSa-Tokenを使用してアカウント禁止、分類禁止、ラダー禁止を実現します

1. 需要分析

前の章では、不正なアカウントを排除するために使用される、ユーザーをオフラインに追い出す機能と強制ログアウトする機能について学びました。シナリオによっては、再度ログインできないようにアカウントを禁止する必要もあります。

Sa-Token は軽量の Java 権限認証フレームワークであり、主にログイン認証、権限認証、シングルサインオン、OAuth2、マイクロサービスゲートウェイ認証などの一連の権限関連の問題を解決します。Gitee オープンソースアドレス: gitee.com/dromara/sa-…

Sa-Token が提供する禁止操作には次の 3 種類があります。

アカウントの禁止: アカウントのログイン機能を禁止し、ログインできなくします。
機密禁止: アカウント全体のログインなどの基本的な機能に影響を与えることなく、アカウントの業務運営権限の一部を禁止します。
段階的禁止: 違反の程度に応じて、異なる禁止が与えられます。

この記事では、Sa-Token で上記 3 つの禁止操作を完了する方法を紹介します。

まず、プロジェクトに 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。

2. アカウントの禁止

指定されたアカウントを禁止します:

// 封禁指定账号 
StpUtil.disable(10001, 86400);

パラメータの意味:

パラメータ 1: 禁止されるアカウント ID。
パラメータ 2: 禁止時間、単位: 秒、これは 86400 秒 = 1 日です (この値が -1 の場合、永久禁止を意味します)。

注意すべき点: 現在ログインしているアカウントの場合、禁止してもすぐにはオフラインになりません。すぐにオフラインにする必要がある場合は、最初にキックして禁止する戦略を使用できます。たとえば、次のようになります。

// 先踢下线
StpUtil.kickout(10001); 
// 再封禁账号
StpUtil.disable(10001, 86400);

次回ログインするときに、アカウントが禁止されているかどうかを確認してみましょう。

// 校验指定账号是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`
StpUtil.checkDisable(10001); 

// 通过校验后，再进行登录：
StpUtil.login(10001);

旧バージョンではStpUtil.login()アカウントがBANされているかどうかを自動でチェックしていましたが、v1.31.0以降はBANのチェックとログインの2つの動作に分離され、自動チェックは行われなくなりました。変化します。

このモジュールのすべてのメソッド:

// 封禁指定账号 
StpUtil.disable(10001, 86400); 

// 获取指定账号是否已被封禁 (true=已被封禁, false=未被封禁) 
StpUtil.isDisable(10001); 

// 校验指定账号是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`
StpUtil.checkDisable(10001); 

// 获取指定账号剩余封禁时间，单位：秒，如果该账号未被封禁，则返回-2 
StpUtil.getDisableTime(10001); 

// 解除封禁
StpUtil.untieDisable(10001);

3. カテゴリ禁止

場合によっては、アカウント全体を禁止する必要はなく、一部のサービスへのアクセスのみを禁止する必要があります。

電子商取引システムを開発していると仮定して、違法アカウントに対する処罰として 3 種類の禁止を設定します。

1、封禁评价能力：账号A 因为多次虚假好评，被限制订单评价功能。
2、封禁下单能力：账号B 因为多次薅羊毛，被限制下单功能。
3、封禁开店能力：账号C 因为店铺销售假货，被限制开店功能。

相比于封禁账号的一刀切处罚，这里的关键点在于：每一项能力封禁的同时，都不会对其它能力造成影响。

也就是说我们需要一种只对部分服务进行限制的能力，对应到代码层面，就是只禁止部分接口的调用。

// 封禁指定用户评论能力，期限为 1天
StpUtil.disable(10001, "comment", 86400);

参数释义：

参数1：要封禁的账号id。
参数2：针对这个账号，要封禁的服务标识（可以是任意的自定义字符串）。
参数3：要封禁的时间，单位：秒，此为 86400秒 = 1天（此值为 -1 时，代表永久封禁）。

分类封禁模块所有可用API：

/*
 * 以下示例中："comment"=评论服务标识、"place-order"=下单服务标识、"open-shop"=开店服务标识
 */

// 封禁指定用户评论能力，期限为 1天
StpUtil.disable(10001, "comment", 86400);

// 在评论接口，校验一下，会抛出异常：`DisableServiceException`，使用 e.getService() 可获取业务标识 `comment` 
StpUtil.checkDisable(10001, "comment");

// 在下单时，我们校验一下 下单能力，并不会抛出异常，因为我们没有限制其下单功能
StpUtil.checkDisable(10001, "place-order");

// 现在我们再将其下单能力封禁一下，期限为 7天 
StpUtil.disable(10001, "place-order", 86400 * 7);

// 然后在下单接口，我们添加上校验代码，此时用户便会因为下单能力被封禁而无法下单（代码抛出异常）
StpUtil.checkDisable(10001, "place-order");

// 但是此时，用户如果调用开店功能的话，还是可以通过，因为我们没有限制其开店能力 （除非我们再调用了封禁开店的代码）
StpUtil.checkDisable(10001, "open-shop");

通过以上示例，你应该大致可以理解 业务封禁 -> 业务校验 的处理步骤。

有关分类封禁的所有方法：

// 封禁：指定账号的指定服务 
StpUtil.disable(10001, "<业务标识>", 86400); 

// 判断：指定账号的指定服务 是否已被封禁 (true=已被封禁, false=未被封禁) 
StpUtil.isDisable(10001, "<业务标识>"); 

// 校验：指定账号的指定服务 是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`
StpUtil.checkDisable(10001, "<业务标识>"); 

// 获取：指定账号的指定服务 剩余封禁时间，单位：秒（-1=永久封禁，-2=未被封禁）
StpUtil.getDisableTime(10001, "<业务标识>"); 

// 解封：指定账号的指定服务
StpUtil.untieDisable(10001, "<业务标识>");

四、阶梯封禁

对于多次违规的用户，我们常常采取阶梯处罚的策略，这种 “阶梯” 一般有两种形式：

处罚时间阶梯：首次违规封禁 1 天，第二次封禁 7 天，第三次封禁 30 天，依次顺延……
处罚力度阶梯：首次违规消息提醒、第二次禁言禁评论、第三次禁止账号登录，等等……

基于处罚时间的阶梯，我们只需在封禁时 StpUtil.disable(10001, 86400) 传入不同的封禁时间即可，下面我们着重探讨一下基于处罚力度的阶梯形式。

假设我们在开发一个论坛系统，对于违规账号的处罚，我们设定三种力度：

1、轻度违规：封禁其发帖、评论能力，但允许其点赞、关注等操作。
2、中度违规：封禁其发帖、评论、点赞、关注等一切与别人互动的能力，但允许其浏览帖子、浏览评论。
3、重度违规：封禁其登录功能，限制一切能力。

解决这种需求的关键在于，我们需要把不同处罚力度，量化成不同的处罚等级，比如上述的 轻度、中度、重度 3 个力度，我们将其量化为一级封禁、二级封禁、三级封禁 3个等级，数字越大代表封禁力度越高。

次に、ラダー禁止 API を認証に使用できます。

// 阶梯封禁，参数：封禁账号、封禁级别、封禁时间 
StpUtil.disableLevel(10001, 3, 10000);

// 获取：指定账号封禁的级别 （如果此账号未被封禁则返回 -2）
StpUtil.getDisableLevel(10001);

// 判断：指定账号是否已被封禁到指定级别，返回 true 或 false
StpUtil.isDisableLevel(10001, 3);

// 校验：指定账号是否已被封禁到指定级别，如果已达到此级别（例如已被3级封禁，这里校验是否达到2级），则抛出异常 `DisableServiceException`
StpUtil.checkDisableLevel(10001, 2);

注:DisableServiceExceptionこの例外は、現在のアカウントが禁止の検証に合格していないことを意味します。次のことが可能です。

このアカウントが実際にによって禁止されるレベルを取得しますe.getLevel()。
e.getLimitLevel()このアカウントに必要な、による検証時よりも低いレベルを取得します。そのLevel >= LimitLevel時点、フレームワークは例外をスローします。

ビジネスが十分に複雑な場合は、機密禁止とラダー禁止を組み合わせて使用することもあります。

// 分类阶梯封禁，参数：封禁账号、封禁服务、封禁级别、封禁时间 
StpUtil.disableLevel(10001, "comment", 3, 10000);

// 获取：指定账号的指定服务 封禁的级别 （如果此账号未被封禁则返回 -2）
StpUtil.getDisableLevel(10001, "comment");

// 判断：指定账号的指定服务 是否已被封禁到指定级别，返回 true 或 false
StpUtil.isDisableLevel(10001, "comment", 3);

// 校验：指定账号的指定服务 是否已被封禁到指定级别（例如 comment服务 已被3级封禁，这里校验是否达到2级），如果已达到此级别，则抛出异常 
StpUtil.checkDisableLevel(10001, "comment", 2);

5. 注釈を使用して禁止の検証を完了する

まず、Sa-Token グローバルインターセプターを登録する必要があります。

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
	// 注册 Sa-Token 拦截器，打开注解式鉴权功能 
	@Override
	public void addInterceptors(InterceptorRegistry registry) {
		registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");	
	}
}

次に、次のアノテーションを使用して、アカウントが禁止されているかどうかを確認できます。

// 校验当前账号是否被封禁，如果已被封禁会抛出异常，无法进入方法 
@SaCheckDisable
@PostMapping("send")
public SaResult send() {
	// ... 
	return SaResult.ok(); 
}

// 校验当前账号是否被封禁 comment 服务，如果已被封禁会抛出异常，无法进入方法 
@SaCheckDisable("comment")
@PostMapping("send")
public SaResult send() {
	// ... 
	return SaResult.ok(); 
}

// 校验当前账号是否被封禁 comment、place-order、open-shop 等服务，指定多个值，只要有一个已被封禁，就无法进入方法 
@SaCheckDisable({"comment", "place-order", "open-shop"})
@PostMapping("send")
public SaResult send() {
	// ... 
	return SaResult.ok(); 
}

// 阶梯封禁，校验当前账号封禁等级是否达到5级，如果达到则抛出异常 
@SaCheckDisable(level = 5)
@PostMapping("send")
public SaResult send() {
	// ... 
	return SaResult.ok(); 
}

// 分类封禁 + 阶梯封禁 校验：校验当前账号的 comment 服务，封禁等级是否达到5级，如果达到则抛出异常 
@SaCheckDisable(value = "comment", level = 5)
@PostMapping("send")
public SaResult send() {
	// ... 
	return SaResult.ok(); 
}

6 つ目、理解を深めるための小さな例

package com.pj.cases.up;

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

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

/**
 * Sa-Token 账号封禁示例 
 * 
 * @author kong
 * @since 2022-10-17 
 */
@RestController
@RequestMapping("/disable/")
public class DisableController {

	// 会话登录接口  ---- http://localhost:8081/disable/login?userId=10001
	@RequestMapping("login")
	public SaResult login(long userId) {
		// 1、先检查此账号是否已被封禁 
		StpUtil.checkDisable(userId);
		// 2、检查通过后，再登录 
		StpUtil.login(userId);
		return SaResult.ok("账号登录成功");
	}

	// 会话注销接口  ---- http://localhost:8081/disable/logout
	@RequestMapping("logout")
	public SaResult logout() {
		StpUtil.logout();
		return SaResult.ok("账号退出成功");
	}

	// 封禁指定账号  ---- http://localhost:8081/disable/disable?userId=10001
	@RequestMapping("disable")
	public SaResult disable(long userId) {
		/*
		 * 账号封禁：
		 * 	参数1：要封禁的账号id
		 * 	参数2：要封禁的时间，单位：秒，86400秒=1天
		 */
		StpUtil.disable(userId, 86400);
		return SaResult.ok("账号 " + userId + " 封禁成功");
	}

	// 解封指定账号  ---- http://localhost:8081/disable/untieDisable?userId=10001
	@RequestMapping("untieDisable")
	public SaResult untieDisable(long userId) {
		StpUtil.untieDisable(userId);
		return SaResult.ok("账号 " + userId + " 解封成功");
	}

}

テスト手順:

ログインインターフェイスにアクセスすると、通常通りログインできます ----http://localhost:8081/disable/login?userId=10001
ログアウト - - http://localhost:8081/disable/logout
アカウントを無効にします - - http://localhost:8081/disable/disable?userId=10001
ログインインターフェイスに再度アクセスすると、ログインが失敗します----http://localhost:8081/disable/login?userId=10001
アカウントのブロックを解除----http://localhost:8081/disable/untieDisable?userId=10001
再度ログインインターフェイスにアクセスすると、ログインが成功します----http://localhost:8081/disable/login?userId=10001

参考文献

Sa-Token 文档：sa-token.cc
Gitee 倉庫のアドレス: gitee.com/dromara/sa-…
GitHub ウェアハウスのアドレス: github.com/dromara/sa-…