Bitzsoft.Integrations.Express.Kdniao 1.0.0-alpha.10

Bitzsoft.Integrations.Express.Kdniao

快递鸟物流服务实现 -- 基于快递鸟 API 覆盖 2000+ 快递公司，支持全量物流操作。

功能特性

• 覆盖即时查询、物流跟踪订阅、上门取件、电子面单、智选物流、单号识别等全量 API
• 认证方式：EBusinessID + AppKey，签名 = Base64(MD5(RequestData + AppKey))
• 支持批量轨迹查询、订阅推送回调
• 统一异常处理，供应商错误码自动映射为 ExpressException
• 顺丰等需要校验的运单支持传入 phoneSuffix（手机号后四位）
• 实现 IExpressProvider 统一契约，可无缝替换其他供应商实现

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express.Kdniao

PackageReference

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

配置

appsettings.json

{
  "Express": {
    "Kdniao": {
      "EBusinessId": "你的商户ID",
      "AppKey": "你的应用密钥",
      "BaseUrl": "https://api.kdniao.com/api/",
      "HttpClientName": "KdniaoExpress"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Express.Kdniao;

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

委托配置

builder.Services.AddBitzsoftKdniaoExpress(options =>
{
    options.EBusinessId = "your_id";
    options.AppKey = "your_key";
});

请求审计

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftKdniaoExpress(options => { /* ... */ });

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

使用示例

物流轨迹查询

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 TrackAsync(string trackingNumber)
    {
        // 查询单个运单轨迹
        ExpressTrackingInfo info = await _express.TrackAsync(trackingNumber);
        Console.WriteLine($"状态: {info.State}, 轨迹数: {info.Traces.Count}");

        foreach (var step in info.Traces)
            Console.WriteLine($"[{step.Time:yyyy-MM-dd HH:mm}] {step.Description}");

        // 顺丰运单需传入手机号后四位
        var sfInfo = await _express.TrackAsync("SF1234567890", carrierCode: "SF", phoneSuffix: "1234");

        // 批量查询
        IReadOnlyList<ExpressTrackingInfo> batch =
            await _express.BatchTrackAsync(new[] { "YT001", "ZTO002" });
    }
}

订阅轨迹推送

ExpressSubscriptionResult sub = await _express.SubscribeAsync(
    trackingNumber: "YT001",
    callbackUrl: "https://yourapp.com/express/callback");
// 状态变更时快递鸟会向 callbackUrl 推送

核心类型一览

支持的操作

依赖

注意事项

• 顺丰查询需传入 phoneSuffix 参数（手机号后四位）
• 快递鸟有调用频率限制（3000 次/小时），建议在业务层实现缓存
• BatchTrackAsync 通过逐条调用实现，大批量查询建议控制并发数
• IExpressProvider 使用 TryAddSingleton 注册，如需同时注册多个供应商请单独引用并自行解析

相关包

• Bitzsoft.Integrations.Express -- 抽象层
• Bitzsoft.Integrations.Express.All -- 聚合包
• Bitzsoft.Integrations.Express.Kuaidi100 -- 快递100
• Bitzsoft.Integrations.Compatibility -- 基础工具库