验证码体系
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的过期时间
