PHP 8.1 的 enum 不兼容旧版本，需统一用 ->value 序列化、OrderStatus::tryFrom() 安全解析、网关层透明转换，并覆盖低版本客户端的测试用例。
PHP 8.1 的 enum 本身无法在低于 8.1 的 PHP 环境中运行——语法层面直接报错，不存在“向下兼容”的可能。所谓“旧版本接口中的兼容处理”，实际是指：当你的系统存在 PHP
核心原则：枚举只存在于服务端逻辑层，序列化出口必须降级为标量
枚举是类型安全的内部结构，不能也不该暴露给低版本环境。所有对外输出（API 响应、消息队列 payload、缓存值、日志字段）都必须显式转为字符串或整数。
- 禁止直接
json_encode($order->status)—— 若$order->status是OrderStatus::SHIPPED，PHP 8.1 默认会编码为对象（含__toString未定义时行为不可控），旧客户端解析失败 - 必须统一走
->value：例如json_encode(['status' => $order->status->value])，确保输出是"shipped"或3 - API 响应中状态字段始终声明为
string或integer类型，OpenAPI 文档 enum 值也只填底层值（如["pending", "shipped"]），不出现枚举类名
入参兼容：从字符串/数字安全还原为枚举
旧接口调用方传来的仍是原始值（如 status=pending 或 {"status": 2}），服务端需主动解析，且必须容错。
- 永远使用
OrderStatus::tryFrom($input)，而非from()；输入非法时返回null或抛出明确业务异常（如400 Bad Request），不静默 fallback - 控制器层做第一道校验：
if (!$status = OrderStatus::tryFrom($request->input('status'))) { throw ValidationException::withMessages(['status' => 'Invalid status value']); } - 避免在模型属性赋值前绕过校验，例如不要写
$order->status = $request->status（此时$request->status是字符串，Eloquent 不识别枚举）
跨版本服务通信的中间层适配
若旧服务无法升级，又需双向传递状态，可在网关或 DTO 层做透明转换：
立即学习“PHP免费学习笔记（深入）”；
- 接收旧服务请求时：将
status字段从字符串映射为枚举实例，再交由核心业务逻辑处理 - 向旧服务返回响应前：把枚举实例转回字符串，再组装数组/json，不暴露任何
enum对象 - 消息队列场景下，建议约定 payload schema 使用纯标量字段，消费端无需感知枚举存在
测试覆盖要点
专门针对低版本兼容性补全测试用例，不依赖 PHP 版本，只验证数据流：
- 用 cURL 模拟 PHP 7.4 客户端发
POST /orders?status=invalid→ 断言返回 400 - 发送
status=shipped→ 断言响应中"status": "shipped"且数据库存入一致 - 检查日志输出是否含枚举对象 var_dump（应避免，只打
$status->value）
