Bitzsoft.Integrations.Captcha.Geetest 1.0.4

Bitzsoft.Integrations.Captcha.Geetest

极验 GeeTest v4 验证码实现包 -- 前端 gt.js 自渲染 + 服务端 /validate 二次校验。

功能特性

• 无感验证：前端 gt.js SDK 自渲染，验证通过后回传 lot_number + captcha_output + pass_token + gen_time
• 服务端二次校验：后端用 CaptchaKey 计算 sign_token（HMAC-SHA256），调极验 /validate 接口校验
• v4 签名：内置 GeeTest v4 sign_token 生成（HMAC-SHA256），无需引入极验 SDK
• 零厂商 SDK 依赖：裸 HttpClient 直调 REST API
• 请求审计：内置 RequestLogging 管道
• 构造校验：CaptchaId / CaptchaKey 缺失时构造即失败（fail-fast）

安装

dotnet add package Bitzsoft.Integrations.Captcha.Geetest

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

配置

appsettings.json

{
  "Captcha": {
    "Geetest": {
      "CaptchaId": "your-captcha-id",
      "CaptchaKey": "your-captcha-key",
      "ApiServer": "gcaptcha4.geetest.com"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Microsoft.Extensions.DependencyInjection;

builder.Services.AddBitzsoftGeetestCaptcha(
    builder.Configuration.GetSection("Captcha:Geetest"));

委托配置

builder.Services.AddBitzsoftGeetestCaptcha(options =>
{
    options.CaptchaId = "your-captcha-id";
    options.CaptchaKey = "your-captcha-key";
});

使用示例

生成前端 SDK 凭证

var provider = factory.GetProvider(CaptchaProviderCode.Geetest);
var result = await provider.GenerateAsync(new CaptchaGenerateRequest { Type = CaptchaType.Intelligent });
// result.Data.AppId → CaptchaId，前端 gt.js 初始化用

前端加载 gt4.js，用 CaptchaId 初始化，验证通过后拿到 lot_number + captcha_output + pass_token + gen_time。

服务端校验

[HttpPost("captcha/verify")]
public async Task<IActionResult> Verify([FromBody] VerifyDto dto)
{
    var provider = factory.GetProvider(CaptchaProviderCode.Geetest);
    var result = await provider.VerifyAsync(new CaptchaVerifyRequest
    {
        LotNumber = dto.LotNumber,          // 前端回传
        CaptchaOutput = dto.CaptchaOutput,  // 前端回传
        PassToken = dto.PassToken,          // 前端回传
        GenTime = dto.GenTime               // 前端回传
    });

    if (result.IsSuccess && result.Data!.Passed)
        return Ok();

    return BadRequest(result.ErrorMessage);
}

Token 字段作为 LotNumber 的兼容入口：若 LotNumber 为空则回退取 Token。

响应解析

result 字段：success 校验通过，其余失败。score（0~100）部分场景返回。失败时 ErrorCode 形如 VERIFY_fail。

请求审计

services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.SensitiveFields.Add("CaptchaKey");
});
services.AddBitzsoftGeetestCaptcha(builder.Configuration.GetSection("Captcha:Geetest"));

安全说明

• CaptchaKey：服务端签名密钥，通过环境变量注入，禁止硬编码；务必加入 RequestLogging 脱敏字段
• 验证数据一次性：lot_number + captcha_output 等校验后即失效

依赖

相关包

• Bitzsoft.Integrations.Captcha -- 抽象层
• Bitzsoft.Integrations.Captcha.Aliyun -- 阿里云验证码 2.0 实现
• Bitzsoft.Integrations.Captcha.Tencent -- 腾讯天御实现
• Bitzsoft.Integrations.Captcha.All -- 聚合包