发布于 由admin

PHP Enums在前端与后端的统一：利用Value Object实现类型安全的数据传输

PHP Enums在前端与后端的统一：利用Value Object实现类型安全的数据传输

大家好，今天我们来探讨一个在Web开发中经常遇到的问题：如何在前后端之间安全且一致地传递数据，尤其是在使用PHP Enums时。传统的做法往往会导致代码冗余、类型不安全，并且难以维护。今天，我们将介绍一种利用Value Object来解决这个问题的方案，以实现前后端数据传输的类型安全和代码复用。

问题背景：前后端数据传输的挑战

在典型的Web应用中，后端负责处理业务逻辑和数据存储，而前端负责用户交互和数据展示。前后端之间的数据传输通常通过JSON格式进行。然而，这种方式存在一些固有的问题：

  1. 类型不安全： JSON本身是一种弱类型的数据格式。后端PHP代码中定义的类型信息，例如Enum，在传输到前端后会丢失，变成字符串或数字。前端需要自行解析并验证这些值的有效性，容易出错。
  2. 代码冗余： 前后端都需要定义相同的数据类型和验证逻辑，导致代码重复。例如，一个表示用户状态的Enum，可能需要在PHP代码和JavaScript代码中都定义一遍。
  3. 难以维护： 当数据类型发生变化时，需要同时修改前后端的代码，维护成本高。

为了解决这些问题，我们需要一种机制，能够将PHP Enum的类型信息安全地传递到前端，并在前端进行类型检查。Value Object正是实现这一目标的利器。

Value Object：类型安全的数据载体

Value Object是一种设计模式，它表示一个具有特定属性和行为的值。与Entity不同，Value Object没有唯一的ID，它的相等性取决于它的属性值。Value Object可以用来封装复杂的数据类型，并提供类型安全的操作。

在我们的场景中，Value Object将封装PHP Enum的值，并提供方法来将其转换为前端可用的数据格式。

实现方案：PHP Enum + Value Object + JSON Schema

我们的方案主要包括以下几个步骤：

  1. 定义PHP Enum： 使用PHP 8.1引入的Enum特性来定义业务相关的枚举类型。
  2. 创建Value Object： 为每个Enum创建一个对应的Value Object，用于封装Enum的值，并提供将其转换为前端可用的格式的方法。
  3. 生成JSON Schema： 根据Value Object的定义，自动生成JSON Schema，用于前端的数据验证。
  4. 前端类型定义： 利用JSON Schema生成TypeScript类型定义，确保前端代码类型安全。
  5. 前后端数据传输： 后端将Value Object序列化为JSON，前端使用JSON Schema进行验证，并将其转换为对应的TypeScript类型。

接下来，我们将通过一个具体的例子来演示如何实现这个方案。

示例：用户状态管理

假设我们需要管理用户的状态，包括Active、Inactive和Pending三种状态。

1. 定义PHP Enum：

<?php

namespace AppEnums;

enum UserStatus: string
{
    case Active = 'active';
    case Inactive = 'inactive';
    case Pending = 'pending';

    public function label(): string
    {
        return match ($this) {
            self::Active => '激活',
            self::Inactive => '未激活',
            self::Pending => '待审核',
        };
    }
}

2. 创建Value Object：

<?php

namespace AppValueObjects;

use AppEnumsUserStatus;
use JsonSerializable;

class UserStatusValue implements JsonSerializable
{
    private UserStatus $status;

    public function __construct(UserStatus $status)
    {
        $this->status = $status;
    }

    public static function fromString(string $status): self
    {
        return new self(UserStatus::from(strtolower($status)));
    }

    public function getStatus(): UserStatus
    {
        return $this->status;
    }

    public function getValue(): string
    {
        return $this->status->value;
    }

    public function getLabel(): string
    {
        return $this->status->label();
    }

    public function jsonSerialize(): mixed
    {
        return [
            'value' => $this->getValue(),
            'label' => $this->getLabel(),
        ];
    }

    public function __toString(): string
    {
        return $this->getValue();
    }
}

在这个例子中，UserStatusValue封装了UserStatus Enum，并提供了getValue()和getLabel()方法来获取Enum的值和标签。jsonSerialize()方法用于将Value Object转换为JSON格式。fromString()方法允许从字符串创建Value Object。

3. 生成JSON Schema：

我们需要一种机制来自动生成JSON Schema。可以使用现有的库，例如opis/json-schema，或者自己编写一个简单的生成器。

以下是一个简单的JSON Schema生成器的示例：

<?php

namespace AppUtils;

use AppValueObjectsUserStatusValue;

class JsonSchemaGenerator
{
    public static function generate(string $valueObjectClass): array
    {
        if ($valueObjectClass === UserStatusValue::class) {
            return [
                'type' => 'object',
                'properties' => [
                    'value' => [
                        'type' => 'string',
                        'enum' => [
                            'active',
                            'inactive',
                            'pending',
                        ],
                    ],
                    'label' => [
                        'type' => 'string',
                    ],
                ],
                'required' => [
                    'value',
                    'label',
                ],
            ];
        }

        throw new InvalidArgumentException("Unsupported value object class: $valueObjectClass");
    }
}

使用方法：

<?php

use AppUtilsJsonSchemaGenerator;
use AppValueObjectsUserStatusValue;

$schema = JsonSchemaGenerator::generate(UserStatusValue::class);

echo json_encode($schema, JSON_PRETTY_PRINT);

生成的JSON Schema如下：

{
    "type": "object",
    "properties": {
        "value": {
            "type": "string",
            "enum": [
                "active",
                "inactive",
                "pending"
            ]
        },
        "label": {
            "type": "string"
        }
    },
    "required": [
        "value",
        "label"
    ]
}

4. 前端类型定义：

可以使用工具，例如json2ts，将JSON Schema转换为TypeScript类型定义。

npx json2ts.cmd -i user-status.schema.json -o user-status.d.ts

生成的TypeScript类型定义如下：

/**
 * This file was automatically generated by json-schema-to-typescript.
 * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
 * and run json-schema-to-typescript to regenerate this file.
 */

export interface UserStatus {
  value: "active" | "inactive" | "pending";
  label: string;
}

5. 前后端数据传输：

后端代码：

<?php

use AppEnumsUserStatus;
use AppValueObjectsUserStatusValue;

$userStatus = new UserStatusValue(UserStatus::Active);

// 将Value Object序列化为JSON
$json = json_encode($userStatus);

echo $json; // 输出: {"value":"active","label":"激活"}

前端代码：

import { UserStatus } from './user-status.d.ts';
import Ajv from 'ajv';
import userStatusSchema from './user-status.schema.json';

const ajv = new Ajv();
const validate = ajv.compile(userStatusSchema);

const jsonString = '{"value":"active","label":"激活"}';
const jsonData = JSON.parse(jsonString);

if (validate(jsonData)) {
  const userStatus: UserStatus = jsonData as UserStatus;
  console.log(userStatus.value); // 输出: active
  console.log(userStatus.label); // 输出: 激活
} else {
  console.error(validate.errors);
}

在这个例子中，我们使用Ajv库来验证JSON数据是否符合JSON Schema的定义。如果验证通过，我们可以安全地将JSON数据转换为UserStatus类型。

改进方案：自动生成所有必需的代码

以上方案虽然可行，但是需要手动编写一些代码，例如JSON Schema生成器。为了进一步简化开发流程，我们可以使用代码生成器来自动生成所有必需的代码，包括Value Object、JSON Schema和TypeScript类型定义。

可以使用PHP的反射API来分析Enum的定义，并自动生成Value Object的代码。然后，可以使用类似的方法来生成JSON Schema和TypeScript类型定义。

例如，我们可以创建一个EnumToValueObjectGenerator类，它接收Enum的类名作为参数，并生成对应的Value Object的代码。

<?php

namespace AppUtils;

use ReflectionEnum;
use ReflectionEnumUnitCase;

class EnumToValueObjectGenerator
{
    public static function generate(string $enumClass): string
    {
        $reflection = new ReflectionEnum($enumClass);
        $enumName = $reflection->getShortName();
        $valueObjectName = $enumName . 'Value';
        $namespace = $reflection->getNamespaceName();

        $code = "<?phpnn";
        $code .= "namespace {$namespace};nn";
        $code .= "use {$enumClass};n";
        $code .= "use JsonSerializable;nn";
        $code .= "class {$valueObjectName} implements JsonSerializablen";
        $code .= "{n";
        $code .= "    private {$enumName} $status;nn";
        $code .= "    public function __construct({$enumName} $status)n";
        $code .= "    {n";
        $code .= "        $this->status = $status;n";
        $code .= "    }nn";
        $code .= "    public static function fromString(string $status): selfn";
        $code .= "    {n";
        $code .= "        return new self({$enumName}::from(strtolower($status)));n";
        $code .= "    }nn";
        $code .= "    public function getStatus(): {$enumName}n";
        $code .= "    {n";
        $code .= "        return $this->status;n";
        $code .= "    }nn";
        $code .= "    public function getValue(): stringn";
        $code .= "    {n";
        $code .= "        return $this->status->value;n";
        $code .= "    }nn";
        $code .= "    public function getLabel(): stringn";
        $code .= "    {n";
        $code .= "        return $this->status->label();n";
        $code .= "    }nn";
        $code .= "    public function jsonSerialize(): mixedn";
        $code .= "    {n";
        $code .= "        return [n";
        $code .= "            'value' => $this->getValue(),n";
        $code .= "            'label' => $this->getLabel(),n";
        $code .= "        ];n";
        $code .= "    }nn";
        $code .= "    public function __toString(): stringn";
        $code .= "    {n";
        $code .= "        return $this->getValue();n";
        $code .= "    }n";
        $code .= "}n";

        return $code;
    }
}

使用方法：

<?php

use AppEnumsUserStatus;
use AppUtilsEnumToValueObjectGenerator;

$code = EnumToValueObjectGenerator::generate(UserStatus::class);

echo $code;

// 将生成的代码保存到文件
file_put_contents('App/ValueObjects/UserStatusValue.php', $code);

类似地，我们可以创建ValueObjectToJsonSchemaGenerator和JsonSchemaToTypescriptGenerator类来自动生成JSON Schema和TypeScript类型定义。

结论：类型安全的数据传输

通过使用PHP Enum、Value Object和JSON Schema，我们可以实现前后端数据传输的类型安全。这种方案可以减少代码冗余，提高代码的可维护性，并减少出错的可能性。

优点：

  • 类型安全： 前后端都使用相同的类型定义，避免类型不匹配的问题。
  • 代码复用： 避免在前后端重复定义相同的数据类型。
  • 易于维护： 当数据类型发生变化时，只需要修改PHP Enum和Value Object，然后重新生成JSON Schema和TypeScript类型定义。
  • 可扩展性： 可以很容易地添加新的Enum类型，并自动生成对应的Value Object、JSON Schema和TypeScript类型定义。

缺点：

  • 复杂性： 需要引入Value Object和JSON Schema等概念，增加代码的复杂性。
  • 自动化： 需要花费一些精力来实现代码生成器，或者使用现有的代码生成工具。

优雅实现类型安全的数据传输

总而言之，利用PHP Enum、Value Object和JSON Schema，我们可以优雅地解决前后端数据传输的类型安全问题。虽然需要一定的学习成本和额外的配置，但带来的好处是显而易见的：更高的代码质量、更强的可维护性和更少的错误。通过自动化代码生成，可以进一步降低开发成本，提高开发效率。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注