thrift接口描述语言 (基于thrift 0.13.0版本)

thrift接口描述语言(IDL)用来定义thrift类型. 一个Thrift IDL文件用来生成各种语言使用的结构体和服务.

IDL中包含如下部分:

1. Document

Document中包含0或者多条如下的声明:

(1) include Literal

Thrift Include: 用来导入其他thrift中的符号, 在这个thrift中使用导入的thrift中的符号时, 需要带一个前缀.这个thrift编译时, 被导入thrift的对应头文件会被插入到这个thrift编译的相应文件中.

说明: Literal表示字符串常量, 写法要求有可选值(其中*表示0或者多个字符):

1) “[^”]*” (其中[^”]表示不为双引号的字符)

2) ‘[^’]*’ (其中[^’]表示不为单引号的字符)

示例: include "xxx.thrift"

(2) cpp_include Literal

C++ Include: 用来在这个thrift编译生成的文件中添加Literal头文件.

示例: cpp_include "xxx.h"

(3) namespace NamespaceScope Identifier

Namespace: 一个namespace表示一个命名空间/包/模块等, 含义基于编译成的目标语言, 其中在C++中表示命名空间名, 在golang中表示包名. NamespaceScope表示对应的编程语言, 如果使用*, 则表示对所有的语言都使用同样的Namespace名.

说明:

(1) NamespaceScope可以使用如下值取代: *, c_glib, cpp, csharp, delphi, go, java, js, lua, netcore, perl, php, py, py.twisted, rb, st, xsd.

(2) Identifier允许的写法(其中|表示或的关系, *表示出现0次或者多次): (Letter|_)(Letter | Digit | . | _ | -)*.

(3) Letter表示A-Z或者a-z中的一个字符.

(4) Digit表示0-9中的一个数字.

示例: namespace cpp tutorial

2. Definition

Definition包含如下的多条定义:

(1) const FieldType Identifier = ConstValue ListSeparator?

说明: ?表示可选, 其中ListSeparator包括两个可选值: (1) ,(逗号) (2);(分号)

用来定义一个常量, 可以参考如下示例:

const i32 INT32CONSTANT = 9853
const map<string,string> MAPCONSTANT = {'hello':'world', 'goodnight':'moon'}

(2) typedef DefinitionType Identifier

用来定义一个类型的别名, 其中DefinitionType包括可选值: (1) BaseType (2) ContainerType, BaseType和ContainerType的说明见后文, 关于定义别名, 可以参考如下示例:

typedef i32 MyInteger

(3) enum Identifier { (Identifier (= IntConstant)? ListSeparator?)* }

说明: 其中的*表示多条

用来定义一个枚举类型. 如果枚举结构体内的标识符没有提供常量, 那么第一个元素取0, 对于后续元素会比前一个元素大1. 所有提供的常量都必须是非负的. 可以参考如下示例:

enum Operation {
  ADD = 1,
  SUBTRACT = 2,
  MULTIPLY = 3,
  DIVIDE = 4
}

/**
 * Common status reporting mechanism across all services
 */
enum fb_status {
  DEAD = 0,
  STARTING = 1,
  ALIVE = 2,
  STOPPING = 3,
  STOPPED = 4,
  WARNING = 5,
}

(4) senum Identifier { (Literal ListSeparator?)* }

注: 和slist都是deprecated, 都使用string来代替.

(5) struct Identifier { Field* }

用来定义复合类型, struct中的每个成员名都需要是唯一的, 可以参考如下示例:

 struct Work {
  1: i32 num1 = 0,
  2: i32 num2,
  3: Operation op,
  4: optional string comment,
}

(6) union Identifier { Field* }

用来定义union类型, union类型中的所有成员只有一个成员有值, 当设置另一个成员时, 就只会有那个成员有值, 这个类型类似于C++中的union. 所以, union中的成员都默认为可选的(查看requiredness). 可以参考如下示例:

union Dessert  {
  1: string port
  2: string iceWine
}

(7) exception Identifier { Field* }

用来定义一个异常. exception中的每一个成员都需要是唯一的.

/**
 * Structs can also be exceptions, if they are nasty.
 */
exception InvalidOperation {
  1: i32 whatOp,
  2: string why
}

(8) service Identifier (extends Identifier)? { Function* }

用来定义使用thrift的服务器的函数接口. 一个服务可以扩展(extend)其他的服务, 那么这个服务就可以提供被扩展服务的函数接口. 关于服务的一个简单示例:

/**
 * Standard base service
 */
service FacebookService {

  /**
   * Returns a descriptive name of the service
   */
  string getName(),

  /**
   * Returns the version of the service
   */
  string getVersion(),

  /**
   * Gets the status of this service
   */
  fb_status getStatus(),

  /**
   * User friendly description of status, such as why the service is in
   * the dead or warning state, or what is being started or stopped.
   */
  string getStatusDetails(),

  /**
   * Gets the counters for this service
   */
  map<string, i64> getCounters(),

  /**
   * Gets the value of a single counter
   */
  i64 getCounter(1: string key),

  /**
   * Sets an option
   */
  void setOption(1: string key, 2: string value),

  /**
   * Gets an option
   */
  string getOption(1: string key),

  /**
   * Gets all options
   */
  map<string, string> getOptions(),

  /**
   * Returns a CPU profile over the given time interval (client and server
   * must agree on the profile format).
   */
  string getCpuProfile(1: i32 profileDurationInSec),

  /**
   * Returns the unix time that the server has been running since
   */
  i64 aliveSince(),

  /**
   * Tell the server to reload its configuration, reopen log files, etc
   */
  oneway void reinitialize(),

  /**
   * Suggest a shutdown to the server
   */
  oneway void shutdown(),

}

下面解释一下上面出现的Field和Function.

Field

Field的定义如下:

IntConstant : FieldReq? FieldType Identifier (= ConstValue)? ListSeparator?

其中FieldReq可选值包括: (1) required (2) optional (3) 如果没有指定, 则为default.

(1) required表示这个字段是必需的.

(2)  optional 表示这个字段是可选的.

大多数语言使用推荐的”isset”标志来标示optional的成员有没有被设置值.

(3) default

default是optional和required的混合,因此内部名为”opt-in,req-out”. 虽然理论上这些字段都会被写入(“req-out”), 实际上未被设置的字段总是不会写入. 尤其是, 结构体中的某个字段根据定义包含不能通过thrift发送的值. 这种情况下,唯一能够采取的方式,就是根本不写入这个值.

关于默认值特定要注意的是, 任何没有显示写入的默认值, 会随着接口定义而改变, 而将默认值写入到output中, IDL改变默认值,不会对这个产生影响.

FieldType说明:

　　1. FieldType包括可选值: (1) Identifier (thrift中定义的struct, union等) (2) BaseType (3) ContainerType

　　2. BaseType包括可选值: bool, byte, i8, i16, i32, i64, double, string, binary, slist

　　3. ContainerType包括可选值:

　　　　(1) map (cpp_type Literal)? <FieldType, FieldType>

　　　　(2) set (cpp_type Literal)? <FieldType>

　　　　(3) list<FieldType> (cpp_type literal)?

ConstValue包括如下可选值(其中+号表示1个或者多个, |表示或的关系):

(1) IntConstant: (+ | -)? Digit+

(2) DoubleConstant: (+ | -)? Digit* (.Digit+)? ( (E | e) IntConstant)?

(3) ConstList: [ (ConstValue ListSeparator?)*]

(4) ConstMap: { (ConstValue : ConstValue ListSeparator?)* }

Function:

Function的定义格式: oneway? (FieldType | void) Identifier (Field*) (throws (Field*))?  ListSeparator?

其中涉及的FieldType, Identifier, Field等的定义, 参考上面的说明.