PHP 枚举序列化JSON 输出枚举值时为什么格式不一致怎样在批处理代码中减少额外分配

接口里把 PHP 枚举直接交给 json_encode()，出现“有时输出字符串、有时变成对象、纯枚举直接报错”并不是编码器随机变化，而是枚举类型和序列化契约不同。最稳妥的做法是：对需要传输的状态使用 Backed Enum，让 JSON 默认输出它的字符串或整数值；需要固定对象结构时，再统一实现 JsonSerializable。

批量接口还要把转换集中在一个边界上：每条记录只读取一次枚举值，按需写回响应字段，避免在循环里反复创建临时对象或完整复制数组。下面用一个订单状态例子说明。

官方地址：https://www.php.net/manual/en/language.enumerations.serialization.php

先判断枚举类型，再决定 JSON 输出

PHP 有两类常用枚举。Pure Enum 只有 case 名称，没有标量值；Backed Enum 绑定 string 或 int，每个 case 都有明确的 value。官方规则是：Pure Enum 直接编码为 JSON 会抛出错误，Backed Enum 则编码为对应标量值。

因此，接口状态不应把 case 名称当作偶然的展示文本。可以把外部契约固定在 backed value 上：

 OrderStatus::Paid,
];

// Backed Enum 会按其 value 参与 JSON 编码，结果是 {"status":"paid"}。
$json = json_encode($payload, JSON_THROW_ON_ERROR);

如果业务必须输出名称、值和展示文本，可以让枚举实现 JsonSerializable。此时要把返回结构视为公开 API 契约，后续新增字段也要考虑客户端兼容：

 $this->value,
            'name' => $this->name,
        ];
    }
}

把枚举转换集中在批处理边界

批量读取数据库记录时，原始状态通常是字符串。不要在多个控制器里各写一套强制转换；把“未知值如何处理”和“响应字段叫什么”放到一个映射函数中，循环只负责组装结果。

value;
}

function buildOrders(iterable $rows): array
{
    $result = [];

    foreach ($rows as $row) {
        // 只保留接口需要的字段，减少每条记录的中间结构。
        $result[] = [
            'id' => (int) $row['id'],
            'status' => statusValue($row),
        ];
    }

    return $result;
}

这里的“减少额外分配”不是把所有数组都消灭，而是把分配放到明确的接口边界：结果数组必须存在，但不必先复制完整数据库行，再用第二个数组删除无关字段。对于超大批次，还可以分块输出或使用生成器把内存上限交给调用方。

生产环境的配置、错误和权限边界

序列化策略确定后，再处理三个容易被忽略的边界。第一，外部输入使用 tryFrom()，未知值返回 null 后要有明确的默认策略；可信且必须成功的内部值才适合 from()，因为它会在找不到 case 时抛出 ValueError。

第二，使用 JSON_THROW_ON_ERROR 让编码失败进入统一异常处理，不要把 false 当作合法响应继续发送。第三，接口层只暴露 backed value 或 JsonSerializable 声明的字段，日志可以记录原始状态，但不要把内部对象结构当作客户端协议。

 $status], JSON_THROW_ON_ERROR);

发布前检查：固定契约，再看批处理成本

可以用下面的清单做代码评审：状态字段是否明确选择 Pure Enum 或 Backed Enum；JSON 输出是否与前端约定一致；未知输入是否区分 null、默认值和拒绝；映射是否只存在一个入口；循环是否复制了完整行数据；异常是否进入统一日志和错误响应。

如果客户端只需要 paid 这样的值，就直接使用 Backed Enum；如果客户端需要 code 与 name，就实现 JsonSerializable 并锁定结构。这样既能解释格式为何不同，也能把批处理中的对象转换和数组分配控制在可维护的边界内。

常见问题

为什么 Pure Enum 不能直接 JSON 输出？

它没有内建标量值，PHP 无法猜测应该把 case 名称、类名还是其他字段作为 API 值，因此默认会报错。可以改用 Backed Enum，或显式实现 JsonSerializable。

Backed Enum 输出的是 case 名还是 value？

默认输出 backed value，例如 OrderStatus::Paid 会作为 "paid" 参与 JSON 编码；需要名称时应显式读取 name 或返回自定义结构。

批量接口一定要把枚举转成字符串吗？

不一定。关键是外部契约稳定、未知值有处理策略、转换边界集中。若直接让编码器处理 Backed Enum，也要避免同一字段在不同接口中采用不同的自定义序列化结构。