XYS.Utils.Web 2.5.0

XYS.Utils.Web

Web 相关工具类库，提供基于 RestSharp 的高并发 REST 调用封装，以及带超时控制的文件下载客户端。

目标框架

net8.0 · net462 · netcoreapp3.1 · netstandard2.0 · netstandard2.1

依赖

• RestSharp 113.1.0
• RestSharp.Serializers.NewtonsoftJson 113.1.0
• XYS.Utils.Log4Net、XYS.Utils.Sys、XYS（同解决方案内项目引用）

HttpRestUtil

基于 RestSharp 的静态 REST 工具类，命名空间 XYS.Utils.Web。按 baseUrl 复用 RestClient（线程安全缓存），适用于高并发场景。

基本用法

using XYS.Utils.Web;

// 异步：对象体（内部自动序列化为 JSON）
var result = await HttpRestUtil.PostAsync<ResultDto>(
    "https://api.example.com", "/order/create", new { id = 1, name = "test" });

// 异步：直接传 JSON 字符串
var result2 = await HttpRestUtil.PostAsync<ResultDto>(
    "https://api.example.com", "/order/create", "{\"id\":1}");

// 同步（内部已做并发与超时隔离，失败会抛异常而非返回 null）
var result3 = HttpRestUtil.PostSync<ResultDto>(
    "https://api.example.com", "/order/create", new { id = 1 });

// GET：查询参数用匿名对象（按公共属性展开为 ?id=1&name=test）
var result4 = await HttpRestUtil.GetAsync<ResultDto>(
    "https://api.example.com", "/order/detail", new { id = 1, name = "test" });

// GET：查询参数也可用字典
var result5 = HttpRestUtil.GetSync<ResultDto>(
    "https://api.example.com", "/order/detail",
    new Dictionary<string, object> { ["id"] = 1 });

// GET：无查询参数时省略即可
var result6 = await HttpRestUtil.GetAsync<ResultDto>(
    "https://api.example.com", "/order/list");

// 表单提交（multipart/form-data）：服务端以表单字段接收，字段值本身可为 JSON 字符串
var result7 = HttpRestUtil.PostFormSync<ResultDto>(
    "https://api.example.com", "/gateway",
    new Dictionary<string, string>
    {
        ["interfaceName"] = "doctor",
        ["methodName"]    = "getPatientEmrContentById",
        ["data"]          = "{\"recordId\":\"xxx\",\"contentType\":\"html\"}",
    });
// 异步同理：await HttpRestUtil.PostFormAsync<ResultDto>(baseUrl, path, fields)

所有方法均支持 timeoutMs 参数（默认 30000ms）进行请求级超时隔离，异步方法额外支持 CancellationToken。GET 的查询参数支持匿名对象/实体（按公共可读属性展开）或 IDictionary，值为 null 的参数会自动跳过。PostFormSync<T> / PostFormAsync<T> 以 multipart/form-data 提交表单字段，适配「服务端以表单字段接收、字段值为 JSON 字符串」的统一网关类接口（字段 UTF-8 编码，Value 为 null 时按空串提交）。

序列化

内部统一使用 Newtonsoft.Json（通过 RestSharp.Serializers.NewtonsoftJson 配置），与 XYS.Utils.Sys 的 HttpJsonUtil 保持一致：响应实体上的 [JsonProperty] 特性生效，模型可在两个工具类间无差别复用（RestSharp v107+ 默认使用 System.Text.Json，不识别 [JsonProperty]，故在此显式切换）。

认证 Token 注入

为避免本程序集反向引用上层 UI/会话程序集，认证 Token 通过委托注入（通常在应用启动时设置一次）：

// 例如在 NovaUI 启动时：
HttpRestUtil.AuthTokenProvider = () => UserSession.Current?.Token;

设置后，每次请求会自动附加 Authorization: Bearer {token} 头；返回 null/空 时不附加（兼容未登录场景）。

自定义请求头

支持两种方式，可叠加使用（同名头以单次请求的值为准）：

// 方式一：全局默认头（启动时注入一次，附加到每次请求）
HttpRestUtil.DefaultHeaderProvider = () => new Dictionary<string, string>
{
    ["X-Api-Key"] = "your-api-key",
    ["X-Tenant"]  = "hospital-001",
};

// 方式二：单次请求头（各方法末尾的 headers 参数，POST/GET 同步异步均支持）
var result = await HttpRestUtil.PostAsync<ResultDto>(
    "https://api.example.com", "/order/create", new { id = 1 },
    headers: new Dictionary<string, string> { ["X-Request-Id"] = Guid.NewGuid().ToString() });

• 内部使用 AddOrUpdateHeader：同名头覆盖而非追加，因此单次请求头可覆盖全局默认头。
• Key 为空或 Value 为 null 的项自动跳过；全局头读取抛异常时不阻断请求。

TLS 证书校验

// 默认 true：兼容内网自签名/过期证书部署
// 生产环境建议置为 false 以启用标准 TLS 校验，防止中间人攻击
HttpRestUtil.AllowUntrustedCertificate = false;

高并发说明

• RestClient 按 baseUrl 通过 ConcurrentDictionary<string, Lazy<RestClient>> 缓存，保证同一地址仅创建一次实例，正确复用连接池。
• 超时在请求级设置，各请求互不干扰。
• PostSync 会监控线程池可用工作线程数，当可用线程过低时记录告警，并对"线程池饥饿假超时"与"真实网络超时"做区分诊断，便于高并发排障。

NovaWebClient

继承自 WebClient 的下载客户端，命名空间 XYS.Utils.Web，支持"无数据接收即超时取消"的文件下载。

using XYS.Utils.Web;

var client = new NovaWebClient { Timeout = 5000 }; // 毫秒
client.DownloadFileAsyncWithTimeout(new Uri("https://.../big.zip"), "big.zip", null);

• Timeout 单位为毫秒，作用于底层请求以及"无进度即超时"的空闲计时。
• 下载过程中每收到一次数据即重置计时；在超时时间内无任何数据到达则自动取消下载。

版本

当前版本 2.5.0。