VonaJS業(yè)務抽象層: 驗證碼體系

VonaJS的內置模塊a-captcha提供了通用的驗證碼體系，使用Captcha Provider支持各種驗證碼方式，并且使用Captcha Scene支持不同場景的驗證碼使用策略

驗證碼體系

VonaJS的內置模塊a-captcha提供了通用的驗證碼體系，使用Captcha Provider支持各種驗證碼方式，并且使用Captcha Scene支持不同場景的驗證碼使用策略

特性

Captcha Provider：使用Captcha Provider支持各種驗證碼方式，如：文字圖形驗證碼、短信驗證碼，等等
Captcha Scene：使用Captcha Scene支持不同場景的驗證碼使用策略。比如，在某個場景下，可以在多個 Captcha Provider 中進行輪替，或者根據(jù)用戶狀態(tài)使用不同難度的 Captcha Provider，等等
立即驗證：前端可以對用戶輸入的驗證碼進行立即驗證。立即驗證之后在提交表單時仍然要進行二次驗證
表單驗證：前端可以將用戶輸入的驗證碼與表單數(shù)據(jù)一起發(fā)往后端驗證

bean.captcha

模塊a-captcha提供了全局 Bean bean.captcha，可以通過統(tǒng)一的方式使用所有 Provider/Scene 提供的驗證碼能力

模塊a-captchasimple提供了一個 Provider a-captchasimple:imageText，基于svg-captcha實現(xiàn)文字圖片的驗證碼能力

模塊a-captchasimple提供了一個 Scene a-captchasimple:simple。該 Scene 只使用一個 Provider，即a-captchasimple:imageText

下面演示如何使用模塊a-captchasimple提供的驗證碼能力

1. create

// create captcha
const captcha = await this.bean.captcha.create('a-captchasimple:simple');

返回值類型：ICaptchaData

export interface ICaptchaData {
  id: string;
  provider: keyof ICaptchaProviderRecord;
  token?: unknown;
  payload: unknown;
}

名稱	說明
id	本次驗證碼數(shù)據(jù)的id標識
provider	本次驗證碼所使用的Provider名稱
token	本次驗證碼數(shù)據(jù)的token，用于比對用戶輸入值。在開發(fā)環(huán)境可以通過修改系統(tǒng)配置，將token發(fā)往前端，用于調試
payload	本次驗證碼的負載內容，不同的Provider有不同的payload類型

2. refresh

// refresh captcha
const captchaNew = await this.bean.captcha.refresh(captchaId, 'a-captchasimple:simple');

如果一個 Scene 配置了多個 Provider，那么在刷新 capthca 時可以基于策略選取不同的 Provider

3. verify

// verify captcha
const passed = await this.bean.captcha.verify(captchaId, '1234', 'a-captchasimple:simple');

4. verifyImmediate

前端可以對用戶輸入的驗證碼進行立即驗證。立即驗證之后在提交表單時仍然要進行二次驗證

// verifyImmediate captcha
const tokenOrFalse = await this.bean.captcha.verifyImmediate(captchaId, '1234');

如果立即驗證失敗，返回false
如果立即驗證成功，返回二次token
前端需要將二次token與表單數(shù)據(jù)一起發(fā)往后端進行二次驗證

interceptor.captchaVerify

模塊a-captcha提供了一個局部攔截器a-captcha:captchaVerify，可以針對 API 啟用驗證碼校驗

src/suite/a-home/modules/home-user/src/controller/passport.ts

import { Core } from 'vona-module-a-core';

class ControllerPassport {
  @Web.post('login')
+ @Core.captchaVerify({ scene: 'a-captchasimple:simple' })
  async login(@Arg.body() data) {}
}

@Core.captchaVerify: 用于使用局部攔截器a-captcha:captchaVerify，傳入需要使用的 Scene 名稱
該攔截器支持表單驗證和二次驗證

Captcha API

模塊a-captcha提供了一組開箱即用的 Captcha API，對bean.captcha的能力進行了封裝

src/suite-vendor/a-vona/modules/a-captcha/src/controller/captcha.ts

名稱	說明
create
refresh
verifyImmediate

為何沒有提供verifyAPI？

因為bean.captcha.verify方法用于局部攔截器a-captcha:captchaVerify

參數(shù)配置

可以在 App Config 中修改模塊a-captcha的參數(shù)配置

src/backend/config/config/config.ts

// modules
config.modules = {
  'a-captcha': {
    captcha: {
      showToken: false,
    },
    captchaProvider: {
      ttl: 20 * 60 * 1000,
      ttlSecondary: 20 * 60 * 1000,
    },
  },
};

名稱	說明
captcha.showToken	是否顯示token。如果為true，就將token發(fā)往前端，用于調試。默認為false
captchaProvider.ttl	captcha token的過期時間
captchaProvider.ttlSecondary	二次token的過期時間

posted @ 2025-11-03 09:30 濮水大叔閱讀(89) 評論(0) 收藏舉報

刷新頁面返回頂部

zhennann