Thrift.0

0. Thrift的特性

1. 安装Thrift编译器

[Todo]

http://thrift.apache.org/docs/install/

http://thrift.apache.org/docs/install/os_x

2. Thrift类型 (Thrift Type)

[Ref]: http://thrift.apache.org/docs/types

基本类型

bool: A boolean value (true or false)
byte: An 8-bit signed integer
i16: A 16-bit signed integer
i32: A 32-bit signed integer
i64: A 64-bit signed integer
double: A 64-bit floating point number
string: A text string encoded using UTF-8 encoding

特殊类型

binary: a sequence of unencoded bytes

结构体 (Structs)

Thrift structs define a common object -- they are essentially equivalent to classes in OOP languages,

but without inheritance. A struct has a set of strongly typed fields, each with a unique name identifier.

Fields may have various annotations (numeric field IDs, optional default values, etc.)

容器 (Containers)

Thrift containers are strongly typed containers that map to commonly used and commonly available

container types in most programming languages.

三种类型的容器:

list: An ordered list of elements.

set: An unordered set of unique elements. (PHP does not support sets, so it is treated similar to a List)

map: A map of strictly unique keys to values.

容器元素可以是任意合法的Thrift Type.

[注]: For maximal compatibility, the key type for map should be a basic type rather than a struct or container type.

异常 (Exceptions)

Exceptions are functionally equivalent to structs, except that they inherit from the native exception

base class as appropriate in each target programming language, in order to seamlessly integrate with the

native exception handling in any given language.

服务 (Services)

Services are defined using Thrift types. Definition of a service is semantically equivalent to defining an

interface (or a pure virtual abstract class) in object oriented programming. The Thrift compiler generates

fully functional client and server stubs that implement the interface.

A service consists of a set of named functions, each with a list of parameters and a return type.

Note that void is a valid type for a function return, in addition to all other defined Thrift types.

Additionally, an oneway modifier keyword may be added to a void function, which will generate

code that does not wait for a response. Note that a pure void function will return a response to

the client which guarantees that the operation has completed on the server side. With oneway

method calls the client will only be guaranteed that the request succeeded at the transport layer.

Oneway method calls of the same client may be executed in parallel/out of order by the server.

3. IDL

[Ref]: http://thrift.apache.org/docs/idl

A Thrift IDL file is processed by the Thrift code generator to produce code for the various target

languages to support the defined structs and services in the IDL file.

3.1 Document

每个Thrift文档包含0或者多个header，header后紧跟0或者多个definitions.

[1]  Document        ::=  Header* Definition*

3.2 Header

A header is either a Thrift include, a C++ include, or a namespace declaration.

[2]  Header          ::=  Include | CppInclude | Namespace

3.2.1 Thrift Include

An include makes all the symbols from another file visible (with a prefix) and adds corresponding

include statements into the code generated for this Thrift document.

[3]  Include         ::=  'include' Literal

3.2.2 C++ Include

A C++ include adds a custom C++ include to the output of the C++ code generator for this Thrift document.

[4]  CppInclude      ::=  'cpp_include' Literal

3.2.3 Namespace

A namespace declares which namespaces/package/module/etc. the type definitions in this file will be declared in

for the target languages. The namespace scope indicates which language the namespace applies to;

a scope of '*' indicates that the namespace applies to all target languages.

[5]  Namespace       ::=  ( 'namespace' ( NamespaceScope Identifier ) |
                                        ( 'smalltalk.category' STIdentifier ) |
                                        ( 'smalltalk.prefix' Identifier ) ) |
                          ( 'php_namespace' Literal ) |
                          ( 'xsd_namespace' Literal )

[6]  NamespaceScope  ::=  '*' | 'cpp' | 'java' | 'py' | 'perl' | 'rb' | 'cocoa' | 'csharp'

3.3 Definition

[7]  Definition      ::=  Const | Typedef | Enum | Senum | Struct | Union | Exception | Service

3.3.1 Const

[8]  Const           ::=  'const' FieldType Identifier '=' ConstValue ListSeparator?

3.3.2 Typedef

[9]  Typedef         ::=  'typedef' DefinitionType Identifier

3.3.3 Enum

An enum creates an enumerated type, with named values. If no constant value is supplied, the value is

either 0 for the first element, or one greater than the preceding value for any subsequent element.

Any constant value that is supplied must be non-negative.

[10] Enum            ::=  'enum' Identifier '{' (Identifier ('=' IntConstant)? ListSeparator?)* '}'

3.3.4 Senum

Senum (and Slist) are now deprecated and should both be replaced with String.

3.3.5 Struct

[12] Struct          ::=  'struct' Identifier 'xsd_all'? '{' Field* '}'

[注]: The xsd_all keyword has some purpose internal to Facebook but serves no purpose in Thrift itself.

Use of this feature is strongly discouraged

3.3.6 Union

Unions are similar to structs, except that they provide a means to transport exactly one field of a

possible set of fields, just like union {} in C++. Consequently, union members cannot be required fields.

[13] Union          ::=  'union' Identifier 'xsd_all'? '{' Field* '}'

[注]: The xsd_all keyword has some purpose internal to Facebook but serves no purpose in Thrift itself.

Use of this feature is strongly discouraged

3.3.7 Exception

Exceptions are similar to structs except that they are intended to integrate with the native exception

handling mechanisms in the target languages. The name of each field must be unique within the exception.

[14] Exception       ::=  'exception' Identifier '{' Field* '}'

3.3.8 Service

A service provides the interface for a set of functionality provided by a Thrift server. The interface is simply

a list of functions. A service can extend another service, which simply means that it provides the functions of

the extended service in addition to its own.

[15] Service         ::=  'service' Identifier ( 'extends' Identifier )? '{' Function* '}'

3.3.9 Field

[16] Field           ::=  FieldID? FieldReq? FieldType Identifier ('= ConstValue)? XsdFieldOptions ListSeparator?

Field ID

[17] FieldID         ::=  IntConstant ':'

Field Requiredness

[18] FieldReq        ::=  'required' | 'optional'

XSD Options

[注]: These have some internal purpose at Facebook but serve no current purpose in Thrift.

Use of these options is strongly discouraged.

[19] XsdFieldOptions ::=  'xsd_optional'? 'xsd_nillable'? XsdAttrs?

[20] XsdAttrs        ::=  'xsd_attrs' '{' Field* '}'

3.3.10 Functions

[21] Function        ::=  'oneway'? FunctionType Identifier '(' Field* ')' Throws? ListSeparator?

[22] FunctionType    ::=  FieldType | 'void'

[23] Throws          ::=  'throws' '(' Field* ')'

3.3.11 Types

[24] FieldType       ::=  Identifier | BaseType | ContainerType

[25] DefinitionType  ::=  BaseType | ContainerType

[26] BaseType        ::=  'bool' | 'byte' | 'i16' | 'i32' | 'i64' | 'double' | 'string' | 'binary' | 'slist'

[27] ContainerType   ::=  MapType | SetType | ListType

[28] MapType         ::=  'map' CppType? '<' FieldType ',' FieldType '>'

[29] SetType         ::=  'set' CppType? '<' FieldType '>'

[30] ListType        ::=  'list' '<' FieldType '>' CppType?

[31] CppType         ::=  'cpp_type' Literal

3.3.12 Constant Values

[32] ConstValue      ::=  IntConstant | DoubleConstant | Literal | Identifier | ConstList | ConstMap

[33] IntConstant     ::=  ('+' | '-')? Digit+

[34] DoubleConstant  ::=  ('+' | '-')? Digit* ('.' Digit+)? ( ('E' | 'e') IntConstant )?

[35] ConstList       ::=  '[' (ConstValue ListSeparator?)* ']'

[36] ConstMap        ::=  '{' (ConstValue ':' ConstValue ListSeparator?)* '}'

3.3.13 Basic Definitions

Literal

[37] Literal         ::=  ('"' [^"]* '"') | ("'" [^']* "'")

Identifier

[38] Identifier      ::=  ( Letter | '_' ) ( Letter | Digit | '.' | '_' )*

[39] STIdentifier    ::=  ( Letter | '_' ) ( Letter | Digit | '.' | '_' | '-' )*

List Separator

[40] ListSeparator   ::=  ',' | ';'

Letters and Digits

[41] Letter          ::=  ['A'-'Z'] | ['a'-'z']

[42] Digit           ::=  ['0'-'9']

3.4 例子