.NET 高性能 HTTP 客户端库 Oryx 的最佳实践

1. 项目介绍

Oryx 是一个高性能的 .NET 跨平台功能 HTTP 请求处理器库，使用 F# 语言编写。它旨在用于创建 HTTP 客户端以及编排 Web 请求。Oryx currently 被用于 .NET SDK 中，以便与 Cognite Data Fusion (CDF) 进行交互。它借鉴了 AsyncRx 和 Giraffe 框架的设计理念，将这些理念应用于客户端发起的 Web 请求处理。

2. 项目快速启动

在您的项目中使用 Oryx 非常简单。首先，您需要通过 NuGet 包管理器安装 Oryx 包。

使用 NuGet 包管理器控制台执行以下命令：

Install-Package Oryx

或者，如果您使用 .NET CLI，可以执行：

dotnet add package Oryx

接下来，您可以使用以下示例代码快速启动一个 HTTP 请求：

open System.Net.Http
open System.Text.Json
open FSharp.Control.Tasks.V2
open Oryx
open Oryx.SystemTextJson.ResponseReader

[<Literal>]
let Url = "https://en.wikipedia.org/w/api.php"

let options = JsonSerializerOptions()

let query term = [
    struct ("action", "opensearch")
    struct ("search", term)
]

let asyncMain argv = task {
    use client = new HttpClient()
    let request term = 
        httpRequest
        |> GET
        |> withHttpClient client
        |> withUrl Url
        |> withQuery (query term)
        |> fetch
        |> json options

    let! result = request "F#"
    printfn "Result: %A" result
}

[<EntryPoint>]
let main argv = 
    asyncMain argv
    |> Async.AwaitTask
    |> ignore
    0 // 返回一个整数退出码

确保您已经正确处理了异步操作，并在适当的地方使用 await。

3. 应用案例和最佳实践

编写 HTTP 请求处理器

Oryx 的核心是 HttpContext 和 HttpHandler。HttpContext 包含了发起请求所需的所有状态，以及从远程服务器接收的任何响应元数据，如头部信息、响应代码等。

type Context = {
    Request: HttpRequest
    Response: HttpResponse
}

type IHttpNext<'TSource> = abstract member OnSuccessAsync: ctx: HttpContext * content: 'TSource -> Task<unit>
                            abstract member OnErrorAsync: ctx: HttpContext * error: exn -> Task<unit>
                            abstract member OnCancelAsync: ctx: HttpContext -> Task<unit>

type HttpHandler<'TSource> = IHttpNext<'TSource> -> Task<unit>

您可以组合不同的 HTTP 处理器来创建复杂的请求流程。例如，使用 withBearerToken 添加认证信息，或者使用 cache 来缓存请求结果。

处理 HTTP 响应

处理响应时，您可以使用如 parseAsync 方法将响应流异步解析为指定的类型：

let! result = request
              |> parseAsync<MyResponseType> // 解析为自定义类型

确保您已经定义了相应的数据类型来匹配 JSON 响应的结构。

4. 典型生态项目

在 Oryx 生态中，您可以找到一些常用的 HTTP 处理器，如缓存、错误处理、并发请求等。这些处理器可以作为构建复杂 HTTP 客户端的基础模块。

例如，使用 concurrent 处理器可以并发运行多个 HTTP 请求：

let concurrentRequest = 
    httpRequest
    |> concurrent [requestA; requestB; requestC]
    |> withHttpClient client

在这里，requestA、requestB 和 requestC 是之前定义的 HTTP 请求处理器。

以上是使用 Oryx 的基础介绍和最佳实践。在实际项目中，您可以根据具体需求调整和组合不同的处理器，以实现高效的 HTTP 请求管理。