Apache Thrift - 介面定義語言

Apache Thrift 的介面定義語言 (IDL) 是一種宣告式語言，用於定義資料和服務的結構，而與任何特定程式語言無關。

它使您能夠以簡單易讀的格式描述資料型別、服務方法及其互動。然後，Thrift 編譯器使用此 IDL 生成多種語言的程式碼，這些程式碼可用於實現和互動定義的服務。

Thrift IDL 結構

Thrift IDL 檔案使用 .thrift 副檔名並遵循簡單的語法。Thrift IDL 檔案的基本結構包括資料型別、常量、列舉、結構體和服務的定義。

以下是 Thrift IDL 結構的簡單分解

名稱空間

名稱空間有助於組織您的 IDL 定義並防止命名衝突。您可以使用 namespace 關鍵字為不同的程式語言定義名稱空間。每個名稱空間指令指定目標語言和相應的名稱空間

namespace java com.example.thrift
namespace py example.thrift

在此示例中

namespace java com.example.thrift 定義了從 IDL 檔案生成的 Java 程式碼的名稱空間。
namespace py example.thrift 定義了從 IDL 檔案生成的 Python 程式碼的名稱空間。

資料型別

Thrift 支援多種基本資料型別，您可以使用它們來定義資料的結構。一些基本型別包括

bool: 布林值（true 或 false）。
byte: 8 位整數。
i16: 16 位整數。
i32: 32 位整數。
i64: 64 位整數。
double: 雙精度浮點數。
string: 字串。
binary: 位元組序列（用於原始資料）。

結構體

結構體用於定義具有命名欄位的複雜資料型別。結構體中的每個欄位都分配一個唯一的識別符號 (ID) 並具有特定的資料型別。欄位可以標記為可選或必需。以下是一個示例

struct User {
  1: i32 id
  2: string name
  3: bool is_active
}

在此 User 結構體中

1、2 和 3 是用於序列化的欄位 ID（唯一整數）。
i32、string 和 bool 是欄位的資料型別。
id、name 和 is_active 是欄位名稱。

列舉

列舉（列舉的簡稱）用於定義一組命名常量。列舉中的每個常量都分配一個整數數值，預設從 0 開始。如果需要，您可以為常量指定自定義值。以下是一個示例

enum Status {
  ACTIVE = 1
  INACTIVE = 2
  PENDING = 3
}

在此 "Status" 列舉中

ACTIVE、INACTIVE 和 PENDING 是可能的值。
每個值都與一個整數相關聯。

聯合體

在 Apache Thrift IDL 中，聯合體是一種特殊型別的資料結構，它可以一次容納多個可能的欄位中的一個。

與可以同時容納多個欄位的結構體不同，聯合體一次只能容納一個欄位。以下是一個示例

union Result {
  1: string message
  2: i32 errorCode
}

在此示例中

"Result" 是聯合體的名稱。
它可以具有名為 "message" 的 "string" 欄位或名為 "errorCode" 的 "i32" 欄位，但不能同時具有兩者。

定義服務

服務定義可以執行的操作以及公開的方法。每個服務都包含一個方法列表，每個方法都指定引數和返回型別。以下是一個示例

語法

以下是 Apache Thrift 中定義服務的基本語法

service ServiceName {
  <returnType> <methodName>(<parameterList>) throws (<exceptionList>)
}

這裡，service 關鍵字後跟服務的名稱。在花括號內，每個方法都定義了其返回型別、方法名稱、引數列表以及可能引發的任何異常。

示例

在以下示例中，"UserService" 是一個具有兩種方法的服務。 "getUserById" 採用 i32 ID 並返回 "User" 結構體。它可能引發 "UserNotFoundException"。 "updateUser" 採用 "User" 結構體並返回空值 (void)。

getUserById 接受一個 i32 ID 並返回一個 User 結構體。
updateUser 接受一個 User 結構體並返回空值 (void)。

service UserService {
  User getUserById(1: i32 id) throws (1: UserNotFoundException e)
  void updateUser(1: User user)
}

定義異常

異常用於處理在服務方法呼叫期間發生的錯誤。您可以像結構體一樣定義它們，但使用 exception 關鍵字

語法

以下是 Apache Thrift 中定義異常的基本語法

exception ExceptionName {
  1: <type> <fieldName>
}

這裡，exception 關鍵字後跟異常的名稱。在花括號內，異常的每個欄位都定義了唯一的整數 ID、資料型別和欄位名稱。

示例

在以下示例中，"UserNotFoundException" 是一個具有一個欄位的異常，"message" 是一個帶有 ID 1 的字串，它儲存錯誤訊息

exception UserNotFoundException {
  1: string message
}

Apache Thrift 中的容器

在 Apache Thrift IDL 中，容器用於將多個值組合在一起。它們有三種類型：列表、集合和對映。每種型別都有不同的用途，並且具有其自身的特性

列表: 元素的有序集合，允許重複。以下為語法示例 -

list<string> names

這定義了一個名為 "names" 的列表，其中每個元素都是一個 "string"。

集合: 元素的無序集合，不允許重複。以下為語法示例 -

set<i32> numbers

這定義了一個名為 "numbers" 的集合，其中每個元素都是一個 32 位整數 (i32)。

對映: 鍵值對的集合，每個鍵都是唯一的。鍵和值可以是不同的型別。以下為語法示例 -

map<string, i32> ageMap

這定義了一個名為 "ageMap" 的對映，其中每個鍵都是一個 "string"（例如，人的姓名），每個值都是一個 "i32"（例如，他們的年齡）。

列印頁面