# HttpAgent

> HttpAgent 是一个高性能、灵活、易用的 .NET HTTP 开源库，内置工业级 HTTP 流量分析引擎（Profiler），彻底消灭第三方 API 对接的"黑盒"困境。

HttpAgent 官方中文文档，面向 AI 助手与爬虫整理的索引。全部正文见 [llms-full.txt](https://http.furion.net/llms-full.txt)。

## 开始上手

- [1.1 HTTP 远程请求概述](https://http.furion.net/docs/getting-started/intro/): HTTP 远程请求是指客户端（如 Web 浏览器、移动应用等）通过 HTTP 协议向远程服务器发送请求，以获取所需资源的过程。它是现代互联网应用中最基础且核心的通信方式之一。
- [1.2 安装与注册服务](https://http.furion.net/docs/getting-started/installation/): Furion 框架已内置该功能，无需额外安装 NuGet 包。若使用非 Furion 框架，可通过以下命令安装 HttpAgent 或 HttpAgent.AspNetCore 包：
- [1.3 在 Claude Code / Codex 中使用（llms.txt）](https://http.furion.net/docs/getting-started/ai-assistants/): 本网站在线提供 llms.txt 与 llms-full.txt 两份 AI 友好文件，让 AI 助手（如 Claude Code、Codex）无需逐页抓取网页，即可一次性读取全部文档。
- [1.4 与其他 HTTP 客户端库对比](https://http.furion.net/docs/getting-started/comparison/): HttpAgent、Refit 和 RestSharp 都是 .NET 生态中广受欢迎的 HTTP 客户端解决方案。三者定位不同：Refit 主打「接口即 API」的声明式编程，RestSharp 是经典老牌的流畅式客户端，而 HttpAgent 则是全功能型选手——除了常规请求…
- [1.5 关于作者](https://http.furion.net/docs/getting-started/about-author/): 纵你阅人何其多，再无一人恰似我。
- [1.6 更新日志](https://http.furion.net/docs/changelog/): HttpAgent 完整更新日志：新特性、突破性变化、问题修复与改进。

## 快速入门

- [2.1 获取网站内容](https://http.furion.net/docs/quick-start/get-content/): 获取网站内容是一个常见的需求，例如获取 Furion 框架网站（https://furion.net）的首页内容。以下展示了多种使用 httpRemoteService 来实现这一需求的方法。
- [2.2 携带请求数据](https://http.furion.net/docs/quick-start/with-data/): 在获取第三方 API 数据时，通常需要携带请求数据，这些数据可以是 URL 地址参数或请求内容。最常见的做法是通过 URL 地址传递参数，以及发送 JSON 格式的数据。
- [2.3 Form 表单提交（URL 编码）](https://http.furion.net/docs/quick-start/form-urlencoded/): 在互联网应用中，保存用户自定义的数据最常见的方式是使用 Form 表单提交。Form 表单不仅能携带文本数据，还能携带二进制数据，如文件。
- [2.4 下载网络资源](https://http.furion.net/docs/quick-start/download/): HTTP 远程请求最常见的应用场景之一是下载网络资源并将其保存到本地磁盘，这包括下载网页内容、图片、压缩包以及安装软件等。以下示例展示了如何下载 ASP.NET Core 运行时：
- [2.5 上传文件资源（OSS）](https://http.furion.net/docs/quick-start/upload/): 在互联网应用中，用户上传文件是一项常见需求，涵盖设置头像、发布图文动态、上传相册至网盘、分享 Vlog 到视频社区等场景。以下展示了多种文件上传的实现方式。
- [2.6 HTTP 声明式请求（代理方式）](https://http.furion.net/docs/quick-start/declarative/): HTTP 声明式请求机制通过实现 IHttpDeclarative 接口，在程序运行时动态地构建实现类。该机制会智能地拦截符合特定规则的方法调用，并自动生成相应的 HTTP 远程请求代码。这种方法不仅极大地减轻了开发人员编写 HTTP 请求代码的负担，而且使得代码结构更加条理分明…
- [2.7 请求分析工具](https://http.furion.net/docs/quick-start/profiler/): 在现代化的浏览器中，通常内置了开发者工具，这些工具能够捕获并直观展示用户访问网站时的所有请求与响应数据。类似地，我们也为 HTTP 远程请求模块提供了一套分析工具。
- [2.8 添加授权凭证](https://http.furion.net/docs/quick-start/authentication/): 在互联网社会中，网络安全愈发关键，特别是在与第三方接口对接时，通常需先通过鉴权授权才能访问。目前，互联网应用接口常用的授权方式包括 Bearer 身份认证、Basic 身份认证、Digest 摘要身份认证和 OAuth 身份认证。
- [2.9 设置 Cookie（模拟/自动登录）](https://http.furion.net/docs/quick-start/cookies/): Cookie 是服务器在 HTTP 响应中发送的一段数据。 客户端 (选择性地) 存储 Cookie，并在后续请求中返回它。 这允许客户端和服务器共享状态。在发送 HTTP 远程请求时，设置 Cookie 有以下两种方式。
- [2.10 异常处理（异常抑制）](https://http.furion.net/docs/quick-start/exception-handling/): 在发起 HTTP 远程请求时，可能会遇到以下异常情况：
- [2.11 压力与模拟测试（性能测试）](https://http.furion.net/docs/quick-start/stress-test/): 在开发面向互联网或需承受多人并发访问的应用系统时，性能压测和接口自动化模拟测试成为部署前的关键环节。通过这两项测试获取的报告指标，我们能在系统上线前对代码进行优化，确保其满足最低上线要求。
- [2.12 长轮询 Long Polling](https://http.furion.net/docs/quick-start/long-polling/): 长轮询（Long Polling）是一种实现服务器向客户端推送数据的技术。它通过保持 HTTP 连接打开直到有新数据发送给客户端，或者直到超时为止，从而模拟了服务器推送的效果。长轮询是传统轮询（即客户端定期向服务器发送请求以检查是否有新的数据）的一种改进，可以减少不必要的请求，提…
- [2.13 Server-Sent Events 单向通信](https://http.furion.net/docs/quick-start/sse/): 随着人工智能聊天机器人 ChatGPT 的快速流行，其用户界面中模拟打字机效果的对话设计给人留下了深刻印象。这种生动逼真的交互体验，实际上是通过一种称为“服务器发送事件”（Server-Sent Events, SSE）的技术实现的。
- [2.14 WebSocket 双工通信](https://http.furion.net/docs/quick-start/websocket/): WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议。WebSocket 使得客户端和服务器之间的数据交换变得更加简单，允许服务端主动向客户端推送数据。在 WebSocket API 中，浏览器和服务器只需要完成一次握手，两者之间就直接可以创建持久性的连接，并进行…
- [2.15 HttpContext 转发和代理](https://http.furion.net/docs/quick-start/httpcontext-forward/): HttpContext 转发是指在 ASP.NET Core 应用程序中，将一个 HTTP 请求的上下文信息（包括请求标头、请求内容、查询字符串、响应标头、响应内容等）从一个请求转发到另一个内部请求或服务的过程。这种技术允许开发者在不改变客户端请求的情况下，将请求重定向到另一个处…
- [2.16 WebService 接口请求（SOAP）](https://http.furion.net/docs/quick-start/webservice/): WebService 是一种基于 SOA（面向服务架构）的应用程序，具有语言和平台无关性。它通过 XML 描述实现不同语言间的相互调用，并利用 HTTP 协议在 Internet 上进行网络应用间的交互。框架支持对 WebService 接口的请求，以下为示例代码：
- [2.17 从 cURL 命令发送](https://http.furion.net/docs/quick-start/from-curl/): 推荐使用 ReqBin 在线测试和学习 cURL 命令，该网站提供大量可直接运行的 cURL 示例，调试 API 非常方便。
- [2.18 从 JSON 发送](https://http.furion.net/docs/quick-start/from-json/): 框架同样支持从 JSON 配置字符串一键发起 HTTP 请求，完全替代传统的链式调用。只需将请求参数组织为 JSON 格式，传入 HttpRequestBuilder.FromJson() 方，然后通过 IHttpRemoteService 发送即可。
- [2.19 OData 接口请求](https://http.furion.net/docs/quick-start/odata/): OData（Open Data Protocol）是一个基于 REST 的 Web 协议，通过 URL 参数就能像操作数据库一样对 API 进行查询：筛选、排序、分页、选择字段等。比如：
- [2.20 HTTP 请求与响应断言（Assert）](https://http.furion.net/docs/quick-start/assertions/): 在开发、测试中，经常需要对请求内容和响应结果进行验证，即“断言”。
- [2.21 JSON 响应反序列化包装器](https://http.furion.net/docs/quick-start/json-wrapper/): 在与第三方 API 进行 HTTP 远程通信时，通常会返回统一结构的 JSON 响应，例如 ApiResult 类型，其中实际数据存放在 Data 属性中：
- [2.22 Access Token 自动管理](https://http.furion.net/docs/quick-start/access-token/): 在与第三方服务（如微信公众号、企业微信等）对接时，通常需要先获取 Access Token，并在后续请求中携带该 Access Token 才能正常调用接口。Access Token 具有有效期（通常为两小时），过期后需重新获取并更新。
- [2.23 接口调用配额限制](https://http.furion.net/docs/quick-start/quota/): 在与第三方 API（如微信、支付网关等）集成时，通常需要遵守其每日/每月调用次数限制。为避免因超限导致业务中断或封禁，框架提供了灵活的接口调用配额限制功能，支持按天、按周、按月、永久总次数等策略，并允许自定义策略。
- [2.24 服务发现（ServiceDiscovery）](https://http.furion.net/docs/quick-start/service-discovery/): 服务发现是一种允许开发人员使用逻辑名称而非物理地址（如 IP 地址和端口）来引用外部服务的机制。例如，我们可以使用 furion 来代替 https://furion.net。这种方式的好处在于，可以在运行时通过配置修改服务地址，而无需更改程序代码，同时还能实现自动选择服务终结点…
- [2.25 HttpRemoteResult<TResult> 返回类型](https://http.furion.net/docs/quick-start/http-remote-result/): HttpRemoteResult 是一个泛型类型，专门用于 HTTP 远程请求模块中的响应内容。泛型参数 TResult 代表最终需要转换成的数据类型，除了支持常见的 HTTP 响应类型如 string、byte[]、Stream、HttpResponseMessage、IAsy…
- [2.26 DeepSeek 官方对接](https://http.furion.net/docs/quick-start/deepseek/): DeepSeek 是由深度求索公司开发的多功能人工智能模型，具备聊天、写作、编程、数据分析、翻译及教育辅导等能力。其强大的理解能力和快速学习速度使其适用于多种场景，未来发展潜力巨大。
- [2.27 抓取网页内容（爬虫）](https://http.furion.net/docs/quick-start/web-crawler/): 本节介绍三种抓取网页内容的方式：直接抓取配合 HTML 解析库，以及借助无头浏览器抓取 JavaScript 渲染的页面。
- [2.28 httpbin.org 在线测试服务](https://http.furion.net/docs/quick-start/httpbin/): httpbin.org 是一个免费、开源的在线 HTTP 请求与响应测试服务，由 Python 社区知名项目 requests 的作者 Kenneth Reitz 创建，现由 Postman 团队维护。它能够回显客户端发送的任何请求信息，并模拟各种 HTTP 场景，是开发 HTT…

## 请求构建器

- [3.1 HttpRequestBuilder 请求构建器](https://http.furion.net/docs/request-builder/httprequestbuilder-request-builder/): HttpRequestBuilder 是一个构建器工具，专门用于在通过 HttpClient 发送请求时构建所需的 HttpRequestMessage 对象。可以说，HttpRequestBuilder 是整个 HTTP 远程请求模块的核心组件，负责在发送请求前准备所有必要的请…
- [3.2 创建构建器实例](https://http.furion.net/docs/request-builder/creating-a-builder-instance/): HttpRequestBuilder 类型的构造函数被设计为私有，因此无法直接使用 new 关键字进行实例化。不过，它提供了多个静态方法来方便地创建 HttpRequestBuilder 的实例。
- [3.3 设置请求地址](https://http.furion.net/docs/request-builder/setting-the-request-address/): 在 HttpRequestBuilder 类型提供的静态方法中，您可以配置请求的地址。以下展示了如何使用 HttpRequestBuilder 类型静态方法来定义不同的请求地址：
- [3.4 方法命名原则](https://http.furion.net/docs/request-builder/method-naming-conventions/): 在设计 HttpRequestBuilder 对象的方法时，我们遵循了一套明确的命名规则，以确保方法的功能和行为直观易懂。具体来说，所有只能进行操作的方法均以 Set 或 Use 开头，而所有支持重复调用、进行叠加操作的方法则以 With 或 Add 开头。
- [3.5 设置跟踪标识](https://http.furion.net/docs/request-builder/setting-the-trace-identifier/): 为请求指定一个唯一标识符，便于跟踪和调试。该标识符将被设置在 X-Trace-ID 请求标头中。
- [3.6 设置内容类型](https://http.furion.net/docs/request-builder/setting-the-content-type/): 指定请求的内容类型。
- [3.7 设置内容编码](https://http.furion.net/docs/request-builder/setting-the-content-encoding/): 设置请求的内容编码。
- [3.8 设置 JSON 内容](https://http.furion.net/docs/request-builder/setting-json-content/): 将请求的内容类型设置为 application/json 并发送 JSON 数据。
- [3.9 设置 HTML 内容](https://http.furion.net/docs/request-builder/setting-html-content/): 将请求的内容类型设置为 text/html 并发送 HTML 数据。
- [3.10 设置 XML 内容](https://http.furion.net/docs/request-builder/setting-xml-content/): 将请求的内容类型设置为 text/xml 并发送 XML 数据。
- [3.11 设置文本内容](https://http.furion.net/docs/request-builder/setting-text-content/): 将请求的内容类型设置为 text/plain 并发送纯文本数据。
- [3.12 设置原始 raw 字符串内容](https://http.furion.net/docs/request-builder/setting-raw-raw-string-content/): 在诸如 Postman 等现代 API 测试工具中，用户可以通过 raw 数据格式发送请求。在 ASP.NET Core 服务端应用程序中，这通常表现为接收一个标记有 [FromBody] 特性的字符串参数（例如 str）：
- [3.13 设置 URL 编码表单内容](https://http.furion.net/docs/request-builder/setting-url-encoded-form-content/): 将请求的内容类型设置为 application/x-www-form-urlencoded 并发送表单数据。
- [3.14 设置文件内容](https://http.furion.net/docs/request-builder/setting-file-content/): 从本地路径或互联网地址中设置文件内容，自动识别文件名和 Content-Type。
- [3.15 设置二进制流内容](https://http.furion.net/docs/request-builder/setting-binary-stream-content/): 直接设置 Stream 作为请求内容，适用于文件流、内存流、网络流等场景。
- [3.16 设置请求内容（Body）](https://http.furion.net/docs/request-builder/setting-request-content-body/): 支持设置任意类型的请求内容。
- [3.17 设置 MCP/2.0 消息内容](https://http.furion.net/docs/request-builder/content-mcp/): SetMcpContent 是专门为 MCP（Model Context Protocol）2.0 协议设计的扩展方法，用于快速构建符合 JSON‑RPC 2.0 格式的请求，并自动附加必需的 MCP 请求头。它支持发送请求（需要响应）和通知（无需响应）两种消息类型。
- [3.18 设置多部分表单内容](https://http.furion.net/docs/request-builder/multipart/): 将请求的内容类型设置为 multipart/form-data 并发送多部分表单内容。
- [3.19 设置请求标头](https://http.furion.net/docs/request-builder/setting-request-headers/): 添加或修改请求标头。
- [3.20 设置移除的请求标头](https://http.furion.net/docs/request-builder/setting-request-headers-to-remove/): 移除指定的请求标头。
- [3.21 设置片段标识符](https://http.furion.net/docs/request-builder/fragment/): 在 URL 中添加片段标识符。
- [3.22 设置超时时间](https://http.furion.net/docs/request-builder/setting-the-timeout/): 为单次请求设置超时时长。
- [3.23 配置重试策略](https://http.furion.net/docs/request-builder/configuring-retry-policies/): 为单次请求配置重试策略。默认情况下，若已配置重试策略，则当请求出现未被抑制的异常时，将自动触发重试机制。
- [3.24 设置路径片段](https://http.furion.net/docs/request-builder/setting-path-segments/): 添加 URL 路径片段。
- [3.25 设置移除的路径片段](https://http.furion.net/docs/request-builder/setting-path-segments-to-remove/): 移除指定的路径片段。
- [3.26 设置查询参数（URL 参数）](https://http.furion.net/docs/request-builder/setting-query-parameters-url-parameters/): 添加或修改 URL 查询参数。
- [3.27 设置移除的查询参数](https://http.furion.net/docs/request-builder/setting-query-parameters-to-remove/): 移除指定的查询参数。
- [3.28 设置路径参数（模板/配置参数）](https://http.furion.net/docs/request-builder/path-params/): 在 URL 路径中替换对象模板字符串。
- [3.29 设置 Cookie](https://http.furion.net/docs/request-builder/setting-cookie/): 添加或修改 Cookie。
- [3.30 设置移除的 Cookies](https://http.furion.net/docs/request-builder/setting-cookies-to-remove/): 移除指定的 Cookie。
- [3.31 设置 HttpClient 实例的名称（多个基地址）](https://http.furion.net/docs/request-builder/setting-the-httpclient-instance-name-multiple-base-addresses/): 系统默认使用 IHttpClientFactory 创建 HttpClient 实例，并将默认客户端名称设为空字符串（string.Empty）。您可以通过指定方式设置创建 HttpClient 实例时的客户端名称。
- [3.32 设置响应内容的最大缓存大小](https://http.furion.net/docs/request-builder/setting-the-maximum-buffer-size-for-response-content/): 为单次请求配置响应内容的最大缓存字节数。
- [3.33 设置 HttpClient 实例提供器](https://http.furion.net/docs/request-builder/httpclient-provider/): 系统默认通过 IHttpClientFactory 来创建并自动管理 HttpClient 实例的生命周期。如果需要手动管理 HttpClient 的生命周期，可以针对单次请求单独配置一个 HttpClient 实例。
- [3.34 添加请求内容处理器](https://http.furion.net/docs/request-builder/adding-request-content-processors/): IHttpContentProcessor 接口定义了如何根据请求的内容类型或原始类型构建 HttpContent 实例。
- [3.35 添加响应内容转换器](https://http.furion.net/docs/request-builder/adding-response-content-converters/): IHttpContentConverter 接口指定了如何将响应内容 HttpResponseMessage 转换为目标类型的实例。
- [3.36 启用 HttpClient 池化管理](https://http.furion.net/docs/request-builder/enabling-httpclient-pooling-management/): 默认情况下，HttpClient 实例会在每次发送 HTTP 请求时被新建。但在需要频繁请求的场景中，这种做法可能引发性能瓶颈和内存占用过高的问题，特别是在压力测试期间。为了优化性能，我们可以启用 HttpClient 池化管理，以便在请求过程中复用 HttpClient 实例。
- [3.37 添加请求结束时需释放的资源](https://http.furion.net/docs/request-builder/adding-resources-to-release-when-the-request-ends/): 内存安全是每位程序开发者必须高度重视的问题。在发送 HTTP 请求的过程中，有时需要引入未托管的资源，例如，在发送文件时，需要从本地读取文件并以流的形式发送。这种情况下，若处理不当，可能会遇到流资源无法释放的问题。
- [3.38 管理和释放资源](https://http.furion.net/docs/request-builder/managing-and-releasing-resources/): 请参考第 3.36 和 3.37 章节内容，了解如何在请求结束时释放资源以避免内存泄漏。
- [3.39 设置添加请求内容前的操作](https://http.furion.net/docs/request-builder/setting-the-operation-before-adding-request-content/): 在将 HttpContent 实例设置给 HttpRequestMessage 对象的 Content 属性之前，您可以执行一些额外的预处理操作。
- [3.40 设置发送请求前的操作](https://http.furion.net/docs/request-builder/setting-the-operation-before-sending-the-request/): 在发送 HTTP 远程请求之前，您可以执行一些预处理操作。
- [3.41 设置收到响应后的操作](https://http.furion.net/docs/request-builder/setting-the-operation-after-receiving-the-response/): 在接收到 HTTP 响应之后，您可以执行一些后续处理操作。
- [3.42 设置发送请求失败时的处理](https://http.furion.net/docs/request-builder/setting-the-handling-when-sending-the-request-fails/): 当 HTTP 请求发送过程中发生异常时，您可以执行一些错误处理操作。
- [3.43 确保请求成功](https://http.furion.net/docs/request-builder/ensuring-the-request-succeeds/): 启用该功能后，当 HTTP 响应的状态码不在 200-299 范围内时（即 IsSuccessStatusCode 属性为 false），将自动抛出异常。
- [3.44 设置 Basic 身份认证](https://http.furion.net/docs/request-builder/setting-basic-authentication/): 向请求中添加 Authorization 标头，其值为 Basic 关键字后接由 用户名:密码 字符串的 Base64 编码组成。
- [3.45 设置 Bearer 身份认证（JWT）](https://http.furion.net/docs/request-builder/setting-bearer-authentication-jwt/): 向请求中添加 Authorization 标头，格式为 Bearer 关键字后接 Token 令牌字符串组成。
- [3.46 设置 Digest 摘要身份认证](https://http.furion.net/docs/request-builder/setting-digest-authentication/): 向请求中添加 Authorization 标头，格式为 Digest 关键字后接由用户名和密码生成的摘要字符串组成。
- [3.47 设置自定义身份认证](https://http.furion.net/docs/request-builder/setting-custom-authentication/): 向请求中添加自定义的 Authorization 标头，遵循 Schema 值 的格式。
- [3.48 禁用 HTTP 缓存](https://http.furion.net/docs/request-builder/cache/): 在发送 HTTP GET 请求时，服务器可能会缓存该请求的结果以提高性能。为了取消其缓存行为，可以在添加以下操作：
- [3.49 设置请求处理程序](https://http.furion.net/docs/request-builder/message-handler/): IHttpRequestEventHandler 接口允许您定义 HTTP 请求的预处理操作。通过实现该接口，您可以创建自定义的请求处理程序，例如 CustomRequestEventHandler 类：
- [3.50 模拟浏览器环境（爬虫检测）](https://http.furion.net/docs/request-builder/browser/): 在开发爬虫程序时，目标网站可能会根据用户代理（User-Agent）或其他因素提供不同的页面版本，如 PC 端和移动端。此外，一些网站还具备反爬虫机制，能够识别并阻止爬虫程序的访问。为应对这些问题，我们可以配置请求标头以模拟真实的浏览器环境进行请求。
- [3.51 添加响应状态码处理程序](https://http.furion.net/docs/request-builder/statuscode/): 在发送 HTTP 请求并接收响应时，我们经常需要根据不同的响应状态码执行特定的操作。为了实现这一需求，HttpRequestBuilder 提供了 WithStatusCodeHandler 方法，允许我们为特定的状态码配置回调处理逻辑。
- [3.52 启用请求分析工具](https://http.furion.net/docs/request-builder/profiler/): 在现代化的浏览器中，通常内置了开发者工具，这些工具能够捕获并直观展示用户访问网站时的所有请求与响应数据。类似地，我们也为 HTTP 远程请求模块提供了一套分析工具。
- [3.53 设置客户端偏好的语言和区域](https://http.furion.net/docs/request-builder/setting-the-client-preferred-language-and-region/): 全球化是互联网应用产品的发展趋势，因此，面向全球的应用产品应具备国际化功能。发送 HTTP 请求时，可通过添加 Accept-Language 标头来指定客户端偏好的自然语言和区域。
- [3.54 设置 HttpRequestMessage 属性](https://http.furion.net/docs/request-builder/setting-httprequestmessage-properties/): 在特定场景下，我们可能需要为 HttpRequestMessage 请求添加额外的属性，而非通过请求标头。这时，可以如下操作：
- [3.55 启用标准请求标头](https://http.furion.net/docs/request-builder/enabling-standard-request-headers/): 为了提升应用通过 HTTP 客户端发送网络请求的兼容性并避免被 WAF（Web 应用防火墙）拦截，框架提供了一键式配置方法，方便快速统一设置标准的请求头部：
- [3.56 设置自动 Host 标头](https://http.furion.net/docs/request-builder/setting-the-automatic-host-header/): Host 标头是 HTTP/1.1 协议中的一个必需标头。Host 标头用于指定请求的目标服务器的主机名和端口号，确保服务器能正确区分同一 IP 地址上的不同域名并进行相应处理。框架提供了简便的方法进行设置：
- [3.57 配置请求基地址](https://http.furion.net/docs/request-builder/configuring-the-request-base-address/): 当需要对接多个第三方 API 时，我们通常会全局注册并配置多个 HttpClient 实例的 BaseAddress。例如：
- [3.58 配置来源地址 Referer](https://http.furion.net/docs/request-builder/configuring-the-referer-referrer-address/): 当访问某些第三方服务器时，服务器可能会验证请求头中的 Referer 来源地址。例如在下载图片时，可能因触发防盗链机制导致获取的图片不符合预期。此时，可通过 SetReferer 方法来设置 Referer 请求头，模拟来源页面以绕过防盗链检测。
- [3.59 配置 User-Agent](https://http.furion.net/docs/request-builder/configuring-user-agent/): User-Agent 请求标头是一个特征字符串，使得服务器和对等网络能够识别发出请求的用户代理的应用程序、操作系统、供应商或版本信息。框架提供了 SetUserAgent 方法来设置 User-Agent 请求头。
- [3.60 配置 HTTP 版本](https://http.furion.net/docs/request-builder/configuring-the-http-version/): 在发起 HTTP 远程请求时，默认采用的 HTTP 协议版本为 1.1。不过，在访问部分第三方服务器时，这些服务器可能会对 HTTP 版本进行校验（例如，要求使用 2.0 版本）。此时，可以通过以下两种方式进行设置：
- [3.61 异常抑制机制（静默处理）](https://http.furion.net/docs/request-builder/suppression/): 在发起 HTTP 远程请求时，可能会遇到以下异常情况：
- [3.62 移除内容的默认 Content-Type](https://http.furion.net/docs/request-builder/removing-the-default-content-type-of-content/): 在与部分较老版本的 HTTP 服务进行对接时，如果发送请求内容时设置了 Content-Type 请求标头，可能会导致请求处理异常。而现代 HTTP 接口通常不会存在此类限制。
- [3.63 条件化配置构建器](https://http.furion.net/docs/request-builder/conditional-configuration-builder/): 在构建 HTTP 远程请求的构建器实例时，常需根据不同条件动态配置请求参数。例如，当用户执行搜索操作时，应将 ?search=关键字 查询参数添加到请求中；反之，则无需添加。
- [3.64 启用断言功能](https://http.furion.net/docs/request-builder/enabling-assertions/): 在开发或编写单元测试、集成测试时，我们经常需要验证请求内容和响应结果是否符合预期，这一过程通常称为“断言”。断言分为两类：
- [3.65 配置断言逻辑](https://http.furion.net/docs/request-builder/configuring-assertion-logic/): 启用断言功能后，可通过 Asserts(configure) 方法统一配置请求断言与响应断言：
- [3.66 启用 JSON 响应反序列化包装器](https://http.furion.net/docs/request-builder/enabling-the-json-response-deserialization-wrapper/): 在与第三方 API 进行 HTTP 远程通信时，通常会返回统一结构的 JSON 响应，例如 ApiResult 类型，其中实际数据存放在 Data 属性中：
- [3.67 响应 JSON 双重序列化处理](https://http.furion.net/docs/request-builder/handling-double-serialization-of-response-json/): 在与第三方 API 进行 HTTP 远程通信时，极少数情况下可能会遇到服务器返回的 JSON 数据被意外进行了双重序列化（有时也可能是刻意为之）。例如，本应返回 "{\"id\":1,\"name\":\"furion\"}"，却因双重序列化变成了 "\"{\\\"id\\\":…
- [3.68 设置在构建最终请求 URL 的操作](https://http.furion.net/docs/request-builder/setting-an-operation-for-building-the-final-request-url/): 在某些特殊场景下（例如需要动态拼接服务路径或查询参数），可以通过自定义逻辑来修改请求的 URL。使用 SetOnUriBuilding 方法即可调整 UriBuilder 对象的各个组成部分，从而构建出最终的请求地址。
- [3.69 设置重定向时进行额外配置](https://http.furion.net/docs/request-builder/setting-additional-configuration-on-redirect/): 当请求发生自动重定向（例如 301、302、307、308 等状态码）时，框架会基于当前构建器克隆一个新的构建器用于重定向请求。如果你需要在重定向时对新的构建器进行额外处理（例如移除跨域的 Authorization 头、调整请求头、修改超时时间等），可以使用 SetOnRedi…
- [3.70 清除请求内容](https://http.furion.net/docs/request-builder/clearing-request-content/): 在编写 HTTP 代理或单元测试时，有时需要一次性清空已设置的请求内容及其相关配置。框架提供了 RemoveContent() 方法来实现这一点。
- [3.71 追加请求内容](https://http.furion.net/docs/request-builder/appending-request-content/): 当需要向已存在的请求内容中动态添加更多数据，而不影响已设置的 ContentType 和 ContentEncoding 时，可以使用 AppendContent() 方法。该方法会依据现有内容与传入内容的类型进行智能合并：
- [3.72 禁用 Access Token 自动管理](https://http.furion.net/docs/request-builder/disabling-automatic-access-token-management/): 框架内置了 Access Token 自动管理功能，只需实现 IHttpAccessTokenProvider 接口，并在 GetAsync 方法中编写获取 Access Token 的逻辑即可。通常情况下，获取 Access Token 需要借助独立的 HTTP 请求，而若在 …
- [3.73 设置 Access Token 请求的自定义数据](https://http.furion.net/docs/request-builder/setting-custom-data-for-the-access-token-request/): 当使用 IHttpAccessTokenProvider 自动获取 Access Token 时，有时需要向 GetAsync 方法传递额外的动态参数（如用户名、密码、客户端密钥等）。通过 WithAccessTokenData 方法，可以在构建请求时预设这些参数，框架会自动将它…
- [3.74 移除 URL 地址末尾的 /](https://http.furion.net/docs/request-builder/removing-the-trailing--from-the-url/): 部分服务端对路径末尾的 / 敏感（如 /api/ 与 /api），可能造成 301 重定向或路由匹配失败。开启该功能后，框架会在构造最终请求地址时自动去除路径末尾的 /。
- [3.75 设置请求接口配额键](https://http.furion.net/docs/request-builder/setting-the-request-interface-quota-key/): 为当前请求指定配额键，用于关联在 HttpClientOptions 中配置的配额限制规则。
- [3.76 启用 ETag 响应缓存](https://http.furion.net/docs/request-builder/enabling-etag-response-caching/): ETag（实体标签）是 HTTP 协议中用于标识资源版本的一种机制。服务器在响应头中返回资源的 ETag 值（例如 "abc123"），客户端在后续请求中可通过 If-None-Match 头携带该值。若资源未发生变化，服务器返回 304 Not Modified，无需重新传输内…
- [3.77 设置 SOAP 请求头（WebService）](https://http.furion.net/docs/request-builder/setting-the-soap-request-header-webservice/): 当调用基于 SOAP 协议的 Web 服务时，通常需要在请求头中指定 SOAPAction，以便服务端识别要执行的操作。使用 SetSOAPAction 方法可快速设置该头。
- [3.78 模拟请求响应与异常（Mock）](https://http.furion.net/docs/request-builder/simulating-request-responses-and-exceptions-mock/): MockResponse 和 MockException 专为单元测试设计，可在不实际发送 HTTP 请求的情况下，直接返回预设响应或抛出预设异常，对业务代码零侵入。
- [3.79 克隆和复制](https://http.furion.net/docs/request-builder/cloning-and-copying/): 框架提供了 Clone() 和 CopyTo() 方法，用于复制或迁移 HttpRequestBuilder 的配置。这在需要复用一组公共配置（如认证头、超时时间等）并应用到多个不同请求时尤为有用。
- [3.80 设置自定义数据](https://http.furion.net/docs/request-builder/setting-custom-data/): 通过 WithData 方法向 HttpRequestBuilder 注入自定义数据，后续的内部组件或拦截器可通过 Items 字典访问这些信息。
- [3.81 获取请求构建器或请求消息（预检请求）](https://http.furion.net/docs/request-builder/getting-the-request-builder-or-request-message-pre-flight-request/): 在某些情况下，您可能希望只获取 HTTP 请求对象本身，而不实际发送请求。例如：在单元测试中验证生成的请求是否符合预期，或拿到请求构建器后进一步手动修改，亦或是将请求消息传递给另一个系统执行。
- [3.82 HttpRequestBuilder 统一配置器](https://http.furion.net/docs/request-builder/httprequestbuilder-unified-configurator/): 在通过 HttpRequestBuilder 类构建 HttpRequestMessage 对象时，若需对所有请求进行全局配置，框架提供了统一的配置机制。
- [3.83 自定义 HttpRequestBuilder 扩展方法](https://http.furion.net/docs/request-builder/custom-httprequestbuilder-extension-methods/): 除了框架自带的 HttpRequestBuilder 方法外，您还可以通过自定义扩展方法来简化代码、减少重复逻辑。例如，添加一个 SetAccept 方法，用于快速设置 HTTP 请求头中的 Accept 字段：
- [3.84 自定义扩展其他构建器](https://http.furion.net/docs/request-builder/custom-extensions-for-other-builders/): 以下构建器均派生自 HttpRequestBuilderConfigurator 抽象类型：

## 多部分表单构建器

- [4.1 HttpMultipartFormDataBuilder 表单构建器](https://http.furion.net/docs/multipart-builder/httpmultipartformdatabuilder-form-builder/): 在互联网应用中，保存用户自定义数据最常用的方法是使用 Form 表单提交。Form 表单不仅能传输文本数据，还能传输二进制数据（例如文件）。
- [4.2 创建构建器实例](https://http.furion.net/docs/multipart-builder/creating-a-builder-instance/): 由于 HttpMultipartFormDataBuilder 的构造函数是私有的，因此无法直接使用 new 关键字进行实例化。若想在 HTTP 远程请求中设置多部分表单内容，必须通过 HttpRequestBuilder 对象提供的 SetMultipartContent(Ac…
- [4.3 设置内容边界](https://http.furion.net/docs/multipart-builder/setting-the-content-boundary/): 在构建多部分表单内容时，可以通过以下链式调用方法为多部分表单内容设置边界（Boundary）：
- [4.4 保留内容的默认 Content-Type](https://http.furion.net/docs/multipart-builder/keeping-the-default-content-type-of-the-content/): 在与一些较老的 HTTP 服务对接时，提交表单数据时不应设置多部分表单内容的 Content-Type，否则可能引发异常。 而现代 HTTP 接口则无此限制。因此，框架默认在提交表单数据时会自动移除多部分表单内容的 Content-Type。
- [4.5 添加单个表单项内容](https://http.furion.net/docs/multipart-builder/adding-a-single-form-item/): 向多部分表单内容添加独立的项，即添加单个表单属性。
- [4.6 添加 JSON 内容](https://http.furion.net/docs/multipart-builder/adding-json-content/): 当需要将 JSON 数据添加到多部分表单内容中时，HttpMultipartFormDataBuilder 提供了灵活的处理方式，具体取决于是否指定了表单名。
- [4.7 添加 HTML 内容](https://http.furion.net/docs/multipart-builder/adding-html-content/): 向多部分表单内容中添加 HTML 内容。
- [4.8 添加 XML 内容](https://http.furion.net/docs/multipart-builder/adding-xml-content/): 向多部分表单内容中添加 XML 内容。
- [4.9 添加文本内容](https://http.furion.net/docs/multipart-builder/adding-text-content/): 向多部分表单内容中添加文本内容。
- [4.10 添加对象内容（复杂表单/上传文件）](https://http.furion.net/docs/multipart-builder/adding-object-content-complex-forms--file-uploads/): 当需要将对象添加到多部分表单内容中时，HttpMultipartFormDataBuilder 提供了灵活的处理方式，具体取决于是否指定了表单名。
- [4.11 添加互联网文件内容](https://http.furion.net/docs/multipart-builder/adding-internet-file-content/): 在多部分表单内容中添加来自互联网地址的文件内容。
- [4.12 添加 Base64 字符串文件内容](https://http.furion.net/docs/multipart-builder/adding-base64-string-file-content/): 在多部分表单内容中添加来自 Base64 字符串的文件内容。
- [4.13 添加本地路径文件内容（进度）](https://http.furion.net/docs/multipart-builder/adding-local-path-file-content-progress/): 在多部分表单内容中添加来自本地路径的文件内容。
- [4.14 添加 Stream 内容](https://http.furion.net/docs/multipart-builder/adding-stream-content/): 在多部分表单内容中添加 Stream 内容。
- [4.15 添加字节数组内容](https://http.furion.net/docs/multipart-builder/adding-byte-array-content/): 在多部分表单内容中添加字节数组内容。
- [4.16 添加 MultipartFile 内容](https://http.furion.net/docs/multipart-builder/adding-multipartfile-content/): MultipartFile 类型专为处理多部分表单文件而设计，它的构造函数是私有的，因此无法直接使用 new 关键字进行实例化，不过，框架提供了 MultipartFile.CreateFrom[Source] 的多个静态重载方法创建 MultipartFile 的实例。示例如下…
- [4.17 添加 IFormFile 和 IFormFileCollection 内容](https://http.furion.net/docs/multipart-builder/adding-iformfile-and-iformfilecollection-content/): 在 ASP.NET Core 中，IFormFile 接口用于处理单个文件上传，而 IFormFileCollection 接口则管理多个文件上传。这两个接口简化了文件上传功能的实现。框架提供了 AddFile(IFormFile) 和 AddFiles(IFormFileCol…
- [4.18 添加 IBrowserFile 和 IEnumerable<IBrowserFile> 内容](https://http.furion.net/docs/multipart-builder/adding-ibrowserfile-and-ienumerableibrowserfile-content/): 在 Blazor 中，IBrowserFile 接口用于处理单个文件上传，而 IEnumerable 接口则管理多个文件上传。这两个接口简化了文件上传功能的实现。框架提供了 AddFile(IBrowserFile) 和 AddFiles(IEnumerable) 扩展方法，便于…
- [4.19 添加 FileInfo 内容](https://http.furion.net/docs/multipart-builder/adding-fileinfo-content/): 若需上传本地文件，通常需先创建 FileInfo 实例，再通过 OpenRead() 获取流进行上传。。框架提供了 AddFile(FileInfo) 扩展方法，便于为多部分表单内容添加文件。示例如下：
- [4.20 添加 URL 编码表单内容](https://http.furion.net/docs/multipart-builder/adding-url-encoded-form-content/): 在多部分表单内容中添加 URL 编码表单内容。
- [4.21 添加多部分表单内容](https://http.furion.net/docs/multipart-builder/adding-multipart-form-content/): 在多部分表单内容中添加多部分表单内容的需求并不常见。
- [4.22 添加 HttpContent 内容](https://http.furion.net/docs/multipart-builder/adding-httpcontent-content/): 添加所有派生自 HttpContent 的请求内容。
- [4.23 设置添加表单项内容前的操作](https://http.furion.net/docs/multipart-builder/setting-the-operation-before-adding-form-item-content/): 在将 HttpContent 实例添加到 MultipartFormDataContent 对象之前，您可以执行一些预处理操作。例如，在与某些对象存储服务（如阿里云 OSS）对接时，您可能需要移除 Content-Type 设置（框架已内置该操作）。
- [4.24 设置表单名称策略（转换器）](https://http.furion.net/docs/multipart-builder/setting-the-form-name-policy-transformer/): 在发送 HTTP 表单数据时，与直接发送 application/json 格式的 JSON 数据不同，无法直接利用自定义 JSON 序列化选项对属性名称进行格式化。当将对象设置为表单数据时，框架会先将对象转换为 IDictionary 类型，再逐项添加为表单字段。因此，该过程不…
- [4.25 设置多部分表单内容项的排序规则](https://http.furion.net/docs/multipart-builder/setting-the-sort-rule-for-multipart-form-content-items/): 尽管对多部分表单内容项进行排序的需求并不常见，但在一些安全性要求较高的系统中，往往需要校验表单字段的提交顺序。框架为此提供了排序支持：
- [4.26 添加 HttpMultipartFormDataBuilder 扩展](https://http.furion.net/docs/multipart-builder/extensions/): 除了系统自带的 HttpMultipartFormDataBuilder 方法，您还可以为其添加自定义扩展方法，以简化代码并减少重复。例如，您可以添加一个 AddRawString 方法，用于为多部分表单添加原始 raw 字符串内容。具体实现如下：

## 声明式请求

- [5.1 HTTP 声明式请求](https://http.furion.net/docs/declarative/http-declarative-requests/): HTTP 声明式请求机制通过实现 IHttpDeclarative 接口，在程序运行时动态地构建实现类。该机制会智能地拦截符合特定规则的方法调用，并自动生成相应的 HTTP 远程请求代码。这种方法不仅极大地减轻了开发人员编写 HTTP 请求代码的负担，而且使得代码结构更加条理分明…
- [5.2 接口定义与使用](https://http.furion.net/docs/declarative/interface-definition-and-usage/): 在利用 HTTP 声明式请求之前，您需要定义一个接口，并确保它实现 IHttpDeclarative 接口：
- [5.3 定义请求方法](https://http.furion.net/docs/declarative/defining-request-methods/): 在 IHttpService 声明式接口中，您可以定义各种 API 请求方法。这些方法需要标记有从 HttpMethodAttribute 派生的特性，以指明其对应的 HTTP 请求类型。系统预置了多种常见的 HTTP 请求方法特性，同时也支持自定义方法特性：
- [5.4 定义请求地址](https://http.furion.net/docs/declarative/defining-request-addresses/): 在 HttpMethodAttribute 及其派生特性的构造函数中，您可以配置请求的地址。以下展示了如何在 IHttpService 接口中利用这些特性来定义不同的请求地址：
- [5.5 同步与异步方法](https://http.furion.net/docs/declarative/synchronous-and-asynchronous-methods/): 在 IHttpService 的声明式请求接口方法定义中，我们既提供了异步方法的实现，也支持同步方法的定义。例如：
- [5.6 定义返回值类型](https://http.furion.net/docs/declarative/defining-return-value-types/): 在 HTTP 声明式请求接口方法中，除了支持常见的 HTTP 响应类型如 string、byte[]、Stream、HttpRequestMessage、HttpResponseMessage、void、IAsyncEnumerable 和 IActionResult 以及它们的…
- [5.7 设置跟踪标识](https://http.furion.net/docs/declarative/setting-trace-identifier/): 为请求指定一个唯一标识符，便于跟踪和调试。该标识符将被设置在 X-Trace-ID 请求标头中。
- [5.8 设置超时时间](https://http.furion.net/docs/declarative/setting-timeout/): 为单次请求设置超时时长。
- [5.9 配置重试策略](https://http.furion.net/docs/declarative/configuring-retry-strategy/): 为单次请求配置重试策略。默认情况下，若已配置重试策略，则当请求出现未被抑制的异常时，将自动触发重试机制。
- [5.10 设置路径片段](https://http.furion.net/docs/declarative/setting-path-segments/): 添加或移除 URL 路径片段。
- [5.11 设置查询参数（URL 参数）](https://http.furion.net/docs/declarative/setting-query-parameters-url-parameters/): 添加、修改或移除 URL 查询参数。
- [5.12 设置请求标头](https://http.furion.net/docs/declarative/setting-request-headers/): 添加、修改或移除请求标头。
- [5.13 设置路径参数（模板/配置参数）](https://http.furion.net/docs/declarative/setting-path-parameters-templateconfiguration-parameters/): 在 URL 路径中替换对象模板字符串。
- [5.14 设置 Cookie](https://http.furion.net/docs/declarative/setting-cookie/): 添加、修改或移除 Cookie。
- [5.15 设置 HttpClient 实例的名称（多个基地址）](https://http.furion.net/docs/declarative/setting-the-httpclient-instance-name-multiple-base-addresses/): 系统默认使用 IHttpClientFactory 创建 HttpClient 实例，并将默认客户端名称设为空字符串（string.Empty）。您可以通过 HttpClientNameAttribute 特性设置创建 HttpClient实例时的客户端名称。
- [5.16 设置请求内容（Body）](https://http.furion.net/docs/declarative/setting-request-content-body/): 支持设置任意类型的请求内容。
- [5.17 设置多部分表单内容（复杂表单/上传文件）](https://http.furion.net/docs/declarative/multipart/): 将请求的内容类型设置为 multipart/form-data 并发送多部分表单内容。
- [5.18 禁用 HTTP 缓存](https://http.furion.net/docs/declarative/disabling-http-caching/): 在发送 HTTP GET 请求时，服务器可能会缓存该请求的结果以提高性能。为了取消其缓存行为，可以添加 DisableCacheAttribute 特性。
- [5.19 确保请求成功](https://http.furion.net/docs/declarative/ensuring-request-success/): 添加 EnsureSuccessStatusCodeAttribute 特性后，当 HTTP 响应的状态码不在 200-299 范围内时（即 IsSuccessStatusCode 属性为 false），将自动抛出异常。
- [5.20 模拟浏览器环境（爬虫检测）](https://http.furion.net/docs/declarative/simulating-a-browser-environment-crawler-detection/): 在开发爬虫程序时，目标网站可能会根据用户代理（User-Agent）或其他因素提供不同的页面版本，如 PC 端和移动端。此外，一些网站还具备反爬虫机制，能够识别并阻止爬虫程序的访问。为应对这些问题，我们可以配置请求标头以模拟真实的浏览器环境进行请求。
- [5.21 启用请求分析工具](https://http.furion.net/docs/declarative/enabling-the-request-profiler/): 在现代化的浏览器中，通常内置了开发者工具，这些工具能够捕获并直观展示用户访问网站时的所有请求与响应数据。类似地，我们也为 HTTP 远程请求模块提供了一套分析工具。
- [5.22 设置客户端偏好的语言和区域](https://http.furion.net/docs/declarative/setting-the-clients-preferred-language-and-region/): 全球化是互联网应用产品的发展趋势，因此，面向全球的应用产品应具备国际化功能。发送 HTTP 请求时，可通过添加 AcceptLanguageAttribute 特性来指定客户端偏好的自然语言和区域。
- [5.23 设置 HttpRequestMessage 属性](https://http.furion.net/docs/declarative/setting-httprequestmessage-properties/): 在特定场景下，我们可能需要为 HttpRequestMessage 请求添加额外的属性，而非通过请求标头。
- [5.24 启用标准请求标头](https://http.furion.net/docs/declarative/enabling-standard-request-headers/): 为了提升应用通过 HTTP 客户端发送网络请求的兼容性并避免被 WAF（Web 应用防火墙）拦截，框架提供了一键式配置方法，方便快速统一设置标准的请求头部。
- [5.25 设置自动 Host 标头](https://http.furion.net/docs/declarative/setting-the-automatic-host-header/): Host 标头是 HTTP/1.1 协议中的一个必需标头。Host 标头用于指定请求的目标服务器的主机名和端口号，确保服务器能正确区分同一 IP 地址上的不同域名并进行相应处理。框架提供了简便的方法进行设置：
- [5.26 设置请求基地址](https://http.furion.net/docs/declarative/setting-the-request-base-address/): 当需要对接多个第三方 API 时，我们通常会全局注册并配置多个 HttpClient 实例的 BaseAddress。例如：
- [5.27 设置来源地址（防盗链）](https://http.furion.net/docs/declarative/setting-the-referrer-address-hotlink-protection/): 当访问某些第三方服务器时，服务器可能会验证请求头中的 Referer 来源地址。例如在下载图片时，可能因触发防盗链机制导致获取的图片不符合预期。此时，可通过设置 Referer 请求头，模拟来源页面以绕过防盗链检测。
- [5.28 配置 HTTP 版本](https://http.furion.net/docs/declarative/configuring-the-http-version/): 在发起 HTTP 远程请求时，默认采用的 HTTP 协议版本为 1.1。不过，在访问部分第三方服务器时，这些服务器可能会对 HTTP 版本进行校验（例如，要求使用 2.0 版本）。
- [5.29 异常抑制机制（静默处理）](https://http.furion.net/docs/declarative/exception-suppression-mechanism-silent-handling/): 在发起 HTTP 远程请求时，可能会遇到以下异常情况：
- [5.30 启用参数验证](https://http.furion.net/docs/declarative/validation/): 在调用 HTTP 声明式接口方法时，支持验证传递的参数数据的合法性。
- [5.31 启用 JSON 响应反序列化包装器](https://http.furion.net/docs/declarative/enabling-the-json-response-deserialization-wrapper/): 在与第三方 API 进行 HTTP 远程通信时，通常会返回统一结构的 JSON 响应，例如 ApiResult 类型，其中实际数据存放在 Data 属性中：
- [5.32 响应 JSON 双重序列化处理](https://http.furion.net/docs/declarative/response-json-double-serialization-handling/): 在与第三方 API 进行 HTTP 远程通信时，极少数情况下可能会遇到服务器返回的 JSON 数据被意外进行了双重序列化（有时也可能是刻意为之）。例如，本应返回 "{\"id\":1,\"name\":\"furion\"}"，却因双重序列化变成了 "\"{\\\"id\\\":…
- [5.33 设置请求处理程序](https://http.furion.net/docs/declarative/setting-the-request-event-handler/): IHttpRequestEventHandler 接口允许您定义 HTTP 请求的预处理操作。通过实现该接口，您可以创建自定义的请求处理程序，例如 CustomRequestEventHandler 类：
- [5.34 禁用 Access Token 自动管理](https://http.furion.net/docs/declarative/disabling-automatic-access-token-management/): 框架内置了 Access Token 自动管理功能，只需实现 IHttpAccessTokenProvider 接口，并在 GetAsync 方法中编写获取 Access Token 的逻辑即可。通常情况下，获取 Access Token 需要借助独立的 HTTP 请求，而若在 …
- [5.35 移除 URL 地址末尾的 /](https://http.furion.net/docs/declarative/removing-the-trailing--from-the-url-address/): 部分服务端对路径末尾的 / 敏感（如 /api/ 与 /api），可能造成 301 重定向或路由匹配失败。开启该功能后，框架会在构造最终请求地址时自动去除路径末尾的 /。
- [5.36 设置请求接口配额键](https://http.furion.net/docs/declarative/setting-the-request-interface-quota-key/): 为当前请求指定配额键，用于关联在 HttpClientOptions 中配置的配额限制规则。
- [5.37 启用 ETag 响应缓存](https://http.furion.net/docs/declarative/enabling-etag-response-caching/): ETag（实体标签）是 HTTP 协议中用于标识资源版本的一种机制。服务器在响应头中返回资源的 ETag 值（例如 "abc123"），客户端在后续请求中可通过 If-None-Match 头携带该值。若资源未发生变化，服务器返回 304 Not Modified，无需重新传输内…
- [5.38 继承与复用](https://http.furion.net/docs/declarative/inheritance-and-reuse/): HTTP 声明式请求支持面向对象的封装与继承等特性。可将通用接口定义在父接口中，再由派生接口继承，实现复用。例如：
- [5.39 冻结参数类型](https://http.furion.net/docs/declarative/frozen-parameter-types/): 在之前的章节中，我们多次提及冻结参数类型，现在终于可以对其进行深入探讨了。
- [5.40 获取请求构建器或请求消息（预检请求）](https://http.furion.net/docs/declarative/getting-the-request-builder-or-request-message-pre-flight-request/): 在某些情况下，您可能希望只获取 HTTP 请求对象本身，而不实际发送请求。例如：在单元测试中验证生成的请求是否符合预期，或拿到请求构建器后进一步手动修改，亦或是将请求消息传递给另一个系统执行。
- [5.41 自定义 HTTP 声明提取器](https://http.furion.net/docs/declarative/custom-http-declarative-extractor/): 在 5.1 声明式请求 章节中，我们了解到每种特性或参数类型都对应着一种 HTTP 声明式提取器。以下系统预置的特性提取器及其对应的实现：
- [5.42 自定义 HTTP 声明提取器（授权）](https://http.furion.net/docs/declarative/custom-http-declarative-extractor-authorization/): 以下是一个示例，展示了如何通过自定义 AuthenticationAttribute 和 AllowAnonymousAttribute 特性，并添加相应的提取器，以实现自动授权和匿名访问功能。
- [5.43 HttpDeclarativeBuilder 构建器（动态构建）](https://http.furion.net/docs/declarative/declarative-builder/): HttpDeclarativeBuilder 构建器是框架提供专门用来动态构建 HTTP 声明式请求所需的各项设置。HttpDeclarativeBuilder 的构造函数是私有的，因此无法直接使用 new 关键字进行实例化，不过，框架提供了 HttpRequestBuilder…

## 进阶指南

- [6.1 IHttpContentProcessor 内容处理器](https://http.furion.net/docs/advanced-guide/ihttpcontentprocessor-content-processor/): IHttpContentProcessor 用于根据用户设置的原始请求内容和类型构建 HttpContent 实例，并将其设置为 HttpRequestMessage 对象的 Content 属性。如下图所示：
- [6.2 内置内容处理器](https://http.furion.net/docs/advanced-guide/built-in-content-processors/): - StringContentProcessor 内容处理器
- [6.3 IHttpContentProcessorFactory 内容处理器工厂](https://http.furion.net/docs/advanced-guide/ihttpcontentprocessorfactory-content-processor-factory/): IHttpContentProcessorFactory 内容处理器工厂负责根据原始请求的内容和类型，确定合适的 IHttpContentProcessor 内容处理器，并调用其 Process 方法来生成 HttpContent 实例。该工厂服务被配置为单例模式，以确保其在应用…
- [6.4 自定义内容处理器（如序列化）](https://http.furion.net/docs/advanced-guide/custom-content-processor-eg-serialization/): 在特定场景下，当框架内置的 IHttpContentProcessor 内容处理器无法满足需求时，可以通过自定义 IHttpContentProcessor 内容处理器来解决。
- [6.5 添加 MessagePack 支持](https://http.furion.net/docs/advanced-guide/adding-messagepack-support/): MessagePack 是一种紧凑、高效的二进制序列化格式，专为多种语言间的数据交换设计。相较于 JSON，MessagePack 提供了更高的性能和更小的数据体积。尽管是二进制格式，MessagePack 在设计时便充分考虑了跨语言使用的便捷性，目前已被广泛应用于 Python…
- [6.6 添加 Protobuf 支持](https://http.furion.net/docs/advanced-guide/adding-protobuf-support/): Protobuf（Protocol Buffers）是 Google 开发的一种语言中立、平台中立、可扩展的序列化结构数据格式，用于通信协议、数据存储等。
- [6.7 IHttpContentConverter 内容转换器](https://http.furion.net/docs/advanced-guide/ihttpcontentconverter-content-converter/): IHttpContentConverter 用于将 HTTP 远程请求返回的 HttpResponseMessage 对象转换成目标类型。如下图所示：
- [6.8 内置内容转换器](https://http.furion.net/docs/advanced-guide/built-in-content-converters/): - StringContentConverter 内容转换器
- [6.9 IHttpContentConverterFactory 内容转换器工厂](https://http.furion.net/docs/advanced-guide/ihttpcontentconverterfactory-content-converter-factory/): IHttpContentConverterFactory 内容转换器工厂负责根据目标接收类型，确定合适的 IHttpContentConverter 内容转换器，并调用其 Read 方法来将 HttpResponseMessage 对象转换为目标接收类型。该工厂服务被配置为单例模…
- [6.10 IObjectContentConverterFactory 对象内容转换器工厂](https://http.furion.net/docs/advanced-guide/iobjectcontentconverterfactory-object-content-converter-factory/): 当 IHttpContentConverterFactory 内容转换器工厂未找到匹配的 IHttpContentConverter 内容处理器，系统会回退到使用 IObjectContentConverterFactory 对象内容转换器工厂来进行转换，其内部通过返回 Obje…
- [6.11 自定义对象内容转换器（如序列化）](https://http.furion.net/docs/advanced-guide/custom-object-content-converter-eg-serialization/): IObjectContentConverterFactory 默认的内容转换器工厂会返回 ObjectContentConverter 实例，该实例利用 HttpResponseMessage.Content 的 ReadFromJsonAsync 方法，结合 System.Te…
- [6.12 自定义内容转换器](https://http.furion.net/docs/advanced-guide/custom-content-converter/): 在特定场景下，当框架内置的 IHttpContentConverter 内容转换器无法满足需求时，可以通过自定义 IHttpContentConverter 内容转换器来解决。
- [6.13 自定义泛型内容转换器](https://http.furion.net/docs/advanced-guide/custom-generic-content-converter/): 除了具体类型，框架同样支持泛型内容的转换。例如，定义如下泛型转换器：
- [6.14 IHttpRemoteService 服务](https://http.furion.net/docs/advanced-guide/ihttpremoteservice-service/): IHttpRemoteService 是一个用于发送 HTTP 远程请求的入口服务，它构成了 HTTP 远程请求模块的核心。简而言之，当需要发送 HTTP 远程请求时，应使用已注入的 IHttpRemoteService 服务。该服务默认以单例模式注册，因此可以在任何生存周期的服…
- [6.15 HttpRemoteBuilder 构建器](https://http.furion.net/docs/advanced-guide/httpremotebuilder-builder/): HttpRemoteBuilder 是一个构建器，用于配置和构建 IHttpRemoteService 服务所需的所有设置。在应用启动时，通常通过调用 services.AddHttpRemote 方法来指定这些配置。
- [6.16 HttpRemoteOptions 配置选项](https://http.furion.net/docs/advanced-guide/httpremoteoptions-configuration-options/): 使用 services.AddHttpRemote() 方法添加 HTTP 远程请求服务时，会返回一个 IHttpRemoteBuilder 实例。通过该实例，可以访问并配置 HttpRemoteOptions，这些配置包括默认请求内容类型、JSON 序列化设置等属性：
- [6.17 统一配置 HttpClient 客户端](https://http.furion.net/docs/advanced-guide/unified-configuration-of-the-httpclient-client/): 在应用项目开发中，通常需要对所有的 HttpClient 客户端实例进行统一配置。为此，框架提供了 ConfigureHttpClientDefaults 方法，支持一键配置：
- [6.18 内置属性与方法](https://http.furion.net/docs/advanced-guide/http-remote-service-members/): IHttpRemoteService 服务类型包含多个属性以及丰富多样的方法。
- [6.19 添加 IHttpRemoteService 扩展](https://http.furion.net/docs/advanced-guide/http-remote-service-extensions/): 除了系统自带的 IHttpRemoteService 方法，您还可以为其添加自定义扩展方法，以简化代码并减少重复。例如，您可以添加一个 SendAsSpan 方法，用于发送 HTTP 远程请求返回 Span。具体实现如下：
- [6.20 HttpRemoteResult<TResult> 返回值](https://http.furion.net/docs/advanced-guide/http-remote-result/): HttpRemoteResult 是一个泛型类型，专门用于 HTTP 远程请求模块中的响应内容。泛型参数 TResult 代表最终需要转换成的数据类型，除了支持常见的 HTTP 响应类型如 string、byte[]、Stream、HttpResponseMessage、IAsy…
- [6.21 下载网络资源](https://http.furion.net/docs/advanced-guide/downloading-network-resources/): HTTP 远程请求最常见的应用场景之一是下载网络资源并将其保存到本地磁盘，这包括下载网页内容、图片、压缩包以及安装软件等。下载网络资源有多种方式，其中最常见的是发送 HTTP 请求，接收返回的 Stream 流，然后将其写入本地磁盘并保存为相应文件。
- [6.22 HttpFileDownloadBuilder 构建器](https://http.furion.net/docs/advanced-guide/the-httpfiledownloadbuilder-builder/): 除了上述方法，您还可以使用 HttpFileDownloadBuilder 构建器来配置下载网络资源所需的各项设置。
- [6.23 文件传输事件处理程序](https://http.furion.net/docs/advanced-guide/file-transfer-event-handler/): IHttpFileTransferEventHandler 接口允许您定义下载或上传文件的预处理操作。通过实现该接口，您可以创建自定义的文件传输事件处理程序，例如 CustomFileTransferEventHandler 类：
- [6.24 上传文件资源](https://http.furion.net/docs/advanced-guide/uploading-file-resources/): 在互联网应用中，用户上传文件是一项常见需求，涵盖设置头像、发布图文动态、上传相册至网盘、分享 Vlog 到视频社区等场景。以下展示了多种文件上传的实现方式。
- [6.25 HttpFileUploadBuilder 构建器](https://http.furion.net/docs/advanced-guide/the-httpfileuploadbuilder-builder/): 除了上述方法，您还可以使用 HttpFileUploadBuilder 构建器来配置上传文件资源所需的各项设置。
- [6.26 文件传输事件处理程序](https://http.furion.net/docs/advanced-guide/file-transfer-event-handler-2/): IHttpFileTransferEventHandler 接口允许您定义下载或上传文件的预处理操作。通过实现该接口，您可以创建自定义的文件传输事件处理程序，例如 CustomFileTransferEventHandler 类：
- [6.27 压力与模拟测试](https://http.furion.net/docs/advanced-guide/stress-and-simulation-testing/): 在开发面向互联网或需承受多人并发访问的应用系统时，性能压测和接口自动化模拟测试成为部署前的关键环节。通过这两项测试获取的报告指标，我们能在系统上线前对代码进行优化，确保其满足最低上线要求。
- [6.28 HttpStressTestHarnessBuilder 构建器](https://http.furion.net/docs/advanced-guide/httpstresstestharnessbuilder-builder/): HttpStressTestHarnessBuilder 构建器是框架提供专门用来进行压力与模拟测试所需的各项设置。HttpStressTestHarnessBuilder 的构造函数是私有的，因此无法直接使用 new 关键字进行实例化，不过，框架提供了 HttpRequestB…
- [6.29 长轮询 Long Polling](https://http.furion.net/docs/advanced-guide/long-polling/): 长轮询（Long Polling）是一种实现服务器向客户端推送数据的技术。它通过保持 HTTP 连接打开直到有新数据发送给客户端，或者直到超时为止，从而模拟了服务器推送的效果。长轮询是传统轮询（即客户端定期向服务器发送请求以检查是否有新的数据）的一种改进，可以减少不必要的请求，提…
- [6.30 HttpLongPollingBuilder 构建器](https://http.furion.net/docs/advanced-guide/httplongpollingbuilder-builder/): HttpLongPollingBuilder 构建器是框架提供专门用来发送长轮询请求所需的各项设置。HttpLongPollingBuilder 的构造函数是私有的，因此无法直接使用 new 关键字进行实例化，不过，框架提供了 HttpRequestBuilder.LongPol…
- [6.31 长轮询事件处理程序](https://http.furion.net/docs/advanced-guide/long-polling-event-handler/): IHttpLongPollingEventHandler 接口允许您定义发送长轮询请求的预处理操作。通过实现该接口，您可以创建自定义的长轮询事件处理程序，例如 CustomLongPollingEventHandler 类：
- [6.32 终止长轮询请求](https://http.furion.net/docs/advanced-guide/terminating-a-long-polling-request/): 除了使用 CancellationToken 来取消长轮询请求，框架还会检查响应标头中的 X-End-Of-Stream，若存在该标头，则终止长轮询请求。
- [6.33 Server-Sent Events 单向通信](https://http.furion.net/docs/advanced-guide/server-sent-events-unidirectional-communication/): 随着人工智能聊天机器人 ChatGPT 的快速流行，其用户界面中模拟打字机效果的对话设计给人留下了深刻印象。这种生动逼真的交互体验，实际上是通过一种称为“服务器发送事件”（Server-Sent Events, SSE）的技术实现的。
- [6.34 HttpServerSentEventsBuilder 构建器](https://http.furion.net/docs/advanced-guide/httpserversenteventsbuilder-builder/): HttpServerSentEventsBuilder 构建器是框架提供专门用来接收服务器 Server-Sent Events 推送事件所需的各项设置。HttpServerSentEventsBuilder 的构造函数是私有的，因此无法直接使用 new 关键字进行实例化，不过，…
- [6.35 Server-Sent Events 事件处理程序](https://http.furion.net/docs/advanced-guide/server-sent-events-event-handler/): IHttpServerSentEventsEventHandler 接口允许您定义接收服务器 Server-Sent Events 推送事件的预处理操作。通过实现该接口，您可以创建自定义的 Server-Sent Events 事件处理程序，例如 CustomServerSent…
- [6.36 WebSocket 双工通信](https://http.furion.net/docs/advanced-guide/websocket-duplex-communication/): WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议。WebSocket 使得客户端和服务器之间的数据交换变得更加简单，允许服务端主动向客户端推送数据。在 WebSocket API 中，浏览器和服务器只需要完成一次握手，两者之间就直接可以创建持久性的连接，并进行…
- [6.37 WebSocketClient 客户端](https://http.furion.net/docs/advanced-guide/the-websocketclient-client/): 框架内置了 WebSocketClient 类型，便于用户通过 ws 或 wss 协议与 WebSocket 服务器建立连接。要使用 WebSocket 功能，首先需要创建并初始化 WebSocketClient 的实例。以下详尽列出了 WebSocketClient 实例所具备…
- [6.38 HttpContext 转发和代理](https://http.furion.net/docs/advanced-guide/httpcontext-forwarding-and-proxying/): HttpContext 转发是指在 ASP.NET Core 应用程序中，将一个 HTTP 请求的上下文信息（包括请求标头、请求内容、查询字符串、响应标头、响应内容等）从一个请求转发到另一个内部请求或服务的过程。这种技术允许开发者在不改变客户端请求的情况下，将请求重定向到另一个处…
- [6.39 HttpContextForwardBuilder 构建器](https://http.furion.net/docs/advanced-guide/the-httpcontextforwardbuilder-builder/): HttpContextForwardBuilder 构建器是框架提供专门用来转换 HttpContext 请求上下文所需的各项设置。HttpContextForwardBuilder 的构造函数是私有的，因此无法直接使用 new 关键字进行实例化，不过，框架提供了 HttpCon…
- [6.40 HttpContextForwardOptions 配置选项](https://http.furion.net/docs/advanced-guide/httpcontextforwardoptions-configuration-options/): HttpContextForwardOptions 类型专门用于配置 HttpContext 的转发行为。您可以在项目的 Startup.cs 或 Program.cs 文件中注册并配置该服务：
- [6.41 HttpContext 转发扩展方法](https://http.furion.net/docs/advanced-guide/httpcontext-forwarding-extension-methods/): 框架为 HttpContext 提供了多种扩展方法，旨在满足各种场景下的 HTTP 请求转发需求。
- [6.42 HttpContext 转发的优势](https://http.furion.net/docs/advanced-guide/advantages-of-httpcontext-forwarding/): 在对接第三方 API 接口时，通常的做法是创建一个入口程序，并在其中调用 HTTP 远程请求服务来发送请求到指定的第三方接口。假设第三方接口的控制器定义如下：
- [6.43 HttpContext 转发在微服务中的应用](https://http.furion.net/docs/advanced-guide/applying-httpcontext-forwarding-in-microservices/): 在微服务架构中，HttpContext 转发功能展现出了极大的价值。微服务间的通信通常依赖于 HTTP 或 gRPC，其中 HTTP 由于其出色的兼容性而被广泛应用。采用 HttpContext 转发不仅能够简化 HTTP 请求的代码量，还能使代码结构更加清晰，便于维护。对于大型…
- [6.44 转发忽略标头说明](https://http.furion.net/docs/advanced-guide/notes-on-headers-ignored-during-forwarding/): 在使用 HttpContext 转发功能时，系统会自动忽略以下请求与响应标头，以确保转发的有效性和准确性：
- [6.45 ForwardAttribute 转发特性](https://http.furion.net/docs/advanced-guide/the-forwardattribute-forwarding-attribute/): 为了简化转发操作，框架提供了便捷的 [Forward] 控制器操作转发特性。相较于手动调用 HttpContext 的 Forward 扩展方法，该特性显著减少了重复的硬编码工作。以下是使用 [Forward] 特性的示例代码：
- [6.46 HTTP 请求管道处理器](https://http.furion.net/docs/advanced-guide/pipeline/): HTTP 请求管道处理器是框架发送 HTTP 远程请求的核心机制，实际发出请求的最终执行逻辑即由这一系列处理器协作完成。几乎所有关键特性——如自动重定向、请求分析、超时管理、重试策略、异常抑制、请求断言及 Access Token 自动管理等——均由独立的管道处理器实现。每个处理…
- [6.47 FTP 客户端功能展望](https://http.furion.net/docs/advanced-guide/ftp/): 自 2019 年谷歌 Chrome 浏览器宣布停止对 FTP 协议的支持后，2022 年微软也紧随其后，在其 Edge 浏览器中移除了对 FTP 协议的支持。
- [6.48 CancellationToken 取消 HTTP 请求](https://http.furion.net/docs/advanced-guide/cancellation/): 框架为所有发送 HTTP 远程请求的方法提供了取消功能，只需通过 cancellationToken 参数即可实现。以下是三种取消请求的方法示例：
- [6.49 HttpClient 实例配置](https://http.furion.net/docs/advanced-guide/httpclient-instance-configuration/): HTTP 远程请求服务内部采用 HttpClient 发送请求。通过配置 HttpClient 客户端，可以调整框架发送 HTTP 远程请求的行为。您可以通过以下两种方式配置客户端行为：
- [6.50 常见属性配置](https://http.furion.net/docs/advanced-guide/common-property-configuration/): // 为默认客户端启用
- [6.51 配置 IHttpClientBuilder](https://http.furion.net/docs/advanced-guide/configuring-ihttpclientbuilder/): .AddHttpClient(name, configure) 方法返回一个 IHttpClientBuilder 实例，允许进行进一步的配置，比如设置 HttpMessageHandler。
- [6.52 配置 SSL 证书](https://http.furion.net/docs/advanced-guide/httpclient-ssl/): 使用 HttpClient 发起 HTTPS 请求时，如果需要配置自定义的 SSL/TLS 证书，通常涉及到使用 HttpClientHandler 类，并通过 ServerCertificateCustomValidationCallback 属性来指定一个回调方法，该方法用于…
- [6.53 配置 Proxy 代理服务器](https://http.furion.net/docs/advanced-guide/configuring-the-proxy-server/): 如果需要通过代理服务器发送请求，可以通过配置 HttpClientHandler 的 Proxy 属性来实现。下面是一个示例，展示了如何配置代理服务器，包括基本的身份认证。
- [6.54 配置 HTTP/3 支持](https://http.furion.net/docs/advanced-guide/configuring-http3-support/): HTTP/3 是 HTTP 协议的最新版本，基于 QUIC（Quick UDP Internet Connections）协议之上，旨在提供更低的延迟、更高的吞吐量和改进的多路复用能力。您可以添加以下配置来启用 HTTP/3 支持：
- [6.55 HttpClientOptions 扩展配置（JSON 序列化）](https://http.furion.net/docs/advanced-guide/httpclientoptions-extended-configuration-json-serialization/): 框架通过 IHttpClientBuilder.ConfigureOptions() 扩展方法，支持为 HttpClient 自定义选项（如 JSON 序列化行为），并提供可注入服务解析的重载。示例如下：
- [6.56 服务解析配置](https://http.furion.net/docs/advanced-guide/service-resolution-configuration/): 在全局配置 HttpClient 时，有时需要先解析依赖服务，再进行客户端配置。例如，以下示例通过解析配置服务来设置请求基地址：
- [6.57 了解更多配置](https://http.furion.net/docs/advanced-guide/learn-more-about-configuration/): 欲了解更多关于 HttpMessageHandler 和 SocketsHttpHandler 的配置，请查阅微软官方文档：
- [6.58 DelegatingHandler 请求处理委托（拦截）](https://http.furion.net/docs/advanced-guide/delegatinghandler-request-processing-delegation-interception/): DelegatingHandler 是 C# 中 HttpClient 类的一个重要组成部分，它允许你以一种链式的方式处理 HTTP 请求和响应。DelegatingHandler 是一个抽象类，通常用于创建自定义的消息处理器，这些处理器可以被插入到 HTTP 消息处理管道中。通…
- [6.59 DelegatingHandler 应用场景](https://http.furion.net/docs/advanced-guide/delegatinghandler-use-cases/): - 请求前处理：在请求发送到服务器之前，可以对请求进行修改或增强，例如添加认证信息、设置特定的请求头等。
- [6.60 自定义 DelegatingHandler](https://http.furion.net/docs/advanced-guide/custom-delegatinghandler/): 以下是一个简单的 DelegatingHandler 示例，展示了如何在请求发送前添加自定义请求头，并在响应接收后记录响应状态码：
- [6.61 实现自动刷新授权 Token](https://http.furion.net/docs/advanced-guide/implementing-automatic-authorization-token-refresh/): 推荐优先使用 2.22 Access Token 自动管理 章节介绍的方式，该方式内置了更完善的刷新机制和异常处理，无需手动编写 DelegatingHandler。以下内容保留作为传统实现参考，适合需要完全自定义刷新逻辑的场景。
- [6.62 HttpClientHandler 发送请求底层处理器](https://http.furion.net/docs/advanced-guide/httpclienthandler-underlying-handler-for-sending-requests/): HttpClientHandler 是 .NET 中用于配置和执行实际 HTTP 请求的核心消息处理器。它是 HttpMessageHandler 的具体实现类，通常作为 HttpClient 消息处理管道的最末端，负责与操作系统网络层交互，完成真正的 HTTP 请求发送与响应接…
- [6.63 HttpClientHandler 的核心功能](https://http.furion.net/docs/advanced-guide/core-features-of-httpclienthandler/): HttpClientHandler 提供了对 HTTP 客户端行为的精细控制，常见配置包括：
- [6.64 与 DelegatingHandler 的协作关系](https://http.furion.net/docs/advanced-guide/collaboration-with-delegatinghandler/): 当你通过 services.AddHttpClient() 创建 HttpClient 时，.NET 默认会为你提供一个 HttpClientHandler 作为管道的“终点”。所有通过 .AddHttpMessageHandler() 添加的 DelegatingHandler…
- [6.65 自定义 HttpClientHandler](https://http.furion.net/docs/advanced-guide/custom-httpclienthandler/): 虽然大多数拦截逻辑应通过 DelegatingHandler 实现，但 HttpClientHandler 本身也是可继承的，允许你在最接近网络 I/O 的层级插入自定义行为。这适用于需要深度控制底层请求/响应流程的场景，例如：
- [6.66 最佳实践建议](https://http.furion.net/docs/advanced-guide/best-practices/): - 不要轻易替换默认的 HttpClientHandler，除非你需要特殊的安全或连接行为。
- [6.67 RateLimitedStream 带速率限制的流](https://http.furion.net/docs/advanced-guide/ratelimitedstream-rate-limited-stream/): 在 SaaS/PaaS 应用平台中，用户常根据资源使用量（如带宽和流量）付费。特别是在用户下载或上传资源时，平台会进行速率限制。此时，框架提供的 RateLimitedStream 流非常有用。该流能够根据设定的速率限制调整读写速度，非常适合用于资源控制。
- [6.68 FileTypeMapper 文件 MIME 类型映射](https://http.furion.net/docs/advanced-guide/filetypemapper-file-mime-type-mapping/): 在文件上传和下载过程中，通常需要依据文件扩展名来获取或设置其 MIME 类型。这一步骤往往要求开发者手动进行正确设置。为了减轻开发者负担，框架提供了 FileTypeMapper 类型，它能够根据文件扩展名自动返回对应的 MIME 类型。例如：
- [6.69 JwtTokenUtility 解析 JWT Token](https://http.furion.net/docs/advanced-guide/jwttokenutility-parsing-jwt-token/): JwtTokenUtility 是一个轻量级的 JWT 实用工具类，无需依赖外部 JWT 库即可解析 JWT 的 Payload 部分并提取常见的声明（Claims），适用于需要快速获取 JWT 中过期时间、签发者、主题等信息的场景。
- [6.70 DigestCredentials 摘要身份认证](https://http.furion.net/docs/advanced-guide/digestcredentials-digest-authentication/): Digest 摘要身份认证是一种在 HTTP 协议中用于验证用户身份的增强安全性的方法，相较于基本的 HTTP Basic 认证，它更为安全。在 Digest 认证过程中，用户的密码不会以明文形式在网络上传输，而是通过加密处理后再发送，从而提升了安全性。框架提供了 DigestC…
- [6.71 HTTP 请求日志（关闭）](https://http.furion.net/docs/advanced-guide/logging/): 默认情况下，系统会在发送 HTTP 远程请求时打印相关日志信息，如下所示：

## 应用案例

- [7.1 应用案例](https://http.furion.net/docs/cases/use-cases/): 这里汇总了 HTTP 远程请求在应用开发中的常见案例。
- [7.2 使用流变对象 Clay 构建和接收请求数据](https://http.furion.net/docs/cases/using-the-dynamic-object-clay-to-build-and-receive-request-data/): 流变对象（Clay）在 HTTP 远程请求中的应用场景非常广泛，尤其是在与第三方 API 接口对接时。通常，这些接口需要传递或接收 JSON 格式的数据，而流变对象可以简化数据的构建和解析过程。以下是如何在 HTTP 远程请求模块中使用流变对象的配置步骤：
- [7.3 在 Blazor WebAssembly 应用中使用](https://http.furion.net/docs/cases/blazor/): Blazor WebAssembly 应用运行在浏览器的沙箱环境中，无法使用操作系统底层的 TCP 套接字。整个网络栈被替换为基于浏览器 fetch API 的实现，因此依赖于 System.Net.Sockets 的 SocketsHttpHandler 和会调用平台原生网络 …
- [7.4 在 File-Based Apps 应用中使用](https://http.furion.net/docs/cases/file-based-apps/): 从 .NET 10 SDK 开始，.NET 提供了 File-Based Apps（基于文件的应用）能力：无需创建项目文件（.csproj）和解决方案，只需一个 .cs 源文件即可构建、运行和发布应用程序，依赖与配置通过文件顶部的 #: 指令声明（支持 #:include、#:p…
- [7.5 在 MAUI 应用中使用](https://http.furion.net/docs/cases/maui/): .NET MAUI 内置了基于 Microsoft.Extensions.DependencyInjection 的依赖注入支持：在应用入口 MauiProgram.CreateMauiApp() 方法中向 builder.Services 注册服务，随后即可在页面（Page）或…

## 常见问题

- [8.1 常见问题](https://http.furion.net/docs/faq/faq/): 这里汇总了一些发送 HTTP 远程请求时可能遇到的常见问题。
- [8.2 忽略 SSL 证书验证（https 错误）](https://http.furion.net/docs/faq/ignoring-ssl-certificate-validation-https-errors/): 若发送 HTTP 远程请求过程中出现 The SSL connection could not be established, see inner exception. 的证书错误问题，您可以通过添加以下配置来忽略 SSL 证书验证：
- [8.3 发送请求出现长时间挂起或阻塞](https://http.furion.net/docs/faq/a-sent-request-hangs-or-blocks-for-a-long-time/): 若发送 HTTP 远程请求时，出现长时间挂起或阻塞，可能是您在构造请求时使用了类似以下方式获取本机 IP 或 MAC 地址：
- [8.4 强制 IPv4 或 IPv6 请求](https://http.furion.net/docs/faq/forcing-ipv4-or-ipv6-requests/): 通过配置 SocketsHttpHandler 的 ConnectCallback，可强制 HttpClient 使用指定 IP 版本或本地出口地址发起请求，适用于网络策略控制或多网卡环境，，以优化性能或满足网络要求。示例如下：
- [8.5 重定向响应处理](https://http.furion.net/docs/faq/handling-redirect-responses/): 在发送 HTTP 远程请求时，若目标服务器返回重定向响应（如 301 Moved Permanently、302 Found 等），框架默认会自动跟随重定向。为精确处理这些情况，可参考以下方案：
- [8.6 启用标准请求标头](https://http.furion.net/docs/faq/enabling-standard-request-headers/): 为了提升应用通过 HTTP 客户端发送网络请求的兼容性并避免被 WAF（Web 应用防火墙）拦截，框架提供了一键式配置方法，方便快速统一设置标准的请求头部：
- [8.7 设置默认 User-Agent](https://http.furion.net/docs/faq/setting-the-default-user-agent/): 在发送 HTTP 请求时，若用户未指定 User-Agent 请求头，框架将默认使用 Edge 浏览器（版本 142）的 User-Agent。示例如下：
- [8.8 发送相对地址（内部）请求](https://http.furion.net/docs/faq/sending-relative-address-internal-requests/): 在 ASP.NET 或 Blazor 等 Web 应用中，发送内部 HTTP 请求时，通常使用相对地址。然而，由于项目启动前无法获取主机地址和端口，无法直接通过 services.AddHttpClient() 配置 BaseAddress。此时，可以通过配置 HttpRemot…
- [8.9 获取响应 Cookie](https://http.furion.net/docs/faq/getting-the-response-cookie/): 在 HTTP 请求中，如果服务器设置了 Cookie，响应头中会包含一个或多个 Set-Cookie 键值对。客户端接收到响应后，可以通过读取这些 Set-Cookie 键值对来获取 Cookie 信息。框架提供了以下两种便捷的方式来获取 Cookie：
- [8.10 配置 Windows 身份认证](https://http.furion.net/docs/faq/configuring-windows-authentication/): Windows 身份认证是微软提供的一种安全机制，用于验证用户或实体的身份，确保他们对系统、网络资源和应用程序的访问符合安全策略。该机制通常用于 Windows 操作系统，允许用户无需手动输入用户名和密码即可登录系统或依赖该机制的应用程序。
- [8.11 配置 Kerberos 和 Active Directory 身份认证](https://http.furion.net/docs/faq/configuring-kerberos-and-active-directory-authentication/): Kerberos 是一种网络认证协议，它利用对称密钥加密技术来验证用户和服务的身份。通过使用票证（tickets）机制，Kerberos 能够确保在网络上的通信是安全的，并且可以有效地防止窃听、重放攻击等安全威胁。自 Windows 2000 开始，Kerberos 成为了域环境…
- [8.12 响应内容解压（支持 gzip、deflate、brotli 和 zstd）和内容乱码处理](https://http.furion.net/docs/faq/decompression/): 以下内容不适用于 Blazor WebAssembly 应用。
- [8.13 JSON 序列化配置](https://http.furion.net/docs/faq/json-serialization/): 框架默认采用 System.Text.Json 处理 HTTP 请求的 JSON 序列化，支持以下配置方式：
- [8.14 禁用分布式跟踪上下文（traceparent 标头）](https://http.furion.net/docs/faq/disabling-the-distributed-tracing-context-the-traceparent-header/): 在发起 HTTP 远程请求时，默认情况下，当前的 Activity 所包含的分布式跟踪上下文（如 traceparent 和 tracestate）会被自动注入到请求的 HTTP 标头中。这一机制有助于下游服务正确识别并关联到同一分布式跟踪链路。
- [8.15 设置 Content-Type（MIME）](https://http.furion.net/docs/faq/setting-content-type-mime/): 在发送 HTTP 远程请求时，如果请求中包含数据体，通常需要正确设置 Content-Type 请求头，以指明发送内容的 MIME 类型，例如 application/json 或 application/x-www-form-urlencoded。
- [8.16 在非依赖注入环境中使用（Console/WinForms/WPF）](https://http.furion.net/docs/faq/di/): 在 ASP.NET Core 或 Worker Service 等应用程序中，通常内置了依赖注入支持。你只需在 Startup.cs 或 Program.cs 文件中，通过 services 或 builder.Services 注册所需服务即可。
- [8.17 并行请求（批量下载）](https://http.furion.net/docs/faq/parallel/): 在需要同时发送多个 HTTP 请求的场景下（如批量下载、并发调用多个 API、混合执行不同类型的请求等），可以使用框架内置的 ParallelUtility 工具类，提供更简洁的 API，并支持控制最大并发数。
- [8.18 使用 LoadIntoBufferAsync 缓存响应内容](https://http.furion.net/docs/faq/using-loadintobufferasync-to-cache-response-content/): 在发送 HTTP 远程请求时，默认情况下响应内容以流的形式返回，只能被读取一次。若您需要在多个地方重复读取响应内容（例如同时进行日志记录、内容校验和业务处理），直接读取流会导致后续读取为空或异常。
- [8.19 与旧版 Java 程序提供的 API 对接](https://http.furion.net/docs/faq/integrating-with-apis-provided-by-legacy-java-programs/): 在与旧版 Java 程序提供的 API 接口进行对接时，通常需要启用自动设置 Host 标头的功能，以确保请求能够正常发送。例如：
- [8.20 AddHttpRemote 二义性错误](https://http.furion.net/docs/faq/addhttpremote-ambiguity-error/): 若遇到 AddHttpRemote 方法的二义性错误，可通过为其添加一个空的委托参数来解决，示例如下：
- [8.21 反馈与建议](https://http.furion.net/docs/faq/feedback-and-suggestions/): 欢迎向 HttpAgent 提交 Issue。

## 博客

- [HttpAgent 正式发布：内置工业级 HTTP 流量分析引擎](https://http.furion.net/blog/hello-httpagent/): HttpAgent 1.0 正式发布：一个高性能、灵活、易用的 .NET HTTP 开源库，内置工业级流量分析引擎 Profiler，彻底消灭第三方 API 对接的黑盒困境。
- [别再折磨 HttpClient 了！全新 HttpAgent 横空出世，重新定义 .NET 远程请求！](https://http.furion.net/blog/stop-suffering-with-httpclient/): 从 HttpClient 的痛点说起：五种写法、cURL/JSON 解析引擎、内置韧性治理与工业级流量分析引擎，HttpAgent 重新定义 .NET 远程请求。
- [别再翻文档了！HttpAgent 上线「工坊 + AI 助手」双引擎，写 HTTP 代码进入所见即所得时代](https://http.furion.net/blog/workshop-ai-assistant/): 别的 HTTP 库只给你一个库和一份文档，HttpAgent 直接给你两个「新物种」：可视化代码生成工坊与基于官方文档的 AI 助手——从写代码到排错，全程所见即所得。

## Optional

- [llms-full.txt](https://http.furion.net/llms-full.txt): 全部文档与博客正文的单文件合集，供一次性加载
- [sitemap.xml](https://http.furion.net/sitemap.xml): 全站页面地图