当前位置：首页 > 文章列表 > 文章 > php教程 > PHP __serialize 与 __unserialize 怎么迁移对象持久化：字段版本与兼容恢复

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

来源：17golang原创 2026-08-27 12:00:55 0浏览收藏

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

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

要点速览

__serialize() 返回的是自定义关联数组，不必等同于对象全部属性。
保存格式加上 version 后，旧快照可以在 __unserialize() 中逐步补齐。
恢复阶段要校验字段类型和允许的版本，外部输入优先使用 JSON 或签名校验。

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

对象属性是代码内部结构，持久化数据却是跨版本协议。今天的 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。

PHP OrderSnapshot 的 __serialize 返回 version、orderId、status 和 currency 字段，并进入持久化快照

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

不要在业务调用方到处写 $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，而不是把半初始化对象继续交给订单流程。