FendxPHP/app/Dto/ApiResponseDto.php

<?php
declare(strict_types=1);

namespace App\Dto;

/**
 * API响应数据传输对象
 */
class ApiResponseDto extends BaseDto
{
    private int $code = 0;

    private string $message = 'success';

    private mixed $data = null;

    private string $traceId = '';

    private int $timestamp = 0;

    private array $meta = [];

    public function __construct()
    {
        $this->timestamp = time();
        $this->traceId = \Fendx\Core\Context\Context::getTraceId();
    }

    public function getCode(): int
    {
        return $this->code;
    }

    public function setCode(int $code): self
    {
        $this->code = $code;
        return $this;
    }

    public function getMessage(): string
    {
        return $this->message;
    }

    public function setMessage(string $message): self
    {
        $this->message = $message;
        return $this;
    }

    public function getData(): mixed
    {
        return $this->data;
    }

    public function setData(mixed $data): self
    {
        $this->data = $data;
        return $this;
    }

    public function getTraceId(): string
    {
        return $this->traceId;
    }

    public function setTraceId(string $traceId): self
    {
        $this->traceId = $traceId;
        return $this;
    }

    public function getTimestamp(): int
    {
        return $this->timestamp;
    }

    public function setTimestamp(int $timestamp): self
    {
        $this->timestamp = $timestamp;
        return $this;
    }

    public function getMeta(): array
    {
        return $this->meta;
    }

    public function setMeta(array $meta): self
    {
        $this->meta = $meta;
        return $this;
    }

    /**
     * 添加元数据
     */
    public function addMeta(string $key, mixed $value): self
    {
        $this->meta[$key] = $value;
        return $this;
    }

    /**
     * 创建成功响应
     */
    public static function success(mixed $data = null, string $message = 'success'): self
    {
        return (new self())
            ->setCode(0)
            ->setMessage($message)
            ->setData($data);
    }

    /**
     * 创建错误响应
     */
    public static function error(string $message, int $code = 400, mixed $data = null): self
    {
        return (new self())
            ->setCode($code)
            ->setMessage($message)
            ->setData($data);
    }

    /**
     * 创建分页响应
     */
    public static function paginate(array $items, int $total, int $page, int $pageSize, string $message = 'success'): self
    {
        $data = [
            'items' => $items,
            'pagination' => [
                'total' => $total,
                'page' => $page,
                'page_size' => $pageSize,
                'total_pages' => ceil($total / $pageSize),
                'has_more' => $page * $pageSize < $total,
                'has_prev' => $page > 1,
            ]
        ];

        return (new self())
            ->setCode(0)
            ->setMessage($message)
            ->setData($data);
    }

    /**
     * 创建未找到响应
     */
    public static function notFound(string $message = 'Resource not found'): self
    {
        return self::error($message, 404);
    }

    /**
     * 创建未授权响应
     */
    public static function unauthorized(string $message = 'Unauthorized'): self
    {
        return self::error($message, 401);
    }

    /**
     * 创建禁止访问响应
     */
    public static function forbidden(string $message = 'Forbidden'): self
    {
        return self::error($message, 403);
    }

    /**
     * 创建验证错误响应
     */
    public static function validationError(string $message = 'Validation failed', array $errors = []): self
    {
        return self::error($message, 422, $errors);
    }

    /**
     * 创建服务器错误响应
     */
    public static function serverError(string $message = 'Internal server error'): self
    {
        return self::error($message, 500);
    }

    /**
     * 检查是否为成功响应
     */
    public function isSuccess(): bool
    {
        return $this->code === 0;
    }

    /**
     * 检查是否为错误响应
     */
    public function isError(): bool
    {
        return $this->code !== 0;
    }

    /**
     * 获取HTTP状态码
     */
    public function getHttpStatusCode(): int
    {
        return match ($this->code) {
            0 => 200,
            400 => 400,
            401 => 401,
            403 => 403,
            404 => 404,
            422 => 422,
            500 => 500,
            default => 200,
        };
    }

    /**
     * 设置分页元数据
     */
    public function setPaginationMeta(int $total, int $page, int $pageSize): self
    {
        return $this->addMeta('total', $total)
                   ->addMeta('page', $page)
                   ->addMeta('page_size', $pageSize)
                   ->addMeta('total_pages', ceil($total / $pageSize));
    }

    /**
     * 设置时间元数据
     */
    public function setTimeMeta(float $executionTime = null, string $timezone = null): self
    {
        if ($executionTime !== null) {
            $this->addMeta('execution_time', round($executionTime, 3));
        }
        
        if ($timezone !== null) {
            $this->addMeta('timezone', $timezone);
        }
        
        return $this;
    }

    /**
     * 设置请求元数据
     */
    public function setRequestMeta(string $method = null, string $path = null, string $ip = null): self
    {
        if ($method !== null) {
            $this->addMeta('method', $method);
        }
        
        if ($path !== null) {
            $this->addMeta('path', $path);
        }
        
        if ($ip !== null) {
            $this->addMeta('ip', $ip);
        }
        
        return $this;
    }

    /**
     * 转换为数组（格式化输出）
     */
    public function toArray(): array
    {
        return [
            'code' => $this->code,
            'message' => $this->message,
            'data' => $this->data,
            'trace_id' => $this->traceId,
            'timestamp' => $this->timestamp,
            'meta' => empty($this->meta) ? null : $this->meta,
        ];
    }

    /**
     * 转换为HTTP响应数组
     */
    public function toHttpResponse(): array
    {
        return [
            'status_code' => $this->getHttpStatusCode(),
            'headers' => [
                'Content-Type' => 'application/json',
                'X-Trace-Id' => $this->traceId,
            ],
            'body' => $this->toArray(),
        ];
    }
}