Dubbo RPC 中 Hessian 序列化协议深度剖析 —— 从原理到线上问题

// Dubbo 源码: org.apache.dubbo.common.serialize.Serialization
@SPI("hessian2")  // 默认扩展名为 hessian2
public interface Serialization {
    byte getContentTypeId();
    ObjectOutput serialize(URL url, OutputStream output) throws IOException;
    ObjectInput deserialize(URL url, InputStream input) throws IOException;
}

// Hessian2Output 源码简化
public void writeInt(int value) throws IOException {
    if (INT_DIRECT_MIN <= value && value <= INT_DIRECT_MAX) {
        // -16 ~ 47: 单字节编码 [0x80, 0xbf]
        _os.write(value + 0x90);
    } else if (INT_SHORT_MIN <= value && value <= INT_SHORT_MAX) {
        // -0x800 ~ 0x7ff: 2字节编码 [0xc0, 0xcf] + byte
        _os.write(0xc8 + (value >> 8));
        _os.write(value);
    } else if (INT_3BYTE_MIN <= value && value <= INT_3BYTE_MAX) {
        // -0x40000 ~ 0x3ffff: 3字节编码 [0xd0, 0xd7] + 2 bytes
        _os.write(0xd4 + (value >> 16));
        _os.write(value >> 8);
        _os.write(value);
    } else {
        // 其他: 5字节 'I' + 4 bytes (大端)
        _os.write('I');
        _os.write(value >> 24);
        _os.write(value >> 16);
        _os.write(value >> 8);
        _os.write(value);
    }
}

// Hessian2Output 源码简化
public void writeString(String value, int offset, int length) {
    // 小字符串：直接写
    if (length <= SIZE) {
        _os.write('S');          // tag: String 定长模式
        _os.write(length >> 8);  // 长度高字节
        _os.write(length);       // 长度低字节
    } else {
        // 大字符串：分块写
        while (length > 0) {
            int sublen = Math.min(length, SIZE);
            _os.write('s');      // tag: String 分块模式  (小写 s!)
            _os.write(sublen >> 8);
            _os.write(sublen);
            _os.write(value, offset, sublen);
            length -= sublen;
            offset += sublen;
        }
        _os.write('S');          // 结束标记
    }
}

// null
writeNull() → _os.write('N');       // 永远 1 字节

// boolean
writeBoolean(true)  → _os.write('T');  // 1 字节
writeBoolean(false) → _os.write('F');  // 1 字节

// java.util.Date —— 序列化为 UTC 毫秒时间戳
writeObject(new Date()) →
  'M'           // Map tag（Hessian 将 Date 当 Map 序列化）
  '\x04' + type // "java.util.Date"
  ':'           // 毫秒值（紧凑 long）
  结束 'Z'

// BigDecimal —— 序列化为字符串表示
writeObject(new BigDecimal("123.45")) →
  'S'           // String tag
  '\x00\x06'    // 长度 6
  "123.45"      // 字符串内容

public class User {
    private String name;
    private int age;
    // getter/setter 省略
}

User user = new User("张三", 25);

// UnsafeSerializer.writeObject()
public void writeObject(Object obj, AbstractHessianOutput out) {
    // 1. 写入类定义 (C tag)，如果已经写过了就跳过
    int ref = out.writeObjectBegin(cl.getName());
    if (ref < -1) {
        // 首次：写入类定义
        for (Field field : fields) {
            out.writeString(field.getName());
        }
        out.writeMapEnd();  // H tag
        ref = out.writeObjectBegin(cl.getName());
        // 写字段值
        for (Field field : fields) {
            out.writeObject(field.get(obj));
        }
    } else if (ref == -1) {
        // 已写过类定义，直接写实例数据
        for (Field field : fields) {
            out.writeObject(field.get(obj));
        }
    }
    // ref >= 0: 已写过完全相同的对象实例，写引用
}

// Hessian2Output 源码
private IdentityHashMap<Object, Integer> _refs = new IdentityHashMap<>();

public boolean addRef(Object object) {
    if (_refs == null) _refs = new IdentityHashMap<>();
    Integer newRef = _refs.size();
    Integer ref = _refs.put(object, newRef);
    if (ref != null) {
        // 这个对象之前已经被序列化过
        writeRef(ref);  // 写 R tag + 引用编号
        return true;    // 上层不再序列化字段值
    }
    return false;
}

class Node {
    String name;
    Node next;
}

Node a = new Node("A");
Node b = new Node("B");
a.next = b;
b.next = a;  // 环形引用！

List<String> list = Arrays.asList("A", "B");

Map<String, Integer> map = new HashMap<>();
map.put("key1", 1);

enum Color { RED, GREEN, BLUE }
Color c = Color.GREEN;

// ThrowableSerializer
public void writeObject(Object obj, AbstractHessianOutput out) {
    Throwable e = (Throwable) obj;
    // 把异常像普通对象一样序列化其字段（message, cause, stackTrace...）
    // 序列化器强行把异常的字段提取出来，逐个写
}

// Hessian2Input 源码简化
public int readInt() throws IOException {
    int tag = read();
    switch (tag) {
        case 'I':  // 0x49: 定长 int
            return (read() << 24) + (read() << 16) + (read() << 8) + read();

        case 'L':  // 0x4c: 实际上是 long，但适合 int 时直接转
            return (int) ((long) read() << 56 + ...)

        case 0xd8: case 0xd9: case 0xda: case 0xdb:
        case 0xdc: case 0xdd: case 0xde: case 0xdf:
            // [0xd8, 0xdf]: 3字节 int
            is = read();  // 第二个字节
            return ((tag - 0xd4) << 16) + (is << 8) + read();

        case 0xc0: ... case 0xcf:
            // [0xc0, 0xcf]: 2字节 int
            return ((tag - 0xc8) << 8) + read();

        case 0x80: ... case 0xbf:
            // [0x80, 0xbf]: 单字节 int
            return tag - 0x90;

        default:
            throw error("expected integer at " + ...);
    }
}

// readObjectDefinition() 核心逻辑
private void readObjectDefinition() {
    String type = readString();        // 类名，如 "com.example.User"
    int len = readInt();              // 字段数量

    String[] fieldNames = new String[len];
    for (int i = 0; i < len; i++) {
        fieldNames[i] = readString();  // 逐个读字段名
    }

    ClassDef def = new ClassDef(type, fieldNames);
    _classDefs.add(def);              // 缓存类定义
}

// readObjectInstance() 核心逻辑
private Object readObjectInstance(ClassDef def) throws IOException {
    String type = def.getType();        // "com.example.User"
    Class<?> cl = loadClass(type);     // 通过 Class.forName 加载

    // 实例化策略选择
    Object obj;
    if (UnsafeAllocator.isAvailable()) {
        obj = UnsafeAllocator.create().newInstance(cl);  // 绕过构造器
    } else {
        obj = cl.newInstance();  // 调用无参构造器
    }

    _refs.add(obj);  // 加入引用表，支持后续 R tag 引用

    // 按字段顺序反序列化
    Serializer ser = findSerializer(cl);
    for (int i = 0; i < def.getFields().length; i++) {
        String fieldName = def.getFields()[i];
        Object value = readObject();   // 递归读字段值
        ser.setField(obj, fieldName, value);
    }

    return obj;
}

// 策略选择逻辑
if (UnsafeAllocator.isAvailable()) {
    // 路径1: 使用 sun.misc.Unsafe 直接分配内存
    // 优点: 不依赖无参构造器，类没有无参构造器也能反序列化
    // 缺点: 可能绕过构造器中的初始化逻辑
    obj = UnsafeAllocator.create().newInstance(cl);
} else {
    // 路径2: 通过反射调用无参构造器
    // 要求: 类必须有 public/protected 的无参构造器
    obj = cl.getDeclaredConstructor().newInstance();
}

public class Config {
    private Map<String, String> props;

    public Config() {
        this.props = new ConcurrentHashMap<>();  // 构造器中初始化
        this.props.put("timeout", "3000");       // 设置默认值
    }
}

// 如果 Hessian 通过 Unsafe 实例化 Config，
// 构造器不会执行！props 为 null！
// 后续 setField("props", someMap) 没问题，
// 但如果流中没有 props 字段的数据（版本不兼容），props 就一直是 null

// readRef() 核心逻辑
private Object readRef() {
    int ref = readInt();          // 引用编号
    return _refs.get(ref);        // 从引用表中取出之前反序列化的对象
}

// readList() 核心逻辑
private Object readList() {
    int tag = read();
    if (tag == 'M') readType();     // 读类型描述
    if (tag == 't') readString();   // "type"
    if (tag == 'V') readString();   // value
    if (tag == 'z') readMapEnd();

    // 确定目标集合类
    String type = ...;  // 从流中解析出的类型名
    Collection list;
    if (type.equals("java.util.ArrayList")) {
        list = new ArrayList();
    } else {
        list = (Collection) Class.forName(type).newInstance();
    }

    _refs.add(list);

    // 逐个读元素
    while ((tag = read()) != 'Z') {
        list.add(readObject());
    }
    return list;
}

// Provider 端
public List<User> getUsers() {
    return Arrays.asList(new User("张三", 25));
}

// Hessian 序列化: V [M [S "type" S "[com.example.User" Z] ... Z]
// 类型信息 "[com.example.User" 在流中

// 但 Consumer 端收到的 Response 中，方法返回值类型是
// java.lang.reflect.Type → ParameterizedType → List<User>
// 而 Hessian 反序列化出来的实际对象是
// java.util.ArrayList<Map> !!!

// Dubbo 源码: DecodeableRpcResult
// 反序列化后，对返回值做类型兼容转换
Object value = Hessian2ObjectInput.readObject();
// value 实际类型可能是 ArrayList<HashMap>
// 方法签名期望 List<User>

// Dubbo 的修复: 使用 TypeUtils 做强制类型转换
value = TypeUtils.cast(value, returnType);
// 将 HashMap 转为 User 对象（反射 setter）

// Hessian2Output 中
_refs       // IdentityHashMap<Object, Integer> — 值引用
_classRefs  // HashMap<String, Integer> — 类定义引用
_typeRefs   // HashMap<String, Integer> — 类型名引用

// SerializerFactory 的关键缓存
private ConcurrentHashMap<String, Serializer> _cachedSerializerMap
    = new ConcurrentHashMap<>();

private ConcurrentHashMap<String, Deserializer> _cachedDeserializerMap
    = new ConcurrentHashMap<>();

private WeakHashMap<ClassLoader, HashMap<String, ClassDef>> _classDefs;

// 编码规则实现
if (-16 <= v && v <= 47) {
    write(0x90 + v);           // 单字节
} else if (-0x800 <= v && v <= 0x7ff) {
    write(0xc8 + (v >> 8));    // tag + 高字节
    write(v);                   // 低字节
} else if (-0x40000 <= v && v <= 0x3ffff) {
    write(0xd4 + (v >> 16));   // tag + 高字节
    write(v >> 8);              // 中字节
    write(v);                   // 低字节
} else {
    write('I');                 // 定长 int tag
    write(v >> 24);
    write(v >> 16);
    write(v >> 8);
    write(v);
}

// Dubbo 源码: ClassUtils
// 反序列化前检查类名是否在白名单/黑名单中
private static boolean isAllowClass(Class<?> cl) {
    // 1. 检查系统黑名单（已知危险类）
    if (CLASS_BLACKLIST.contains(cl.getName())) return false;

    // 2. 检查用户配置的白名单
    String whitelist = System.getProperty("dubbo.security.serialization.whitelist");
    if (whitelist != null) {
        return whitelist.contains(cl.getName());
    }

    // 3. 默认允许常见 JDK 类和用户类
    return cl.getName().startsWith("java.")
        || cl.getName().startsWith("javax.")
        || cl.getName().startsWith("com.example.");
}

// 配置方式
// dubbo.properties
// dubbo.security.serialization.whitelist=com.example.dto.*,com.example.model.*

// Provider 端（新版本）
public class User {
    private String name;
    private int age;
    private String email;  // ← 新增字段
}

// Consumer 端（旧版本）
public class User {
    private String name;
    private int age;
    // 没有 email 字段
}

public class User implements Serializable {
    private static final long serialVersionUID = 1L;  // ← 必须加

    private String name;
    private int age;
    // 新增字段放最后，Hessian 按顺序读，多余的会跳过的
}

// 序列化时 Color.GREEN → 字节流 → 反序列化后变成 null
Color color = rpcService.getColor();  // 返回 null !!

// 旧版本
enum Color { RED, GREEN, BLUE }

// 新版本（GREEN → GREEN_COLOR）
enum Color { RED, GREEN_COLOR, BLUE }
// 序列化发的是 "GREEN"，反序列化端找不到 "GREEN"，返回 null

enum Color {
    RED,
    @Deprecated
    GREEN,        // 保留旧名称
    GREEN_COLOR,  //  新名称（但内部用这个）
    BLUE
}

public class ColorSerializer extends EnumSerializer {
    @Override
    public void writeObject(Object obj, AbstractHessianOutput out) {
        // 按 ordinal 序列化，而不是 name
        Enum<?> e = (Enum<?>) obj;
        out.writeInt(e.ordinal());
    }
}
// 注册: SerializerFactory.addFactory(...)

// Provider 返回 List<User>
public List<User> getUsers() { ... }

// Consumer 收到后
List<User> users = rpcService.getUsers();
User first = users.get(0);  // ClassCastException: HashMap cannot be cast to User!

// 不要这样
Map<String, List<User>> getUsersByDept();

// 改为这样
UserListResponse getUsersByDept();  // UserListResponse 内部封装 Map

// Provider 端
BigDecimal amount = new BigDecimal("123.45");
// 到了 Consumer 端
// amount.toString() → "123.45000000000000001"

// 业务代码中显式控制传输格式
public class AmountDTO implements Serializable {
    private String amountStr;  // 用 String 传金额，不用 BigDecimal

    @Transient  // 不序列化
    private BigDecimal amount;

    // 手动转换
    public BigDecimal getAmount() {
        if (amount == null && amountStr != null) {
            amount = new BigDecimal(amountStr);
        }
        return amount;
    }
}

// 方案3: 编程式配置
@Bean
public ProtocolConfig protocolConfig() {
    ProtocolConfig config = new ProtocolConfig();
    config.setSerialization("hessian2");
    config.setSerializationSecurityCheck(true);
    return config;
}

// 一次 RPC 调用返回 10 万条记录
List<Order> orders = orderService.queryAll();
// Consumer 端 OOM: Java heap space

// 方案1: 分页传输
List<Order> queryOrders(int pageNo, int pageSize);

// 方案2: 流式传输（Dubbo 3.x）
// 使用 StreamObserver / ServerStream

// 方案3: 手动 reset
Hessian2Output out = new Hessian2Output(outputStream);
for (int i = 0; i < orders.size(); i++) {
    out.writeObject(orders.get(i));
    if (i % 100 == 0) {
        out.reset();  // 每 100 个对象清理一次引用表
    }
}

// Hessian2Input.readObjectInstance() 核心逻辑
for (int i = 0; i < def.getFields().length; i++) {
    String fieldName = def.getFields()[i];  // ← 来自流的字段名
    Object value = readObject();            // ← 从流中消费一个值
    ser.setField(obj, fieldName, value);    // ← 按字段名匹配本地类的字段
}

// === v1 ===
public class OrderDTO implements Serializable {
    private Long orderId;
    private BigDecimal amount;
}

// === v2 (安全演进) ===
public class OrderDTO implements Serializable {
    private Long orderId;
    private BigDecimal amount;

    // v2 新增: 都是末尾追加，不影响老消费者
    private String remark;           // 新增字段，老消费者忽略
    private Integer discountType;    // 新增字段，老消费者忽略
}

// === v3 (安全演进) ===
public class OrderDTO implements Serializable {
    private Long orderId;
    private BigDecimal amount;

    @Deprecated  // ← 标记废弃但不删除
    private String remark;          // 老消费者可能还在用

    private Integer discountType;

    // v3 新增: 替代 remark 的新字段
    private String orderNote;       // 新字段，老消费者拿 null
}

public class SingletonConfig implements Serializable {
    private static final SingletonConfig INSTANCE = new SingletonConfig();

    // 序列化时用代理对象代替
    private Object writeReplace() {
        return new ConfigProxy(this.name, this.value);
        // 代理对象更简单，字段更少
    }

    // 反序列化后还原为单例
    private Object readResolve() {
        return INSTANCE;  // 始终返回同一个实例
    }
}

// 错误: 从不 reset，引用表无限增长
Hessian2Output out = ...;
for (Object item : hugeList) {
    out.writeObject(item);
}

// 正确: 定期 reset
Hessian2Output out = ...;
int count = 0;
for (Object item : hugeList) {
    out.writeObject(item);
    if (++count % 500 == 0) {
        out.reset();       // 清理引用表
        out.resetReferences(); // 清理类引用表  ← 容易遗漏!
    }
}

// 强类型调用: 序列化/反序列化直接到目标类型
User user = userService.getUser(1L);
// 序列化: User对象 → 二进制
// 反序列化: 二进制 → User对象 (一次完成)

// 泛化调用: 中间多一层 Map 转换
GenericService svc = (GenericService) userService;
Object result = svc.$invoke("getUser", new String[]{"long"}, new Object[]{1L});
// 序列化: Map → User(反射填充) → 二进制
// 反序列化: 二进制 → User → Map(反射提取)
// 多了两次反射操作!