文档章节

Thrift 接口定义语言(interface description language)参考手册

lostsquirrel
 lostsquirrel
发布于 2017/03/22 16:52
字数 2627
阅读 322
收藏 0

Thrift 接口定义语言(interface description language)

说明: 本文适用于作为参考手册查阅。不适合为学习教程。

文档(Document)

一个文档即一个.thrift文件

语法:

[1]  Document        ::=  Header* Definition*
  • Header: 头信息,一个文档可以有0到多个Header
  • Definition: 定义体, 一个文档可以有0到多个Definition

头信息(Header)

头信息

语法:

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

Thrift include

引入另一个文档中的所有 Thrift类型的 定义,使其在本文档中可见(可用)并在生成本文档代码时加入对应的引入信息(比如java import 对应的类)

语法:

[3]  Include         ::=  'include' Literal
  • Literal: 字面量,这里指引入.thrift文件名称(全路径?待测试)

C++ Include

添加自定的C++ include,会输出到本文档对应的C++代码中

语法:

[4]  CppInclude      ::=  'cpp_include' Literal
  • Literal: 字面量,这里指引入C++头文件文件名称(全路径?待验证,短期应该不会做)

namespace

名字空间 对应各语言的namespaces/package/module 等。 比如java的包

语法:

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

  • NamespaceScope 对就名字空间输出的作用域
  • Identifier: 标识符,在这里指对应各语言的namespaces/package/module 等

注意 Smalltalk 两种类型的名字空间指令

  • smalltalk.prefix: Prepended to generated classnames.
  • smalltalk.category: Determines the category for generated classes.
  • Smalltalk allows filing both classes and methods within classes into named groups. These named groups of methods are called categories. (不了解smalltack, 暂不作处理)

注意 The php_namespace directive will be deprecated at some point in the future in favor of the scoped syntax, but the scoped syntax is not yet supported for PHP. (不了解php, 暂不作处理)

注意 xsd_namespace 指令是Facebook内部有作用,对Thrift本身没啥作用。强烈建议不要使用

NamespaceScope

名字空间输出的作用域

语法:

[6]  NamespaceScope  ::=  '*' | 'cpp' | 'java' | 'py' | 'perl' | 'rb' | 'cocoa' | 'csharp'
  • * 表示对所有的输出语言(不单独指定每种语言)
  • cpp 生成代码时c++ 的 namespace
  • java 生成代码时Java对应的包名

定义指令(Definition)

文档的主体内容, 定义常量,对象,服务,异常等

语法:

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

常量 (Const)

生成对应语言的常量定义

语法:

[8]  Const           ::=  'const' FieldType Identifier '=' ConstValue ListSeparator?
  • FieldType: 字段类型,这里指常量类型
  • Identifier: 标识符,在这里指常量名
  • ConstValue: 常量值,这里指定义常量的值
  • ListSeparator: 列表分隔符,如果常量后还有其它定义,需要加分隔符

类型别名(Typedef)

给类型启一个别名

语法:

[9]  Typedef         ::=  'typedef' DefinitionType Identifier
  • DefinitionType: 预定义类型,这里别名的源类型,(注:可应该也可以是自定义类型,但自定义类型不太可能再命别名, 需要验证)
  • Identifier: 标识符,在这里指别名

枚举(Enum)

创建一个枚举类型,默认第一个元素值为0,后一个比前一个大一;不能是负数

语法:

[10] Enum            ::=  'enum' Identifier '{' (Identifier ('=' IntConstant)? ListSeparator?)* '}'
  • Identifier: 标识符,这里指 枚举名称
  • IntConstant: 常整数, 这里指 枚举量的值 (但有限制, 不能小于0, 后一个枚举昊默认比前一个大1)
  • ListSeparator: 列表分隔符, 这里指 枚举量之间的分隔

zuo: 如果将第一个枚举量值设置为5,下一个为4, 再下一个默认为会是多少?

Senum(废弃)

Slist 各 Senum都被废弃了。用string 代替。 注:不太清楚这是什么,有了解的请告知下,不胜感激

语法:

[11] Senum           ::=  'senum' Identifier '{' (Literal ListSeparator?)* '}'

结构体(Struct)

Thrift中基础的复合类型,一个结构体中的每个字段名必须唯一。

语法:

[12] Struct          ::=  'struct' Identifier 'xsd_all'? '{' Field* '}'
  • Identifier: 标识符,结构体名称(类名)
  • Field: 字段, 指里指结构体中的字段

注意 xsd_all 又是Facebook 家内部的玩,不要用就对了

语法:

[12.x] Struct          ::=  'struct' Identifier '{' Field* '}'

联合体(Union)

说是和 C++ union {}一样,(C++ 记不太清了,暂不译)

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 are implicitly considered optional (see requiredness).

语法:

[13] Union          ::=  'union' Identifier 'xsd_all'? '{' Field* '}'
  • Identifier: 标识符,这里指联合体名称
  • Field: 字段,这里指联合体里的字段

注意 xsd_all 又是Facebook 家内部的玩意儿,不要用就对了 语法:

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

异常(Exception)

基本上和结构体是一样的,唯一的区别就是会继续目标语言的异常基类,以便无缝集成对应语言的异常处理

语法:

[14] Exception       ::=  'exception' Identifier '{' Field* '}'
  • Identifier: 标识符,这里指异常名称
  • Field: 字段,这里指异常内的字段

服务(Service)

Thrift服务的功能接口,一个接口其实就是一系列方法(这是什么意思呢?) 一个服务可以继承另一个服务,表示它提供自己功能的同时也提供它继续接口的功能

语法:

[15] Service         ::=  'service' Identifier ( 'extends' Identifier )? '{' Function* '}'
  • Identifier: 标识符,这里指服务名称
  • Function: 函数,这里指服务内的功能方法

字段 (Field)

字段定义语法

语法:

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

字段ID(Field ID)

字段ID, 整数常量

语法:

[17] FieldID         ::=  IntConstant ':'
  • IntConstant: 常整数, 这里指 字段ID, 从1开始,依次累加

是否必要(Field Requiredness)

指定这个字段的值是否必须要有,同数据库相似吧

语法:

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

必要(required)

  • Write: Required fields are always written and are expected to be set.
  • Read: Required fields are always read and are expected to be contained in the input stream.
  • Defaults values: are always written

可选 (optional)

Write: Optional fields are only written when they are set Read: Optional fields may, or may not be part of the input stream. Default values: are written when the isset flag is set

默认(default requiredness)

Write: In theory, the fields are always written. There are some exceptions to that rule, see below. Read: Like optional, the field may, or may not be part of the input stream. Default values: may not be written (see next section) Default requiredess is a good starting point. The desired behaviour is a mix of optional and required, hence the internal name "opt-in, req-out". Although in theory these fields are supposed to be written ("req-out"), in reality unset fields are not always written. This is especially the case, when the field contains a value, which by definition cannot be transported through thrift. The only way to achieve this is by not writing that field at all, and that's what most languages do.

关于默认值(Semantics of Default Values)

There are ongoing discussions about that topic, see JIRA for details. Not all implementations treat default values in the very same way, but the current status quo is more or less that default fields are typically set at initialization time. Therefore, a value that equals the default may not be written, because the read end will set the value implicitly. On the other hand, an implementation is free to write the default value anyways, as there is no hard restriction that prevents this.

The major point to keep in mind here is the fact, that any unwritten default value implicitly becomes part of the interface version. If that default is changed, the interface changes. If, in contrast, the default value is written into the output data, the default in the IDL can change at any time without affecting serialized data. (包含其它模块(客户端与服务端调用时)信息,暂不清楚,暂不作翻译, 后续补充)

XSD Options

Facebook 家内部的玩意儿,不要用就对了

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

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

函数 (Functions)

定义在服务中的函数

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

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

[23] Throws          ::=  'throws' '(' Field* ')'
  • Field: Function中的Field 指函数的参数字段

  • FunctionType: 返回值有两个情况

    • void 无返回值,但与 oneway 有区别
    • FieldType 其它类型
  • Throws: 抛出异常, 当然需要定义好异常类

  • Field: Throws 后台面的这个Field, 我觉得应该是Exception才对, 需要验证(计划)

  • oneway: 不需要等待返回,详见服务

  • Identifier: 标识符, 这里指函数名

类型 (Types)

可用类型,另见Thrift 类型介绍

字段类型 (FieldType)

字段类型,可以是标识符(自定义类型名称), 基本类型,容器类型

语法:

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

预定义类型 (DefinitionType)

Thrift 提供的类型

语法:

[25] DefinitionType  ::=  BaseType | ContainerType

基本类型(BaseType)

Thrift 提供基本数据类型

语法:

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

详见: 基本类型

容器类型(ContainerType)

语法:

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

字典类型(MapType)

键值对

语法:

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

SetType

无序,唯一序列

语法:

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

列表(ListType)

有序序列

语法:

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

C++类型 (CppType)

语法:

[31] CppType         ::=  'cpp_type' Literal
  • Literal: 字面量, 这里指 对应类型的名称

常量 (Constant Values)

语法:

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

整型常量(IntConstant)

可以是正整数,或负整数

语法:

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

浮点型常量(DoubleConstant)

实数或以科学计数方式表现

语法:

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

常量列表(ConstList)

看起来常量列表的元素也可以是常量列表

语法:

[35] ConstList       ::=  '[' (ConstValue ListSeparator?)* ']'
  • ConstValue: 常量值,这里指 常量列表的元素值
  • ListSeparator: 列表分隔符, 这里指常量元素值之间的分隔符

常量字典(ConstMap)

键值对常量

语法:

[36] ConstMap        ::=  '{' (ConstValue ':' ConstValue ListSeparator?)* '}'
  • ConstValue: 常量值,这里指常量字典的 键和值
  • ListSeparator: 列表分隔符, 这里指键值对之间的分隔符

基础定义(Basic Definitions)

字面量(Literal)

单引号或双引号都可以

语法:

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

验证能不能使用转义

标识符(Identifier)

语法:

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

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

列表分隔符(List Separator)

语法:

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

字母(Letters)

语法:

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

数字(Digits)

语法:

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

示例

(后续添加)

来源

译自 https://thrift.apache.org/docs/idl

© 著作权归作者所有

lostsquirrel
粉丝 1
博文 25
码字总数 14766
作品 0
成都
后端工程师
私信 提问
RPC框架Thrift例子-PHP调用C++后端程序

前言 前段时间用了一下Facebook的开源RPC框架Thrift,做PHP客户端调用C++后端程序,真心觉得Thrift不错! 本文项目地址: https://github.com/zekunyan/ThriftDemoPHP_CPP 先看看本文的例子示...

snowing1990
2016/08/16
106
0
基于Thrift的java和PHP互相调用范例

首先我们看看 Thrift是什么? thrift是一个软件框架,用来进行可扩展且跨语言的服务的开发。它结合了功能强大的软件堆栈和代码生成引擎,以构建在 C++, Java, Go,Python, PHP, Ruby, Erlang,...

r00txx
2016/09/09
745
0
[Thrift]Apache Thrift入门Java实例

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/SunnyYoona/article/details/52606287 1. 概述 Apache Thrift 是 Facebook 实现的一种高效的、支持多种编程语...

sjf0115
2016/09/21
0
0
Thrift教程初级篇——thrift安装环境变量配置第一个实例

前言: 因为项目需要跨语言,c++客户端,web服务端,远程调用等需求,所以用到了RPC框架Thrift,刚开始有点虚,第一次接触RPC框架,后来没想到Thrift开发方便上手快,而且性能和稳定性也不错...

诸葛西门
2017/08/18
0
0
Thrift学习笔记—IDL基本类型

原文地址:http://zhwen.org/xlog/?p=658 thrift 采用IDL(Interface Definition Language)来定义通用的服务接口,并通过生成不同的语言代理实现来达到跨语言、平台的功能。在thrift的IDL中...

helight
2014/01/22
15K
0

没有更多内容

加载失败,请刷新页面

加载更多

nginx学习笔记

中间件位于客户机/ 服务器的操作系统之上,管理计算机资源和网络通讯。 是连接两个独立应用程序或独立系统的软件。 web请求通过中间件可以直接调用操作系统,也可以经过中间件把请求分发到多...

码农实战
今天
5
0
Spring Security 实战干货:玩转自定义登录

1. 前言 前面的关于 Spring Security 相关的文章只是一个预热。为了接下来更好的实战,如果你错过了请从 Spring Security 实战系列 开始。安全访问的第一步就是认证(Authentication),认证...

码农小胖哥
今天
10
0
JAVA 实现雪花算法生成唯一订单号工具类

import lombok.SneakyThrows;import lombok.extern.slf4j.Slf4j;import java.util.Calendar;/** * Default distributed primary key generator. * * <p> * Use snowflake......

huangkejie
昨天
12
0
PhotoShop 色调:RGB/CMYK 颜色模式

一·、 RGB : 三原色:红绿蓝 1.通道:通道中的红绿蓝通道分别对应的是红绿蓝三种原色(RGB)的显示范围 1.差值模式能模拟三种原色叠加之后的效果 2.添加-颜色曲线:调整图像RGB颜色----R色增强...

东方墨天
昨天
11
1
将博客搬至CSDN

将博客搬至CSDN

算法与编程之美
昨天
13
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部