Bitzsoft.Integrations.Express 1.0.0-alpha.10

Bitzsoft.Integrations.Express

快递物流服务抽象层 -- 统一接口定义与基础模型，屏蔽各快递供应商 API 差异。

功能特性

• 统一的 IExpressProvider 接口，封装轨迹查询、订阅推送、寄件下单、运费查询、电子面单、单号识别等核心操作
• 独立的 ISfLegalDocumentProvider 接口，面向顺丰函证通法律函件寄递场景
• 统一快递公司编码枚举（ExpressCarrierCode），各供应商内部维护平台编码到此枚举的映射
• 物流状态 ExpressTrackingState、法律函件状态 LegalDocumentStatus 统一枚举
• 不可变模型设计，所有属性使用 init 访问器
• ExpressException 统一异常，携带供应商名称与错误码，便于上层处理

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express

PackageReference

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

配置

本包为纯抽象层，不包含具体供应商配置，也不涉及 appsettings.json。请将各实现包（如 Express.Kdniao）注册到 DI 容器后，通过依赖注入消费 IExpressProvider。

注册服务

本包不提供 DI 扩展方法。请使用具体实现包的 AddBitzsoft* 方法注册服务，或直接使用聚合包 Express.All 一键注册全部供应商。

// 以快递鸟为例（实现包提供注册扩展）
using Bitzsoft.Integrations.Express.Kdniao;

builder.Services.AddBitzsoftKdniaoExpress(
    builder.Configuration.GetSection("Express:Kdniao"));

使用示例

物流轨迹查询

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

public class TrackingService
{
    private readonly IExpressProvider _express;

    public TrackingService(IExpressProvider express) => _express = express;

    public async Task ShowTrackingAsync(string trackingNumber)
    {
        // 查询单个运单轨迹（carrierCode 可选，部分供应商支持自动识别）
        ExpressTrackingInfo info = await _express.TrackAsync(trackingNumber);

        Console.WriteLine($"运单号: {info.TrackingNumber}");
        Console.WriteLine($"状态: {info.State}");

        // 轨迹按时间倒序排列
        foreach (var step in info.Traces)
        {
            Console.WriteLine($"[{step.Time:yyyy-MM-dd HH:mm}] {step.Location} {step.Description}");
        }
    }

    public async Task BatchTrackAsync(IEnumerable<string> numbers)
    {
        // 批量查询
        IReadOnlyList<ExpressTrackingInfo> results =
            await _express.BatchTrackAsync(numbers);
    }
}

单号识别快递公司

ExpressCarrierInfo carrier = await _express.DetectCarrierAsync("SF1234567890");
Console.WriteLine($"{carrier.CarrierName}（统一编码 {carrier.UnifiedCode}，置信度 {carrier.Confidence}）");

法律函件寄递（顺丰函证通）

using Bitzsoft.Integrations.Express.Interfaces;

public class LegalService
{
    private readonly ISfLegalDocumentProvider _legal;

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

    public async Task TrackDocumentAsync(string documentId)
    {
        LegalDocumentTrackingResult result =
            await _legal.TrackDocumentAsync(documentId);

        Console.WriteLine($"函件 {result.DocumentId} 当前状态: {result.Status}");
    }
}

核心类型一览

接口

IExpressProvider 方法

ISfLegalDocumentProvider 方法

模型

枚举

异常

请求审计

本包为抽象层，不发起 HTTP 请求。各实现包内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

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

依赖

无其他外部依赖。

相关包

• Bitzsoft.Integrations.Express.All -- 聚合包，一键注册全部供应商
• 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 -- 万维易源实现