EJoyer.SDK.AddressService 1.0.0

EJoyer.SDK.AddressService

项目概述

EJoyer.SDK.AddressService 是 EJoyer 平台的地址服务 SDK，封装了与地址服务 API 的交互逻辑。该 SDK 基于 IHttpClientFactory 构建高效的 HTTP 通信，提供全球地址管理、DHL 偏远地址检测、地址有效性校验、日本邮政仕分番号查询以及全球国家/地区信息查询等功能。

核心功能

应用场景

• 跨境电商物流系统的地址管理与验证
• 国际快递（DHL）偏远地区附加费检测
• 全球收件地址的标准化录入与校验
• 日本市场物流配送的仕分番号查询

运行环境

依赖项

技术架构

┌─────────────────────────────────────────────────┐
│              调用方应用程序                        │
├─────────────────────────────────────────────────┤
│  ServiceCollectionExtensions （服务注册入口）       │
│       ↓ 注册 IAddressClient → AddressClient      │
├─────────────────────────────────────────────────┤
│  IAddressClient （接口抽象层）                     │
│       ↓ 实现                                     │
│  AddressClient : ApiClientBase （HTTP 通信层）     │
│       ↓ 继承                                     │
│  ApiClientBase （IHttpClientFactory 封装）         │
├─────────────────────────────────────────────────┤
│  EJoyer Address API Server                       │
│  (http://api.address.yjlglobal.cn:8811/)         │
└─────────────────────────────────────────────────┘

快速开始

1. 安装 NuGet 包

通过 NuGet 包管理器安装：

dotnet add package EJoyer.SDK.AddressService

2. 注册服务

在 Program.cs 或 Startup.cs 中注册地址服务：

using EJoyer.SDK.AddressService;

var builder = WebApplication.CreateBuilder(args);

// 注册地址服务客户端
builder.Services.EJoyerAddressService();

var app = builder.Build();
app.Run();

注册完成后，IAddressClient 将以 Transient 生命周期注入到 DI 容器中，同时会注册名为 AddressServiceClient 的 HttpClient，其基础地址为 http://api.address.yjlglobal.cn:8811/。

集成示例

以下示例展示 IAddressClient 接口的所有功能用法：

using EJoyer.SDK.AddressService;
using EJoyer.SDK.Common;

public class AddressServiceExample(IAddressClient addressClient)
{
    // API 令牌，由平台分配
    private const string ApiToken = "your-api-token-here";

    /// <summary>
    /// 示例1：获取单个地址
    /// </summary>
    public async Task GetAddressAsync()
    {
        // 通过地址Key查询单个地址信息
        var result = await addressClient.GetAsync(
            apiToken: ApiToken,
            addressKey: "abc123def456ghi789jkl012mno345p"
        );

        if (result.Success)
        {
            var address = result.Data!;
            Console.WriteLine($"收件人：{address.FullName}");
            Console.WriteLine($"国家：{address.Country}（{address.CountryISO}）");
            Console.WriteLine($"地址：{address.Street1} {address.Street2}");
            Console.WriteLine($"城市：{address.City}，省份：{address.Province}");
            Console.WriteLine($"邮编：{address.PostalCode}");
        }
        else
        {
            Console.WriteLine($"查询失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例2：批量获取地址
    /// </summary>
    public async Task GetMultipleAddressesAsync()
    {
        // 通过多个地址Key批量查询地址信息
        var addressKeys = new string[]
        {
            "abc123def456ghi789jkl012mno345p",
            "xyz789uvw456rst123opq012mno345p"
        };

        var result = await addressClient.GetsAsync(
            apiToken: ApiToken,
            addressKeyArray: addressKeys
        );

        if (result.Success)
        {
            foreach (var address in result.Data!)
            {
                Console.WriteLine($"[{address.AddressKey}] {address.FullName} - {address.Country}");
            }
        }
        else
        {
            Console.WriteLine($"批量查询失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例3：创建新地址（必填 + 可选字段）
    /// </summary>
    public async Task CreateAddressAsync()
    {
        // 创建新的收件地址，fullName/country/street1/postalCode 为必填项
        var result = await addressClient.CreateAsync(
            apiToken: ApiToken,
            fullName: "张三",                // 必填：收件人全名
            country: "CN",                   // 必填：国家ISO编码
            street1: "科技园路100号",         // 必填：街道地址1
            postalCode: "518000",            // 必填：邮政编码
            isUseDHLDCTService: true,        // 必填：是否启用DHL偏远地址检测
            company: "某某科技有限公司",      // 可选：公司名称
            province: "广东省",              // 可选：省份
            city: "深圳市",                  // 可选：城市
            street2: "A栋5楼",              // 可选：街道地址2
            email: "zhangsan@example.com",   // 可选：邮箱
            phoneNumber: "+8613800138000"    // 可选：电话号码
        );

        if (result.Success)
        {
            var created = result.Data!;
            Console.WriteLine($"地址创建成功，Key：{created.AddressKey}");
        }
        else
        {
            Console.WriteLine($"创建失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例4：DHL偏远地址检测
    /// </summary>
    public async Task CheckDHLDCTAsync()
    {
        // 检测目标地址是否为DHL偏远地区，并获取运费估算
        var packages = new List<Package>
        {
            new(weight: 5, length: 30, width: 20, height: 10),  // 5kg，30x20x10cm
            new(weight: 3, length: 25, width: 15, height: 8)    // 3kg，25x15x8cm
        };

        var result = await addressClient.DHLDCTAsync(
            apiToken: ApiToken,
            country: "AU",                   // 目的国家
            postalCode: "2000",              // 目的邮编
            city: "Sydney",                  // 目的城市（可选）
            packages: packages               // 包裹尺寸信息（可选）
        );

        if (result.Success)
        {
            var dhl = result.Data!;
            Console.WriteLine($"是否偏远地区：{(dhl.IsRemote ? "是" : "否")}");
            Console.WriteLine($"目的城市：{dhl.DestinationCity}");
            Console.WriteLine($"总费用：{dhl.TotalPrice}");
            Console.WriteLine($"体积重量：{dhl.VolumeWeight}");
            Console.WriteLine($"燃油附加费：{dhl.FuelSurcharge}");
            Console.WriteLine($"偏远地区附加费：{dhl.RemoteAreaDelivery}");
        }
        else
        {
            Console.WriteLine($"DHL检测失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例5：全球地址有效性搜索
    /// </summary>
    public async Task MatchingAddressAsync()
    {
        // 根据国家、城市、邮编搜索有效地址记录，用于地址校验和补全
        var result = await addressClient.MatchingAsync(
            apiToken: ApiToken,
            country: "US",                   // 国家编码
            city: "New York",                // 城市名称
            postalCode: "10001"              // 邮政编码
        );

        if (result.Success)
        {
            foreach (var record in result.Data!)
            {
                Console.WriteLine($"邮编：{record.PostalCode}，城市：{record.City}，" +
                                  $"省份：{record.Province}，县：{record.County}");
                Console.WriteLine($"经度：{record.Longitude}，纬度：{record.Latitude}");
            }
        }
        else
        {
            Console.WriteLine($"地址匹配失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例6：日本邮政仕分番号查询
    /// </summary>
    public async Task QueryJapanPostalBatchNumberAsync()
    {
        // 根据日本邮编查询仕分番号，用于日本国内物流分拣
        var result = await addressClient.QueryJapanPostalBatchNumberAsync(
            apiToken: ApiToken,
            postalCode: "1000001"            // 日本邮政编码
        );

        if (result.Success)
        {
            Console.WriteLine($"仕分番号：{result.Data}");
        }
        else
        {
            Console.WriteLine($"查询失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例7：获取大洲列表
    /// </summary>
    public async Task GetAreasAsync()
    {
        // 获取全球大洲列表
        var result = await addressClient.GetAreasAsync(
            apiToken: ApiToken
        );

        if (result.Success)
        {
            foreach (var area in result.Data!)
            {
                Console.WriteLine($"大洲：{area}");
            }
        }
        else
        {
            Console.WriteLine($"获取大洲列表失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例8：获取全球国家列表
    /// </summary>
    public async Task GetCountryListAsync()
    {
        // 获取全球国家详细信息列表，包含省份、城市等层级数据
        var result = await addressClient.GetCountryListAsync(
            apiToken: ApiToken
        );

        if (result.Success)
        {
            foreach (var country in result.Data!)
            {
                Console.WriteLine($"国家：{country.DefaultCNName} / {country.DefaultENName}");
                Console.WriteLine($"  ISO编码：{country.ISOCode}，区号：{country.InternationalTelephoneCode}");
                Console.WriteLine($"  地区：{country.RegionalLocation}，邮编规则：{country.PostalCodeRules}");
                Console.WriteLine($"  省份数量：{country.Provinces.Count}");
            }
        }
        else
        {
            Console.WriteLine($"获取国家列表失败：{result.Message}");
        }
    }

    /// <summary>
    /// 示例9：按ISO编码查询国家
    /// </summary>
    public async Task GetCountryByIsoCodeAsync()
    {
        // 根据ISO编码查询单个国家的详细信息
        var result = await addressClient.GetCountryAsync(
            apiToken: ApiToken,
            isoCode: "CN"                    // 国家ISO编码
        );

        if (result.Success)
        {
            var country = result.Data!;
            Console.WriteLine($"国家：{country.DefaultCNName} / {country.DefaultENName}");
            Console.WriteLine($"ISO编码：{country.ISOCode}");
            Console.WriteLine($"国际区号：{country.InternationalTelephoneCode}");
            Console.WriteLine($"邮编规则：{country.PostalCodeRules}");

            // 遍历省份信息
            foreach (var province in country.Provinces)
            {
                Console.WriteLine($"  省份：{province.Label}，时区：{province.TimeZone}");
                Console.WriteLine($"  城市：{string.Join(", ", province.City)}");
            }
        }
        else
        {
            Console.WriteLine($"查询国家失败：{result.Message}");
        }
    }
}

API 接口一览

所有接口均通过 APIToken 请求头进行身份认证。

数据模型

AddressDto - 地址信息

CountryDto - 国家信息

DHLDCTDto - DHL偏远地址检测结果

AddressRecord - 地址匹配记录

统一响应格式

所有接口均返回 APIResponse<T> 类型，继承自 BaseResponse：

注意事项

1. API 令牌：所有接口调用均需传入 apiToken 参数，令牌通过 HTTP 请求头 APIToken 传递至服务端。
2. 参数校验：SDK 内部对所有必填参数进行了前置校验，若参数为空会立即返回错误响应，不会发起 HTTP 请求。
3. 异常处理：SDK 捕获了 HttpRequestException 及通用 Exception，异常信息通过 APIResponse.Message 返回，不会抛出至调用方。
4. HttpClient 管理：使用 IHttpClientFactory 管理连接池，避免 Socket 耗尽问题，请勿手动创建 HttpClient。
5. 服务注册：通过 services.EJoyerAddressService() 扩展方法完成注册，内部注册了名为 AddressServiceClient 的命名 HttpClient。