Apache HttpClient 4.5.x 學習總結十二：Fluent API(流式API)

第5章 流式API

5.1 易用的門面API
從4.2版本開始，HttpClient提供了一種基于流式接口概念的易用門面API。該API僅暴露HttpClient最核心的功能，適用于不需要HttpClient全部靈活性的簡單場景。例如，流式門面API讓用戶無需手動管理連接和資源釋放。

流式API調用示例：

// 執行GET請求：設置超時，返回字符串響應內容
Request.Get("http://somehost/")
        .connectTimeout(1000)      // 連接超時1秒
        .socketTimeout(1000)       // 數據傳輸超時1秒
        .execute().returnContent().asString();

// 執行POST請求：啟用Expect-Continue握手，使用HTTP/1.1協議
// 提交字符串請求體，返回字節數組響應
Request.Post("http://somehost/do-stuff")
        .useExpectContinue()       // 啟用Expect-Continue
        .version(HttpVersion.HTTP_1_1) // 指定HTTP版本
        .bodyString("重要數據", ContentType.DEFAULT_TEXT) // 文本類型請求體
        .execute().returnContent().asBytes();

// 執行POST請求：添加自定義標頭，通過代理提交表單數據
// 并將響應內容保存到文件
Request.Post("http://somehost/some-form")
        .addHeader("X-Custom-header", "自定義值") // 添加標頭
        .viaProxy(new HttpHost("myproxy", 8080)) // 設置代理
        .bodyForm(Form.form().add("username", "vip").add("password", "secret").build()) // 表單數據
        .execute().saveContent(new File("result.dump")); // 保存到文件

通過Executor執行安全上下文請求：

// 創建帶認證的執行器（復用認證信息）
Executor executor = Executor.newInstance()
        .auth(new HttpHost("somehost"), "用戶名", "密碼")    // 目標主機認證
        .auth(new HttpHost("myproxy", 8080), "用戶名", "密碼") // 代理認證
        .authPreemptive(new HttpHost("myproxy", 8080));      // 啟用預認證

// 復用執行器執行請求
executor.execute(Request.Get("http://somehost/"))
        .returnContent().asString();
        
executor.execute(Request.Post("http://somehost/do-stuff")
        .useExpectContinue()
        .bodyString("重要數據", ContentType.DEFAULT_TEXT))
        .returnContent().asString();

5.1.1 響應處理
流式門面API通常自動管理連接和資源釋放，但代價是需在內存中緩沖響應內容。強烈建議使用ResponseHandler處理響應，避免內存緩沖。

// 使用ResponseHandler直接處理XML響應
Document result = Request.Get("http://somehost/content")
        .execute().handleResponse(new ResponseHandler<Document>() {

    public Document handleResponse(final HttpResponse response) throws IOException {
        // 狀態碼檢查（非2xx狀態拋出異常）
        if (response.getStatusLine().getStatusCode() >= 300) {
            throw new HttpResponseException(...);
        }
        // 內容類型檢查
        if (!ContentType.APPLICATION_XML.equals(ContentType.getOrDefault(entity))) {
            throw new ClientProtocolException("非XML內容類型");
        }
        // 直接解析響應流（不緩沖到內存）
        return docBuilder.parse(entity.getContent(), charset);
    }
});

核心知識點總結：

1. 流式接口設計 (Fluent Interface)

   • 通過鏈式方法調用（如.connectTimeout(1000).socketTimeout(1000)）
   • 使代碼更接近自然語言（如"執行獲取請求->設置超時->返回內容"）

2. 自動資源管理

   • 自動釋放連接，無需手動關閉 HttpClient 或響應對象
   • 適合快速開發，但需注意響應內容的內存緩沖問題

3. 關鍵功能封裝

   • 超時控制（連接/傳輸超時）
   • 代理配置（.viaProxy()）
   • 認證集成（.auth() 和 .authPreemptive()）
   • 內容類型處理（bodyString(), bodyForm()）
   • 協議特性（如HTTP/1.1, Expect-Continue握手）

4. 安全執行器 (Executor)

   • 復用認證信息（如基本認證/Basic Auth）
   • 支持預認證（避免401響應延遲）
   • 跨請求共享安全上下文

5. 高效響應處理

   • returnContent().asXxx()：簡單場景但內存緩沖風險
   • ResponseHandler：直接流處理，避免大響應內存溢出
   • 內置錯誤處理（自動檢查狀態碼/內容類型）

通俗易懂的解釋：

想象流式API像點奶茶：

1. 選基礎操作（Get("地址") 相當于"我要一杯奶茶"）
2. 加定制要求（.addHeader("加珍珠")，.timeout("5分鐘做好")）
3. 最后取結果（.execute() 等于下單，.asString() 是直接拿到做好的奶茶）

關鍵優勢：

• 自動清理：喝完奶茶店員自動收杯子（自動釋放連接）
• 復雜訂單：通過 .viaProxy() 叫跑腿代買，.auth() 用會員卡支付
• 大訂單處理：
  • 直接喝奶茶（asXxx()） → 杯子小可能灑出來（內存溢出）
  • 用吸管喝（ResponseHandler） → 大杯奶茶也能慢慢喝（流式處理）

適用場景：適合快速發請求（如調用簡單API），復雜需求（如大文件下載）需改用底層API。

?? 重要提醒：處理大響應（如圖片/文件）時，務必使用 ResponseHandler 直接流式處理到磁盤，避免 .returnContent() 導致內存爆滿！

補充解釋：基于流式接口概念的易用門面API

1. 什么是“流式接口”

• 流式接口（Fluent Interface）是一種讓代碼像 “說一句話” 一樣連貫的編程風格。核心特點是：每個方法調用后會返回一個對象（通常是當前對象），讓你可以接著調用下一個方法，形成 “鏈式調用”。

// 普通寫法
user.setName("張三");
user.setAge(20);
user.setGender("男");

// 流式接口寫法
user.setName("張三").setAge(20).setGender("男");

2. 什么是“門面API”

• “門面”（Facade）源于設計模式中的 “門面模式”，核心作用是：給復雜的系統套一個 “簡化接口”，隱藏內部的復雜邏輯，讓用戶用起來更簡單。

在 API 里，比如一個處理文件的系統：
內部可能需要做 “打開文件→讀取內容→解析格式→轉換編碼→保存文件” 等復雜操作，但門面 API 可以把這些打包成一個簡化的接口，比如fileTool.convert("舊文件.txt", "新文件.json")，用戶不用管中間步驟，直接調用就行。

3. 基于流式接口的易用門面API

• 既用 “門面” 簡化了復雜操作，又用 “流式接口” 讓調用過程像 “說一句話” 一樣連貫。

舉例：假設用一個“圖片處理API”，內部需要完成“加載圖片→調整尺寸→加濾鏡→保存圖片” 等復雜步驟（涉及很多底層邏輯）

• 門面API 的實現

ImageTool tool = new ImageTool();
tool.load("照片.jpg");    // 步驟1：加載
tool.resize(800, 600);   // 步驟2：調尺寸
tool.addFilter("復古");   // 步驟3：加濾鏡
tool.save("處理后.jpg");  // 步驟4：保存

• 基于流式接口的門面API實現

ImageTool.process("照片.jpg")  // 門面：簡化入口
         .resize(800, 600)    // 流式：返回對象，繼續調用
         .addFilter("復古")
         .save("處理后.jpg");

說明：

• process("照片.jpg") 是門面，隱藏了 “初始化工具、加載圖片” 的復雜邏輯；
• 后續的 .resize().addFilter().save() 是流式接口，讓步驟像 “一句話” 一樣連貫，讀起來像 “處理這張照片，調尺寸，加濾鏡，然后保存”，非常直觀。