Flurl 用于 C# (.NET)：完整指南与示例

\n\n

Flurl 是一个现代、优雅的 .NET 库，集流畅 URL 构建器和 HTTP 客户端于一体。它旨在让 HTTP 请求的处理尽可能简单、可读且方便。与使用 HttpClient、UriBuilder 和大量字符串拼接的冗长代码不同，Flurl 提供了简洁且富有表现力的语法，类似于 LINQ 中的方法链。

\n\n

为什么需要 Flurl？标准 HttpClient 的主要问题是过于冗长。要发送一个带有参数和标头的简单 GET 请求，需要编写 10-15 行代码。Flurl 将其缩减为 2-3 行，使代码自文档化。此外，Flurl 解决了安全构建 URL 的问题：自动编码参数，处理路径和查询字符串，防止因字符转义不当而导致的错误。

\n\n

该库非常适合任何需要与 REST API 交互的场景：从简单的移动应用到复杂的企业系统。Flurl 支持所有主要的 HTTP 方法、JSON 处理、文件上传、超时、重试等功能。它完全异步，兼容 .NET Standard 2.0+，因此可在 .NET Framework、.NET Core 和 .NET 5/6/7/8 中使用。

\n\n

安装

\n\n

Flurl 可通过 NuGet Package Manager 安装。要处理 HTTP 请求，需要 Flurl.Http 包，该包也包含 Flurl（URL 构建器）。

\n\n

通过 .NET CLI：

\n

dotnet add package Flurl.Http

\n\n

通过 Package Manager Console：

\n

Install-Package Flurl.Http

\n\n

通过 Visual Studio： 右键点击项目 → 管理 NuGet 包 → 搜索 "Flurl.Http" → 安装。

\n\n

如果您只需要 URL 构建器而不需要 HTTP 客户端，可以安装：

\n

dotnet add package Flurl

\n\n

快速入门

\n\n

一个最小的工作示例——从公共 API 获取数据并输出到控制台：

\n\n

using Flurl.Http;\nusing System;\nusing System.Threading.Tasks;\n\nclass Program\n{\n    static async Task Main(string[] args)\n    {\n        // 向 JSON API 发送 GET 请求\n        var response = await "https://jsonplaceholder.typicode.com/posts/1"\n            .GetJsonAsync<dynamic>();\n\n        Console.WriteLine($"标题: {response.title}");\n        Console.WriteLine($"正文: {response.body}");\n    }\n}

\n\n

这段代码执行 GET 请求，自动将 JSON 响应反序列化为动态对象，并输出字段。注意：Flurl 允许直接在 URL 字符串上调用方法——这就是“流畅”风格。

\n\n

主要方法和类

\n\n

1. Url.Combine() — 安全拼接 URL

\n

签名： public static string Combine(params string[] parts)

\n

功能： 拼接 URL 的多个部分，自动添加/删除多余的斜杠。防止斜杠重复。

\n

using Flurl;\n\nstring fullUrl = Url.Combine("https://api.example.com", "/v1/", "users", "/123");\nConsole.WriteLine(fullUrl); // https://api.example.com/v1/users/123

\n\n

2. Url.SetQueryParams() — 流畅添加参数

\n

签名： public static string SetQueryParams(this string url, object values)

\n

功能： 从匿名对象或字典向 URL 添加查询参数。自动编码值。

\n

using Flurl;\n\nstring url = "https://api.example.com/search"\n    .SetQueryParams(new { q = "hello world", page = 1, limit =