Thrift使用指南及语法介绍

最新推荐文章于 2024-06-08 11:11:27 发布

2021不再有雨

最新推荐文章于 2024-06-08 11:11:27 发布

阅读量2.8k

点赞数

分类专栏： RPC 文章标签： rpc

本文链接：https://blog.csdn.net/w727655308/article/details/121316412

版权

RPC 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

本文详细介绍了Thrift的语法，包括数据类型、容器、结构体、异常和服务定义。Thrift文件格式中涉及命名空间、包含、类型重定义、枚举和常量等内容。此外，还讲解了Thrift的代码生成过程和最佳实践，如版本兼容性策略。Thrift作为一个跨语言的RPC框架，提供了结构化数据序列化和通信服务。

摘要由CSDN通过智能技术生成

1. 数据类型（Types）

Thrift类型系统包括预定义的基本类型，容器类型，用户自定义结构体，服务定义和异常。

基本类型（Basic types）

bool: 布尔类型，true或false，占1字节
byte: 有符号char
i16: 16位有符号整数
i32: 32位有符号整数
i64: 64位有符号整数
double: 64位浮点数
binary: 字符数组
string: 字符串（比如二进制字符串或者其他编码过的文本）

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

容器（Containers）

Thrift容器与流行编程语言的容器类型相对应，采用Java泛型风格。它有3种可用容器类型：

list：元素类型为t1的有序表，允许元素重复；
set：元素类型为t1的无序表，不允许元素重复；
map<t1,t2>：键类型为t1，值类型为t2的kv对，键不容许重复；

说明：容器中元素类型可以是除了service之外的任何合法的Thrift类型（包括结构体和异常）。

结构体和异常（Structs and Exceptions）

Thrift结构体类型在概念上类似于C语言中结构体类型，Thrift结构体将会被转换成面向对象语言中的类。
异常在语法和功能上类似于结构体，一个差别是异常使用关键字exception而不是struct来声明。但他们在语义上有明显不同之处：当定义一个RPC服务时，我们可以声明一个远程方法能够抛出一个异常。

struct Location {                          
    1: required double latitude;
    2: required double longitude;
}
 
struct Tweet {
    1: required i32 userId;                 
    2: required string userName;             
    3: required string text;
    4: optional Location loc;             
    16: optional string language = "english"
}

服务（Services）

服务的定义方法在语义上等同于面向对象语言中的接口。Thrift编译器会产生执行这些接口的client和server stub。

service Twitter {
  
    void ping(),                                                            
  
    bool postTweet(1:Tweet tweet) throws (1:TwitterUnavailable unavailable),
  
    TweetSearchResult searchTweets(1:string query);                          

    oneway void zip()                                                       
}

2. thrift文件格式

名字空间（Namespacces）

Thrift中的命名空间类似于C++中的namespace或者java中的package，命名空间提供了一种组织（隔离）代码的简便方式。命名空间也可以用于防止类型定义中的名字冲突。

由于每一种语言都有自己的独特命名空间定义方式（如python里是module）, thrift允许我们针对每一种语言定制namespace的写法：

namespace cpp com.example.project  // 1
namespace java com.example.project // 2

转换成namespace com { namespace example { namespace project
转换成 package com.example.project

文件包含（Includes）

Thrift允许一个IDL文件包含另一个IDL文件，被包含的文件会在当前目录下查找。在使用被包含文件中的类型时要注意通过文件名前缀来访问。

include "tweet.thrift"           // 文件名必须用双引号引用，末尾没有分号；
...
struct TweetSearchResult {
    1: list<tweet.Tweet> tweets; // 注意tweet前缀；
}

类型重定义（Typedef)

typedef i32 MyInteger   // 1.末尾没有分号
typedef Tweet ReTweet   // 2.struct也可以使用Typedef

枚举（Enums）

什么是枚举类型就不介绍了吧，Thrift也支持枚举。略

常量（constants）

Thrift允许定义跨语言使用的常量，复杂的类型和结构体可使用JSON形式表示。

const i32 INT_CONST = 1234;    // 1
const map<string,string> MAP_CONST = {"hello": "world", "goodnight": "moon"}

结构体定义（Defining Struct）

struct（一些系统中称作消息）是Thrift IDL中的基本组成块，由一系列的域组成，每个域由唯一整数标识符、类型、名字和可选的缺省值构成。比如定义一个简单的类似于Twitter服务：

struct Location {                            //5.一个Thrift文件中可以定义多个结构体，并且可以引用；
    1: required double latitude;
    2: required double longitude;
}

struct Tweet {
    1: required i32 userId;                  //1.每个域有一个唯一的正整数标识符；
    2: required string userName;             //2.每个字段可标识为required或optional；
    3: required string text;
    4: optional Location loc;                //3.结构体可以包含其它结构体；
    16: optional string language = "english" //4.每个字段可以设置一个默认值；
}

消息定义中的每个字段都有一个唯一数字标识符，这些数字标识符在传输时用来确定相应的字段，一旦我们定义的消息类型开始，这些数字标识符都不应该再改变。（即使将来可能要变更定义，比如增加字段，但最好不要改变原有的数字标识符）。

规范的struct定义中的每个字段均会使用required或者optional关键字进行标识。如果required标识的域没有赋值，Thrift将给予提示；如果optional标识的域没有赋值，该域将不会被序列化传输；如果某个optional标识域有缺省值而用户没有重新赋值，则该域的值一直为缺省值。

与services不同，结构体不支持继承，也就是说一个结构体不能继承另一个结构体。

服务定义（Defining Services）

在几个流行的序列化/反序列化框架（如protocal buffer）中，Thrift是少有的提供跨语言RPC服务的框架。这也是Thrift的一大特色。

Thrift编译器会根据你选择的目标语言为server端产生服务接口代码，为client端产生stubs代码。

service Twitter {
  
    void ping(),   // 1.接口声明支持以逗号或分号结束，这一点显得有点乱
  
  	//2.参数可以是基本类型或结构体
    bool postTweet(1:Tweet tweet) throws (1:TwitterUnavailable unavailable), 
  
    TweetSearchResult searchTweets(1:string query); //3.返回值可以是基本类型或结构体

    // oneway 标识符表明client端仅仅发起一个请求但不等待该请求的响应
    // oneway接口的返回类型必须是void的
    oneway void zip() //4.返回值也可以是void
}

注意：

参数列表（异常列表）的定义同结构体完全一致；

service支持继承，一个service可以通过关键字extends继承自另一个service。

注释（Comments）

Thrift支持shell风格、C语言多行风格以及Java/C++语言单行风格的注释形式。

# This is a valid comment.

/*
 * This is a multi-line comment.
 * Just like in C.
 */

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

3. 代码生成

本段主要介绍通过thrift产生各种目标语言代码的方式。这里先从几个基本概念开始，然后介绍生成的代码是怎么样组织的，进而帮助我们理解如何更有效的使用thrift。

概念

Thrift的网络架构

+-------------------------------------------+
| cGRE                                      |
| Server                                    |
| (single-threaded, event-driven etc)       |
+-------------------------------------------+
| cBLU                                      |
| Processor                                 |
| (compiler generated)                      |
+-------------------------------------------+
| cGRE                                      |
| Protocol                                  |
| (JSON, compact etc)                       |
+-------------------------------------------+
| cGRE                                      |
| Transport                                 |
| (raw TCP, HTTP etc)                       |
+-------------------------------------------+

Transport

Transport层提供了简单对网络层进行数据读写的抽象层，这使得transport层与系统其它部分（如：序列化/反序列化）中解耦。以下是Transport层提供的一些方法：

open

close

read

write

flush

In addition to the Transport interface above, Thrift also uses a ServerTransport interface used to accept or create primitive transport objects. As the name suggest, ServerTransport is used mainly on the server side to create new Transport objects for incoming connections.

除了以上几个接口，Thrift使用ServerTransport接口接收或创建基本的transport对象。正如其名，ServerTransport用在server端，为即将到来的client连接创建Transport对象。

open

listen

accept

close

这也有一些对支持thrift的编程语言的可用传输协议：

file: 对硬盘上的文件进行读写

http: http协议

Protocol

Protocol抽象层定义了一种将内存中数据结构映射成可进行网络传输数据格式的机制。换句话说，Protocol层定义了datatype怎样使用底层的Transport对类型进行编解码。因此，Protocol的实现要给出编码机制并负责对数据进行序列化。协议的编码格式有JSON、XML、纯文本、压缩的二进制等等。

Protocol接口的定义如下：

writeMessageBegin(name, type, seq)
writeMessageEnd()
writeStructBegin(name)
writeStructEnd()
writeFieldBegin(name, type, id)
writeFieldEnd()
writeFieldStop()
writeMapBegin(ktype, vtype, size)
writeMapEnd()
writeListBegin(etype, size)
writeListEnd()
writeSetBegin(etype, size)
writeSetEnd()
writeBool(bool)
writeByte(byte)
writeI16(i16)
writeI32(i32)
writeI64(i64)
writeDouble(double)
writeString(string)

name, type, seq = readMessageBegin()
readMessageEnd()
name = readStructBegin()
readStructEnd()
  
name, type, id = readFieldBegin()
readFieldEnd()
k, v, size = readMapBegin()

readMapEnd()
etype, size = readListBegin()

readListEnd()
etype, size = readSetBegin()

readSetEnd()
bool = readBool()
byte = readByte()
i16 = readI16()
i32 = readI32()
i64 = readI64()
double = readDouble()
string = readString()

Thrift Protocols是为流式而设计的，因此也没有明确的帧的概念。例如，也就是说在我们序列化一个类型时，并不需要知道其中string字符串的长度或者list中每一项的值（it is not necessary to know the length of a string or the number of items in a list before we start serializing them.）。

下面是一些大部分thrift主要支持的语言都可以使用的protocol：

binary ：简单的二进制编码，一个字段的长度和类型后面再跟上该字段的实际值
compact ：具体见THRIFT-110
Json：

Processor

Processor封装了从输入数据流中读数据和向输出流中写数据的操作。读写数据流都可以用Protocol对象表示。Processor的接口非常简单:

interface TProcessor {
    bool process(TProtocol in, TProtocol out) throws TException
}

与服务(service)相关的processor实现由thrift 编译器产生。Processor本质上就是从网络中读取数据（使用输入protocol），将处理委托给handler（由用户实现），最后将响应结果写到网络上（使用输出protocol）。

Server

Server将以上所有特性集成在一起：

创建一个transport对象

为transport对象创建输入输出protocol

基于输入输出protocol创建processor

等待连接请求并将之交给processor处理

代码生成

接下来我们讨论下针对具体语言的生成代码，除非另外说明，否则本节之后所有内容都假设使用下面的Thrift IDL。

示例IDL

namespace cpp thrift.example
namespace java thrift.example

enum TweetType {
    TWEET,
    RETWEET = 2,
    DM = 0xa,
    REPLY
}

struct Location {
    1: required double latitude;
    2: required double longitude;
}

struct Tweet {
    1: required i32 userId;
    2: required string userName;
    3: required string text;
    4: optional Location loc;
    5: optional TweetType tweetType = TweetType.TWEET;
    16: optional string language = "english";
}

typedef list<Tweet> TweetList

struct TweetSearchResult {
    1: TweetList tweets;
}

exception TwitterUnavailable {
    1: string message;
}

const i32 MAX_RESULTS = 100;

service Twitter {
    void ping(),
    bool postTweet(1:Tweet tweet) throws (1:TwitterUnavailable unavailable),
    TweetSearchResult searchTweets(1:string query);
    oneway void zip()
}

产生的文件(Java)

一个单独的文件（Constants.java）包含所有的常量定义；
每个结构体，枚举或者服务各占一个文件；
我们查看一个示例idl生成后的文件列表：

$ tree gen-java
`-- thrift
    `-- example
        |-- Constants.java
        |-- Location.java
        |-- Tweet.java
        |-- TweetSearchResult.java
        |-- TweetType.java
        `-- Twitter.java

类型转换

thrift将各种基本类型和容器类型映射到java语言中的类型，比如：

bool: boolean
binary: byte[]
byte: byte
i16: short
i32: int
i64: long
double: double
string: String
list: List
set: Set
map<t1,t2>: Map<t1, t2>
如入我们看到的那样，这种映射很直观，而且大部分情况下都是一一对应的。不过也没什么奇怪的，因为Thrift项目最初就是以Java为主要的目标语言的。

Typedefs

Java语言中对typedef没有提供任何原生支持，所以如果在Thrift IDL中使用了typedef，那么生成的java代码中会直接替换成typedef前的原始类型。也就是说即使想typedef TypeA TypeB，但在生成的java代码中，所有使用TypeB类型的地方都会用TypeA代替。像上面的IDL例子产生的Java代码中，TweetSearchResult会被替换成list<tweets>

Enums

Thrift将枚举类型映射成java的枚举类型。我们可以使用geValue方法获取枚举的值(通过TEnum接口)。此外，编译器会产生一个findByValue方法用来获取枚举对应的数值。这比利用java中枚举类型的特性有更强的鲁棒性。

Constants

Thrift把所有的常量都放在一个叫Constants的public类中，每个常量修饰符是public static final。任何基本类型的常量定义都是支持的。

4. 最佳实践

版本/兼容性

我们使用的协议可能会随着时间而变更，如果一个已经存在的消息类型不再符合我们的需求，比如打算为消息格式添加一个额外字段，但又想继续使用之前旧的thrift 消息格式生成的代码，这对thrift来说就很简单，而且不需要更改当前使用的任何代码，而仅仅需要满足以下规则：

绝不要修改thrift idl中已经存在字段的整数编号
任何新添加的字段需要设置成optional

这就意味着任何使用你的“旧”消息格式的代码序列化的消息可以被你的新代码所解析，因为它们不会丢掉任何required的元素。你应该为这些元素设置合理的默认值，这样新的代码就能够正确地与老代码生成的消息交互了。类似地，你的新代码创建的消息也能被你的老代码解析（老的二进制程序在解析的时候只是简单地将新字段忽略）。然而，未知的字段是不会被抛弃的，如果之后消息被序列化，未知的字段会随之一起被序列化——所以，如果消息传到了新代码那里，则新的字段仍然可用；