簡介

ylong_http 構建了完整的 HTTP 能力，支持用戶使用 HTTP 能力完成通信場景的需求。

ylong_http 使用 Rust 編寫，為 OpenHarmony 的 Rust 能力構筑提供支持。

ylong_http 在 OpenHarmony 中的位置

ylong_http 向 OpenHarmony 系統(tǒng)服務層中的網(wǎng)絡協(xié)議棧模塊提供 HTTP 協(xié)議支持，經由網(wǎng)絡協(xié)議棧模塊幫助上層應用建立 HTTP 通信能力。

以下是對于上圖關鍵字段的描述信息：

• APP：需要使用上傳下載能力的直接面向用戶的上層應用。
• request：提供上傳下載能力的系統(tǒng)組件。
• netstack：提供網(wǎng)絡協(xié)議棧功能的系統(tǒng)組件。
• ylong_http：提供 HTTP 能力的系統(tǒng)組件。
  • ylong_http_client：ylong_http 下的模塊之一，提供 HTTP 客戶端能力。
  • ylong_http:ylong_http 下的模塊之一，提供 HTTP 的基礎能力。
• ylong_runtime：ylong 提供的 Rust 異步運行時庫。
• tokio：業(yè)界常用的第三方 Rust 異步運行時庫。
• OpenSSL：業(yè)界常用的第三方 TLS 實現(xiàn)庫。

ylong_http 的內部架構:

ylong_http 內部當前分為兩個主要模塊：ylong_http_client 客戶端模塊和 ylong_http 協(xié)議組件模塊。

ylong_http_client 模塊負責提供 HTTP 客戶端功能，能夠支持用戶發(fā)送 HTTP 請求，并接收 HTTP 響應，內部又分為三個主要部分:

• sync_impl：同步的 HTTP 客戶端實現(xiàn)，該客戶端實現(xiàn)不依賴于任何運行時，可以直接在線程模型上運行，但是整體使用同步阻塞策略。
• async_impl：異步的 HTTP 客戶端實現(xiàn)，該客戶端實現(xiàn)需要使用 Rust 的異步運行時組件。異步 HTTP 客戶端利用 Rust 的異步能力，具有優(yōu)異的性能表現(xiàn)。
• Util：同步和異步的 HTTP 客戶端部分實現(xiàn)共通，例如自動重定向、HTTP 代理等。

sync_impl 和 async_impl 接口原型基本一致（主要是 Rust 異步語法與同步語法的差異），所以用戶可以在較小的代碼改動量下完成同步和異步邏輯的切換。

sync_impl 和 async_impl 的整體架構相同，分為如下模塊：

• Client：對外提供 HTTP 客戶端的基本接口，例如配置客戶端的相關選項，發(fā)送 HTTP 請求等。
• ConnectionPool：主要負責大量連接管理，管理所有 Dispatcher 的生命周期，包括啟動、運行、停止。HTTP 協(xié)議是基于連接的通信協(xié)議，涉及連接復用、連接管理等功能。
• Dispatcher：主要負責單一連接管理，管理單個連接的啟動、運行、停止、傳輸。每個連接都被一個 Dispatcher 管轄，由 Dispatcher 決定當前待發(fā)送的請求是不是使用它管理的連接。
• Connections：連接對象，可以是 TCP 連接、TLS 連接或者是更加泛化的連接對象，在該連接上進行消息傳輸和接收，是 Client 和 HTTP 協(xié)議的底座。
• Connector：負責創(chuàng)建連接對象。Connector 也是一個 trait，用戶可以使用它來定義創(chuàng)建連接時的行為。

Util 中包含了同步和異步的 HTTP 客戶端共通的能力，例如：

• Redirect：HTTP 自動重定向能力。當 HTTP 響應返回重定向相關的狀態(tài)碼時，HTTP 客戶端會進行自動重定向，并自動發(fā)送新的請求到下一跳。
• Proxy：HTTP 代理能力。發(fā)送 HTTP 請求時，向代理發(fā)送而非直接發(fā)送給原始服務器，然后由代理服務器返回原始服務器的響應。
• Pool：通用連接池實現(xiàn)，支持多個同步或異步連接的管理，便于上層同步或異步客戶端復用已有連接，減少連接重復創(chuàng)建次數(shù)，提高性能。
• OpenSSL_adapter：HTTPS 需要在 HTTP 的基礎上使用 TLS 能力，在 OpenHarmony 上使用的是 OpenSSL，所以需要對 OpenSSL 的接口進行 Rust 封裝。

ylong_http 模塊負責提供 HTTP 的基礎能力，例如 HTTP2 的 HPACK、HTTP3 的 QPACK 等，主要包含以下關鍵模塊：

• Request：HTTP 請求基礎能力，根據(jù) RFC9110 規(guī)定實現(xiàn)了 HTTP 請求的所有內容和行為。HTTP 請求主要用于向指定服務器發(fā)送請求。
• Response：HTTP 響應基礎能力，根據(jù) RFC9110 規(guī)定實現(xiàn)了 HTTP 響應的所有內容和行為。HTTP 響應主要是服務器針對客戶端請求的回應。
• Body： HTTP 消息體能力，根據(jù) RFC9110 規(guī)定實現(xiàn)了 HTTP 消息體的所有內容和行為。HTTP 消息體保存主要數(shù)據(jù)內容，以便客戶端和服務器通信。 HTTP 消息體在協(xié)議中有多種形式，在 ylong_http 庫中有對應實現(xiàn)，例如 EmptyBody 對應于空消息體，TextBody 對應于明文消息體，ChunkBody 對應于分塊消息體，Mime 對應于 Multipart 消息體。
• H1：HTTP1 的所有基礎能力，例如 HTTP1 格式的請求和響應的編碼器和解碼器等。
• H2：HTTP2 的所有基礎能力，例如 HTTP2 格式的請求和響應的編碼器和解碼器、HTTP2 幀編碼器和解碼器、HPACK等。
• H3：HTTP3 的所有基礎能力，例如 HTTP3 格式的請求和響應的編碼器和解碼器、QPACK 等。

編譯構建

若使用 GN 編譯工具鏈, 在 BUILD.gn 的 deps 段下添加依賴。添加后使用 GN 進行編譯和構建：

deps += ["http://example_path/ylong_http_client:ylong_http_client"]

若使用 Cargo 編譯工具鏈, 在 Cargo.toml 下添加依賴。添加后使用 cargo 進行編譯和構建：

[dependencies]
ylong_http_client = { path = "/example_path/ylong_http_client" } # 請使用路徑依賴

目錄

ylong_http
├── docs                        # ylong_http 用戶指南
├── figures                     # ylong_http 圖片資源
├── patches                     # ylong_http 門禁使用的補丁資源
├── ylong_http
│   ├── examples                # ylong_http 基礎組件庫代碼示例
│   ├── src                     # ylong_http 基礎組件庫源碼
│   │   ├── body                # Body trait 定義和擴展 Body 類型
│   │   ├── h1                  # HTTP/1.1 相關組件實現(xiàn)
│   │   ├── h2                  # HTTP/2 相關組件實現(xiàn)
│   │   ├── h3                  # HTTP/3 相關組件實現(xiàn)
│   │   ├── huffman             # Huffman 編解碼實現(xiàn)
│   │   ├── request             # Request 定義和實現(xiàn)
│   │   └── response            # Response 定義和實現(xiàn)
│   └── tests                   # ylong_http 基礎組件庫測試目錄
│
└── ylong_http_client
    ├── examples                # ylong_http_client 庫代碼示例
    ├── src                     # ylong_http_client 庫源碼
    │   ├── async_impl          # ylong_http_client 異步客戶端實現(xiàn)
    │   │   ├── conn            # 異步連接層
    │   │   ├── downloader      # 異步下載器實現(xiàn)
    │   │   ├── ssl_stream      # 異步 tls 適配層
    │   │   └── uploader        # 異步上傳器實現(xiàn)   
    │   ├── sync_impl           # ylong_http_client 同步客戶端實現(xiàn)
    │   │   └── conn            # 同步連接層
    │   └── util                # ylong_http_client 組件實現(xiàn)
    │       ├── c_openssl       # OpenSSL 封裝層
    │       │   ├── ffi         # ffi 封裝層
    │       │   └── ssl         # ssl 適配層
    │       └── config          # 配置選項實現(xiàn)
    │           └── tls         # TLS 選項實現(xiàn)
    │               └── alpn    # ALPN 實現(xiàn)
    └── tests                   # ylong_http_client 庫測試目錄

審核編輯：劉清