hlnBlog
0%

Thrift IDL 学习笔记

发表于 更新于 分类于

Thrift IDL 学习笔记

​ Thrift 可以实现跨语言的接口描述，并通过代码生成引擎将 thrift 文件中定义的数据结构和服务转换成目标语言的代码。

1 类型

1.1 基础数据类型

类型 含义
bool 布尔类型，占用一个字节（和C++中一样）
byte 有符号的字符（相当于 signed char）
i16 16位的有符号整数（相当于short）
i32 32位的有符号整数（相当于 int）
i64 64位的有符号整数 （相当于 long long）
double 64 位的浮点数
binary 字符数组
string 字符串

1.2 容器类型

类型 含义
list T类型元素的列表
set 无序集合（相当于 C++ 中的unordered_set）
map<K, V> 哈希映射

1.3 结构体类型

从概念上看，和 C 语言中的结构体 struct 相似，会被代码生成引擎转换成面向对象语言的Class。

1
2
3
4
5
6
7
8
struct Tweet {
    1: required i32 userId;
    2: required string userName;
    3: required string text;
    4: optional Location loc;
    5: optional TweetType tweetType = TweetType.TWEET // 5
    16: optional string language = "english"
}

1.4 异常类型

Exception 在语法和功能上几乎和Struct等同，然而在语义上不同，可以在定义服务的时候声明可能抛出的异常类型。

1.5 服务类型

使用Service关键字声明的服务。

1
2
3
4
5
6
7
8
9
10
11
12
13
service Twitter {
    // A method definition looks like C code. It has a return type, arguments,
    // and optionally a list of exceptions that it may throw. Note that argument
    // lists and exception list are specified using the exact same syntax as
    // field lists in structs.
    void ping(),                                                             // 
    bool postTweet(1:Tweet tweet) throws (1:TwitterUnavailable unavailable), // 
    TweetSearchResult searchTweets(1:string query);                          // 

    // The 'oneway' modifier indicates that the client only makes a request and
    // does not wait for any response at all. Oneway methods MUST be void.
    oneway void zip()                                                        // 
}

2 Typedef

相当于 C++ 中的 typedef，可以为底层数据类型起一个别名。

1
2
typedef i32 MyInteger  
typedef Tweet ReTweet

3 Enum

概念上和 C 语言中的枚举类型相似，可以定义一组常量的集合。默认值从0开始，也可以自己指定，接受10进制和16进制形式的数值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
enum TweetType {
    TWEET,       
    RETWEET = 2, 
    DM = 0xa,    
    REPLY
}                

struct Tweet {
    1: required i32 userId;
    2: required string userName;
    3: required string text;
    4: optional Location loc;
    5: optional TweetType tweetType = TweetType.TWEET // 

    16: optional string language = "english"
}

4 注释

Thrift 支持 bash 风格注释、C++风格单行和多行注释。

1
2
3
4
5
6
7
8
# This is a valid comment.

/*
 * This is a multi-line comment.
 * Just like in C.
 */
 
// C++/Java style single-line comments work just as well.

5 命名空间

概念上和 C++ 中的命名空间相似，提供了一种代码的组织方式，可以避免名字冲突。

1
2
namespace cpp com.example.project  
namespace java com.example.project
  1. 转换成 C++ 风格的命名空间嵌套，
1
namespace com { namespace example { namespace project {
  1. 转换成 Java 的包声明
1
package com.example.project

6 Include

可以在thrift文件中使用include关键字包含另外一个thrift文件，和C++不同的是，使用include进的thrift文件中的内容需要显式地带上前缀。

1
2
3
4
5
6
7
include "tweet.thrift"            

...
struct TweetSearchResult {
    1: list<tweet.Tweet> tweets;  // 注意：需要带上前缀

}

7 常量

使用 const 关键字可以定义常量，对于复合数据类型和结构体用JSON格式表示。

1
2
3
const i32 INT_CONST = 1234;    

const map<string,string> MAP_CONST = {"hello": "world", "goodnight": "moon"}

8 定义结构体

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
struct Location {                            

    1: required double latitude;
    2: required double longitude;
}
struct Tweet {
    1: required i32 userId;                   

    2: required string userName;             

    3: required string text;
    4: optional Location loc;                

    16: optional string language = "english" 

}
  1. 对于结构体中的每一个属性，都 必须有一个 唯一的、正的 整数作为标识
  2. 属性可以被标记为 required (必须的)或 optional（可选的）
  3. Struct 可以嵌套
  4. 可以为某一个属性指定默认值
  5. 在同一个thrift文件可以定义多个Struct
  6. Struct 不支持继承，所以不能拓展（extends）另一个Struct

9 定义Service

1
2
3
4
5
6
7
8
9
10
11
12
13
service Twitter {
    // A method definition looks like C code. It has a return type, arguments,
    // and optionally a list of exceptions that it may throw. Note that argument
    // lists and exception list are specified using the exact same syntax as
    // field lists in structs.
    void ping(),                                                             // 
    bool postTweet(1:Tweet tweet) throws (1:TwitterUnavailable unavailable), // 
    TweetSearchResult searchTweets(1:string query);                          // 

    // The 'oneway' modifier indicates that the client only makes a request and
    // does not wait for any response at all. Oneway methods MUST be void.
    oneway void zip()                                                        // 
}
  1. 函数声明可以用 逗号 或 分号 间隔
  2. 参数和返回值可以是 基础数据类型 和 结构体
  3. Void 也可以作为返回值类型
  4. 使用 throws 关键字声明函数可能会抛出的异常