Apache Ignite 二进制客户端协议数据格式详解

Apache Ignite 二进制客户端协议数据格式详解

ignite Apache Ignite 项目地址: https://gitcode.com/gh_mirrors/ignite16/ignite

概述

Apache Ignite 是一个高性能、集成化和分布式的内存计算平台，它提供了强大的数据处理能力。在分布式系统中，客户端与服务器之间的通信协议至关重要。本文将深入解析 Ignite 二进制客户端协议中的数据格式规范，帮助开发者更好地理解和应用这一技术。

基本数据格式结构

Ignite 二进制协议中的所有数据类型都采用统一的表示方式：类型码+值的组合形式。

| 字段 | 字节大小 | 描述 | |------|---------|------| | type_code | 1 | 有符号单字节整数，表示值的类型 | | value | 可变 | 值本身，其格式和大小取决于 type_code |

这种设计既简洁又高效，能够支持从基本类型到复杂对象的广泛数据表示需求。

基本数据类型

数值类型

Ignite 支持多种数值类型，所有数值类型都采用小端字节序(Little-endian)：

1. Byte(类型码:1)：单字节有符号整数
2. Short(类型码:2)：2字节有符号整数
3. Int(类型码:3)：4字节有符号整数
4. Long(类型码:4)：8字节有符号整数
5. Float(类型码:5)：4字节IEEE 754浮点数
6. Double(类型码:6)：8字节IEEE 754浮点数

其他基本类型

1. Char(类型码:7)：单个UTF-16编码单元(2字节)
2. Bool(类型码:8)：布尔值(1字节，0表示false，非0表示true)
3. NULL(类型码:101)：空值标记，没有附加数据

标准对象类型

字符串(类型码:9)

UTF-8编码的字符串，格式如下：

| 字段 | 字节大小 | 描述 | |------|---------|------| | length | 4 | 字符串的字节长度 | | data | length | UTF-8编码的字符串数据(不含BOM) |

UUID(类型码:10)

128位全局唯一标识符：

| 字段 | 字节大小 | 描述 | |------|---------|------| | most_significant_bits | 8 | UUID的高64位 | | least_significant_bits | 8 | UUID的低64位 |

时间相关类型

1. Timestamp(类型码:33)：高精度时间戳

   • msecs_since_epoch(8字节)：自1970年1月1日以来的毫秒数
   • msec_fraction_in_nsecs(4字节)：毫秒内的纳秒部分(0-999999)

2. Date(类型码:11)：日期(8字节，自1970年1月1日以来的毫秒数)

3. Time(类型码:36)：时间(8字节，自当天午夜以来的毫秒数)

十进制数(类型码:30)

任意精度的数值：

| 字段 | 字节大小 | 描述 | |------|---------|------| | scale | 4 | 缩放因子(10的幂次) | | length | 4 | 数值的字节长度 | | data | length | 数值本身(大端序)，第一位为符号位 |

枚举(类型码:28)

枚举类型值：

| 字段 | 字节大小 | 描述 | |------|---------|------| | type_id | 4 | 枚举类型的ID | | ordinal | 4 | 枚举值的序号 |

数组类型

Ignite 支持两种数组格式：基本类型数组和对象数组。

基本类型数组

基本类型数组(类型码12-19)只包含值的有效载荷(payload)，不包含类型码。所有元素具有相同的大小。

通用结构：

| 字段 | 字节大小 | 描述 | |------|---------|------| | length | 4 | 数组元素数量 | | elements | 类型相关 | 连续的元素有效载荷 |

例如，Int数组(类型码14)的每个元素占4字节，总大小为4 + length*4字节。

对象数组

对象数组(类型码20-22,29,31,34,37)包含完整的值(类型码+有效载荷)，允许元素为NULL。

通用结构：

| 字段 | 字节大小 | 描述 | |------|---------|------| | length | 4 | 数组元素数量 | | elements | 可变 | 完整的元素值(类型码+有效载荷)或NULL标记 |

例如，String数组(类型码20)中，每个字符串元素占用5+字符串长度字节，NULL元素只占1字节。

集合类型

通用对象数组(类型码23)

可以包含任意类型对象的数组：

| 字段 | 字节大小 | 描述 | |------|---------|------| | type_id | 4 | 元素的基础类型ID(-1表示Object) | | length | 4 | 元素数量 | | elements | 可变 | 任意类型的完整对象值 |

集合(类型码24)

通用的集合类型，包含类型提示：

| 字段 | 字节大小 | 描述 | |------|---------|------| | length | 4 | 元素数量 | | type | 1 | 集合类型提示(如HASH_SET=3) | | elements | 可变 | 元素值 |

支持多种集合类型提示，包括普通集合(USER_COL)、数组列表(ARR_LIST)、链表(LINKED_LIST)、哈希集(HASH_SET)等。

映射(类型码25)

键值对集合：

| 字段 | 字节大小 | 描述 | |------|---------|------| | length | 4 | 键值对数量 | | type | 1 | 映射类型提示(HASH_MAP=1) | | elements | 可变 | 交替的键和值 |

最佳实践

1. 类型选择：根据数据特性选择最合适的类型，例如对货币值使用Decimal而非Double

2. 集合提示：尽量使用与目标平台匹配的集合类型提示，提高序列化/反序列化效率

3. NULL处理：对象数组和集合中NULL值只占1字节，合理使用可以节省空间

4. 时间精度：需要高精度时间时使用Timestamp而非Date

5. 字符串编码：确保字符串数据是有效的UTF-8编码

通过深入理解Ignite二进制协议的数据格式，开发者可以更高效地实现客户端与Ignite集群的交互，优化数据传输性能，并确保数据的准确性和一致性。

ignite Apache Ignite 项目地址: https://gitcode.com/gh_mirrors/ignite16/ignite