Bitzsoft.Integrations.Captcha 1.0.4

Bitzsoft.Integrations.Captcha

验证码抽象层 -- 统一第三方验证码（阿里云验证码 2.0 / 腾讯天御 / 极验 GeeTest v4）的接口定义与基础模型。

本包仅含抽象层（接口、工厂、模型、异常）。各厂商实现见独立的子包： Captcha.Aliyun / Captcha.Tencent / Captcha.Geetest， 或一步到位的聚合包 Captcha.All。

功能特性

• 统一契约：一套 ICaptchaProvider 接口覆盖三家厂商，消费方不感知厂商差异
• Provider 工厂：ICaptchaProviderFactory 按供应商编码（aliyun / tencent / geetest）运行时解析 Provider
• 无感验证统一模式：三家均采用「前端 SDK 自渲染 → 用户无感验证 → 前端提交 token → 后端二次校验」
• 统一结果模型：CaptchaResult<T> / CaptchaVerification / CaptchaChallenge，含成功/失败/供应商原始错误码
• 安全优先：fail-closed 校验语义（响应字段缺失一律判失败），密钥不落日志
• 降级友好：第三方不可用时返回 Fail，宿主可回退自有验证码（如 SVG 图形码）

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Captcha

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Captcha" Version="1.0.0" />

通常无需单独安装本包，安装任意一个厂商实现包或聚合包时会自动引入。

核心契约

ICaptchaProvider

public interface ICaptchaProvider
{
    // 供应商编码（"aliyun" / "tencent" / "geetest"）
    string Code { get; }

    // 生成验证码挑战（返回前端 SDK 初始化凭证，无感验证码不发网络请求）
    Task<CaptchaResult<CaptchaChallenge>> GenerateAsync(CaptchaGenerateRequest request, CancellationToken ct = default);

    // 校验前端回传的 token（服务端二次校验，token 一次性）
    Task<CaptchaResult<CaptchaVerification>> VerifyAsync(CaptchaVerifyRequest request, CancellationToken ct = default);
}

ICaptchaProviderFactory

public interface ICaptchaProviderFactory
{
    ICaptchaProvider GetProvider(string code);        // 按编码解析
    IEnumerable<string> GetRegisteredCodes();         // 已注册的供应商编码
}

核心类型一览

供应商编码对照表

使用模式

完整的注册与使用示例见各厂商包 README 或聚合包 Captcha.All README。

// 通过工厂按编码解析（推荐：风控引擎等消费方按配置动态选择厂商）
var factory = sp.GetRequiredService<ICaptchaProviderFactory>();
var provider = factory.GetProvider("aliyun");

// 生成前端 SDK 凭证
var challenge = await provider.GenerateAsync(new CaptchaGenerateRequest { Type = CaptchaType.Intelligent });

// 校验前端回传 token
var result = await provider.VerifyAsync(new CaptchaVerifyRequest { Token = frontEndToken, RemoteIp = userIp });
if (result.IsSuccess && result.Data!.Passed) { /* 校验通过 */ }

安全说明

• fail-closed：阿里云响应缺 VerifyResult 字段时一律判失败，绝不静默放行
• token 一次性：所有厂商的验证 token 校验后即失效，不可重放
• 密钥脱敏：AccessKeySecret / SecretKey / AppSecretKey / CaptchaKey 等敏感字段须配合 RequestLogging 脱敏配置，不落入审计日志
• 腾讯 AppSecretKey：腾讯 DescribeCaptchaResult 接口要求 AppSecretKey 随请求体传输（系腾讯既定设计），务必确保该字段被日志脱敏

依赖

相关包

• Bitzsoft.Integrations.Captcha.Aliyun -- 阿里云验证码 2.0 实现
• Bitzsoft.Integrations.Captcha.Tencent -- 腾讯天御验证码实现
• Bitzsoft.Integrations.Captcha.Geetest -- 极验 GeeTest v4 实现
• Bitzsoft.Integrations.Captcha.All -- 聚合包（一次引用全部实现）
• Bitzsoft.Integrations.SocialAuth -- 社交登录集成（同属身份认证分类）