Galosys.Foundation.Integration.Payment.Abstractions 26.7.31.1

Galosys.Foundation.Integration.Payment.Abstractions

成熟度: 🟢 稳定 — 统一支付抽象 + 插件路由，含完整测试覆盖

统一支付抽象模块，通过 IPaymentDispatcher + IPaymentChannel 插件路由实现多支付通道统一管理。代码只需依赖 IPaymentDispatcher，无需关心底层支付通道实现。

功能特性

• 插件路由 — PluginRegistry<IPaymentChannel, PaymentRequest> 自动按 Channel 字符串分发
• 统一 API — IPaymentDispatcher 提供创建/查询/退款/回调/关单 5 个操作
• 可扩展 — 实现 IPaymentChannel 接口即可接入新支付通道
• 内置 Mock — MockPaymentChannel 用于开发和测试环境
• 完整 DTO — 6 种支付场景（PagePay/FaceToFace/JsApi/H5/Native/App）、5 种订单状态

安装

<PackageReference Include="Galosys.Foundation.Integration.Payment.Abstractions" Version="x.x.x" />

快速开始

1. 注册服务

// 方式一：模块自动发现（推荐）
await Host.CreateDefaultBuilder()
    .UseModularization()
    .Locate()
    .RunAsync();

// 方式二：手动注册
services.AddPayment();
services.AddTransient<IPaymentChannel, AlipayChannel>();
services.AddTransient<IPaymentChannel, WeChatPayChannel>();

2. 创建支付

using Galosys.Foundation.Integration.Payment.Abstractions;

public class OrderService
{
    private readonly IPaymentDispatcher _payment;

    public OrderService(IPaymentDispatcher payment) => _payment = payment;

    // PC 网页支付
    public async Task<PaymentCreateResult> CreatePagePayAsync()
    {
        return await _payment.PayAsync(new PaymentCreateRequest
        {
            Channel = "alipay",          // 路由到 AlipayChannel
            OutTradeNo = "ORD001",
            Amount = 99.9m,
            Subject = "测试订单",
            PaymentType = PaymentType.PagePay,
            NotifyUrl = "https://example.com/notify",
            ReturnUrl = "https://example.com/return"
        });
    }

    // 微信小程序支付
    public async Task<PaymentCreateResult> CreateJsApiAsync()
    {
        return await _payment.PayAsync(new PaymentCreateRequest
        {
            Channel = "wechat",
            OutTradeNo = "ORD002",
            Amount = 199.0m,
            Subject = "小程序订单",
            PaymentType = PaymentType.JsApi,
            OpenId = "用户的OpenId"
        });
    }
}

3. 查询/退款/回调/关单

// 查询订单状态
var result = await _payment.QueryAsync("alipay", "ORD001");

// 退款
var refund = await _payment.RefundAsync(new PaymentRefundRequest
{
    Channel = "alipay",
    OutTradeNo = "ORD001",
    OutRefundNo = "REF001",
    RefundAmount = 50.0m,
    TotalAmount = 99.9m,
    Reason = "部分退款"
});

// 处理支付回调
var notify = await _payment.HandleNotifyAsync("alipay", new PaymentNotifyRequest
{
    RawBody = rawBody,
    Headers = headers
});

// 关闭订单
await _payment.CloseAsync("alipay", "ORD001");

4. 扩展支付通道

using Galosys.Foundation.Integration.Payment.Abstractions;

public class AlipayChannel : IPaymentChannel
{
    public string ChannelName => "alipay";

    public bool Supports(PaymentRequest request)
        => string.Equals(request.Channel, ChannelName, StringComparison.OrdinalIgnoreCase);

    public Task<PaymentCreateResult> CreateAsync(PaymentCreateRequest request)
    {
        // 调用支付宝 SDK
        return Task.FromResult(new PaymentCreateResult("ORD001", payUrl: "https://..."));
    }

    public Task<PaymentQueryResult> QueryAsync(string outTradeNo) => throw new NotImplementedException();
    public Task<PaymentRefundResult> RefundAsync(PaymentRefundRequest request) => throw new NotImplementedException();
    public Task<PaymentNotifyResult> HandleNotifyAsync(PaymentNotifyRequest request) => throw new NotImplementedException();
    public Task CloseAsync(string outTradeNo) => throw new NotImplementedException();
}

// 注册
services.AddTransient<IPaymentChannel, AlipayChannel>();

5. 开发/测试环境使用 Mock

services.AddPayment();
// MockPaymentChannel 已内置，无需额外注册，Channel 传 "mock" 即可

var result = await _payment.PayAsync(new PaymentCreateRequest
{
    Channel = "mock",
    OutTradeNo = "TEST001",
    Amount = 1.0m,
    Subject = "测试"
});

6. 日终对账

using Galosys.Foundation.Integration.Payment.Abstractions;

public class DailyReconciliationJob
{
    private readonly IReconciliationExecutor _executor;

    public DailyReconciliationJob(IReconciliationExecutor executor) => _executor = executor;

    public async Task RunAsync()
    {
        var yesterday = DateTime.Now.AddDays(-1).ToString("yyyy-MM-dd");

        // 分别对账支付宝和微信
        var alipayResult = await _executor.ExecuteAsync(yesterday, "alipay");
        var wechatResult = await _executor.ExecuteAsync(yesterday, "wechatpay");

        Console.WriteLine($"支付宝差异: {alipayResult.TotalDiffs}");
        Console.WriteLine($"微信差异: {wechatResult.TotalDiffs}");
    }
}

对账规则链自动执行四个阶段：

7. 账单拉取与标准化

// 渠道账单拉取
var rawFile = await channel.PullBillFileAsync(new BillPullRequest(
    "2024-01-20", BillType.Trade));

// 标准化为统一 DTO
var normalizer = new AlipayBillNormalizer();
var bills = await normalizer.NormalizeAsync(rawFile);
// bills[0].TotalAmount, bills[0].TradeStatus, bills[0].Platform...

支付场景（PaymentType）

订单状态（PaymentStatus）

核心类

依赖

• Galosys.Foundation.Core（PluginRegistry<TPlugin, TRequest>、IModule）