当前位置：首页 > news >正文

VonaJS业务抽象层: 验证码体系

news 2026/6/15 6:07:22

验证码体系

VonaJS的内置模块a-captcha提供了通用的验证码体系，使用Captcha Provider支持各种验证码方式，并且使用Captcha Scene支持不同场景的验证码使用策略

特性

Captcha Provider：使用Captcha Provider支持各种验证码方式，如：文字图形验证码、短信验证码，等等
Captcha Scene：使用Captcha Scene支持不同场景的验证码使用策略。比如，在某个场景下，可以在多个 Captcha Provider 中进行轮替，或者根据用户状态使用不同难度的 Captcha Provider，等等
立即验证：前端可以对用户输入的验证码进行立即验证。立即验证之后在提交表单时仍然要进行二次验证
表单验证：前端可以将用户输入的验证码与表单数据一起发往后端验证

bean.captcha

模块a-captcha提供了全局 Bean bean.captcha，可以通过统一的方式使用所有 Provider/Scene 提供的验证码能力

模块a-captchasimple提供了一个 Provider a-captchasimple:imageText，基于svg-captcha实现文字图片的验证码能力

模块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	本次验证码数据的id标识
provider	本次验证码所使用的Provider名称
token	本次验证码数据的token，用于比对用户输入值。在开发环境可以通过修改系统配置，将token发往前端，用于调试
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与表单数据一起发往后端进行二次验证

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

参数配置

可以在 App Config 中修改模块a-captcha的参数配置

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发往前端，用于调试。默认为false
captchaProvider.ttl	captcha token的过期时间
captchaProvider.ttlSecondary	二次token的过期时间