PHP 8.3 readonly class 做请求 DTO：反序列化校验与失败边界

接收订单接口时，把数组直接传进业务层很快就会失控：字段可能缺失，金额可能是字符串，调用方还能在后续流程里改掉原始数据。PHP 8.3 的 readonly class 可以把请求 DTO 变成不可变对象，但它只负责限制属性重新赋值，不负责 JSON 字段存在性、类型和业务范围校验。可靠的做法是让“解析、校验、构造”在入口一次完成，失败则返回稳定的 422 响应。

readonly class 解决的是数据可变，不是输入可信

readonly class 会让类中的实例属性只能初始化一次，并自动带上 readonly 约束。它很适合表示“请求已经被解析”的 DTO：订单号、用户号和金额在进入服务层后不再被悄悄改写。

但下面这段输入仍然可能通过 JSON 解码：{"user_id":"8","amount_cents":"1999"}。如果接口契约要求整数，DTO 不能替你猜测是否应该强转。把字符串金额直接转成整数，可能会把调用方的错误变成订单金额错误。

readonly class CreateOrderRequest
{
    public function __construct(
        public int $userId,
        public int $amountCents,
        public ?string $couponCode,
    ) {}
}

在 HTTP 入口先把 JSON 变成可检查的数据

入口代码先区分 JSON 语法错误、顶层类型错误和字段类型错误。不要把 null、空对象和数组混为一谈；它们对应的客户端修复方向不同。

function readJsonObject(string $body): array
{
    try {
        $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    } catch (JsonException $error) {
        throw new InvalidArgumentException('request body is not valid JSON');
    }

    if (!is_array($data) || array_is_list($data)) {
        throw new InvalidArgumentException('request body must be a JSON object');
    }
    return $data;
}

这里返回的仍然是外部数据，下一步才是字段白名单与类型检查。把原始数组限制在控制器入口，服务层只接收 DTO，能明显减少“某个分支忘了校验”的概率。

用工厂方法把字段校验和构造器边界收在一起

构造器可以保持简单，复杂的外部输入校验放在命名工厂方法里。金额必须是整数且大于零，优惠券为空或为非空字符串；额外字段则直接拒绝，避免客户端拼错字段却没有提示。

readonly class CreateOrderRequest
{
    private function __construct(
        public int $userId,
        public int $amountCents,
        public ?string $couponCode,
    ) {}

    public static function fromArray(array $input): self
    {
        $allowed = ['user_id', 'amount_cents', 'coupon_code'];
        $unknown = array_diff(array_keys($input), $allowed);
        if ($unknown !== []) {
            throw new InvalidArgumentException('unknown request field');
        }

        $userId = $input['user_id'] ?? null;
        $amount = $input['amount_cents'] ?? null;
        $coupon = $input['coupon_code'] ?? null;
        if (!is_int($userId) || $userId  100000000) {
            throw new InvalidArgumentException('amount_cents is out of range');
        }
        if ($coupon !== null && (!is_string($coupon) || $coupon === '')) {
            throw new InvalidArgumentException('coupon_code must be a non-empty string');
        }

        return new self($userId, $amount, $coupon);
    }
}

这段代码故意不做宽松转换。若前端把数字写成字符串，应在接口契约或前端序列化处修正，而不是在服务端默默改变语义。

异常响应要区分语法错误、字段错误和业务拒绝

控制器只负责把入口异常转换成 HTTP 响应，业务服务不需要知道 JSON 的具体格式。建议把客户端可修复的输入错误统一映射为 422，把 JSON 语法错误映射为 400，避免客户端只能看到一个模糊的 500。

try {
    $payload = readJsonObject((string) file_get_contents('php://input'));
    $request = CreateOrderRequest::fromArray($payload);
    $orderId = $orderService->create($request);

    http_response_code(201);
    echo json_encode(['order_id' => $orderId], JSON_UNESCAPED_UNICODE);
} catch (InvalidArgumentException $error) {
    http_response_code(422);
    echo json_encode([
        'error' => 'invalid_request',
        'message' => $error->getMessage(),
    ], JSON_UNESCAPED_UNICODE);
} catch (Throwable $error) {
    error_log($error->getMessage());
    http_response_code(500);
    echo json_encode(['error' => 'internal_error']);
}

生产日志可以记录请求追踪号、错误类型和字段名，但不要把完整的认证信息或原始请求体无条件写入日志。响应消息也应保持稳定，避免把数据库异常直接暴露给客户端。

版本和继承边界是 readonly class 的发布检查点

readonly class 从 PHP 8.2 开始可用，PHP 8.3 项目可以直接采用；它不能继承普通可变类，子类也不能撤销只读约束。若项目还要兼容 PHP 8.1，不能只在文档里写“建议升级”，而应在 CI 矩阵中明确阻断版本。

用四组输入做回归，而不是只测一个成功请求

1. 合法对象：整数用户号、正数金额、可选优惠券，预期返回 201 和订单号。
2. 语法损坏：缺少引号或括号，预期返回 400，日志包含追踪号。
3. 类型错误：金额为字符串、用户号为 0、优惠券为数组，预期返回 422。
4. 额外字段：加入未约定的 debug，预期被拒绝，而不是悄悄忽略。

如果测试只覆盖成功请求，DTO 最容易变成一层好看的类型声明，真正的输入风险仍留在服务层。回归时还应检查构造完成后没有任何代码重新赋值，并用 PHP 8.2、8.3 的最低支持版本各跑一次。

常见问题：readonly class DTO 怎么选

readonly class 会自动验证 JSON 类型吗？

不会。它约束对象属性的再次赋值，JSON 语法、字段存在性和类型仍需要在工厂方法或专用校验层处理。

可以把 JSON 字符串直接传给 DTO 构造器吗？

不建议。先解码并检查顶层结构，再把经过校验的标量传入构造器，错误响应会更稳定。

PHP 8.1 项目能使用 readonly class 吗？

不能。readonly class 的版本门槛是 PHP 8.2；兼容 8.1 时可以使用普通 DTO 加私有属性和工厂方法，但语法和约束不能照搬。

为什么不直接把未知字段忽略掉？

严格拒绝更容易发现客户端拼写错误和接口版本漂移。若确实要兼容旧客户端，应记录明确的兼容策略，而不是无声忽略所有额外字段。

让 DTO 在入口完成一次可信转换

readonly class 的价值不在于替代校验器，而在于把“已验证、不可再改”的状态表达在类型上。PHP 接口只要坚持先解码、再校验、后构造，并把异常映射和 PHP 版本检查纳入回归，服务层就能专注订单规则，而不是反复猜测输入数组的形状。