Bitzsoft.Integrations.Express.All 1.0.1

Bitzsoft.Integrations.Express.All

快递物流服务聚合包 -- 一次安装包含所有供应商实现，按配置自动注册。

功能特性

• 一次安装包含全部 7 家快递物流供应商实现，无需逐包引用
• 按配置节自动注册供应商，未配置的子节不会加载（避免多余 HTTP 客户端）
• 支持混合使用多个供应商（如快递鸟查询 + 顺丰函证通寄递）
• IExpressProvider 与 ISfLegalDocumentProvider 独立注册，互不冲突
• 各供应商共享统一的接口契约与模型，详见抽象包 Express

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express.All

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Express.All" Version="1.0.0" />

配置

appsettings.json

{
  "Express": {
    "Kdniao": {
      "EBusinessId": "你的商户ID",
      "AppKey": "你的应用密钥"
    },
    "Kuaidi100": {
      "Key": "你的授权码",
      "Customer": "你的顾客编码"
    },
    "SfLegal": {
      "MonthlyCardNo": "你的月结卡号",
      "CustomerCode": "你的顾客编码",
      "CheckWord": "你的校验码"
    },
    "ChinaPost": {
      "SenderNo": "协议客户号",
      "Authorization": "测试或生产授权码"
    },
    "Cainiao": {
      "AppKey": "菜鸟提供的对接码",
      "AppSecret": "双方约定的secretKey"
    },
    "Zto": {
      "AppKey": "你的AppKey",
      "AppSecret": "你的AppSecret"
    },
    "ShowApi": {
      "AppId": "你的AppId",
      "AppSecret": "你的AppSecret"
    }
  }
}

每个供应商使用独立的配置子节，仅注册配置中存在的子节，未配置的不会加载。各子节的详细字段见对应实现包文档。

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Express.All;

builder.Services.AddBitzsoftExpressAll(builder.Configuration);
// 等价于 builder.Services.AddBitzsoftExpressAll(builder.Configuration, "Express");

AddBitzsoftExpressAll 仅接受 IConfiguration（按子节存在性自动注册），无 Action 重载。如需委托配置单个供应商，请直接引用对应实现包的 AddBitzsoft* 方法。

请求审计

聚合包本身不发起请求，其引用的各实现包内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

// 宿主注册 IRequestLogStore 实现后，所有已注册供应商的出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 只控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("AppKey");
    opts.SensitiveFields.Add("CheckWord");
});
services.AddBitzsoftExpressAll(builder.Configuration);

使用示例

通用物流查询

using Bitzsoft.Integrations.Express.Interfaces;
using Bitzsoft.Integrations.Express.Models;
using Bitzsoft.Integrations.Core;

public class TrackingService
{
    private readonly IIntegrationProviderResolver<IExpressProvider> _providers;

    public TrackingService(IIntegrationProviderResolver<IExpressProvider> providers)
        => _providers = providers;

    public async Task TrackAsync(string trackingNumber)
    {
        var express = _providers.GetRequired("kdniao");
        ExpressTrackingInfo info = await express.TrackAsync(trackingNumber);
        Console.WriteLine($"状态: {info.State}, 轨迹数: {info.Traces.Count}");
    }
}

顺丰函证通寄递（独立接口，可与上述查询共存）

using Bitzsoft.Integrations.Express.Interfaces;

public class LegalService
{
    private readonly ISfLegalDocumentProvider _legal;

    public LegalService(ISfLegalDocumentProvider legal) => _legal = legal;

    public async Task TrackAsync(string documentId)
    {
        var result = await _legal.TrackDocumentAsync(documentId);
        Console.WriteLine($"函件 {result.DocumentId} 状态: {result.Status}");
    }
}

核心类型一览

包含的供应商

注意事项

• 多个 IExpressProvider 可同时注册，使用 IIntegrationProviderResolver<IExpressProvider> 按稳定 ID 解析
• ISfLegalDocumentProvider 独立注册，不与 IExpressProvider 冲突，可放心混用
• Provider 与 typed client 使用 Transient，底层 HttpMessageHandler 连接池由 IHttpClientFactory 管理并相互隔离

依赖

相关包

• Bitzsoft.Integrations.Express -- 抽象层
• Bitzsoft.Integrations.Express.Kdniao -- 快递鸟
• Bitzsoft.Integrations.Express.Kuaidi100 -- 快递100
• Bitzsoft.Integrations.Express.SfLegal -- 顺丰函证通
• Bitzsoft.Integrations.Express.ChinaPost -- 中国邮政
• Bitzsoft.Integrations.Express.Cainiao -- 菜鸟物流
• Bitzsoft.Integrations.Express.Zto -- 中通快递
• Bitzsoft.Integrations.Express.ShowApi -- 万维易源