跨语言RPC框架Thrift实战

Thrift框架定义

Apache Thrift 是一款由Facebook于2007年开源、后捐赠给Apache基金会的跨语言RPC（远程过程调用）框架。它通过一套独立的接口定义语言（IDL）来定义数据类型和服务接口，并借助代码生成引擎，在多种编程语言之间生成高效的网络通信代码。

核心定位 ：Thrift不只是一个通信协议，更是一套完整的服务治理与通信解决方案，涵盖了数据序列化、传输层协议、服务端/客户端模型以及多语言运行时支持。

关键组成：

IDL编译器 ：将.thrift文件编译成目标语言的源码。
语言运行时库：为各语言提供序列化、传输、IO处理的基础能力。
传输与协议层：可插拔的传输方式（如Socket、HTTP）和协议格式（如Binary、Compact、JSON）。

Thrift框架优点

2.1 跨语言支持能力突出

支持超过25种编程语言（包括C++、Java、Python、Go、Node.js、PHP、Ruby等），使异构系统间的服务调用变得透明且高效。

2.2 性能优异，资源开销低

二进制序列化：默认采用二进制编码，数据体积小，解析速度快。
紧凑协议（Compact Protocol） 进一步压缩整数和字符串，节省带宽。
相比于基于文本的协议（如HTTP+JSON），Thrift在CPU和内存消耗上具有明显优势。

2.3 灵活的传输层与协议层设计

通过分层架构（Transport → Protocol → Processor → Server），开发者可以自由组合：

传输方式：阻塞Socket、非阻塞Socket、HTTP等。
协议格式：Binary、Compact、JSON、Multiplexed（多服务复用）。

2.4 支持多种服务模型

内置单线程、线程池、非阻塞（NIO）等多种服务端模式，可适配不同并发场景。

2.5 接口定义与实现解耦

IDL文件作为"契约"，将服务接口与具体实现彻底分离，有利于前后端并行开发和版本管理。

2.6为什么选择Thrift ，而不选择Http

|-----------|-----------------------|------------------------------|
| 对比维度 | Thrift | HTTP（REST/JSON） |
| 协议类型 | 二进制RPC协议（可选JSON） | 基于文本的HTTP/1.1或HTTP/2 |
| 序列化效率 | 高（Binary/Compact），体积小 | 低（JSON文本冗余大） |
| 解析速度 | 快（无需复杂字符串解析） | 慢（需词法/语法解析） |
| 跨语言性 | 原生支持多语言代码生成 | 依赖手动序列化/反序列化 |
| 服务治理 | 内置接口契约，强类型约束 | 需依赖OpenAPI等外部文档 |
| 适用场景 | 高性能微服务、高频内部调用 | 对外API、浏览器/移动端兼容、缓存穿透敏感场景 |
| 学习成本 | 需学习IDL语法和框架机制 | 通用标准，上手容易 |

选择建议：

内部服务间高并发、低延迟调用 → 优先Thrift。
对外暴露API、需要浏览器或第三方系统兼容 → 优先HTTP。
混合场景：可在网关层提供HTTP接入，后端内部使用Thrift。

lDL详解

IDL（Interface Definition Language） 是Thrift的核心契约工具，用于独立于具体编程语言描述服务接口和数据结构。

作用

作为服务提供方与消费方之间的共同约定。
通过编译器自动生成各语言的服务端骨架（Skeleton）和客户端代理（Stub）。
保证不同语言间的数据格式与调用方法一致。

文件结构

一个标准的.thrift文件基本上包含：

namespace → 定义生成代码的包/命名空间

include → 引用其他thrift文件

typedef → 类型别名

常量定义

结构体（struct） → 复杂数据类型

枚举（enum） → 枚举类型

异常（exception） → 自定义异常

服务（service） → 接口方法定义

IDL语法

注释：支持C/C++风格 // 和 /* */。
命名空间 ：namespace <语言> <路径>，如 namespace java com.example.demo。
文件引入 ：include "shared.thrift"。
类型定义 ：使用 typedef 为已有类型起别名，如 typedef i64 UserId。
常量：const i32 MAX_RETRY = 3。
必填与可选 ：字段可标记为 required（必须传递）或 optional（可选），未标记时默认为 optional 但带有默认值行为。

基本数据类型

|----------|------------|-----------------------|
| 类型 | 说明 | 对应Java类型（示例） |
| bool | 布尔值 | boolean |
| byte | 有符号8位整数 | byte |
| i16 | 有符号16位整数 | short |
| i32 | 有符号32位整数 | int |
| i64 | 有符号64位整数 | long |
| double | 64位浮点数 | double |
| string | UTF-8编码字符串 | String |
| binary | 字节序列（Blob） | ByteBuffer / byte\[\] |

集合数据类型

|------------|--------------------|-----------------|
| 类型 | 定义方式 | 说明 |
| list<T> | list<i32> | 有序列表，可重复 |
| set<T> | set<string> | 无序集合，不可重复 |
| map<K,V> | map<string, i64> | 键值对映射，键类型可为基本类型 |

定义常量

复制代码

// 数值型常量
const i32 DEFAULT_TIMEOUT = 3000;
const i64 MAX_FILE_SIZE = 10485760;  // 10MB
const double PI = 3.1415926;

// 布尔常量
const bool ENABLE_CACHE = true;
const bool IS_DEBUG_MODE = false;

// 字符串常量
const string DEFAULT_ENCODING = "UTF-8";
const string SERVICE_VERSION = "v2.1.0";

Struct类型

struct 是Thrift中最核心的复合数据类型，用于定义一组相关的字段集合，类似于编程语言中的类（Class）或POJO（Plain Old Java Object）。结构体是Thrift中进行数据传输的基本单元，几乎所有服务方法的请求参数和响应结果都通过结构体来承载。

语法格式

复制代码

struct <结构体名称> {
  <字段序号>: <可选性> <字段类型> <字段名> [= <默认值>]
  [逗号或分号可选]
}

字段组成要素

注意：标有 "required" 的字段为必填项，提交时请务必完整填写。

官方不推荐用 required：

使用 required会固化接口契约，限制接口的演进能力。一旦服务端变更，容易导致老客户端调用失败，引发线上事故。因此官方不推荐使用 `required`，更推荐运行时条件校验的方式，以保持接口的灵活性与兼容性。

|----------|-------------------------------------------|------|
| 要素 | 说明 | 是否必须 |
| 字段序号 | 正整数，从1开始，用于序列化时的字段标识 | ✅ 必须 |
| 可选性 | required / optional / 未标注（默认optional） | ❌ 可选 |
| 字段类型 | 基本类型、容器类型、其他struct、enum等 | ✅ 必须 |
| 字段名 | 小驼峰命名，如 userName 、userId | ✅ 必须 |
| 默认值 | 当字段未传递时使用的值 | ❌ 可选 |

使用案例

复制代码

// 用户信息结构体
struct User {
  1: required i64 userId,           // 必填字段
  2: required string userName,      // 必填字段
  3: optional string email,         // 可选字段
  4: optional i32 age = 0,          // 可选字段，带默认值
  5: optional string phoneNumber,   // 可选字段
  6: optional bool isActive = true  // 可选字段，默认true
}

嵌套类型使用案例

复制代码

// 地址信息
struct Address {
  1: required string province,
  2: required string city,
  3: required string district,
  4: optional string detailAddress,
  5: optional string zipCode
}

// 订单信息（嵌套Address）
struct Order {
  1: required i64 orderId,
  2: required i64 userId,
  3: required list<OrderItem> items,   // 容器嵌套
  4: required Address shippingAddress,  // 结构体嵌套
  5: optional string remark = "",
  6: optional i64 createTime
}

枚举

枚举（Enum） 用于定义一组具名的常量集合，表示某个字段只能取预定义的一组值之一。枚举在Thrift中会被编译成各语言原生的枚举类型（如Java的enum、Python的Enum类等），提供类型安全和代码可读性。他的数值都是i32的整数类型。

语法格式

复制代码

enum <枚举名称> {
  <常量名1> = <整数值1>,
  <常量名2> = <整数值2>,
  ...
}

使用案例

cpp 复制代码

// 订单状态枚举
enum OrderStatus {
  PENDING = 0,      // 待支付
  PAID = 1,         // 已支付
  SHIPPED = 2,      // 已发货
  COMPLETED = 3,    // 已完成
  CANCELLED = 4     // 已取消
}

// 用户角色枚举
enum UserRole {
  GUEST = 0,        // 游客
  USER = 1,         // 普通用户
  VIP = 2,          // VIP用户
  ADMIN = 3,        // 管理员
  SUPER_ADMIN = 4   // 超级管理员
}

枚举类型如果不指定后面的数值是，它默认是递增的，但是实际开发中还是推荐使用显示指定的方式。

cpp 复制代码

enum MixEnum {
  A = 1,
  B,        // 自动为2
  C = 10,
  D,        // 自动为11
  E = 5     // ❌ 错误：值必须递增，不能小于前一个（5 < 11）
}

异常

异常（Exception） 是Thrift中用于定义服务端业务异常的特殊结构体。当服务端处理请求时发生业务错误（如用户不存在、订单已取消等），可以通过抛出异常的方式将错误信息传递给客户端。

语法格式

cpp 复制代码

exception <异常名称> {
  <字段序号>: <可选性> <字段类型> <字段名> [= <默认值>],
  ...
}

使用示例

cpp 复制代码

// 基础业务异常
exception BusinessException {
  1: required i32 errorCode,
  2: required string errorMessage,
  3: optional string detailInfo,
  4: optional i64 timestamp
}

// 用户不存在异常
exception UserNotFoundException {
  1: required i64 userId,
  2: required string message = "用户不存在"
}

// 参数验证异常
exception ValidationException {
  1: required string fieldName,
  2: required string reason,
  3: optional string actualValue
}



//服务中可以抛出多种异常
service OrderService {
  Order createOrder(1: CreateOrderRequest request) 
    throws (1: UserException e, 2: OrderException e, 3: BaseException e)
}

Service（服务定义类型）

Service（服务） 是Thrift IDL中最核心的顶层定义，用于声明一组远程可调用的方法接口。Service相当于传统面向对象编程中的接口（Interface），定义了服务端能够提供的所有RPC方法，包括方法名、参数类型、返回值类型以及可能抛出的异常。

核心定位 ：Service是客户端与服务端之间的通信契约，客户端通过Service定义生成代理（Proxy/Stub），服务端通过Service定义生成骨架（Skeleton），双方基于此契约进行透明的远程调用。

语法格式

cpp 复制代码

service <服务名称> [extends <父服务名称>] {
  <返回值类型> <方法名>(<参数列表>) [throws (<异常列表>)]
  <返回值类型> <方法名>(<参数列表>) [throws (<异常列表>)]
  ...
}

使用案例展示

cpp 复制代码

// 定义一个简单的服务，包含一个方法
service HelloService {
  // 无参数，返回字符串
  string sayHello(),
  
  // 带参数，返回字符串
  string sayHelloTo(1: string name),
  
  // 带多个参数，返回字符串类型
  string sayHelloWithAge(1: string name, 2: i32 age)
}

namespace命名空间

Namespace（命名空间） 是Thrift IDL中用于指定生成代码的包名/模块名的关键字。它告诉Thrift编译器：为不同编程语言生成的代码应该放在哪个包（Package）、命名空间（Namespace）或模块（Module）下。

核心作用：

避免不同项目间的类名冲突
组织和管理生成的代码结构
符合各语言的项目规范和最佳实践

语法格式

复制代码

namespace <语言标识> <命名空间路径>

|-------------|----------|---------------|-----------------------------------------------------------------|
| 语言 | 关键字 | 命名空间格式 | 生成代码示例 |
| Java | java | 包路径，用. 分隔 | package com.example.service; |
| Python | py | 模块路径，用. 分隔 | 生成在对应模块目录下 |
| Go | go | 包路径，用/ 分隔 | package service |
| C++ | cpp | 命名空间，用:: 分隔 | namespace com { namespace example { namespace service { } } } |
| C# | csharp | 命名空间，用. 分隔 | namespace Com.Example.Service |
| PHP | php | 命名空间，用\ 分隔 | namespace Com\Example\Service; |
| Node.js | js | 模块路径 | 生成在对应模块下 |
| Ruby | rb | 模块路径 | module Com::Example::Service |
| Swift | swift | 命名空间 | import ComExampleService |

使用案例

cpp 复制代码

// 为不同语言分别指定命名空间
namespace java com.example.thrift.demo
namespace py com.example.thrift.demo
namespace go com/example/thrift/demo
namespace cpp com.example.thrift.demo
namespace csharp Com.Example.Thrift.Demo
namespace php Com\\Example\\Thrift\\Demo
namespace js com.example.thrift.demo
namespace rb Com::Example::Thrift::Demo

Thrift编译器

核心作用

Thrift编译器（thrift命令）是整个Thrift框架的核心引擎 。它的作用可以概括为一句话：把语言无关的IDL定义，翻译成各语言专用的代码。

具体来说，它的核心功能就是根据 .thrift 文件，自动生成你所需要的编程语言的代码。这些生成的代码替你完成了所有"脏活累活"，包括：

数据结构的序列化与反序列化逻辑 ：把你定义的 struct 变成自带读写方法的类。
RPC服务的基础框架：生成服务端骨架和客户端调用代理。

这样一来，你就不用手动编写大量繁琐的、用于网络传输和对象转换的样板代码，可以把精力完全集中在业务逻辑上。

安装

安装Thrift编译器，根据你的操作系统选择:

Apache Thrift - Index of install/ 这个时下载的软件，大家可以按着自己的操作系统进行安装

Apache Download Mirrors windows的用户直接在这里下载就可以了。

但是需要配置环境变量，配置之后，可以执行命令thrift --version

如果这里显示失败的话，就需要将我们的thrift-<版本号>.exe 文件。请确保把它重命名 为 thrift.exe。执行就可以成功的执行了。

编译

编译命令

cpp 复制代码

thrift -gen <语言> <你的IDL文件名>.thrift

//使用 -o 指定将文件生成到哪个文件夹下
thrift -gen java -o ./src/main/java user_service.thrift

尝试执行

cpp 复制代码

//指定将文件放到哪里
namespace java com.hdk.rpc

//执行之后创建出User类
struct User {
    1: i32 id;
    2: string name;
    3: string password;
    4: i32 age;
}


//创建出服务
service UserService {
    User getUser(1: string name);

    User getUserByPassword(1: string password);
}

执行命令之后，编译出java代码：

Thrift协议

协议决定了 数据如何序列化/反序列化 。就是把你的 User 对象变成二进制或 JSON 格式，以及反过来。

常用协议类型

|-------------------------|-------------------|--------------------|
| 协议 | 说明 | 特点 |
| TBinaryProtocol | 二进制格式，Thrift 默认协议 | 高效、紧凑，但不可读 |
| TCompactProtocol | 压缩二进制格式 | 比 Binary 更省空间，推荐使用 |
| TJSONProtocol | JSON 格式 | 可读性好，适合调试或跨语言 |
| TSimpleJSONProtocol | 简化 JSON（只写不读） | 用于输出调试日志 |
| TDebugProtocol | 调试用，可读文本 | 开发测试时使用 |

当前介绍了我们可以使用的协议类型，但是数据的格式需要服务端和客户端统一才可以序列化和反序列化成功，下面问大家展示一下在代码中是如何使用的。

客户端构建方式

java 复制代码

TProtocol protocol = new TBinaryProtocol(transport);
//对于其他类型的，其实就是换一个类 new就可以了

服务端构建方式

在服务端进行创建的时候，我们要创建一个工厂的方式。

java 复制代码

TBinaryProtocol.Factory factory = new TBinaryProtocol.Factory();
//对于其他类型的，其实就是换一个类 new就可以了

Thrift传输层

传输层决定了 数据如何从 A 点送到 B 点。它封装了底层的 I/O 操作，屏蔽了网络细节。

常用传输层类型

|----------------------|--------------------|------------------------|----------------------|
| 传输层 | 工作原理 | 适用场景 | 注意点 |
| TSocket | 阻塞式Socket，一个连接一个线程 | 开发测试、小流量内部工具（QPS<100） | 连接数多时性能差 |
| TFramedTransport | 数据前加4字节长度头，配合NIO | 线上高并发RPC、微服务调用 | 非阻塞服务必须用这个，两端要统一 |
| TMemoryTransport | 纯内存读写，无网络I/O | 单元测试、序列化测试 | 不能跨进程通信 |
| TFileTransport | 写入本地文件 | 请求审计日志、流量回放 | 受磁盘I/O限制 |
| TZlibTransport | Zlib压缩/解压 | 跨机房调用、公网传输、大数据量 | CPU换带宽，两端都要开启 |
| THttpTransport | 封装成HTTP POST请求 | 穿透防火墙（80/443端口）、浏览器端调用 | HTTP头有额外开销 |

客户端创建方式

java 复制代码

//TSocket
TTransport transport = new TSocket("localhost", 8080);

//TFramedTransport
TTransport transport = new TSocket("localhost", 8080);

TFramedTransport tFramedTransport = new TFramedTransport(transport, 2048);

服务端创建方式

java 复制代码

TServerTransport serverTransport = new TServerSocket(8080);
//TFramedTransport
 TServer.Args arg = new TSimpleServer.Args(serverTransport)
          .transportFactory(new TFramedTransport.Factory())  // ← 这一步
          .processor(userServiceProcessor)
          .protocolFactory(factory);

重要规则：协议和传输层必须匹配！

|------------------------------------|------------------------------------|-------------|
| 服务端 | 客户端 | 结果 |
| TBinaryProtocol + TSocket | TBinaryProtocol + TSocket | ✅ 正常工作 |
| TCompactProtocol + TSocket | TCompactProtocol + TSocket | ✅ 正常工作 |
| TBinaryProtocol + TFramedTransport | TBinaryProtocol + TFramedTransport | ✅ 正常工作 |
| TCompactProtocol + TSocket | TBinaryProtocol + TSocket | ❌ 协议不匹配，报错 |
| TBinaryProtocol + TSocket | TBinaryProtocol + TFramedTransport | ❌ 传输层不匹配，报错 |

快速开始

接下来在这里为大家展示一个使用thrift的开发学习demo.下面的demo只是让大家感受一下。

创建.thrift文件

cpp 复制代码

//指定将文件放到哪里
namespace java com.hdk.rpc

//执行之后创建出User类
struct User {
    1: i32 id;
    2: string name;
    3: string password;
    4: i32 age;
}


//创建出服务
service UserService {
    User getUser(1: string name);

    User getUserByPassword(1: string password);
}

通过命令，进行文件编译。编译之后将生成的文件copy到项目中，我在这里直接将文件copy到了thrift-api文件中，使用这个文件用户在实际开发中，进行客户端和服务端之间的通信。

服务端需要实现的Iface接口，客户端使用client进行开发。

引入依赖

XML 复制代码

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

服务端应用

创建服务端的应用，这个服务端的应用就是我们在实际开发中的server端。服务端中实现UserService.Iface接口

java 复制代码

public class UserServiceImpl implements UserService.Iface{
    @Override
    public User getUser(String name) throws TException {
        if(name == null ||"".equals(name)){
            throw new RuntimeException("用户名不能为空");
        }
        return new User(new Random().nextInt(10000),name,"123456",new Random().nextInt(100));
    }

    @Override
    public User getUserByPassword(String password) throws TException {
        if(password == null ||"".equals(password)){
            throw new RuntimeException("密码不能为空");
        }
        return new User(new Random().nextInt(10000),getName(),"123456",new Random().nextInt(100));
    }

    private String getName() {
        String[] firstName = {"张","王","李","赵","刘","陈","李","章","璋"};
        String[] lastName = {"三","四","五","六","七","八","九","十"};
        return firstName[new Random().nextInt(firstName.length)]+lastName[new Random().nextInt(lastName.length)];
    }
}

客户端应用

在实际开发中，客户端通过依赖 thrift-api 模块中的接口定义，使用生成的 Client 类与服务端进行通信。整个调用过程对开发者透明，就像调用本地方法一样简单。

java 复制代码

public static void main(String[] args) throws TTransportException {
        // 1. 创建传输层：监听 8080 端口，等待客户端连接
        TServerTransport serverTransport = new TServerSocket(8080);
        // 2. 创建处理器：将客户端请求路由到 UserServiceImpl 业务实现
        UserService.Processor<UserServiceImpl> userServiceProcessor =
                new UserService.Processor<>(new UserServiceImpl());
        // 3. 创建协议工厂（为什么用工厂？）
        //    客户端只有 1 条连接 → 直接 new TBinaryProtocol(transport)
        //    服务端要处理 N 条并发连接 → 框架每 accept 一个连接就调用 factory.getProtocol(transport)
        //    工厂模式让框架控制创建时机，为每条连接生成独立的 Protocol 实例
        TBinaryProtocol.Factory factory = new TBinaryProtocol.Factory();
        // 4. 组装 TSimpleServer 参数：传输 + 处理器 + 协议
        TServer.Args arg = new TSimpleServer.Args(serverTransport)
                .processor(userServiceProcessor)
                .protocolFactory(factory);
        // 5. 创建并启动服务端，阻塞当前线程，持续接收请求
        TSimpleServer tSimpleServer = new TSimpleServer(arg);
        tSimpleServer.serve();
    }

网络服务模型详解

Thrift 提供了多种网络服务模型，用于满足不同场景下的性能需求。从不同维度可以划分为：

线程模型维度：单线程、多线程、事件驱动
I/O 模型维度：阻塞 I/O、非阻塞 I/O

Thrift 四种服务模型对比

|-----------------------------|--------|--------|---------------------------------------------|------------|
| Server 模型 | I/O 模式 | 处理线程模型 | 一句话总结 | 生产推荐 |
| TSimpleServer | 阻塞 | 单线程 | 一次一个，纯玩具，只适合测试 | ❌ |
| TThreadPoolServer | 阻塞 | 线程池 | 一连接一线程，连接多了线程数爆炸，C10K扛不住 | ⚠️ 谨慎使用 |
| TNonblockingServer | 非阻塞 | 单线程 | NIO收发包，但业务也在这个线程处理，一阻塞全卡 | ❌ |
| THsHaServer | 非阻塞 | 线程池 | NIO + Worker线程池，解决了业务阻塞问题，但 Selector 还是只有一个 | ✅ 还行 |
| TThreadedSelectorServer | 非阻塞 | 线程池 | 多Selector + Worker池，I/O读写也并发，吞吐最高 | ✅✅ 最优解 |

各层职责

|----------|----------------|--------------|
| 层级 | 职责 | 关注点 |
| 服务模型 | 如何处理并发请求（线程策略） | 线程、并发、性能 |
| 传输层 | 数据如何通过网络收发 | Socket、连接、网络 |
| 协议层 | 数据如何编码解码 | 序列化格式、兼容性 |

三层组合矩阵

服务模型 × 传输层

|--------------------|--------------------|----------|
| 服务模型 | 可用传输层 | 说明 |
| TSimpleServer | TSocket | 阻塞传输 |
| TThreadPoolServer | TSocket | 阻塞传输 |
| TNonblockingServer | TNonblockingSocket | 必须用非阻塞传输 |
| THsHaServer | TNonblockingSocket | 必须用非阻塞传输 |

服务模型 × 协议层（完全自由组合）

|--------------------|-------|--------|
| 服务模型 | 可用协议层 | 说明 |
| TSimpleServer | 任意协议 | ✅ 自由组合 |
| TThreadPoolServer | 任意协议 | ✅ 自由组合 |
| TNonblockingServer | 任意协议 | ✅ 自由组合 |
| THsHaServer | 任意协议 | ✅ 自由组合 |