thrift IDL 快速上手

thrift IDL

IDL(interface description language)

---

数据类型

0. 基本类型：

类型	描述	说明
bool	bool类型,取值true或false
byte	8-bit有符号整数	thrift 不提供无符号整数
i16	16-bit有符号整数
i32	32-bit有符号整数
i64	64-bit有符号整数
double	64-bit 浮点数
string	utf8编码的文本串
binary	无编码的byte集

1. 结构体

thrift 结构体定义通用的结构对象，结构体可以嵌套，但没有继承，也不允许递归嵌套。每个字段唯一并拥有它们的类型。

struct Demo01 {
    1: i32 age,
    2: i64 bignumber = 1010552,  // 设置默认值
    3: double weight,
    4: string name
}

3. 容器类型

thrift提供常见的三种容器类型。
容器元素的类型可以是thrift中定义的类型，但是有些语言不可以使用结构或容器类型作为key，例如c++中set、map的key得需要重载<,=运算符等。

类型	描述	说明
list<T>	列表，对应c++ STL里面的vector，Java ArrayList，python 的list
set<T>	对应c++ STL里面的set，JAVA的HashSet，python的set
map<K, V>	对应C++ STL里面的map， Java的HashMap， python dict

4. 异常

异常除了声明时的关键字和结构（struct）定义不一样之外，其他的都一样，在目标语言中一个异常都是派生于原生的异常类。

定义：

exception Key404 {
    1: string key_name,
    2: string message
}

5. service

相当于定义接口（或者纯虚抽象类），编译器将它编译为-存根-，服务端基于其实现，客户端基于此进行远程过程调用。

service <name> {
  <returntype> <name>(<arguments>) [throws <exceptions>)]
  ...
}

eg.
service StringCache {
  void set(1:i32 key, 2:string value),
  string get(1:i32 key) throws (1:Key404 k404),
  void delete(1:i32 key)
}

6. enum 枚举

定义枚举类型：类似于c中枚举，若没有指定值默认从0开始或是上一个枚举常量的值+1。只能表示32位正整数。

enum Numberz
{
  ZERO,         /*默认从0开始*/
  ONE = 1,
  TWO,          /*上一个枚举常量的值+1*/
  THREE,
  FIVE = 5,     /* 指定某个值*/
  SIX,
  EIGHT = 0x08  /** 可以支持十六进制描述*/
}

7. typedef

给类型取别名： typedef i64 UserId

8. union

union SomeUnion {
  1: map<Numberz, UserId> map_thing,
  2: string string_thing,
  3: i32 i32_thing,
  4: Xtruct3 xtruct_thing,
  5: Insanity insanity_thing
}

9. 常量（Constant）

跨语言定义常量

const Numberz myNumberz = Numberz.ONE;
const i64 INT_VAL = 123456789;

namespace

名字空间，类似于c++中的namespace，java的package的方式，来组织代码，也有利于解决变量名字冲突。

namespace cpp  project.module
namespace java com.project.module
namespace py   project.module

namespace * project.module

说明：

注释

thrift提供shell style，c/c++ style 注释：

#单行注释

/***
  *    多行
  *    注释
  */

// c++风格单行注释

Includes

thrift的代码管理、重用，支持类似于c++的include方式引用其他文件定义的.thrift 文件

// user_type.thrift
const double PI = 3.1415926

struct UserInfoRequest {
  1:string token,
  2:i64    uid,
  3:i64    tuid,
  4:string sign,
  5:string request_uuid,
  6:string request_timestmp
}

struct UserInfoResponse {
  1:i64 uid,
  2:string uname,
  3:string uemail,
  4:string uheadimg,
  5:string udescribe,
  6:i32    ulevel,
  7:i32    permission
}

exception User404 {
    1: i64 uid,
    2: string message
}

exception ServerErr {
    1: i32 err_code,
    2: string message
}

// user_service.thrift
namespace cpp user
namespace py user

include "user_type.thrift"