Apache Ignite Binary Object Restrictions

这段内容讲的是 Apache Ignite 的 Binary Object（二进制对象）格式实现中的一些限制（Restrictions），这些限制来源于 Ignite 为了提高序列化/反序列化性能而采用的内部机制。下面我们逐条解释这些限制的含义、原因以及应对方法。

📌 一、字段和类型的 ID 是通过哈希计算的（Hash Code）

原文：

Internally, the type and fields of a binary object are identified by their IDs. The IDs are calculated as the hash codes of the corresponding string names. Consequently, fields or types with the identical name hash are not allowed.

翻译：

在 Ignite 内部，每个类型（class）和字段（field） 都会通过一个 唯一的 ID 来标识；
这个 ID 是通过 字段名或类名的字符串哈希值（hash code） 计算出来的；
因此，如果两个字段或类型名的哈希值相同，就会冲突，Ignite 不允许这种情况。

示例：

java 复制代码

// 假设 fieldA 和 fieldB 的哈希值相同（虽然字符串不同）
String fieldA = "name1";
String fieldB = "name2";

if (fieldA.hashCode() == fieldB.hashCode()) {
    // Ignite 会抛出异常
}

如何解决？

避免使用哈希冲突的字段名或类名；
如果你确实需要使用这样的名字，可以自定义 ID 生成逻辑。

自定义 ID 生成方式：

你可以在配置中设置一个 BinaryIdMapper，自定义字段或类的 ID 映射：

java 复制代码

BinaryConfiguration binaryCfg = new BinaryConfiguration();
binaryCfg.setIdMapper(new BinaryIdMapper() {
    @Override
    public int typeId(String typeName) {
        // 自定义类 ID
        if ("com.example.MyClass".equals(typeName))
            return 12345;
        return typeName.hashCode();
    }

    @Override
    public int fieldNameId(int typeId, String fieldName) {
        // 自定义字段 ID
        return fieldName.hashCode();
    }
});

📌 二、不允许在类继承层次结构中使用相同的字段名

原文：

For the same reason, the binary object format does not allow identical field names on different levels of class hierarchy.

翻译：

由于字段 ID 是基于字段名的哈希值生成的；
如果在父类和子类中使用了 相同名字的字段，Ignite 会认为它们是同一个字段；
所以 不允许在类继承结构中使用相同的字段名，否则会引发冲突或数据错误。

示例：

java 复制代码

class Parent {
    private String id;
}

class Child extends Parent {
    private String id; // ❌ 错误：不允许在子类中定义同名字段
}

如何解决？

避免在父类和子类中使用相同的字段名；
或者，使用自定义字段 ID 映射来区分字段（如上文）；
或者，使用 @BinaryField 注解为字段指定别名。

java 复制代码

class Child extends Parent {
    @BinaryField("childId") // 用别名避免冲突
    private String id;
}

📌 三、实现了 Externalizable 接口的类不会使用 Binary Format

原文：

If a class implements the Externalizable interface, Ignite uses OptimizedMarshaller instead of the binary one. OptimizedMarshaller uses the writeExternal() and readExternal() methods to serialize and deserialize objects; therefore, the class must be added to the classpath of the server nodes.

翻译：

如果某个类实现了 Externalizable 接口；
Ignite 会使用 OptimizedMarshaller 而不是 BinaryMarshaller 来序列化这个类；
它会调用 writeExternal() 和 readExternal() 方法进行序列化；
所以，这个类必须存在于集群中所有节点的 classpath 中；
否则会抛出 ClassNotFoundException。

示例：

java 复制代码

public class MyData implements Externalizable {
    private int value;

    public void writeExternal(ObjectOutput out) throws IOException {
        out.writeInt(value);
    }

    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
        value = in.readInt();
    }
}

注意事项：

使用 Externalizable 的类 不能使用 Binary Object 格式；
必须保证所有节点都有这个类的定义；
否则，反序列化会失败。

✅ 总结：Binary Object 的主要限制

限制	原因	解决方法
字段名或类名哈希冲突	ID 是字段名或类名的哈希值	使用 `BinaryIdMapper` 自定义 ID
类继承中字段名不能重复	同上	使用 `@BinaryField` 注解指定别名
实现 `Externalizable` 的类不使用 Binary Format	使用 OptimizedMarshaller	所有节点都必须包含该类

📚 建议做法

场景	建议
使用 Binary Object	避免字段名冲突，避免继承结构中重名字段
自定义 ID 映射	使用 `BinaryIdMapper` 避免哈希冲突
使用 Externalizable 类	确保所有节点 classpath 包含该类
使用 `@BinaryField`	控制字段映射，避免冲突

如果你还有关于 Ignite 的 序列化机制、Binary Object、类加载、缓存配置、集群部署 等方面的问题，欢迎继续提问！