Thrift IDL

Thrift类型

Thrift类型系统旨在允许程序员尽可能使用本机类型，无论使用何种编程语言。此信息基于并取代Thrift白皮书中的信息。Thrift IDL为每一种目标语言提供了用于生成代码的类型描述。

基本类型

基本类型是侧重于所有编程语言可用的关键类型：

bool:一个布尔值（true或false）

byte:一个8位有符号整数

i16:一个16位有符号整数

i32:一个32位有符号整数

i64:一个64位有符号整数

double:一个64位浮点数

string:使用UTF-8编码的文本字符串

特殊类型

binary:未编码的字节流。

注意：这是目前上述字符串类型的一种特殊形式，用于提供与Java更好的互操作性。目前的记录计划在某种程度上将其提升为基本类型。

结构体

Thrift结构体定义了一个通用对象，它们基本等同于OOP语言中的类，但是没有继承。结构体具有一组强类型字段，每个字段都具有唯一的名称标识符。字段可能具有Thrift IDL中描述的各种注释（数字字段ID，可选的默认值等）。

struct Example {
  1:i32 number = 0,
  2:i64 bigNumber,
  3:double decimals,
  4:string name = "thrifty"
}

字段有optional和required之分，如果不指定则默认为required。其中required是必填字段，optional是可选字段，非必填的。而且每个字段可以设置默认值。

struct Example {
  1: required i32 number = 0,
  2:optional i64 bigNumber,
  3:double decimals,
  4:string name = "thrifty"
}

容器

Thrift容器是强类型的容器，映射到大多数编程语言中常用的容器类型。

Thrift有三种容器：

list:一个有序的元素列表，转换成STL vector，Java ArrayList，脚本语言的native数组。

set:一个无序的元素集合，所有元素都是唯一的。转换成STL set，Java HashSet，Python的set等，PHP不支持set，所以它被视为类似于List。

map:一个严格唯一的键值映射。转换成STL map，Java HashMap，PHP关联数组，Python/Ruby字典等。虽然提供了默认值，但类型映射并未明确固定。已添加自定义代码生成器指令以允许用各种目标语言替换自定义类型。

容器元素可以是任何有效的Thrift类型。

注意：为了达到最大的兼容性，map的键类型应该是基本类型，而不是结构体或容器类型。有一些语言本机map类型不支持更复杂的键类型。另外，Json协议仅支持基本类型的键类型。

struct Example {
  1:i32 number = 0,
  2:i64 bigNumber,
  3:double decimals,
  4:string name = "thrifty",
  5:map<string, string> idMap,
  6:list<string> telphoneNumbers,
  7:set<i32> testSet
}

异常

异常在功能上等同于结构体，除了它们在每种目标编程语言中适当地继承本机异常基类以便与任何给定语言中的本机异常处理无缝集成之外。

exception TException {
    1: i32 errCode,
    2: string msg
}

枚举

1.编译器默认从0开始赋值
2.可以赋予某个常量某个整数
3.允许常量是十六进制整数
4.末尾没有分号
5.给常量赋缺省值时，使用常量的全称

enum TResult {
    SUCCEED = 0,
    FAILED = 1
}

常量定义

在变量前面加上const

const i32 SUCCEED = 0;

服务

服务使用Thrift类型进行定义。服务的定义在语义上等同于定义面向对象编程中的接口（或纯虚拟抽象类）。Thrift编译器生成实现该接口的功能齐全的客户端和服务器原型。

服务由一组命名函数组成，每个函数都有一个参数列表和一个返回类型。

请注意，除了所有其他定义的Thrift类型之外，void是函数返回的有效类型。此外，单向修饰符关键字可以添加到void函数中，该函数将生成不等待响应的代码。请注意，纯粹的void函数会向客户端返回一个响应，以确保操作在服务器端完成。使用单向方法调用客户端将只能保证请求在传输层成功。服务器可以并行/不按顺序执行同一客户端的单向方法调用。

service StringCache {
  void setNode(1:i32 key, 2:string value),
  string getNode(1:i32 key) throws(1:TException exp),
  void delNode(1:i32 key)
}

Include

一个包含所有来自另一个文件的符号可见（带有前缀），并将相应的包含语句添加到为此Thrift文档生成的代码中。该特性可以清晰地管理代码模块。

include "example.thrift"
service StringTest {
  void sayHello()throws(1:example.TException exp)
}

命名空间

Thrift中的命名空间类似于C++中的namespace和java中的package，它们提供了一种组织（隔离）代码的简便方式。命名空间也可以用于解决类型定义中的名字冲突。

namespace java thrift.test
namespace cpp thrift.test

注释

支持Java多行和单行注释风格。

/**
 * Program doctext.
 * Seriously, this is the documentation for this whole program.
 */

// this is a test