一、简介

Thrift 接口定义语言 Thrift 接口定义语言(IDL, Interface Definition Language)中允许使用的是 thrift types。每个 thrift 文件主要有 hearder，类型定义，异常及服务组成，每个 thrift 文档包含 0 个或多个 headers 以及 0 个或多个 definitions。

1、thrift 文件的组成

1. Header ：header 可以是 thrift include，C++ include，或者是 namespace 声明。
2. Thrift include 的目的是使得其他 thrift 文件中的所有定义都能够通过 include 声明添加到该 thrift 文档产生的代码中。 语法： include "../../***.thrift" ，被引用的 thrift 文件产生的代码中的头文件即可包含在 thrift 产生的代码的头部，使得其能够使用、访问。
3. C++ include 能够将 C++定义的头文件添加到该 thrift 文件产生的 C++代码中。 语法： cpp_include "../../***.h" ，被引用的.h 文件将包含到 thrift 产生的代码的头部。
4. namespace 的声明方式采用为 namespaces/package/module/etc。namespace scope 表示该 namespace 应用于哪种编程语言，若 scope 的取值为“*”，则表示该 namespace 适用于所有的目标语言。 语法： namespace namespaceScope 名称，其中namespaceScope 的取值 有*| cpp | java | py | perl | rb | cocoa | csharp。

2、Definition

thrift 中可以定义的类型有 const | typedef | enum | struct | exception | service

1. const 语法： const 字段类型 标识符 = 值
2. typedef 语法： typedef 为一个类型创建一个别名
3. enum 语法： enum 标识符 {***，***，…}。其中，第一个值的取值默认为 0。
4. struct 语法： struct 标识符 { Field* } 。其中，每个 Field 的定义语法为： FieldId: (required | optional) FieldType Identifier ( = value) 。
5. exception： Exceptions 的定义与 struts 的定义相似，exception 中每个 field 的定义必须唯一 语法： exception 标识符 { Field* }
6. service： Service 定义了 server 端提供的功能集合的接口。一个 service 可以继承另一个 service。 语法： service 标识符 (extends otherService) { Function* }

二、类型详解

Thrift类型系统包括预定义基本类型，用户自定义结构体，容器类型，异常和服务定义。

1、基本类型

1. bool: 布尔类型，占一个字节
2. byte: 有符号字节
3. i16：16位有符号整型
4. i32：32位有符号整型
5. i64：64位有符号整型
6. double：64位浮点数
7. string：未知编码或者二进制的字符串
    注意：thrift不支持无符号整形，因为很多目标语言不存在无符号整形（比如java）

2、容器类型

1. List：一系列t1类型的元素组成的有序列表，元素可以重复，映射到Java的ArrayList，c++的vector，脚本语言的Arrays等。
2. Set：一些t1类型的元素组成的无序集合，元素唯一不重复，映射到Java的HashSet，c++的STL中的set。
3. Map<t1,t2>：key/value对，key唯一，映射到Java的HashMap， c++的STL中的map。
4. 容器中的元素类型可以是除service以外的任何合法的thrift类型，包括结构体和异常类型 。

3、结构体和异常

1. Thrift结构体在概念上同c语言的结构体类似，在面向对象语言中，thrift结构体将被转化为类。
2. thrift 结构体之间 不能继承，每个结构体都有一组类型定义的字段，每个 field 都有一个唯一的命名标识符。
3. 异常在语法和功能上类似于结构体，只是异常使用关键字exception而不是struct关键字来声明。但它在语义上不同于结构体，当定义一个RPC服务时，开发者可能需要声明一个远程方法抛出一个异常。
4. 异常可以继承目标编程语言的异常类，目的是与给定编程语言的异常处理功能无缝的结合。

4、服务

1. Thrift中服务定义的方式和语法等同于面向对象语言中定义接口。Thrift编译器会产生实现接口的client和server stubs。
2. 一个服务包括一个命名的 functions 集合，每个 function 有一个参数列表，一个返回值以及抛出或产生的一个异常列表。这些异常是 thrift 本身的exception类型。
3. 注意： void 是一种确定的 function 返回值类型， oneway 关键词（加在 void 之前）等同于 async，这种方法产生的客户端代码无需等待 server 端的响应（异步调用）。
4. 单纯的 void 函数将会为 client 返回一个确认，用于表示操作在 server 端已经执行完毕。
    注意： 当调用 oneway 方法时，client 端只保证 request 已成功发送至 transport 层，不能保证 server 端看到过这个 message，单个 client connection 的 oneway/async 方法可以在 server 端并行执行。

5、类型重定义

Thrift支持C/C++风格的typedef: typedef i32 MyInteger /*a typedef Tweet ReTweet*/
说明：末尾没有逗号、分号，struct可以使用typedef

三、数据结构定义

1、常量

Thrift允许用户定义常量，复杂的类型和结构体可以使用JSON形式表示：

1. const i32 INT_CONST = 1234;
2. const map<string,string> MAP_CONST = {"hello": "world", "goodnight": "moon"}
    说明：分号是可选的，支持十六进制赋值。

2、枚举类型

可以像C/C++那样定义枚举类型，如：

enum TweetType
{
	TWEET,
	RETWEET = 2,
	DM = 0xa,
	REPLY
}

1. 编译器默认从0开始赋值
2. 可以赋予某个常量
3. 允许常量是十六进制整数
4. 给常量赋缺省值时，使用常量的全称
5. 不同于protocol buffer，thrift不支持枚举类嵌套，枚举常量必须是32位正整数

3、定义结构体

struct Tweet
{
    1: required i32 userId;                  // a
    2: required string userName;             // b
    3: required string text;
    4: optional Location loc;                // c
    16: optional string language = "english" // d
}

struct Location
{
    1: required double latitude;
    2: required double longitude;
}

1. 每一个域都有一个唯一的正整数标识符（如示例中冒号前的数字），称为数字标签，这些数字标签在传输时用来确定序列化顺序，一旦使用消息类型，标签不可改变。（随着项目的进展，可以变更Thrift文件，最好不要改变原有的数字标签）
2. 每个域可以标识为required（必选的）或者optional(可选的)（也可以不注明）
3. 结构体可以包含其他结构体
4. 域可以有缺省值
5. 一个thrift中可以定义多个结构体，并存在引用关系
6. 规范的struct定义中的每个域均会使用required或者optional关键字进行标识。如果required标识的域没有赋值，thrift将给予提示。如果optional标识的域没有赋值，该域将不会被序列化传输。如果某个optional标识域有缺省值而用户没有重新赋值，则该域的值一直为缺省值。
7. 与service不同， 结构体不支持继承，即一个结构体不能继承另一个结构体。

4、定义服务

在流行的序列化/反序列化框架（如protocol buffer）中，thrift是少有的提供多语言间RPC服务的框架。Thrift编译器会根据选择的目标语言为server产生服务接口代码，为client产生桩代码。

//“Twitter”与“{”之间需要有空格！！！
//方法定义方式类似于C语言中的方式，它有一个返回值，一系列参数和可选的异常
//注意，参数列表和异常列表定义方式与结构体中域定义方式一致
//”oneway”标识符表示client发出请求后不必等待回复（非阻塞）直接进行下面的操作，”oneway”方法的返回值必须是void
service Twitter {
	void ping(),                                    // a
	bool postTweet(1:Tweet tweet);                  // b
	TweetSearchResult searchTweets(1:string query); // c
	oneway void zip()                               // d
}

1. 函数定义可以使用逗号或分号标识结束
2. 参数可以是基本类型或者结构体，参数只能是只读的（const），不可以作为返回值（参数不可携带数据返回）
3. 返回值可以是基本类型或者结构体
4. 返回值可以是void
5. Service支持继承，一个service可使用extends关键字继承另一个service

四、注释、命名空间、文件包含

1、注释

Thrift支持shell注释风格、C/C++语言中的单行或多行注释风格

# This is a valid comment.  shell风格注释
/*
* This is a multi-line comment.
* Just like in C.
*/

// C++/Java style single-line comments work just as well.

2、命名空间

Thrift中的命名空间同C++中的namespace和java中的package类似，它们均提供了一种组织（隔离）代码的方式。因为每种语言均有自己的命名空间定义方式（如python中有module），thrift允许开发者针对特定语言定义namespace：

namespace cpp com.example.project  // a
namespace java com.example.project // b

3、文件包含

Thrift允许文件包含，需要使用thrift文件名作为前缀访问被包含的对象，如：

include "tweet.thrift"           // a
...

struct TweetSearchResult {
	1: list<tweet.Tweet> tweets; // b
}

thrift文件名需要双引号包含，末尾没有逗号或者分号