使用 Jetbrains 的 HttpClient 調用 Web API

一直以來 Postman 都是我們調用 REST API 的首選,但經過了幾次專案的協作,總是覺得它的功能沒有那麼到位,於是我轉向別的解決方案 Jetbrains 的 Http Client 就是我這一次的標的

開發環境

  • Rider 2022.3.2
    • 內建 Http Client

請求

兩種建立 Http Client 檔案的方式

建立臨時 Http Client 檔案

有時候需要臨時使用,不需要納入版控

 

建立實體 Http Client 檔案

可以跟專案綁在一塊,納入版控,存檔時以 .http.rest 為副檔名

 

如何建立請求

工具列上的 Add Request

 

匯入 cURL Command

可以在 Posman 匯出 cURL Command 再匯入 Jetbrains Http Client

Ctrl + J 熱鍵

查看有哪指令

多個請求

一個檔案可以有多個請求,請求彼此之間用 3 個 # 隔開

從請求移至原始碼

請求的端點位置如果跟 .https 同一個方案,可以按 F12,移至原始碼,例如,我在 Rider 就會移到 Controller 的 Actuon

Example 

提供了許多的範例讓我們可以快速地上手

Live Template

用片段程式碼可以加速編寫

 

Code Generate

如果有 OpenApi 的文檔也可以透過其他套件幫我們快速產生 Jetbrains Http Client

專案來源 OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3) (github.com)

 

安裝

npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli version

 

OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3) (github.com)

產生 .http 檔案

openapi-generator-cli generate -i https://api.opendota.com/api  -g jetbrains-http-client -o dotaClient

 

請求歷程

每一次的請求都會把結果存放下來,檔案路徑在 .idea 資料夾下

請求變數

宣告

有三種變數

環境變數:在外部檔案定義,讓不同的 .http 使用,參考 environment variables

動態變數:每一次執行請求時動態產生的數值,可以說是內建的方法,參考 dynamic variables

在 .http 宣告:一種是請求送出前(Per-request) request.variables.set,另外一種是得到響應結果後指定變數 client.global.set,範例如下

< {%
   request.variables.set("firstname", "John")
%}
GET http://example.org/{{firstname}}
> {%
   client.global.set("id", response.body.id); 
%}

 

 更多的 global 方法可以參考 global variables storage

 

 使用變數

{{ABC}} 代表使用變數ABC的值

若變數不存在,按下 Alt + Enter,即可將變數加到環境變數檔案,執行時可以決定要使用哪一個環境設定

 

定義環境變數

公開檔案

這會將環境變數加到 http-client.env.json 文件中並納入版控中。

私有檔案

將機敏性資料的環境變數加到 http-client.private.env.json 文件中,http-client.private.env.json 中的變數值會覆蓋 http-client.env.json 的變數值

例如 http-client.env.json 檔案有以下內容

{
  "Dev": {
    "BaseUrl": "https://localhost:44347/"
  },
  "Staging": {
    "BaseUrl": "https://staging.example.com/"
  }
}

 

在 HttpClient 就能夠挑選需要哪一個環境

 

 Pre-request 變數

送出請求前宣告變數,除了把不存在的變數放到環境變數之外,也可以寫在 .http 檔案內

 

###宣告變數
< {%
    request.variables.set("ABC", "123")
%}

 

 動態變數

每次執行請求時,會動態產生一個值,他們以 $ 開頭

我常用的是 $random.integer、$random.uuid,其餘的請參考以下連結

Exploring the HTTP request syntax | IntelliJ IDEA Documentation (jetbrains.com)

範例如下

GET http://localhost/api/get?id={{$uuid}}

 

回應

Response 處理的腳本是用 JavaScript ECMAScript 5.1 編寫,幫助我們接續的處理和驗證(Assert),主要有兩個 lib 處理

  1. client:保留 HttpClient session 的資料,例如全域變數,變數的生命週期保留直到 IDE 關閉。
  2. response:處理響應結果,例如狀態碼(Status Code)、類型(Content Type)、內文(Body)

 

我最常用的就是驗證 Response 的內容以及在不同 API 端點的資料傳遞,如以下範例,

當我呼叫 {{BaseUrl}}/WeatherForecast/get:id取得 id 後,再把 id 傳給 {{BaseUrl}}/WeatherForecast/{{id}}

### 取得id
GET {{BaseUrl}}/WeatherForecast/get:id

> {%
    client.global.set("id", response.body.id); 
    client.log("result: " + response.body.id);
    client.test("Request executed successfully", function () {
        client.log(response.body.id);
        client.assert(response.status === 200, "Response status is not 200");
    });
%}

### 依照上一動作取得的 id 取得資料
GET {{BaseUrl}}/WeatherForecast/{{id}}

 

執行結果如下圖:

 

client.log("result: " + response.body.id); 執行結果如下圖:

 

測試結果如下圖:

 

若測試失敗效果如下圖:

 

整合到 CI
 

Windows

安裝 cli

scoop install liberica17-jre

scoop install ijhttp

 

安裝後就可以使用了

ijhttp --env-file http-client.env.json --env QA-TW Item.http

 

Docker

他也有提供 docker,真的香

docker run --rm -i -t -v D:\src:/workdir jetbrains/intellij-http-client -e QA-TW -v http-client.env.json -D Item.http

 

更多的參考以下

HTTP Client CLI – Run Requests and Tests on CI | The IntelliJ IDEA Blog (jetbrains.com)

HTTP Client CLI | IntelliJ IDEA Documentation (jetbrains.com)

專案位置

sample.dotblog/Jetbrains HttpClient/Jetbrains HttpClient at ebd22aff2c6244b9090cb5917e7fa9e46523ce89 · yaochangyu/sample.dotblog (github.com) 

參考

若有謬誤,煩請告知,新手發帖請多包涵


Microsoft MVP Award 2010~2017 C# 第四季
Microsoft MVP Award 2018~2022 .NET

Image result for microsoft+mvp+logo