Thrift开发使用笔记（1）--Thrift简介及安装使用

使用案例

1、 下载安装（Maven中添加依赖）

<dependency>
<groupId>org.apache.thrift</groupId>
<artifactId>libthrift</artifactId>
<version>0.9.3</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>1.6.6</version>
</dependency>

2、 下载编译器

下载地址：http://thrift.apache.org/download

或者直接点击：

http://www.apache.org/dyn/closer.cgi?path=/thrift/0.9.3/thrift-0.9.3.exe

3、  编写测试用例

新建demoHello.thrift，内容如下

namespace java service.demo
service Hello{
string helloString(1:string para)
i32 helloInt(1:i32 para)
bool helloBoolean(1:bool para)
void helloVoid()
string helloNull()
}

打开windows控制台进入Thrift文件夹下，输入：

thrift-0.9.3.exe  -r -gen java ./demoHello.thrift

生成目录如下：

service

└─demo

Hello.java

4、 将hello.java复制到项目中

5、 新建

HelloServiceImpl.java并实现Hello.Iface接口

package com.service.demo.impl;

import com.service.demo.Hello;
import org.apache.thrift.TException;

/**
* Created by ssjk on 2016/10/20.
*/
public class HelloServiceImpl implements Hello.Iface{

@Override
public String helloString(String para) throws TException {
return para;
}

@Override
public int helloInt(int para) throws TException {
try {
Thread.sleep(20000);
} catch (InterruptedException e) {
e.printStackTrace();
}
return para;
}

@Override
public boolean helloBoolean(boolean para) throws TException {
return para;
}

@Override
public void helloVoid() throws TException {
System.out.println("Hello word!");
}

@Override
public String helloNull() throws TException {
return null;
}
}

6、 建立启动服务

HelloServiceServer.java

package com.day06;

import com.service.demo.Hello;
import com.service.demo.impl.HelloServiceImpl;
import org.apache.thrift.TProcessor;
import org.apache.thrift.TProcessorFactory;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.protocol.TBinaryProtocol.Factory;
import org.apache.thrift.server.TServer;
import org.apache.thrift.server.TThreadPoolServer;
import org.apache.thrift.transport.TServerSocket;
import org.apache.thrift.transport.TTransportException;

public class HelloServiceServer {
/**
* 启动 Thrift 服务器
* @param args
*/
public static void main(String[] args) {
try {
// 设置服务端口为 7911
TServerSocket serverTransport = new TServerSocket(7911);
// 设置协议工厂为 TBinaryProtocol.Factory

// 关联处理器与 Hello 服务的实现
TProcessor processor = new Hello.Processor(new HelloServiceImpl());
TProcessorFactory tProcessorFactory = new TProcessorFactory(processor);
TThreadPoolServer.Args args1=new TThreadPoolServer.Args(serverTransport);
args1.processor(processor);
args1.processorFactory(tProcessorFactory);
TServer server =new TThreadPoolServer(args1);
System.out.println("Start server on port 7911...");
server.serve();
} catch (TTransportException e) {
e.printStackTrace();
}
}
}

7、 建立客户端HelloServiceClient.java

package com.day06;

import com.service.demo.Hello;
import org.apache.thrift.TException;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.protocol.TProtocol;
import org.apache.thrift.transport.TSocket;
import org.apache.thrift.transport.TTransport;
import org.apache.thrift.transport.TTransportException;

public class HelloServiceClient {
/**
* 调用 Hello 服务
* @param args
*/
public static void main(String[] args) {
try {
// 设置调用的服务地址为本地，端口为 7911
TTransport transport = new TSocket("localhost", 7911);
transport.open();
// 设置传输协议为 TBinaryProtocol
TProtocol protocol = new TBinaryProtocol(transport);
Hello.Client client = new Hello.Client(protocol);
// 调用服务的 helloString 方法
String str = client.helloString("Thrift测试");
System.out.println(str);
transport.close();
} catch (TTransportException e) {
e.printStackTrace();
} catch (TException e) {
e.printStackTrace();
}
}
}

8、 输出结果



成功！

Thrift 架构

Thrift 包含一个完整的堆栈结构用于构建客户端和服务器端。下图描绘了 Thrift 的整体架构。

图 1. 架构图



如图所示，图中黄色部分是用户实现的业务逻辑，褐色部分是根据 Thrift 定义的服务接口描述文件生成的客户端和服务器端代码框架，红色部分是根据 Thrift 文件生成代码实现数据的读写操作。红色部分以下是 Thrift 的传输体系、协议以及底层 I/O 通信，使用 Thrift 可以很方便的定义一个服务并且选择不同的传输协议和传输层而不用重新生成代码。

Thrift 服务器包含用于绑定协议和传输层的基础架构，它提供阻塞、非阻塞、单线程和多线程的模式运行在服务器上，可以配合服务器 / 容器一起运行，可以和现有的 J2EE 服务器 /Web 容器无缝的结合。

服务端和客户端具体的调用流程如下：

图 2. Server 端启动、服务时序图（查看大图）



该图所示是 HelloServiceServer 启动的过程以及服务被客户端调用时，服务器的响应过程。从图中我们可以看到，程序调用了 TThreadPoolServer 的 serve 方法后，server 进入阻塞监听状态，其阻塞在 TServerSocket 的 accept 方法上。当接收到来自客户端的消息后，服务器发起一个新线程处理这个消息请求，原线程再次进入阻塞状态。在新线程中，服务器通过 TBinaryProtocol 协议读取消息内容，调用 HelloServiceImpl 的 helloVoid 方法，并将结果写入 helloVoid_result 中传回客户端。

图 3. Client 端调用服务时序图（查看大图）



该图所示是 HelloServiceClient 调用服务的过程以及接收到服务器端的返回值后处理结果的过程。从图中我们可以看到，程序调用了 Hello.Client 的 helloVoid 方法，在 helloVoid 方法中，通过 send_helloVoid 方法发送对服务的调用请求，通过 recv_helloVoid 方法接收服务处理请求后返回的结果。

数据类型

Thrift 脚本可定义的数据类型包括以下几种类型：

• 基本类型：

o bool：布尔值，true 或 false，对应 Java 的 boolean

o byte：8 位有符号整数，对应 Java 的 byte

o i16：16 位有符号整数，对应 Java 的 short

o i32：32 位有符号整数，对应 Java 的 int

o i64：64 位有符号整数，对应 Java 的 long

o double：64 位浮点数，对应 Java 的 double

o string：未知编码文本或二进制字符串，对应 Java 的 String

• 结构体类型：

o struct：定义公共的对象，类似于 C 语言中的结构体定义，在 Java 中是一个 JavaBean

• 容器类型：

o list：对应 Java 的 ArrayList

o set：对应 Java 的 HashSet

o map：对应 Java 的 HashMap

• 异常类型：

o exception：对应 Java 的 Exception

• 服务类型：

o service：对应服务的类

协议

Thrift 可以让用户选择客户端与服务端之间传输通信协议的类别，在传输协议上总体划分为文本 (text) 和二进制 (binary) 传输协议，为节约带宽，提高传输效率，一般情况下使用二进制类型的传输协议为多数，有时还会使用基于文本类型的协议，这需要根据项目 / 产品中的实际需求。常用协议有以下几种：

• TBinaryProtocol —— 二进制编码格式进行数据传输

使用方法如清单 3 和清单 4 所示。

• TCompactProtocol —— 高效率的、密集的二进制编码格式进行数据传输

构建 TCompactProtocol 协议的服务器和客户端只需替换清单 3 和清单 4 中 TBinaryProtocol 协议部分即可，替换成如下代码：

清单 5. 使用 TCompactProtocol 协议构建的 HelloServiceServer.java

TCompactProtocol.Factory proFactory = new TCompactProtocol.Factory();

清单 6. 使用 TCompactProtocol 协议的 HelloServiceClient.java

TCompactProtocol protocol = new TCompactProtocol(transport);

• TJSONProtocol —— 使用 JSON 的数据编码协议进行数据传输

构建 TJSONProtocol 协议的服务器和客户端只需替换清单 3 和清单 4 中 TBinaryProtocol 协议部分即可，替换成如下代码：

清单 7. 使用 TJSONProtocol 协议构建的 HelloServiceServer.java

TJSONProtocol.Factory proFactory = new TJSONProtocol.Factory();

清单 8. 使用 TJSONProtocol 协议的 HelloServiceClient.java

TJSONProtocol protocol = new TJSONProtocol(transport);

• TSimpleJSONProtocol —— 只提供 JSON 只写的协议，适用于通过脚本语言解析

传输层

常用的传输层有以下几种：

• TSocket —— 使用阻塞式 I/O 进行传输，是最常见的模式

使用方法如清单 4 所示。

• TFramedTransport —— 使用非阻塞方式，按块的大小进行传输，类似于 Java 中的 NIO

若使用 TFramedTransport 传输层，其服务器必须修改为非阻塞的服务类型，客户端只需替换清单 4 中 TTransport 部分，代码如下，清单 9 中 TNonblockingServerTransport 类是构建非阻塞 socket 的抽象类，TNonblockingServerSocket 类继承 TNonblockingServerTransport

清单 9. 使用 TFramedTransport 传输层构建的 HelloServiceServer.java

TNonblockingServerTransport serverTransport;

serverTransport = new TNonblockingServerSocket(10005);

Hello.Processor processor = new Hello.Processor(new HelloServiceImpl());

TServer server = new TNonblockingServer(processor, serverTransport);

System.out.println(“Start server on port 10005 …”);

server.serve();

清单 10. 使用 TFramedTransport 传输层的 HelloServiceClient.java

TTransport transport = new TFramedTransport(new TSocket(“localhost”, 10005));

• TNonblockingTransport —— 使用非阻塞方式，用于构建异步客户端

使用方法请参考 Thrift 异步客户端构建

服务端类型

常见的服务端类型有以下几种：

• TSimpleServer —— 单线程服务器端使用标准的阻塞式 I/O

代码如下：

清单 11. 使用 TSimpleServer 服务端构建的 HelloServiceServer.java

TServerSocket serverTransport = new TServerSocket(7911);

TProcessor processor = new Hello.Processor(new HelloServiceImpl());

TServer server = new TSimpleServer(processor, serverTransport);

System.out.println(“Start server on port 7911…”);

server.serve();

客户端的构建方式可参考清单 4。

• TThreadPoolServer —— 多线程服务器端使用标准的阻塞式 I/O

使用方法如清单 3 所示。

• TNonblockingServer —— 多线程服务器端使用非阻塞式 I/O

使用方法请参考 Thrift 异步客户端构建

Thrift 异步客户端构建

Thrift 提供非阻塞的调用方式，可构建异步客户端。在这种方式中，Thrift 提供了新的类 TAsyncClientManager 用于管理客户端的请求，在一个线程上追踪请求和响应，同时通过接口 AsyncClient 传递标准的参数和 callback 对象，服务调用完成后，callback 提供了处理调用结果和异常的方法。

首先我们看 callback 的实现：

清单 12.CallBack 的实现：MethodCallback.java

package service.callback;
import org.apache.thrift.async.AsyncMethodCallback;

public class MethodCallback implements AsyncMethodCallback {
Object response = null;

public Object getResult() {
// 返回结果值
return this.response;
}

// 处理服务返回的结果值
@Override
public void onComplete(Object response) {
this.response = response;
}
// 处理调用服务过程中出现的异常
@Override
public void onError(Throwable throwable) {

}
}

如代码所示，onComplete 方法接收服务处理后的结果，此处我们将结果 response 直接赋值给 callback 的私有属性 response。onError 方法接收服务处理过程中抛出的异常，此处未对异常进行处理。

创建非阻塞服务器端实现代码，将 HelloServiceImpl 作为具体的处理器传递给异步 Thrift 服务器，代码如下：

清单 13.HelloServiceAsyncServer.java

package service.server;
import org.apache.thrift.server.TNonblockingServer;
import org.apache.thrift.server.TServer;
import org.apache.thrift.transport.TNonblockingServerSocket;
import org.apache.thrift.transport.TNonblockingServerTransport;
import org.apache.thrift.transport.TTransportException;
import service.demo.Hello;
import service.demo.HelloServiceImpl;

public class HelloServiceAsyncServer {
/**
* 启动 Thrift 异步服务器
* @param args
*/
public static void main(String[] args) {
TNonblockingServerTransport serverTransport;
try {
serverTransport = new TNonblockingServerSocket(10005);
Hello.Processor processor = new Hello.Processor(
new HelloServiceImpl());
TServer server = new TNonblockingServer(processor, serverTransport);
System.out.println("Start server on port 10005 ...");
server.serve();
} catch (TTransportException e) {
e.printStackTrace();
}
}
}

HelloServiceAsyncServer 通过 java.nio.channels.ServerSocketChannel 创建非阻塞的服务器端等待客户端的连接。

创建异步客户端实现代码，调用 Hello.AsyncClient 访问服务端的逻辑实现，将 MethodCallback 对象作为参数传入调用方法中，代码如下：

清单 14.HelloServiceAsyncClient.java

package service.client;
import java.io.IOException;
import org.apache.thrift.async.AsyncMethodCallback;
import org.apache.thrift.async.TAsyncClientManager;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.protocol.TProtocolFactory;
import org.apache.thrift.transport.TNonblockingSocket;
import org.apache.thrift.transport.TNonblockingTransport;
import service.callback.MethodCallback;
import service.demo.Hello;

public class HelloServiceAsyncClient {
/**
* 调用 Hello 服务
* @param args
*/
public static void main(String[] args) throws Exception {
try {
TAsyncClientManager clientManager = new TAsyncClientManager();
TNonblockingTransport transport = new TNonblockingSocket(
"localhost", 10005);
TProtocolFactory protocol = new TBinaryProtocol.Factory();
Hello.AsyncClient asyncClient = new Hello.AsyncClient(protocol,
clientManager, transport);
System.out.println("Client calls .....");
MethodCallback callBack = new MethodCallback();
asyncClient.helloString("Hello World", callBack);
Object res = callBack.getResult();
while (res == null) {
res = callBack.getResult();
}
System.out.println(((Hello.AsyncClient.helloString_call) res)
.getResult());
} catch (IOException e) {
e.printStackTrace();
}
}
}

HelloServiceAsyncClient 通过 java.nio.channels.Socketchannel 创建异步客户端与服务器建立连接。在本文中异步客户端通过以下的循环代码实现了同步效果，读者可去除这部分代码后再运行对比。

清单 15. 异步客户端实现同步效果代码段

Object res = callBack.getResult();

// 等待服务调用后的返回结果

while (res == null) {
res = callBack.getResult();
}

通过与清单 9 和清单 10 的代码比较，我们可以构建一个 TNonblockingServer 服务类型的服务端，在客户端构建一个 TFramedTransport 传输层的同步客户端和一个 TNonblockingTransport 传输层的异步客户端，那么一个服务就可以通过一个 socket 端口提供两种不同的调用方式。有兴趣的读者可以尝试一下。

常见问题

NULL 问题

我们在对服务的某个方法调用时，有时会出现该方法返回 null 值的情况，在 Thrift 中，直接调用一个返回 null 值的方法会抛出 TApplicationException 异常。在清单 2 中，HelloServiceImpl 里实现了 helloNull 方法，返回 null 值，我们在 HelloServiceClient.java 中加入调用该方法的代码，出现如下图所示的异常：

图 4. TApplicationException 异常

为了处理返回 null 值情况，我们要捕获该异常，并进行相应的处理，具体客户端代码实现如下：

清单 16. 处理服务返回值为 null 的代码

package service.client;
import org.apache.thrift.TApplicationException;
import org.apache.thrift.TException;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.protocol.TProtocol;
import org.apache.thrift.transport.TSocket;
import org.apache.thrift.transport.TTransport;
import org.apache.thrift.transport.TTransportException;
import service.demo.Hello;

public class HelloServiceClient {
/**
* 调用 Hello 服务，并处理 null 值问题
* @param args
*/
public static void main(String[] args) {
try {
TTransport transport = new TSocket("localhost", 7911);
transport.open();
TProtocol protocol = new TBinaryProtocol(transport);
Hello.Client client = new Hello.Client(protocol);
System.out.println(client.helloNull());
transport.close();
} catch (TTransportException e) {
e.printStackTrace();
} catch (TException e) {
if (e instanceof TApplicationException
&& ((TApplicationException) e).getType() ==
TApplicationException.MISSING_RESULT) {
System.out.println("The result of helloNull function is NULL");
}
}
}
}

调用 helloNull 方法后，会抛出 TApplicationException 异常，并且异常种类为 MISSING_RESULT，本段代码显示，捕获该异常后，直接在控制台打印“The result of helloNull function is NULL”信息。

类型定义案例

第一包（命名空间）

namespace java com.winwill.thrift

定义枚举

enum RequestType{

SAY_HELLO ,

QUERY_TIME ,

}

定义机构体

struct Request{

1:required RequestType type;

2:required string name;

3:optional i32 age

}

定义异常

exception RequestException{

1:required i32 code;

2:optional string reason;

}

定义service

service HelloService{

string doAction(1:Request request) throws (1:RequestException qe)

}

实现服务端

有阻塞，非阻塞，线程池，半同步半异步，Selector多种服务端实现模式。

TSimpleServer – 简单的单线程服务模型，常用于测试

TThreadedServer – 多线程服务模型，使用阻塞式IO，每个请求创建一个线程。(java 不支持)

TThreadPoolServer – 多线程服务模型，使用标准的阻塞式IO，预先创建一组线程处理请求。

TThreadedSelectorServer 允许你用多个线程来处理网络I/O。它维护了两个线程池，一个用来处理网络I/O，另一个用来进行请求的处理

TNonblockingServer – 多线程服务模型，使用非阻塞式IO（需使用TFramedTransport数据传输方式）,只有一个线程来处理消息

THsHaServer - 半同步半异步的服务模型，一个单独的线程用来处理网络I/O，一个worker线程池用来进行消息的处理

create Socket

TSocket：采用TCP Socket进行数据传输，阻塞型socket,用于客户端，采用系统函数read和write进行读写数据；(BIO)

TNonblockingSocket (NIO) 异步客户端使用

create Transport

TSocket：采用TCP Socket进行数据传输，阻塞型socket,用于客户端，采用系统函数read和write进行读写数据；(BIO)

TNonblockingSocket (NIO) 异步客户端使用

TSSLSocket 继承TSocket，阻塞型socket,　用于客户端；采用openssl的接口进行读写数据。

THttpTransport：采用Http传输协议进行数据传输

TFileTransport – 以文件形式进行传输。

TMemoryTransport – 将内存用于I/O. java实现时内部实际使用了简单的ByteArrayOutputStream。

TZlibTransport – 使用zlib进行压缩， 与其他传输方式联合使用。当前无java实现。

TFramedTransport – 以frame为单位进行传输，非阻塞式服务中使用。类似于Java中的NIO。

TFastFramedTransport 与TFramedTransport相比，始终使用相同的Buffer，提高了内存的使用率。

TSaslClientTransport与TSaslServerTransport， 提供SSL校验

create Protocol must same as service based on transport

TBinaryProtocol – 二进制格式.

TCompactProtocol – 压缩格式

TDenseProtocol -继承TCompactProtocol，不包含meta信息

TJSONProtocol – JSON格式

TSimpleJSONProtocol –提供JSON只写协议, 生成的文件很容易通过脚本语言解析。

基本概念：http://elf8848.iteye.com/blog/1960131

服务端编写的一般步骤：

1. 创建Handler

2. 基于Handler创建Processor

3. 创建Transport（通信方式）

4. 创建Protocol方式（设定传输格式）

5. 基于Processor, Transport和Protocol创建Server

6. 运行Server

客户端编写的一般步骤：

1. 创建Transport

2. 创建Protocol方式

3. 基于Transport和Protocol创建Client

4. 运行Client的方法

参考资源：

http://blog.csdn.net/zhu_tianwei/article/details/40948233

http://www.aboutyun.com/thread-7139-1-1.html

http://www.ibm.com/developerworks/cn/java/j-lo-apachethrift/

https://my.oschina.net/yybear/blog/101217

http://www.ibm.com/developerworks/cn/java/j-lo-apachethrift/

http://www.cnblogs.com/lori/p/3526657.html

https://my.oschina.net/penngo/blog/492253