ObjectOutputStream.putFields() 允许手动控制序列化字段的名称、值、类型及是否写入，适用于版本兼容、脱敏、跨语言适配等场景；需配合 readFields() 使用，且字段名须严格一致，不可混用 defaultWriteObject()。
ObjectOutputStream.putFields() 是 Java 序列化机制中一个被严重低估的高级特性，它允许你在序列化对象时绕过默认的字段反射机制，转而手动控制每个字段的写入逻辑——不是简单地“开关”某个字段，而是动态决定字段名、类型、值甚至是否写入。这种能力在版本兼容、敏感字段脱敏、跨语言协议适配、或遗留系统字段映射等场景下极具价值。
为什么不用默认序列化？
Java 默认序列化（直接 writeObject）依赖类结构和 serialVersionUID，一旦字段增删改类型，就容易触发 InvalidClassException；它也无法处理以下情况：
- 运行时才确定要序列化的字段（比如根据租户策略过滤字段）
- 字段名与实际属性名不一致（如 POJO 字段叫
userId，但协议要求写为user_id） - 需要对字段值做即时转换（如把
Date转成时间戳 long，或加密后再写） - 同一类在不同版本中字段语义变化（v1 的
score是整数，v2 是浮点，但 wire format 必须保持字符串字段名不变）
putFields() 的核心工作流
启用手动字段映射需两步：重写 writeObject(ObjectOutputStream out)，并在其中调用 out.putFields() 获取 PutField 实例，再逐个 put(字段名, 值)，最后调用 out.writeFields() 提交：
private void writeObject(ObjectOutputStream out) throws IOException {
ObjectOutputStream.PutField fields = out.putFields();
fields.put("id", this.id); // 显式指定字段名和值
fields.put("name", this.name.toUpperCase()); // 可加工值
fields.put("createdAt", this.createdAt.getTime()); // 类型转换
fields.put("isLegacy", Boolean.TRUE); // 甚至可写不存在的字段
out.writeFields(); // 真正触发写入
}
</font>
<H3>关键约束与注意事项</H3>
<p>该机制并非万能，使用时必须注意：</p>
<ul>
<li>必须配合 <code>readObject(ObjectInputStream)</code> 中的 <code>readFields()</code> 使用，否则反序列化会失败</li>
<li><code>PutField.put()</code> 的字段名必须是字符串字面量，且需与 <code>readFields()</code> 中读取的名称严格一致（区分大小写）</li>
<li>不能混合使用：一旦调用了 <code>putFields()</code>，就不能再对同一 <code>ObjectOutputStream</code> 调用 <code>defaultWriteObject()</code></li>
<li>字段类型由你传入的值决定，JVM 不校验是否匹配原字段声明类型——写错类型会导致反序列化时报 <code>ClassNotFoundException</code> 或类型转换异常</li>
</ul>
<H3>实用技巧：模拟“动态 schema”</H3>
<p>你可以将字段映射逻辑外置，例如从配置加载字段白名单与转换规则：</p>
<font color="#666">
<pre class="brush:php;toolbar:false;">
private void writeObject(ObjectOutputStream out) throws IOException {
PutField fields = out.putFields();
for (FieldRule rule : config.getFieldRules(this.getClass())) {
Object rawValue = ReflectionUtils.getValue(this, rule.getSourceName());
Object finalValue = rule.getTransformer().apply(rawValue);
fields.put(rule.getTargetName(), finalValue);
}
out.writeFields();
}
这样，不改代码就能调整序列化行为，适合灰度发布或 A/B 协议迁移。
