ZhileTime.Yop 2.2.4

ZhileTime.Yop

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

NuGet · CODING CI · 发布计划 · 变更记录

核心能力

• 支持 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，两个目标框架均执行完整自动化测试。

安装

当前源码版本：2.2.4。公开可用状态以 NuGet 和发布报告为准。

dotnet add package ZhileTime.Yop --version 2.2.4

配置与注册

{
  "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 源码审计
• 工程质量评估
• 测试与发布

构建、验证与发布

使用 global.json 指定的 SDK、.NET 8 运行时、PowerShell 7、Python 3 和固定版本 Gitleaks；CODING 镜像统一提供运行环境。

python build/ci_report.py docs-update
pwsh -NoProfile -File build/ci.ps1

统一入口执行脚本回归、文档/API 门禁、密钥与依赖审计、双框架测试、打包及内容核验。Windows 与 Hope 共用开发机时，通过 Hope 构建协调入口调用并声明实际产物根。

CI 发布分框架的 JUnit、HTML 通用报告、JSON/Markdown 摘要和原始制品归档。版本、安装示例与包表由源码生成，CHANGELOG 是人工评审的变更说明；CI 检查漂移，并生成 NuGet Release Notes 和 CODING 版本说明草稿，不直接改写或提交业务文档。

独立 CD 只发布主干上的稳定标签，默认只校验，正式推送需审批。包可下载且与原件逐文件一致后才记为 Available；部分发布必须恢复原构建归档，不能重新打包同版本。MR 合并后由 CODING 原生设置删除源分支。

• CODING 构建与 NuGet 发布：报告、审批、恢复与平台配置。
• CI/CD 对照审查：对照 Hope 的能力与证据边界。
• 测试与发布：协议测试、性能基准、官方目录漂移与接入方验收。

许可证与问题反馈

本项目采用 MIT。请通过 CODING 仓库 提交问题；报告中只提供脱敏 Request ID、版本和复现步骤，勿包含私钥、签名原文或商户业务数据。

发布维护

发布采用候选 MR、主干 CI 原件、注解标签、人工推包审批和公开内容核验；版本页在整批包可用后自动创建并回读。CD 不重新打包，恢复使用同一原件。新流程的平台启用和验收状态见发布手册。