From 4726544b854c60fd6c1fc73130ded718595ca8d0 Mon Sep 17 00:00:00 2001 From: click33 <2393584716@qq.com> Date: Thu, 20 Mar 2025 09:39:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20api-sign=20=E6=A8=A1=E5=9D=97=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=20@SaCheckSign=20=E6=B3=A8=E8=A7=A3=E7=A4=BA=E4=BE=8B?= =?UTF-8?q?=E4=B8=8E=E5=A4=9A=E5=BA=94=E7=94=A8=E6=A8=A1=E5=BC=8F=E7=A4=BA?= =?UTF-8?q?=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sa-token-doc/plugin/api-sign.md | 113 ++++++++++++++++++++++++++++++-- sa-token-doc/use/at-check.md | 3 +- 2 files changed, 108 insertions(+), 8 deletions(-) diff --git a/sa-token-doc/plugin/api-sign.md b/sa-token-doc/plugin/api-sign.md index 47b85b84..a79c8227 100644 --- a/sa-token-doc/plugin/api-sign.md +++ b/sa-token-doc/plugin/api-sign.md @@ -478,13 +478,112 @@ public SaResult addMoney(long userId, long money) { } ``` -完。 - - - - - - + +### 10、使用注解校验签名 + +`@SaCheckSign` 注解用于为一个接口提供签名校验，用于替代 `SaSignUtil.checkRequest(SaHolder.getRequest())`，示例如下： + +``` java +// 校验全部参数：效果等同于 SaSignUtil.checkRequest(SaHolder.getRequest()) +@SaCheckSign +@RequestMapping("test1") +public SaResult test1() { + // code ... + return SaResult.ok(); +} + +// 指定参与签名的参数有哪些：效果等同于 SaSignUtil.checkRequest(SaHolder.getRequest(), "id", "name"); +@SaCheckSign(verifyParams = {"id", "name"}) +@RequestMapping("test2") +public SaResult test2() { + // code ... + return SaResult.ok(); +} + +// 指定: 在多应用模式下，使用的 appid，详情见下 +@SaCheckSign(appid = "xm-shop") +@RequestMapping("test3") +public SaResult test3() { + // code ... + return SaResult.ok(); +} +``` + + +### 11、多应用模式 + +有时候我们可能需要同时与多个应用对接，每个应用都需要使用不同的秘钥： + +首先在配置文件配置多个应用信息： + + +``` yaml +sa-token: + # API 签名配置 多应用模式 + sign-many: + # 应用1 + xm-shop: + secret-key: 0123456789abcdefg + digest-algo: md5 + # 应用2 + xm-forum: + secret-key: 0123456789hijklmnopq + digest-algo: sha256 + # 应用3 + xm-video: + secret-key: 12341234aaaaccccdddd + digest-algo: sha512 +``` + +``` properties +# API 签名配置 多应用模式 +# 应用1 +sa-token.sign-many.xm-shop.secret-key=0123456789abcdefg +sa-token.sign-many.xm-shop.digest-algo=md5 +# 应用2 +sa-token.sign-many.xm-forum.secret-key=0123456789hijklmnopq +sa-token.sign-many.xm-forum.digest-algo=sha256 +# 应用3 +sa-token.sign-many.xm-video.secret-key=12341234aaaaccccdddd +sa-token.sign-many.xm-video.digest-algo=sha512 +``` + +``` java +@Autowired +public void configSaToken(SaTokenConfig config) { + // API 签名配置 多应用模式 + // 应用1 + config.getSignMany().put("xm-shop", new SaSignConfig() + .setSecretKey("0123456789abcdefg") // 秘钥 + .setDigestAlgo("md5") // 签名算法 + ); + // 应用2 + config.getSignMany().put("xm-forum", new SaSignConfig() + .setSecretKey("0123456789hijklmnopq") + .setDigestAlgo("sha256") + ); + // 应用3 + config.getSignMany().put("xm-video", new SaSignConfig() + .setSecretKey("12341234aaaaccccdddd") + // 自定义签名算法示例 + .setDigestMethod(fullStr -> { + return SaSecureUtil.sha384(fullStr); + }) + ); +} +``` + + + +然后在签名时通过指定 appid 的方式获取对应的 SignTemplate 进行操作： + +``` java +// 创建签名示例 +String paramStr = SaSignMany.getSignTemplate("xm-shop").addSignParamsAndJoin(paramMap); + +// 校验签名示例 +SaSignMany.getSignTemplate("xm-shop").checkRequest(SaHolder.getRequest()); +``` diff --git a/sa-token-doc/use/at-check.md b/sa-token-doc/use/at-check.md index 745e62fd..c7c4b316 100644 --- a/sa-token-doc/use/at-check.md +++ b/sa-token-doc/use/at-check.md @@ -13,8 +13,9 @@ - `@SaCheckSafe`: 二级认证校验 —— 必须二级认证之后才能进入该方法。 - `@SaCheckHttpBasic`: HttpBasic校验 —— 只有通过 HttpBasic 认证后才能进入该方法。 - `@SaCheckHttpDigest`: HttpDigest校验 —— 只有通过 HttpDigest 认证后才能进入该方法。 -- `@SaIgnore`：忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权。 - `@SaCheckDisable("comment")`：账号服务封禁校验 —— 校验当前账号指定服务是否被封禁。 +- `@SaCheckSign`：API 签名校验 —— 用于跨系统的 API 签名参数校验。 +- `@SaIgnore`：忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权。 Sa-Token 使用全局拦截器完成注解鉴权功能，为了不为项目带来不必要的性能负担，拦截器默认处于关闭状态
因此，为了使用注解鉴权，**你必须手动将 Sa-Token 的全局拦截器注册到你项目中**