别再折磨 HttpClient 了！全新 HttpAgent 横空出世，重新定义 .NET 远程请求！

让 HTTP 请求所见即所得。

每个 .NET 开发者，都有一段和 HttpClient 相爱相杀的记忆：

• 每发一个请求，都要重写一遍：new HttpClient()、拼接 URL、拼 QueryString、塞 Headers、判 Content-Type；
• 一个不留神，把 HttpClient 随手 new 在了 using 里，生产环境 Socket 耗尽，压测一跑就崩；
• 超时、重试、退避、熔断？对不起，要么自己手搓，要么再引一个 Polly 全家桶；
• 同事甩来一段 curl 让你"复现一下"，你只能逐行翻译成 C#，翻译错了还查半天；
• 想知道请求到底发出去什么、响应是什么，只能开 Fiddler 抓包，抓半天找不到自己那条；
• 文件上传下载、进度条、SSE、长轮询、WebSocket、SOAP、OData、Token 自动刷新……每一样都要另起炉灶。

写到最后你会发现：真正难的从来不是"发出一个请求"，而是把请求这件事做对、做全、做得可维护。

今天的主角，就是来终结这些折磨的 —— HttpAgent。

一句话认识 HttpAgent

HttpAgent 是一个高性能、灵活、易用的 .NET HTTP 开源库，核心理念只有一句：让 HTTP 请求所见即所得。

它有几组让人无法拒绝的硬指标：

• 零第三方依赖：一个 NuGet 包开箱即用，不需要 Polly、不需要 Flurl，什么都不需要；
• 全平台覆盖：Console / Web / WASM / WinForms / WPF / MAUI，.NET 8+ 通吃；
• 工业级质量：98% 测试覆盖率，每一次发版都经过严格的回归验证；
• 功能全家桶：重试、超时、熔断、配额、ETag 缓存、Access Token 自动管理……全部内置，装上即用。

五种姿势，任你选择

HttpAgent 最"上头"的设计，是把"发请求"这件事拆成了五种写法。你喜欢哪种就用哪种，一个项目里混着用也毫无违和。

姿势一：谓词方式，一行直达

12345

// 一行代码获取网站内容var content = await httpRemoteService.GetAsStringAsync("https://api.example.com/");// 泛型重载，直接拿强类型结果var user = await httpRemoteService.GetAsAsync<User>("https://api.example.com/user/1");

姿势二：构建器方式，链式拼装

12345

var result = await httpRemoteService.SendAsync<string>(    HttpRequestBuilder.Post("https://api.example.com/login")        .SetJsonContent(new { account = "admin", password = "123456" })        .SetTimeout(TimeSpan.FromSeconds(30))        .Profiler());   // 顺手开启请求分析工具

姿势三：声明式请求，接口即 API

12345678

public interface IUserApi : IHttpDeclarative{    [Get("https://api.example.com/user/{id}")]    Task<User> GetUserAsync(int id);    [Post("https://api.example.com/user"), Profiler]    Task<User> CreateUserAsync([Body] User user);}

注册之后直接注入使用，调用远程接口就像调用本地方法。路径模板、查询参数、请求体、表单、多部分上传，全部用特性声明，代码干净得不像话。

1234

services.AddHttpRemote(builder =>{    builder.AddHttpDeclarative<IUserApi>();});

姿势四：从 cURL 发送，粘贴即用

你一定经历过这种场景：第三方平台的接口文档里只有一段 curl，客服甩给你、测试甩给你，甚至老板都甩给你："就按这个来"。

以前，你得把这段 curl 逐字翻译成 C#。现在：

123456789

var result = await httpRemoteService.SendAsStringAsync(    HttpRequestBuilder.FromCurl("""        curl -k -X POST 'https://api.example.com/order?query1=10&query2=hello' \        -H 'Content-Type: application/json' \        -d '{          "id": 1,          "name": "sample"        }'        """));

HttpAgent 内置了 cURL 解析引擎，支持 -X、-H、-d、-F、-u、--data-urlencode、--max-time、--http2 等常用选项，文件上传、URL 编码表单、Basic 认证统统不在话下，还支持自定义扩展标志。

cURL 原文粘贴进去，剩下的交给引擎。 这不仅对人友好，对 AI 也极其友好 —— AI 生成的 curl 命令，不再需要人工翻译成代码。

姿势五：从 JSON 发送，配置即请求

如果觉得链式调用还是啰嗦，那就把请求写成 JSON：

123456789101112

var result = await httpRemoteService.SendAsStringAsync(    HttpRequestBuilder.FromJson("""        {            "url": "https://api.example.com/order",            "method": "POST",            "queries": { "page": 1, "size": 10 },            "headers": { "Content-Type": "application/json" },            "auth": { "type": "bearer", "token": "xxx" },            "timeout": 5000,            "data": { "id": 1, "name": "sample" }        }        """));

地址、基地址、查询参数、Header、Cookie、超时、认证（Bearer / Basic / Digest）、请求体、多部分上传、是否开启分析工具……全部 JSON 化。请求配置可以存进数据库、配置文件，甚至由 AI 动态生成。

一个包，装下整个 HTTP 工程化

很多"轻量"的 HTTP 库，轻到最后什么都得自己补。HttpAgent 的思路正相反：一个包，把 HTTP 工程化需要的一切都内置了，而且没有任何第三方依赖。

• 弹性与容错：重试、指数退避、超时、熔断降级，一行 SetRetry 就能拉起一整套韧性策略；
• Access Token 自动管理：自动获取、过期自动刷新、401 自动重试，Token 注入 Header / Query / Cookie 任你配置，对接微信、企业微信等第三方平台时，再也不用手写 Token 定时器；
• 配额与 ETag 缓存：日 / 周 / 月 / 终身调用额度窗口，304 缓存复用，省流量又防超限；
• 实时通信：SSE、长轮询、WebSocket、IAsyncEnumerable<T> 流式响应，一应俱全；
• 文件传输：上传下载、多线程分块下载、进度回调、控制台进度条，RFC 2047 / RFC 5987 等文件名编码自动解析；
• 网关与代理：HttpContext 一行转发，自带代理网关能力；
• 测试与调试：请求 / 响应断言、Mock 模拟测试、压力测试，内置即用；
• 数据格式全覆盖：JSON、JSON Lines、MessagePack、XML、HTML、SOAP（WebService）、OData 全支持；
• 自动解压：gzip / deflate / brotli / zstd 响应自动解压，无需关心压缩细节。

随便举一个例子，一行开启"带指数退避的智能重试"：

12345

HttpRequestBuilder.Get("https://api.example.com/order/1")    .SetRetry(options => options        .SetMaxRetries(3)        .SetUseExponentialBackoff(true)        .AddRetryStatusCodes(408, 429, 500, 502, 503, 504));

内置工业级流量分析引擎：黑盒变白盒

调试第三方接口最痛苦的是什么？看不见。

请求到底发了什么 Header？Body 编码对不对？为什么响应是空？

HttpAgent 内置工业级 HTTP 流量分析引擎（Profiler），在任意请求后追加一个 .Profiler()，终端立即输出完整、带颜色高亮的请求与响应报文：

12

await httpRemoteService.GetAsync("https://api.example.com/order/1",    builder => builder.Profiler());

请求方法、完整 URL、所有请求头、请求体、响应状态码、响应头、响应体、耗时……一眼看穿，所见即所得。以前抓包半小时，现在一行代码。

对 AI 最友好的 .NET HTTP 库

2026 年，AI 编程已经变成日常。而 HttpAgent，可能是目前对 AI 最友好的 .NET HTTP 库：

1. llms.txt 原生支持：官方文档站内置 llms.txt 与 llms-full.txt 两份 AI 友好文件（中英文皆有），Claude Code、Codex 等 AI 助手可以一次性读取全部文档，不用逐页抓取网页。把 llms-full.txt 放进项目的 CLAUDE.md / AGENTS.md，AI 写出的 HttpAgent 代码几乎不会错。
2. 声明式接口是 AI 的天然游乐场：给 AI 一个接口定义，它就能稳定生成带特性注解的完整 API 客户端，可读性极强，代码审查成本极低。
3. cURL / JSON 即代码：AI 输出的 curl 命令、JSON 配置，粘贴进来直接就是可运行的请求，翻译成本为零。

三步上手

12345

# 1. 安装（任意 .NET 8+ 应用）dotnet add package HttpAgent# Web 应用额外提供 HttpContext 转发能力dotnet add package HttpAgent.AspNetCore

12

// 2. 注册服务builder.Services.AddHttpRemote();

12

// 3. 开干var user = await httpRemoteService.GetAsAsync<User>("https://api.example.com/user/1");

从安装到发出第一个请求，不超过三分钟。

写在最后

如果你也曾在深夜为一段 curl 抓耳挠腮，为 HttpClient 的 Socket 耗尽问题反复排查，为一个"小小的请求功能"堆了三千行封装代码 ——

不妨给 HttpAgent 一个机会，也给自己一个机会。

• 开源仓库（Gitee）：https://gitee.com/dotnetchina/HttpAgent
• NuGet：https://www.nuget.org/packages/HttpAgent

让 HTTP 请求，所见即所得。