ZhileTime.Yop 2.2.2

ZhileTime.Yop

面向易宝开放平台 YOP 的现代 .NET SDK。当前 2.2 版本按官方 yop-auth-v3、.NET SDK v4.0.1、Java SDK v4.4.15 和 PKCS8 密钥规范实现，并进一步收敛密钥资源生命周期与路径安全边界。

核心能力

• 支持 GET、POST Form、POST JSON 和 YOS 流式上传/下载。
• 提供 7 个领域 API 门面和 52 条当前官方路由，全部使用强类型请求与响应。
• 不保留已退出当前官方目录的历史领域方法；官方新增或自定义端点统一通过 IYopClient 扩展。
• 支持 AppKey 与 CustomerNo 两种 RSA2048 身份、请求级凭证和超时。
• 默认验证成功响应签名，并将非 2xx 响应映射为结构化异常。
• 提供 Webhook 表单解析、RSA/AES 数字信封解密和易宝平台验签。
• 集成 HttpClientFactory、连接池、有界响应读取、CRC64-ECMA 下载校验和 ActivitySource 诊断。

支持 net8.0 和 net10.0，两个目标框架均执行完整自动化测试。

安装

dotnet add package ZhileTime.Yop --version 2.2.0

配置与注册

{
  "Yop": {
    "ServerRoot": "https://openapi.yeepay.com/yop-center",
    "YosServerRoot": "https://yos.yeepay.com/yop-center",
    "AppKey": "app_xxx",
    "PrivateKey": "-----BEGIN PRIVATE KEY-----...",
    "YopPublicKey": "-----BEGIN PUBLIC KEY-----...",
    "ConnectTimeoutMilliseconds": 10000,
    "RequestTimeoutMilliseconds": 30000,
    "MaxConnectionsPerServer": 100,
    "PooledConnectionLifetimeSeconds": 300,
    "MaxResponseBodyBytes": 4194304,
    "RequireResponseSignature": true
  }
}

全局默认凭证使用 AppKey 或 CustomerNo，两者必须且只能配置一个。PrivateKey 必须是 RSA2048 PKCS8 私钥，YopPublicKey 是易宝 RSA2048 公钥。多租户系统如果每次调用都通过 YopRequestOptions 或 YopRequest 提供请求级凭证，可以不配置这四个默认凭证字段。生产密钥应由密钥管理服务或部署平台 Secret 注入，不得写入代码、日志或前端配置。

using Microsoft.Extensions.DependencyInjection;

services.AddYop(configuration);

AddYop 返回 IHttpClientBuilder，便于接入方添加日志、遥测或自定义消息处理器。SDK 不默认重试支付写请求；只有业务确认幂等契约后才能增加有界策略。

发起强类型调用

using ZhileTime.Yop.Apis;
using ZhileTime.Yop.Models;
using ZhileTime.Yop.Models.Trade;

public sealed class OrderQueryService(IYopTradeApi tradeApi)
{
    public async Task<YopTradeQueryOrderResponse> QueryAsync(
        string merchantNo,
        string orderId,
        CancellationToken cancellationToken)
    {
        var request = new YopTradeQueryOrderRequest(merchantNo, orderId)
        {
            ParentMerchantNo = merchantNo,
        };

        YopApiResult<YopTradeQueryOrderResponse> result =
            await tradeApi.QueryOrderAsync(request, cancellationToken: cancellationToken);

        if (!result.IsBusinessSuccess)
        {
            throw new InvalidOperationException(
                $"查询失败：{result.Code} {result.Message}; RequestId={result.RequestId}");
        }

        return result.Data;
    }
}

HTTP 成功不等于业务成功。YopApiResult<T> 同时保留强类型数据、业务码、Request ID、HTTP 状态和响应验签状态。

官方新增端点和自定义端点通过 IYopClient 原始入口调用：

var request = yopClient.CreateRequest(builder =>
{
    builder.AddParameter("merchantNo", merchantNo);
    builder.AddParameter("orderId", orderId);
});

YopResponse response = await yopClient.GetAsync(
    "/rest/v1.0/custom/query",
    request,
    cancellationToken);

当前 52 条现行接口不提供重复的原始重载，业务代码应优先使用领域门面。

文件流

using ZhileTime.Yop.Models;
using ZhileTime.Yop.Models.Merchant;

var uploadRequest = new YopMerchantUploadQualificationRequest
{
    MerQual = new YopUploadFile(filePath, "qualification.jpg", "image/jpeg"),
};

YopApiResult<YopMerchantUploadQualificationResponse> uploadResult =
    await merchantApi.UploadQualificationAsync(
        uploadRequest,
        cancellationToken: cancellationToken);

下载响应持有底层 HTTP 连接，必须释放。CopyToAndVerifyAsync 会在单次流式复制中校验 CRC64-ECMA：

using ZhileTime.Yop.Models.Billing;

var billRequest = new YopBillingDownloadTradeDayBillRequest(
    merchantNo,
    new DateOnly(2026, 8, 20));

await using var download = await billingApi.DownloadTradeDayBillAsync(
    billRequest,
    cancellationToken: cancellationToken);
await using var target = File.Create(temporaryPath);
await download.CopyToAndVerifyAsync(target, cancellationToken);

服务端文件名属于不可信输入。业务系统应写入临时文件，完成校验后再在受控目录内原子替换。

Webhook

using ZhileTime.Yop.Client;
using ZhileTime.Yop.Webhooks;

public sealed class WebhookService(IYopWebhookDecoder decoder)
{
    public string DecodeAndVerify(string rawFormBody, YopCredentials credentials)
    {
        YopWebhookEnvelope envelope = decoder.ParseEnvelope(rawFormBody);

        // 未验真标识只能用于选择候选凭证，不能据此更新业务状态。
        YopVerifiedWebhook webhook = decoder.DecodeAndVerify(envelope, credentials);
        return webhook.Payload;
    }
}

Payload 仅表示已完成数字信封解密和易宝平台验签。业务系统仍需校验商户、订单、金额和幂等性，并在事务落库后才能返回成功确认。

文档

• 快速接入
• 生产接入
• 排障手册
• API 路由
• API 版本治理
• 架构与质量不变量
• 官方 Java/.NET SDK 源码审计
• 工程质量评估
• 测试与发布

本地验证

dotnet restore
dotnet format ZhileTime.Yop.slnx --verify-no-changes --no-restore
dotnet build ZhileTime.Yop.slnx -c Release --no-restore
dotnet run --project tests/ZhileTime.Yop.Tests/ZhileTime.Yop.Tests.csproj -f net8.0 -c Release --no-build -- --minimum-expected-tests 163 --no-ansi --progress off
dotnet run --project tests/ZhileTime.Yop.Tests/ZhileTime.Yop.Tests.csproj -f net10.0 -c Release --no-build -- --minimum-expected-tests 163 --no-ansi --progress off
python tools/check_docs.py
python tools/check_handwritten_api.py
dotnet pack src/ZhileTime.Yop/ZhileTime.Yop.csproj -c Release --no-build -o nupkg
python tools/check_package.py nupkg/ZhileTime.Yop.*.nupkg

完整的离线、在线和发布验证边界见测试与发布。