1. Overview

1.概述

In this article, we will discover how to develop cross-platform client-server applications with the help of RPC framework called Apache Thrift.

在这篇文章中，我们将发现如何在名为Apache Thrift的RPC框架的帮助下开发跨平台的客户端-服务器应用程序。

We will cover:

我们将涵盖。

Defining data types and service interfaces with IDL
Installing the library and generating the sources for different languages
Implementing the defined interfaces in particular language
Implementing client/server software

If you want to go straight to examples, proceed straight to section 5.

如果你想直接进入实例，请直接进入第5节。

2. Apache Thrift

2.阿帕奇的节俭

Apache Thrift was originally developed by the Facebook development team and is currently maintained by Apache.

Apache Thrift最初由Facebook开发团队开发，目前由Apache维护。

In comparison to Protocol Buffers, which manage cross-platform object serialization/deserialization processes, Thrift mainly focuses on the communication layer between components of your system.

与管理跨平台对象序列化/反序列化过程的Protocol Buffers相比，Thrift主要关注系统组件间的通信层。

Thrift uses a special Interface Description Language (IDL) to define data types and service interfaces which are stored as .thrift files and used later as input by the compiler for generating the source code of client and server software that communicate over different programming languages.

Thrift使用一种特殊的接口描述语言（IDL）来定义数据类型和服务接口，这些接口被存储为.thrift文件，随后被编译器作为输入，用于生成通过不同编程语言进行通信的客户端和服务器软件的源代码。

To use Apache Thrift in your project, add this Maven dependency:

要在你的项目中使用Apache Thrift，需要添加这个Maven依赖。

<dependency>
    <groupId>org.apache.thrift</groupId>
    <artifactId>libthrift</artifactId>
    <version>0.10.0</version>
</dependency>

You can find the latest version in the Maven repository.

您可以在Maven资源库中找到最新版本。

3. Interface Description Language

3.界面描述语言

As already described, IDL allows defining of communication interfaces in a neutral language. Below you will find the currently supported types.

如前所述，IDL允许用一种中性语言定义通信接口。下面你会发现目前支持的类型。

3.1. Base Types

3.1.基本类型

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

3.2. Special Types

3.2.特殊类型

binary – a sequence of unencoded bytes
optional – a Java 8’s Optional type

3.3. Structs

3.3.结构

Thrift structs are the equivalent of classes in OOP languages but without inheritance. A struct has a set of strongly typed fields, each with a unique name as an identifier. Fields may have various annotations (numeric field IDs, optional default values, etc.).

Thrift structs相当于OOP语言中的类，但没有继承性。一个结构有一组强类型的字段，每个字段有一个唯一的名字作为标识符。字段可以有各种注释（数字字段ID，可选的默认值，等等）。

3.4. Containers

3.4.容器

Thrift containers are strongly typed containers:

Thrift容器是强类型的容器。

list – an ordered list of elements
set – an unordered set of unique elements
map<type1,type2> – a map of strictly unique keys to values

Container elements may be of any valid Thrift type.

容器元素可以是任何有效的Thrift类型。

3.5. Exceptions

3.5.例外情况

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

异常在功能上等同于结构，只是它们继承了本地异常。

3.6. Services

3.6.服务

Services are actually communication interfaces defined using Thrift types. They consist of a set of named functions, each with a list of parameters and a return type.

服务实际上是使用Thrift类型定义的通信接口。它们由一组命名的函数组成，每个函数都有一个参数列表和一个返回类型。

4. Source Code Generation

4.源代码生成

4.1. Language Support

4.1.语言支持

There’s a long list of currently supported languages:

目前支持的语言有一个很长的列表。

C++
C#
Go
Haskell
Java
Javascript
Node.js
Perl
PHP
Python
Ruby

You can check the full list here.

你可以查看完整的名单这里。

4.2. Using Library’s Executable File

4.2.使用库的可执行文件

Just download the latest version, build and install it if necessary, and use the following syntax:

只需下载最新版本，必要时构建和安装它，并使用以下语法。

cd path/to/thrift
thrift -r --gen [LANGUAGE] [FILENAME]

In the commands set above, [LANGUAGE] is one of the supported languages and [FILENAME] is a file with IDL definition.

在上面的命令集中，[LANGUAGE]是支持的语言之一，[FILENAME]是一个带有IDL定义的文件。

Note the -r flag. It tells Thrift to generate code recursively once it notices includes in a given .thrift file.

注意-r标志。它告诉Thrift一旦注意到某个.thrift文件中的包含物，就会递归地生成代码。

4.3. Using Maven Plugin

4.3.使用Maven插件

Add the plugin in your pom.xml file:

在你的pom.xml文件中添加该插件。

<plugin>
   <groupId>org.apache.thrift.tools</groupId>
   <artifactId>maven-thrift-plugin</artifactId>
   <version>0.1.11</version>
   <configuration>
      <thriftExecutable>path/to/thrift</thriftExecutable>
   </configuration>
   <executions>
      <execution>
         <id>thrift-sources</id>
         <phase>generate-sources</phase>
         <goals>
            <goal>compile</goal>
         </goals>
      </execution>
   </executions>
</plugin>

After that just execute the following command:

之后，只需执行以下命令。

mvn clean install

Note that this plugin will not have any further maintenance anymore. Please visit this page for more information.

请注意，这个插件将不再有任何进一步的维护。请访问本页面了解更多信息。

5. Example of a Client-Server Application

5.客户端-服务器应用程序的例子

5.1. Defining Thrift File

5.1.定义节俭的文件

Let’s write some simple service with exceptions and structures:

让我们写一些带有异常和结构的简单服务。

namespace cpp com.baeldung.thrift.impl
namespace java com.baeldung.thrift.impl

exception InvalidOperationException {
    1: i32 code,
    2: string description
}

struct CrossPlatformResource {
    1: i32 id,
    2: string name,
    3: optional string salutation
}

service CrossPlatformService {

    CrossPlatformResource get(1:i32 id) throws (1:InvalidOperationException e),

    void save(1:CrossPlatformResource resource) throws (1:InvalidOperationException e),

    list <CrossPlatformResource> getList() throws (1:InvalidOperationException e),

    bool ping() throws (1:InvalidOperationException e)
}

As you can see, the syntax is pretty simple and self-explanatory. We define a set of namespaces (per implementation language), an exception type, a struct, and finally a service interface which will be shared across different components.

正如你所看到的，其语法相当简单，不言自明。我们定义了一组命名空间（每一种实现语言），一个异常类型，一个结构，最后是一个服务接口，它将在不同的组件之间共享。

Then just store it as a service.thrift file.

然后将其作为service.thrift文件存储即可。

5.2. Compiling and Generating a Code

5.2.编译和生成代码

Now it’s time to run a compiler which will generate the code for us:

现在是时候运行一个编译器，它将为我们生成代码。

thrift -r -out generated --gen java /path/to/service.thrift

As you might see, we added a special flag -out to specify the output directory for generated files. If you did not get any errors, the generated directory will contain 3 files:

正如你可能看到的，我们添加了一个特殊的标志-out来指定生成文件的输出目录。如果你没有得到任何错误，generated目录将包含3个文件。

CrossPlatformResource.java
CrossPlatformService.java
InvalidOperationException.java

Let’s generate a C++ version of the service by running:

让我们通过运行来生成一个C++版本的服务。

thrift -r -out generated --gen cpp /path/to/service.thrift

Now we get 2 different valid implementations (Java and C++) of the same service interface.

现在我们得到了同一个服务接口的两个不同的有效实现（Java和C++）。

5.3. Adding a Service Implementation

5.3.添加一个服务实现

Although Thrift has done most of the work for us, we still need to write our own implementations of the CrossPlatformService. In order to do that, we just need to implement a CrossPlatformService.Iface interface:

尽管Thrift已经为我们做了大部分工作，我们仍然需要编写我们自己的CrossPlatformService的实现。为了做到这一点，我们只需要实现一个CrossPlatformService.Iface接口。

public class CrossPlatformServiceImpl implements CrossPlatformService.Iface {

    @Override
    public CrossPlatformResource get(int id) 
      throws InvalidOperationException, TException {
        return new CrossPlatformResource();
    }

    @Override
    public void save(CrossPlatformResource resource) 
      throws InvalidOperationException, TException {
        saveResource();
    }

    @Override
    public List<CrossPlatformResource> getList() 
      throws InvalidOperationException, TException {
        return Collections.emptyList();
    }

    @Override
    public boolean ping() throws InvalidOperationException, TException {
        return true;
    }
}

5.4. Writing a Server

5.4.编写一个服务器

As we said, we want to build a cross-platform client-server application, so we need a server for it. The great thing about Apache Thrift is that it has its own client-server communication framework which makes communication a piece of cake:

正如我们所说，我们想建立一个跨平台的客户-服务器应用程序，所以我们需要一个服务器。Apache Thrift的伟大之处在于它有自己的客户-服务器通信框架，这使得通信变得小菜一碟。

public class CrossPlatformServiceServer {
    public void start() throws TTransportException {
        TServerTransport serverTransport = new TServerSocket(9090);
        server = new TSimpleServer(new TServer.Args(serverTransport)
          .processor(new CrossPlatformService.Processor<>(new CrossPlatformServiceImpl())));

        System.out.print("Starting the server... ");

        server.serve();

        System.out.println("done.");
    }

    public void stop() {
        if (server != null && server.isServing()) {
            System.out.print("Stopping the server... ");

            server.stop();

            System.out.println("done.");
        }
    }
}

First thing is to define a transport layer with the implementation of TServerTransport interface (or abstract class, to be more precise). Since we are talking about server, we need to provide a port to listen to. Then we need to define a TServer instance and choose one of the available implementations:

第一件事是用TServerTransport接口（或更准确的说是抽象类）的实现定义一个传输层。由于我们谈论的是服务器，我们需要提供一个端口来监听。然后我们需要定义一个TServer实例并选择一个可用的实现。

TSimpleServer – for simple server
TThreadPoolServer – for multi-threaded server
TNonblockingServer – for non-blocking multi-threaded server

And finally, provide a processor implementation for chosen server which was already generated for us by Thrift, i.e. CrossPlatofformService.Processor class.

最后，为选择的服务器提供一个处理器实现，这个处理器已经由Thrift为我们生成，即CrossPlatofformService.Processor类。

5.5. Writing a Client

5.5.编写客户端

And here is the client’s implementation:

而这里是客户的实施。

TTransport transport = new TSocket("localhost", 9090);
transport.open();

TProtocol protocol = new TBinaryProtocol(transport);
CrossPlatformService.Client client = new CrossPlatformService.Client(protocol);

boolean result = client.ping();

transport.close();

From a client perspective, the actions are pretty similar.

从客户的角度来看，这些行动是非常相似的。

First of all, define the transport and point it to our server instance, then choose the suitable protocol. The only difference is that here we initialize the client instance which was, once again, already generated by Thrift, i.e. CrossPlatformService.Client class.

首先，定义传输并将其指向我们的服务器实例，然后选择合适的协议。唯一不同的是，我们在这里初始化客户端实例，而这个实例又是由Thrift生成的，即CrossPlatformService.Client类。

Since it is based on .thrift file definitions we can directly call methods described there. In this particular example, client.ping() will make a remote call to the server which will respond with true.

由于它是基于.thrift文件定义的，我们可以直接调用其中描述的方法。在这个特殊的例子中，client.ping() 将对服务器进行远程调用，服务器将回应true。

6. Conclusion

6.结论

In this article, we’ve shown you the basic concepts and steps in working with Apache Thrift, and we’ve shown how to create a working example which utilizes Thrift library.

在这篇文章中，我们向你展示了使用Apache Thrift的基本概念和步骤，我们还展示了如何利用Thrift库创建一个工作实例。

As usually, all the examples can be always found over in the GitHub repository.

通常，所有的例子都可以在GitHub资源库中找到。