Bitzsoft.Integrations.Captcha.All 1.0.0-alpha.10

Bitzsoft.Integrations.Captcha.All

验证码聚合包 -- 一次引用即包含阿里云验证码 2.0 / 腾讯天御 / 极验 GeeTest v4 全部实现。

本包是元包（meta-package），本身不含代码，仅聚合传递引用三个厂商实现包 + 抽象层。

安装

dotnet add package Bitzsoft.Integrations.Captcha.All

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

安装后自动引入：

• Bitzsoft.Integrations.Captcha -- 抽象层
• Bitzsoft.Integrations.Captcha.Aliyun -- 阿里云验证码 2.0
• Bitzsoft.Integrations.Captcha.Tencent -- 腾讯天御
• Bitzsoft.Integrations.Captcha.Geetest -- 极验 GeeTest v4

配置

appsettings.json -- 按需配置启用的厂商，未配置的厂商不会注册。

{
  "Captcha": {
    "Aliyun": {
      "AccessKeyId": "your-access-key-id",
      "AccessKeySecret": "your-access-key-secret",
      "SceneId": "your-scene-id",
      "AppKey": "your-app-key"
    },
    "Tencent": {
      "SecretId": "your-tencent-secret-id",
      "SecretKey": "your-tencent-secret-key",
      "CaptchaAppId": 1234567,
      "AppSecretKey": "your-captcha-app-secret-key"
    },
    "Geetest": {
      "CaptchaId": "your-captcha-id",
      "CaptchaKey": "your-captcha-key"
    }
  }
}

仅配置中存在的厂商节会被注册（section.Exists() 判定），无需删除不想用的厂商节以外的配置。

注册服务

using Microsoft.Extensions.DependencyInjection;

// 一行注册配置中存在的全部厂商 + 工厂
builder.Services.AddBitzsoftCaptchaAll(builder.Configuration.GetSection("Captcha"));

注册后以下服务均可用：

• ICaptchaProvider（每个厂商各注册一个实例）
• ICaptchaProviderFactory（按编码解析）
• IIntegrationProviderResolver<ICaptchaProvider>（跨领域统一解析入口；Factory 委托给它）

使用示例

通过工厂按编码解析（推荐）

风控引擎等消费方通常按配置动态选择厂商：

public class CaptchaService(ICaptchaProviderFactory factory)
{
    public async Task<bool> VerifyAsync(string providerCode, string token, string? userIp = null)
    {
        var provider = factory.GetProvider(providerCode);   // "aliyun" / "tencent" / "geetest"
        var result = await provider.VerifyAsync(new CaptchaVerifyRequest
        {
            Token = token,
            RemoteIp = userIp
        });
        return result.IsSuccess && result.Data!.Passed;
    }

    public IEnumerable<string> ListProviders() => factory.GetRegisteredCodes();
}

生成前端 SDK 凭证

var provider = factory.GetProvider(CaptchaProviderCode.Aliyun);
var challenge = await provider.GenerateAsync(new CaptchaGenerateRequest
{
    Type = CaptchaType.Intelligent,
    Scene = "login"
});

// challenge.Data.ScriptUrl / AppId / SceneId 返回给前端初始化

降级到自有验证码

第三方不可用时 GenerateAsync / VerifyAsync 返回 Fail，宿主可回退自有实现（如 SVG 图形码）：

var result = await provider.VerifyAsync(request);
if (!result.IsSuccess)
{
    // 第三方不可用 → 回退自有验证码
    return await FallbackToSvgCaptchaAsync(request);
}

请求审计

services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.SensitiveFields.Add("AccessKeySecret");
    opts.SensitiveFields.Add("SecretKey");
    opts.SensitiveFields.Add("AppSecretKey");   // 腾讯随请求体传输，务必脱敏
    opts.SensitiveFields.Add("CaptchaKey");
});
services.AddBitzsoftCaptchaAll(builder.Configuration.GetSection("Captcha"));

安全说明

• 密钥脱敏：所有厂商密钥字段均须加入 RequestLogging 脱敏配置，不落入审计日志
• 腾讯 AppSecretKey：随每个校验请求体明文传输（腾讯既定设计），务必脱敏
• fail-closed：阿里云响应异常时一律判失败
• token 一次性：三家厂商验证 token 校验后即失效

供应商编码对照表

相关包

• Bitzsoft.Integrations.Captcha -- 抽象层
• Bitzsoft.Integrations.Captcha.Aliyun -- 阿里云验证码 2.0 实现
• Bitzsoft.Integrations.Captcha.Tencent -- 腾讯天御实现
• Bitzsoft.Integrations.Captcha.Geetest -- 极验 GeeTest v4 实现