PHP 枚举承载业务状态时怎样避免数据库值漂移

可以，但要把 PHP 枚举当成数据库状态码的类型边界，而不是把 case 名称直接当数据。最稳妥的规则是：数据库只保存显式、短小、长期不变的 backed value；代码始终用 ->value 写入，用 from() 或 tryFrom() 读取；中文文案、按钮名称和状态行为都放在枚举方法里，不能反向成为持久化值。

官方资料：https://www.php.net/manual/en/language.enumerations.backed.php

PHP 官方文档说明，backed enum 只能选择 string 或 int 一种标量类型，每个 case 都必须显式给出唯一值，不会自动生成序号。这正适合数据库往返，但能否避免漂移，取决于团队是否把 backed value 当成公开数据契约。

数据库应该保存哪个值

以订单状态为例，Pending 是代码中的 case 名，pending 是数据库状态码，“待支付”是展示文案。三者职责不同：case 名允许为了代码可读性重构，展示文案允许国际化或产品改版，只有 backed value 要保持长期稳定。

 '待支付',
            self::Paid => '已支付',
            self::Cancelled => '已取消',
        };
    }

    public function canCancel(): bool
    {
        // 业务行为绑定枚举对象，避免调用方重复判断字符串。
        return $this === self::Pending;
    }
}

以后即使把 Pending 重命名为更贴合领域语言的 case，只要 'pending' 不变，历史数据就能继续读取。相反，把 value 从 'pending' 改成 'awaiting_payment' 属于数据协议变更，必须走迁移，不能当普通重构提交。

哪些写法最容易产生漂移

第一个误区是保存 $status->name。name 适合调试和反射，却会跟随代码命名变化。第二个误区是自己用 cases() 的数组下标生成 0、1、2；PHP 枚举本身不会自动生成标量值，手工依赖顺序会让新增或重排 case 改写旧数据含义。第三个误区是直接保存“待支付”“已支付”这类文案，一次产品改词或多语言切换就会制造新旧值并存。

怎样在存取边界集中转换

写入数据库时只取 value，读取时马上恢复成枚举，不让原始字符串进入业务层。PHP 提供的 from() 在找不到值时抛出 ValueError，适合“数据库必须正确，否则立即失败”的严格路径；tryFrom() 返回 null，适合外部输入、灰度迁移或需要记录脏数据的边界。

value;
    }

    public static function fromDatabase(string $raw): OrderStatus
    {
        $status = OrderStatus::tryFrom($raw);

        if ($status === null) {
            // 不把未知值静默映射为正常状态，避免掩盖历史脏数据。
            throw new UnexpectedValueException("未知订单状态: {$raw}");
        }

        return $status;
    }
}

不要用 tryFrom($raw) ?? OrderStatus::Pending 处理数据库未知值。这样会把损坏数据伪装成真实的“待支付”，后续退款、库存或通知逻辑都可能走错。更合理的策略是记录订单主键、原始值和读取位置，阻止当前业务动作，并交给迁移或人工修复。

数据库字段可以使用足够长度的字符串列，并按所用数据库能力增加 CHECK 约束。约束集合应由迁移文件明确维护，不能依赖开发者记忆；但代码仍要处理未知值，因为旧服务、导入脚本、复制延迟和手工数据都可能绕过当前应用层。

旧值改名时怎样分阶段迁移

假设要把 pending 改成 awaiting_payment，不要在同一次发布里直接替换 enum value 和数据库约束。安全顺序是：先让新代码同时认识新旧值，但继续只写旧值；所有实例升级后改为只写新值；再批量回填历史行；确认旧版本和离线任务都停止写旧值后，最后收紧数据库约束并移除兼容分支。

这个兼容方法必须有删除日期和数据统计。发布期间可统计旧值读取次数；只有旧值归零、回填完成、队列消息和缓存都过期后，才删除别名。若多个服务共享同一张表，还要把“谁可能写入状态”列成清单，不能只升级 PHP 主站。

怎样确认代码、数据和约束没有分叉

最小测试应从枚举自动生成合法集合，覆盖每个 value 的数据库往返，同时断言未知值会失败。数据库迁移测试再核对列约束是否包含完全相同的集合。这样新增 case 时，开发者会被迫同步考虑数据库约束和旧版本兼容。

 $case->value,
    OrderStatus::cases(),
);

foreach ($values as $value) {
    // 每个数据库值都必须能无损恢复为同一个枚举 case。
    assert(OrderStatus::from($value)->value === $value);
}

// 未知值应明确失败，不能悄悄退回某个正常业务状态。
assert(OrderStatus::tryFrom('unknown_status') === null);

上线前再检查四点：所有写入是否统一走 ->value；ORM cast 或 hydration 是否在读取边界完成；消息队列、缓存、日志和导出文件是否也把状态当作版本化协议；旧应用实例是否可能继续写已废弃值。数据库值漂移往往不是 enum 本身造成的，而是同一状态在多个边界各自维护了一份字符串。

相关问题

状态字段用 string enum 还是 int enum？

跨数据库、消息和日志传递时，短字符串通常更容易排查，也不依赖序号含义；整数更紧凑，但必须有稳定的数据字典。无论选择哪一种，都不要根据 case 顺序自动编号。

可以直接把枚举对象交给 PDO 吗？

更清晰的做法是显式绑定 $status->value。这样 SQL 参数类型和持久化契约一目了然，也避免不同 ORM 或驱动对对象转换采用不同规则。

新增一个枚举值为什么也需要发布计划？

因为滚动发布期间旧代码可能读到新值并抛错。先让所有读取方认识新值，再启用写入，是避免新旧版本互相破坏的基本顺序。