ZhileTime.Hope.Yop 1.1.0

ZhileTime.Hope.Yop

一个面向 YOP（易宝开放平台）的 .NET 客户端库（已完成 DI + Options + HttpClientFactory + Polly 重试的现代化改造）。

目标：让你在业务项目里通过依赖注入拿到 IYopClient / IYopRsaClient，创建 YopRequest 后直接调用 API。

运行环境

• 目标框架：net10.0
• 推荐：使用 .NET SDK 10（或与你项目一致的 SDK）

本地开发

• 解决方案文件：ZhileTime.Hope.Yop.slnx
• 构建：dotnet build -c Release /p:TreatWarningsAsErrors=true
• 测试：dotnet test -c Release
• 仓库根目录的 .tools/ 为本地 dotnet tool 安装目录（已在 .gitignore 忽略），无需提交

如何引入（外部项目）

NuGet

在你的业务项目 .csproj 中添加：

<ItemGroup>
  <PackageReference Include="ZhileTime.Hope.Yop" Version="x.y.z" />
</ItemGroup>

然后在 Program.cs / Startup.cs 里注册 DI（见下文）。

快速开始（推荐：DI）

1) appsettings.json

{
  "Yop": {
    "ServerRoot": "https://open.yeepay.com/yop-center",

    // 非 RSA（AES/HMAC）模式：
    "AppKey": "your-app-key",
    "AesSecretKey": "your-aes-secret",

    // 如果你用“商户身份（HMAC）”而不是开放应用（AES），请提供：
    // "HmacSecretKey": "your-hmac-secret",

    // 可选：
    "IgnoreServerCertificateErrors": false,
    "ConnectTimeout": 30000,
    "ReadTimeout": 60000,

    "Retry": {
      "Enabled": true,
      "MaxRetries": 3,
      "BaseDelayMs": 200,
      "MaxDelayMs": 5000,
      "UseJitter": true,
      "RetryOnStatusCodes": [408, 429, 500, 502, 503, 504]
    }
  }
}

注意：

• ReadTimeout <= 0 表示不主动取消（不限时）。
• IgnoreServerCertificateErrors=true 仅用于兼容历史行为与开发调试；生产环境强烈建议设置为 false。
• SecretKey 的选择规则：配置了 AppKey 时默认使用 AesSecretKey；否则使用 HmacSecretKey。

2) 注册服务

using Microsoft.Extensions.DependencyInjection;

// ...
services.UseYop(configuration);

3) 调用

public sealed class DemoService
{
    private readonly IYopClient _yop;

    public DemoService(IYopClient yop) => _yop = yop;

    public async Task<string> PingAsync(CancellationToken ct)
    {
      // 推荐：用扩展方法一边创建一边配置（更 .NET）
      var req = _yop.CreateRequest(r =>
      {
        r.AddParameter("foo", "bar");
        r.SignReturn = true;
        // r.IsEncrypted = true; // 如需请求加密
        // r.Format = "json";   // json/xml，默认 json
      });

        return await _yop.PostForStringAsync("/rest/v1.0/your-api", req, ct);
    }
}

如果你想拿到结构化响应（验签结果也会回填到 ValidSign）：

public async Task<bool> CallAndCheckAsync(CancellationToken ct)
{
  var req = _yop.CreateRequest(r =>
  {
    r.AddParameter("foo", "bar");
    r.SignReturn = true;
  });

  var resp = await _yop.PostAsync("/rest/v1.0/your-api", req, ct);
  return resp.IsSuccess && resp.ValidSign;
}

多租户动态切换（每次请求不同凭证）

如果你需要在同一个进程内按租户切换 appKey/secretKey（或切换商户身份的 customerNo/hmacSecretKey），推荐仍然通过 client 扩展方法创建 YopRequest，这样可以复用 DI 注入的默认配置（ServerRoot/Timeout/重试等），同时只覆盖本次请求的凭证。

开放应用（AES）模式：

var req = _yop.CreateRequest(appKey, aesSecretKey, r =>
{
  r.AddParameter("foo", "bar");
});

商户身份（HMAC/Blowfish）模式：

var req = _yop.CreateMerchantRequest(customerNo, hmacSecretKey, r =>
{
  r.AddParameter("foo", "bar");
});

RSA 模式

在 RSA 模式下，签名使用私钥、验签使用 YOP 公钥。

{
  "Yop": {
    "ServerRoot": "https://open.yeepay.com/yop-center",
    "AppKey": "your-app-key",
    "RsaPrivateKey": "-----BEGIN PRIVATE KEY-----...",
    "YopPublicKey": "-----BEGIN PUBLIC KEY-----..."
  }
}

注入并使用 IYopRsaClient：

public sealed class RsaDemoService
{
    private readonly IYopRsaClient _yop;

    public RsaDemoService(IYopRsaClient yop) => _yop = yop;

    public Task<string> CallAsync(CancellationToken ct)
    {
    var req = _yop.CreateRequest(r =>
    {
      // RSA 的 SecretKey/YopPublicKey 默认会从 options 注入到 request
      // 你也可以按需覆盖：r.SecretKey = "..."; r.YopPublicKey = "...";
    });
        return _yop.PostRsaStringAsync("/rest/v1.0/your-api", req, ct);
    }
}

说明

• 对外推荐仅使用：services.UseYop(...) + IYopClient / IYopRsaClient + YopRequest + 响应模型（YopResponse 等）+ 异常（YopClientException 等）。
• 加密、签名、HTTP 细节与各类工具方法已收敛为内部实现（internal），不再作为公共 API 承诺。
• 重试基于 Polly：默认会对网络异常、内部超时（ReadTimeout）、以及指定 HTTP 状态码进行重试。

破坏性变更提示（近期重构，影响使用方代码）

• YopRequest：已移除 Java Bean 风格的 Get*/Set*/Is* 方法，统一改为 .NET 属性（例如 Format/Method/ServerRoot/IsEncrypted/SignReturn/...）。

• YopRequest：参数相关 API 也已收敛并更名：

  • AddParam(...) → AddParameter(...)
  • GetParamValue(...) → TryGetValue(key, out value)（不再用空字符串表示失败）
  • GetParam(...) → TryGetValues(key, out values) 或 req[key]
  • RemoveParam(...) → RemoveParameter(...)
  • Encoding(...) → EncodeParameters(...)

• YopResponse：IsSuccess() 改为只读属性 IsSuccess。

• RegexUtil：GetFirstCaptureOrEmpty(...) 改为 TryGetFirstCapture(pattern, input, out value)。

• HTTP 请求默认行为：不再强制写入旧版 Accept/User-Agent，也不再强制使用 HTTP/1.0 或手动控制 Connection: close/keep-alive；改为遵循 HttpClient 的标准默认行为。若你的网关/服务端依赖这些请求头，请在调用时通过 headers 参数显式传入，或配置 HttpClient.DefaultRequestHeaders。

如果你从旧版本升级，最简单的做法是：

1. 把所有 req.GetXxx()/SetXxx()/IsXxx() 替换成 req.Xxx 属性访问

2. 把 AddParam/RemoveParam/Encoding 这类 API 按上面的对照表替换

3. 参数读取建议：

• 可选参数：优先用 TryGetValue(key, out value)
• 多值参数：用 TryGetValues(key, out values) 或 req[key]（不存在时返回空集合）