PHP __serialize 与 __unserialize 怎么迁移对象持久化：字段版本与兼容恢复

缓存里的订单快照升级后恢复失败，通常不是 serialize() 本身坏了，而是保存格式没有版本边界：旧数据缺字段，新代码却直接读取。PHP 的 __serialize() 和 __unserialize() 适合把对象的持久化形状明确写出来，再在恢复入口集中处理旧字段、默认值和校验。

迁移时先把“要保存的字段”变成带版本的关联数组，再让 __unserialize() 只接受已知版本并为缺失字段提供明确默认值；不要把外部字符串直接交给 unserialize()。

为什么旧快照会在升级后失效

对象属性是代码内部结构，持久化数据却是跨版本协议。今天的 OrderSnapshot 只有 orderId 和 status，明天增加 currency，如果恢复代码直接访问 $data['currency']，旧缓存就会出现未定义键或错误的业务默认值。

PHP 在序列化对象时会优先调用 __serialize()；反序列化时，如果存在 __unserialize()，PHP 会把前者返回的数组传给后者。__construct() 不会替代这个恢复入口，所以初始化和兼容逻辑必须写在恢复方法里。

最小配方：把持久化格式独立出来

 2,
            'orderId' => $this->orderId,
            'status' => $this->status,
            'currency' => $this->currency,
        ];
    }

    public function __unserialize(array $data): void
    {
        $version = $data['version'] ?? 1;
        if (!is_int($version) || !in_array($version, [1, 2], true)) {
            throw new InvalidArgumentException('unsupported snapshot version');
        }

        $this->orderId = self::requiredString($data, 'orderId');
        $this->status = self::requiredString($data, 'status');
        $this->currency = $version === 1
            ? 'CNY'
            : self::optionalString($data, 'currency', 'CNY');
    }

    private static function requiredString(array $data, string $key): string
    {
        $value = $data[$key] ?? null;
        if (!is_string($value) || $value === '') {
            throw new InvalidArgumentException("invalid {$key}");
        }
        return $value;
    }

    private static function optionalString(array $data, string $key, string $default): string
    {
        return isset($data[$key]) && is_string($data[$key])
            ? $data[$key]
            : $default;
    }
}

这里的关键不是把代码写长，而是把协议字段固定下来。version 让恢复逻辑有了判断入口；orderId 和 status 是必需字段，缺失就拒绝；currency 是版本 2 才有的字段，版本 1 按明确规则补成 CNY。

字段增加时，兼容逻辑应该放在哪里

不要在业务调用方到处写 $data['currency'] ?? 'CNY'。这样做会让每个读取点都承担一份迁移规则，最后很难确认哪些旧数据仍被支持。更稳妥的边界是：__unserialize() 负责把旧格式恢复成当前对象状态，业务层只面对完整对象。

如果以后出现版本 3，可以先在恢复方法中把版本 1、2 转换到一个内部规范数组，再统一赋值。迁移逻辑可以拆成私有方法，但不要静默吞掉未知版本；未知版本说明数据格式超出了当前代码的承诺。

恢复验收：缺字段、错类型和未知版本分别处理

测试不要只验证一遍 serialize() 再 unserialize()。至少准备三份输入：版本 1 的旧快照、版本 2 缺少可选字段的快照、带有字符串版本号或未知版本的异常快照。

$snapshot = new OrderSnapshot('A-1001', 'paid', 'CNY');
$wire = serialize($snapshot);
$restored = unserialize($wire, ['allowed_classes' => [OrderSnapshot::class]]);

if (!$restored instanceof OrderSnapshot) {
    throw new RuntimeException('snapshot restore failed');
}

// 旧格式的 __serialize 数据可直接用于单元测试恢复逻辑
$legacy = ['version' => 1, 'orderId' => 'A-1001', 'status' => 'paid'];
$legacyObject = (new ReflectionClass(OrderSnapshot::class))->newInstanceWithoutConstructor();
$legacyObject->__unserialize($legacy);

成功状态不是“没有抛异常”这么简单，还要核对 orderId、status 和版本 1 的默认 currency。对错误输入，验收目标是得到稳定的 InvalidArgumentException，而不是把半初始化对象继续交给订单流程。

迁移旧的 __sleep 与 __wakeup 时别忽略这些边界

__serialize() 和 __unserialize() 出现后，若同一个对象同时定义了旧的 __sleep() 与 __wakeup()，新的魔术方法优先。迁移时应先确认所有写入端和读取端的版本，再删除旧入口；不要只改类文件就认为历史缓存已经升级。

如果对象里有数据库连接、文件句柄、闭包或其他运行时资源，不要把资源本体放进返回数组。只保存可重建的标识和配置，在 __unserialize() 完成字段校验后按需重新建立资源。

不可信字符串不能直接恢复成对象

PHP 手册明确提醒，unserialize() 不应直接处理不可信用户输入，即使传了 allowed_classes 也不能把它当成完整的安全边界。来自请求参数、公开队列或第三方存储的内容，优先改成 JSON；必须使用 PHP 序列化格式时，至少先做完整性校验，并把允许的类名单收紧。

常见问题：对象持久化迁移怎么选

只增加一个字段，也需要 version 吗？

如果数据会跨部署保留，建议从第一版就带上 version。它让“字段缺失”与“格式变更”分开，后续迁移不用猜测旧数据来自哪个类版本。

__unserialize() 里要调用 __construct() 吗？

通常不应直接调用。反序列化不是正常创建流程，应该在 __unserialize() 中完成必要字段恢复和校验；如果需要连接外部资源，等数据确认有效后再建立。

PHP Serializable 接口还要保留吗？

为兼容旧 PHP 版本时可以暂时保留迁移层，但新代码优先实现 __serialize() 和 __unserialize()。迁移完成后用历史快照回归测试，再决定是否移除旧接口。

收尾检查

• 持久化数组只包含可重建字段，并明确写出 version。
• 必需字段缺失或类型错误时立即失败，可选字段使用记录过的默认值。
• 未知版本不静默接受；不可信输入不直接交给 unserialize()。
• 用旧快照、缺字段快照和错误版本快照分别验证恢复结果。