[网络协议]Flurl使用教程

请求和响应

发送HTTP请求
在现实使用场景中，如果需要考虑与HTTP服务交互，一种常见的思考方式是：“我想构建一个URL，然后调用它”。Flurl.Http允许您非常简洁地表达这一点，比如：

using Flurl;
using Flurl.Http;

var result = await baseUrl.AppendPathSegment("endpoint").GetAsync();

上面的代码示例为：发送一个HTTP GET请求并返回一个IFlurlResponse，从这个IFlurlResponse中，你可以通过GetStringAsync和GetJsonAsync等方法获得如:状态码(StatusCode)、请求头和主体等内容。

但通常情况下你只是想直接获取请求主体的内容和信息，Flurl提供了各种快捷方式来实现这一点，比如：

T poco = await "http://api.foo.com".GetJsonAsync<T>();
string text = await "http://site.com/readme.txt".GetStringAsync();
byte[] bytes = await "http://site.com/image.jpg".GetBytesAsync();
Stream stream = await "http://site.com/music.mp3".GetStreamAsync();

对于JSON API，通常最好定义一个与预期JSON响应数据类型匹配的类(T)。但如果你不想创建这个匹配的类，也可以换动态(dynamic)的对象，比如：

dynamic d = await "http://api.foo.com".GetJsonAsync();

或者，从返回JSON数组的API中获取一个动态列表，比如：

var list = await "http://api.foo.com".GetJsonListAsync();

下载文件
你也可以使用Flurl从指定URL下载文件，比如：

// 这里的filename是可选的;如果不指定，默认会使用远程文件的文件名
var path = await "http://files.foo.com/image.jpg".DownloadFileAsync("c:\\downloads", filename);

读取其他信息

从请求中读取其他(如：头部信息等)：

var headResponse = await "http://api.foo.com".HeadAsync();
var optionsResponse = await "http://api.foo.com".OptionsAsync();

使用HTTP发送数据

Flurl常见的向远程服务器发送数据的方式有：PostJsonAsync,PatchJsonAsync,PutStringAsync，使用示例如下：

await "http://api.foo.com".PostJsonAsync(new { a = 1, b = 2 });
await "http://api.foo.com/1".PatchJsonAsync(new { c = 3 });
await "http://api.foo.com/2".PutStringAsync("hello");

以上所有方法都返回一个Tash对象，当然，您可能希望在响应体中返回一些数据，Flurl也是可以轻松实现的，比如：

T poco = await url.PostAsync(content).ReceiveJson<T>();
dynamic d = await url.PutStringAsync(s).ReceiveJson();
string s = await url.PatchJsonAsync(partial).ReceiveString();

或者一些奇特的HTTP请求需求，比如：

await url.PostAsync(content); // 这里的content为System.Net.Http.HttpContent对象
await url.SendJsonAsync(HttpMethod.Trace, data);
await url.SendAsync(
    new HttpMethod("CONNECT"),
    httpContent, // 可选的
    cancellationToken,  // 可选的
    HttpCompletionOption.ResponseHeaderRead);  // 可选的

或者，你还需要设置HTTP请求的头部信息，如下：

// 设置单个头部信息参数
await url.WithHeader("Accept", "text/plain").GetJsonAsync();
// 设置多个头部信息参数
await url.WithHeaders(new { Accept = "text/plain", User_Agent = "Flurl" }).GetJsonAsync();

连字符在头文件名称中很常见，但在C#标识符中不允许，所以写成User_Agent便代表着User-Agent

设置超时时间
Flurl提供了设置请求超时时间的方法，比如：

await url.WithTimeout(10).DownloadFileAsync(); // 超时时间设置成了10秒
await url.WithTimeout(TimeSpan.FromMinutes(2)).DownloadFileAsync(); // 超时时间设置成了2分钟

取消HTTP请求

var cts = new CancellationTokenSource();
var task = url.GetAsync(cts.Token);
//其他业务代码...
cts.Cancel();

设置身份认证
Basic Authentication身份认证

await url.WithBasicAuth("username", "password").GetJsonAsync();

OAuth 2.0 bearer token身份认证

await url.WithOAuthBearerToken("mytoken").GetJsonAsync();

模拟提交数据
模拟HTML表单提交数据：

await "http://site.com/login".PostUrlEncodedAsync(new { 
    user = "user", 
    pass = "pass"
});

multipart/form-data提交数据：

var resp = await "http://api.com".PostMultipartAsync(mp => mp
    .AddString("name", "hello!")                // 一个键值对的数据
    .AddStringParts(new {a = 1, b = 2})         // 多个键值对的数据
    .AddFile("file1", path1)                    // 本地文件
    .AddFile("file2", stream, "foo.txt")        // 文件流
    .AddJson("json", new { foo = "x" })         // json数据
    .AddUrlEncoded("urlEnc", new { bar = "y" }) // 数据URL编码
    .Add(content));

Cookie设置
在请求中携带Cookies：

var resp = await "https://cookies.com"
    .WithCookie("name", "value")
    .WithCookies(new { cookie1 = "foo", cookie2 = "bar" })
    .GetAsync();

更好的方案是，从第一个请求获取响应cookie，并让Flurl决定何时将它们发送回去，比如：

await "https://cookies.com/login".WithCookies(out var jar).PostUrlEncodedAsync(credentials);
await "https://cookies.com/a".WithCookies(jar).GetAsync();
await "https://cookies.com/b".WithCookies(jar).GetAsync();

或者使用CookieSession来代替WithCookies，如：

using (var session = new CookieSession("https://cookies.com")) {
    await session.Request("a").GetAsync();
    await session.Request("b").GetAsync();
}

CookieJar可以显式在被创建和修改，对需要长期保存的Cookies有可能会有用，比如：

var jar = new CookieJar()
    .AddOrUpdate("cookie1", "foo", "https://cookies.com") // 必须指定原始的URL地址
    .AddOrUpdate("cookie2", "bar", "https://cookies.com");

await "https://cookies.com/a".WithCookies(jar).GetAsync();

CookieJar是Flurl在HttpClient堆栈中的CookieContainer的对等物，但是有一个主要的优点：它没有绑定到HttpMessageHandler对象，因此你可以在一个HttpClient/Handler实例上模拟多个Cookie会话。