gRPC

gRPC 是一個高效能、高效率的遠端程序呼叫（RPC）框架，廣泛應用於現代分散式系統。在微服務架構中，gRPC 透過其串流能力與 Protocol Buffers 序列化，促進服務之間以低延遲和較低頻寬消耗進行高效率通訊。

先決條件

在 Apidog 中使用 gRPC 之前，請確認你具備：

Apidog 版本 2.3.1 或更新版本

定義 gRPC 服務與方法的 .proto 檔案

可存取的 gRPC 伺服器端點

建立 gRPC 專案

若要建立新的 gRPC 專案：

在 Apidog 首頁點擊 「New Project」

選擇 「gRPC Project」

匯入 Proto 檔案

gRPC 遵循 API-First 方法，要求在開發之前，先透過 .proto 檔案定義服務、方法與訊息。匯入你的 .proto 檔案，即可開始在 Apidog 中偵錯 gRPC API。

初始匯入

Apidog 支援三種匯入方法：

方法	說明
本機檔案	從你的本機檔案系統上傳 `.proto` 檔案
URL	從託管 `.proto` 檔案的 URL 匯入
伺服器反射	從 gRPC 伺服器自動探索服務

匯入結構

選取的 .proto 檔案會作為一個 Proto 匯入，其中：

服務會匯入為服務

RPC 方法 會匯入為方法

如果 .proto 檔案依賴其他檔案，則必須手動新增 相依項目

來自相依 .proto 檔案且具有相同 package 的 相關服務 也會一併匯入

重新匯入 Proto 檔案

當你的 .proto 檔案有所變更時，請在 Apidog 中更新它：

在目錄樹中的 Proto 上按一下右鍵

點擊 「Reimport」

呼叫方法

gRPC 在 .proto 檔案中定義 API 時支援四種方法類型。Apidog 支援全部四種：

方法類型	說明
Unary	單一請求、單一回應（類似 HTTP）
Server Streaming	單一請求，來自伺服器的多個回應
Client Streaming	來自用戶端的多個請求、單一回應
Bidirectional Streaming	雙向的多個請求與回應

Unary 呼叫

Unary 呼叫的運作方式類似 HTTP 請求：

在網址列中輸入伺服器 URL

在 Message 分頁下以 JSON 格式輸入訊息內容

點擊 「Invoke」 以發起呼叫

你也可以設定 Metadata 和 Auth 資訊，用於驗證或複雜情境。

串流呼叫

串流呼叫的運作方式類似 WebSocket 連線。發起呼叫後，你可以在 Message 分頁下撰寫並傳送訊息。

Apidog 提供 時間軸檢視，可顯示：

呼叫狀態

已傳送的訊息

已接收的訊息（依時間順序）

點擊任一訊息即可檢視其詳細資訊。

進階功能

自動產生動態值

Apidog 可辨識 .proto 檔案內容，並支援自動產生訊息主體：

點擊 「Auto-generate」 按鈕以建立訊息結構

使用 「Dynamic Values」 功能，彈性產生動態資料

如需詳細說明，請參閱 Dynamic Values。

使用變數

Apidog 變數可用於 gRPC 訊息與 Metadata，以動態注入資料。

如需詳細說明，請參閱 Environment Variable。

啟用 TLS

gRPC API 支援透過 TLS（Transport Layer Security）進行安全連線。

若要啟用 TLS：

點擊 URL 前方的通訊協定選擇器，以切換 TLS 狀態

在 URL 中使用 grpcs:// 以啟用 TLS

使用 grpc:// 以停用 TLS

管理伺服器位址與環境

新增伺服器位址

點擊 URL 網址列右側的 加號圖示，將目前的伺服器位址新增至環境。

使用環境伺服器位址

在右上角選擇環境與伺服器位址

在 URL 網址列中選擇 「Follow Default」，以使用統一的伺服器位址偵錯所有方法

檢視 Proto 檔案與 API 參數

Proto 檔案內容

點擊左側目錄樹中的 Proto，即可檢視 .proto 檔案的原始內容。

請求與回應參數

gRPC 使用 Protocol Buffers（ProtoBuf）作為序列化格式。不同於文字型格式（JSON、XML），ProtoBuf 是二進位格式，不適合人類閱讀或撰寫。

在 Apidog 中，為了便於使用，所有 gRPC 訊息都會以 JSON 格式 撰寫與顯示。你可以在 API 資訊頁面中，以 JSON 格式檢視請求與回應參數。

ProtoBuf 到 JSON 的類型對應

ProtoBuf 3	JSON	JSON 範例
message	object	`{"fooBar": v, "g": null, …}`
enum	string	`"FOO_BAR"`
map<K,V>	object	`{"k": v, …}`
repeated V	array	`[v, …]`
bool	boolean	`true, false`
string	string	`"Hello World!"`
bytes	base64 string	`"YWJjMTIzIT8kKiYoKSctPUB+"`
int32, fixed32, uint32	number	`1, -10, 0`
int64, fixed64, uint64	string	`"1", "-10"`
float, double	number	`1.1, -10.0, 0, "NaN", "Infinity"`

儲存偵錯資訊

完成偵錯後，點擊 「Save」 按鈕以儲存：

伺服器 URL

訊息

Metadata

其他設定

這可讓團隊成員重複使用你的偵錯設定。

先決條件#

建立 gRPC 專案#

匯入 Proto 檔案#

初始匯入#

重新匯入 Proto 檔案#

呼叫方法#

Unary 呼叫#

串流呼叫#

進階功能#

自動產生動態值#

使用變數#

啟用 TLS#

管理伺服器位址與環境#

新增伺服器位址#

使用環境伺服器位址#

檢視 Proto 檔案與 API 參數#

Proto 檔案內容#

請求與回應參數#

ProtoBuf 到 JSON 的類型對應#

儲存偵錯資訊#