thrift IDL

参考资料：
[1] Thrift 入门
[2] Thrift入门及Java实例演示
[3] Thrift使用指南及语法介绍
[4] Thrift RPC 系列教程（1）——Thrift语言
[5] Java使用Thrift，Thrift结构体定义
[6] Thrift: The Missing Guide
[7] thrift IDL 基本类型和实践（一）struct 结构体、文件引用 和 基本类型
[8] Thrift IDL 语法定义
[9] What is the purpose of Thrift parameter numbering?
[10] Thrift之IDL

bool：布尔值，true 或 false，对应 Java 的 booleanbyte：8 位有符号整数，对应 Java 的 bytei16：16 位有符号整数，对应 Java 的 shorti32：32 位有符号整数，对应 Java 的 inti64：64 位有符号整数，对应 Java 的 longdouble：64 位浮点数，对应 Java 的 doublestring：utf-8编码的字符串，对应 Java 的 String

tips：thrift 并不支持无符号整形，因为在很多 thrift 支持生成的目标语言中都无法将无符号类型直接转换成该语言的原生类型。

binary: 未经过编码的字节流

tips：为了与 java 有更好的互通，未来可能将其提升为基本类型

thrift 容器类型是强类型，可以映射至大部分编程语言对应的类型

list< t1>：对应 Java 的 ArrayListset< t1>：对应 Java 的 HashSetmap< t1, t2>：对应 Java 的 HashMap

tips：
容器里可用任意 thrift 有效的数据类型，包括 structs 和 exceptions，除了 services；
map 的 key 只能是一个基本类型，不能是 structs 或 containers。

//常量定义
const i32 MALE_INT = 1
const map GENDER_MAP = {1: "male", 2: "female"}
//某些数据类型比较长可以用别名简化
typedef map gmp

和 C 语言结构体差不多，在 Java 中是一个 JavaBean。

struct PersonInfo {
  1: required i32 id;
  2: required string name,
  3: optional string gender;
  6: optional string contry = "china"
}

tips:
1、struct 不能继承，但是可以嵌套，不能嵌套自己；
2、成员都通过正整数编号，编号不能重复，可以跳顺序；
3、成员分割符可以是逗号「,」或是分号「;」，而且可以混用，但是为了清晰期间，建议在定义中只使用一种；
4、每个字段可以设置默认值；
5、规范的 struct 定义中的每个域均会使用 required 或者 optional 关键字进行标识。如果 required 标识的域没有该字段，Thrift 将给予提示；如果 optional 标识的域没有赋值，该域将不会被序列化传输；如果某个 optional 标识域有缺省值而用户没有重新赋值，则该域的值一直为缺省值；如果某个 optional 标识域有缺省值或者用户已经重新赋值，而不设置它的 __isset 为 true，也不会被序列化传输。

当一个结构体中，field 之间的关系是互斥的，即只能有一个field被使用被赋值，可以用union 来声明这个结构体，而不是一堆 optional 的 field。

union JavaObjectArg {
  1: i32 int_arg;
  2: i64 long_arg;
  3: string string_arg;
  4: bool bool_arg;
  5: binary binary_arg;
  6: double double_arg;
}

//变量默认赋值从0开始；
enum GenderEnum{
    UNKNOWN,//0
    MALE,//1
    FEMALE//2
}
//后面的变量一次递增；
enum RoleEnum{
    UNKNOWN,  // -1
    WARIOR = 0,
    MAGE,// 1
    WARLOCK,// 2
    PRIEST,// 3
    DRUID// 4
}

tips：
变量只能赋值整数，可以为负数，也可以使用 16 进制整数赋值；
变量默认从 0 开始赋值；
变量分隔符可使用「,」和「;」，可以混用也可均不用，建议统一。
不支持嵌套

可以自定义异常类型，结构上等同于结构体，所定义的异常会继承对应语言的异常基类，例如java，就会继承 java.lang.Exception。

exception PlayerNotFoundException {
    1: i32 code = 400,
    2: string msg
}

thrift定义服务相当于Java中创建Interface一样，创建的service经过代码生成命令之后就会生成客户端和服务端的框架代码。

service Twitter {
    response func1(1:Request1 request) throws (1:Exception1 exception),
    void func2(),                                                            
    bool func3(1:Request2 request) throws (1:Exception2 exception)                            
}

tips:
命名函数具有参数列表和返回值类型，参数可为空，没有返回值使用void关键字修饰；
参数类似 struct 中的成员字段定义，每个参数前都需要正整数和冒号编号，编号可以不连续；
参数列表可以使用分隔符「,」和「;」，可以混用也可均不用；
支持继承，不支持多态，不支持重载

Thrift支持C多行风格和Java/C++单行风格。

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

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

namespace cpp com.example.test
namespace java com.example.test
namespace php com.example.test

tips：
可以针对不同语言分别定义命名空间

类似于 import

include "xxx.thrift"   // include 整个文件
include "xxx.xxx"  // 单纯 include 某个变量

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