调用USPS WEB API实现邮编转城市州查询时遇XML文档(2,2)错误

问题根源 #

你遇到的"XML文档(2, 2)存在错误"，核心原因是请求URL中的XML内容未正确编码，直接拼接的<、>等转义字符在GET请求中无法被USPS服务器正确解析，导致XML结构损坏；同时缺少参数校验，非法ZipCode也可能破坏XML格式。

修复代码 #

方案1：修复现有WebClient实现 #

修改CityStateLookupRequest方法，先构造完整XML再做URL编码，同时添加参数校验：

using System.Text.RegularExpressions;

private const string BaseURL = "https://secure.shippingapis.com/ShippingAPI.dll";
private WebClient wsClient = new WebClient();
public string USPS_UserID = "********";

public WebTools() { }
public WebTools(string New_UserID)
{
    USPS_UserID = New_UserID;
}

private byte[] GetDataFromSite(string USPS_Request)
{
    return wsClient.DownloadData(USPS_Request);
}

public byte[] CityStateLookupRequest(string ZipCode)
{
    // 校验ZipCode为5位数字格式
    if (!Regex.IsMatch(ZipCode, @"^\d{5}$"))
    {
        throw new ArgumentException("请输入有效的5位邮政编码");
    }

    // 构造完整XML字符串
    string xmlContent = $"<CityStateLookupRequest USERID=\"{USPS_UserID}\"><ZipCode ID=\"0\"><Zip5>{ZipCode}</Zip5></ZipCode></CityStateLookupRequest>";
    // 对XML内容进行URL编码，确保特殊字符被正确传输
    string encodedXml = Uri.EscapeDataString(xmlContent);
    // 拼接合法的请求URL
    string strUSPS = $"{BaseURL}?API=CityStateLookup&XML={encodedXml}";

    return GetDataFromSite(strUSPS);
}

方案2：替换为更可靠的HttpClient（推荐） #

WebClient已被标记为过时，改用HttpClient更稳定：

using System.Text.RegularExpressions;
using System.Net.Http;

private const string BaseURL = "https://secure.shippingapis.com/ShippingAPI.dll";
private readonly HttpClient _httpClient = new HttpClient();
public string USPS_UserID = "********";

public WebTools() { }
public WebTools(string New_UserID)
{
    USPS_UserID = New_UserID;
}

private async Task<byte[]> GetDataFromSiteAsync(string uspsRequest)
{
    return await _httpClient.GetByteArrayAsync(uspsRequest);
}

public async Task<byte[]> CityStateLookupRequestAsync(string ZipCode)
{
    if (!Regex.IsMatch(ZipCode, @"^\d{5}$"))
    {
        throw new ArgumentException("请输入有效的5位邮政编码");
    }

    string xmlContent = $"<CityStateLookupRequest USERID=\"{USPS_UserID}\"><ZipCode ID=\"0\"><Zip5>{ZipCode}</Zip5></ZipCode></CityStateLookupRequest>";
    string encodedXml = Uri.EscapeDataString(xmlContent);
    string requestUrl = $"{BaseURL}?API=CityStateLookup&XML={encodedXml}";

    return await GetDataFromSiteAsync(requestUrl);
}

额外排查要点 #

1. 确认USPS_UserID是生产环境有效ID：如果你用的是测试接口（shippingapis.com），需要替换为测试ID，生产接口（secure.shippingapis.com）用生产ID。
2. 手动验证请求：在浏览器中直接访问构造好的请求URL，查看USPS返回的具体错误XML，比如USERID无效、XML标签不闭合等，这些信息能更快定位问题。
3. 避免硬编码转义字符：直接构造XML字符串再编码，比手动拼接<、>更不易出错。

内容的提问来源于stack exchange，提问作者Xander Kim