PHP 8.1 Enums作为API响应状态码：实现前端与后端约定的类型安全 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

好的，我们开始。

PHP 8.1 Enums 作为 API 响应状态码：实现前端与后端约定的类型安全

大家好，今天我们来聊聊如何利用 PHP 8.1 引入的 Enums 特性，在 API 开发中实现前端与后端之间关于响应状态码的类型安全约定。这对于提高代码质量、减少集成错误、以及改善开发体验都非常有帮助。

背景：传统 API 状态码处理的痛点

在传统的 API 开发模式中，响应状态码通常使用数字或字符串来表示。例如：

200: OK
400: Bad Request
500: Internal Server Error

这种方式存在一些问题：

魔术数字/字符串： 这些数字或字符串分散在代码各处，缺乏明确的语义，难以理解和维护。
类型安全缺失： PHP 是弱类型语言，虽然有类型提示，但是对于这些状态码，通常无法进行严格的类型检查。容易出现拼写错误或使用了未定义的码值的情况。
约定不明： 前端和后端需要通过文档或口头约定来确保对状态码的理解一致。但文档可能不及时更新，口头约定容易遗忘，导致集成问题。
IDE 支持不足： IDE 无法提供自动补全、类型检查等功能，降低开发效率。

PHP 8.1 Enums 的优势

PHP 8.1 引入的 Enums (枚举) 类型，可以很好地解决上述问题。Enums 提供了一种定义具名常量集合的方式，可以为状态码赋予明确的语义，并提供类型安全保障。

示例：定义 API 状态码 Enum

首先，我们定义一个 ApiResponseStatus Enum，来表示常见的 API 状态码：

<?php

namespace AppEnums;

enum ApiResponseStatus: int
{
    case SUCCESS = 200;
    case CREATED = 201;
    case ACCEPTED = 202;
    case NO_CONTENT = 204;
    case BAD_REQUEST = 400;
    case UNAUTHORIZED = 401;
    case FORBIDDEN = 403;
    case NOT_FOUND = 404;
    case METHOD_NOT_ALLOWED = 405;
    case CONFLICT = 409;
    case UNPROCESSABLE_ENTITY = 422;
    case INTERNAL_SERVER_ERROR = 500;
    case SERVICE_UNAVAILABLE = 503;
}

在这个例子中：

ApiResponseStatus 是 Enum 的名称。
int 表示 Enum 的底层类型是整数。这意味着每个 Enum case 都会关联一个整数值。
SUCCESS, CREATED, BAD_REQUEST 等是 Enum cases，每个 case 都关联一个整数值，代表对应的 HTTP 状态码。

在 API 控制器中使用 Enum

现在，我们可以在 API 控制器中使用这个 Enum 来返回响应：

<?php

namespace AppHttpControllers;

use AppEnumsApiResponseStatus;
use IlluminateHttpJsonResponse;
use IlluminateHttpRequest;

class UserController extends Controller
{
    public function index(Request $request): JsonResponse
    {
        // 获取用户数据
        $users = [
            ['id' => 1, 'name' => 'Alice'],
            ['id' => 2, 'name' => 'Bob'],
        ];

        return response()->json([
            'status' => ApiResponseStatus::SUCCESS,
            'message' => 'Users retrieved successfully.',
            'data' => $users,
        ], ApiResponseStatus::SUCCESS->value);
    }

    public function show(int $id): JsonResponse
    {
        // 尝试查找用户
        $user = ['id' => $id, 'name' => 'Charlie']; // 假设找到了用户
        // $user = null; // 假设没找到用户

        if ($user === null) {
            return response()->json([
                'status' => ApiResponseStatus::NOT_FOUND,
                'message' => 'User not found.',
            ], ApiResponseStatus::NOT_FOUND->value);
        }

        return response()->json([
            'status' => ApiResponseStatus::SUCCESS,
            'message' => 'User retrieved successfully.',
            'data' => $user,
        ], ApiResponseStatus::SUCCESS->value);
    }

    public function store(Request $request): JsonResponse
    {
        // 验证请求数据
        $validatedData = $request->validate([
            'name' => 'required|string|max:255',
        ]);

        // 创建新用户（此处省略具体实现）

        return response()->json([
            'status' => ApiResponseStatus::CREATED,
            'message' => 'User created successfully.',
            'data' => ['name' => $validatedData['name']], // 模拟返回新用户数据
        ], ApiResponseStatus::CREATED->value);
    }

    public function update(Request $request, int $id): JsonResponse
    {
        // 验证请求数据
        $validatedData = $request->validate([
            'name' => 'required|string|max:255',
        ]);

        // 更新用户（此处省略具体实现）

        return response()->json([
            'status' => ApiResponseStatus::ACCEPTED,
            'message' => 'User updated successfully.',
            'data' => ['id' => $id, 'name' => $validatedData['name']], // 模拟返回更新后的用户数据
        ], ApiResponseStatus::ACCEPTED->value);
    }

    public function destroy(int $id): JsonResponse
    {
        // 删除用户（此处省略具体实现）

        return response()->json([
            'status' => ApiResponseStatus::NO_CONTENT,
            'message' => 'User deleted successfully.',
        ], ApiResponseStatus::NO_CONTENT->value);
    }

    public function processData(Request $request): JsonResponse
    {
        try {
            // 一些可能抛出异常的处理逻辑
            if ($request->input('some_flag') == 'error') {
                throw new Exception('Simulated error.');
            }

            // 处理数据 (此处省略具体实现)

            return response()->json([
                'status' => ApiResponseStatus::SUCCESS,
                'message' => 'Data processed successfully.',
            ], ApiResponseStatus::SUCCESS->value);

        } catch (Exception $e) {
            return response()->json([
                'status' => ApiResponseStatus::INTERNAL_SERVER_ERROR,
                'message' => 'An error occurred: ' . $e->getMessage(),
            ], ApiResponseStatus::INTERNAL_SERVER_ERROR->value);
        }
    }

    public function validateInput(Request $request): JsonResponse
    {
        $validator = Validator::make($request->all(), [
            'email' => 'required|email',
            'age' => 'required|integer|min:18',
        ]);

        if ($validator->fails()) {
            return response()->json([
                'status' => ApiResponseStatus::UNPROCESSABLE_ENTITY,
                'message' => 'Validation failed.',
                'errors' => $validator->errors(),
            ], ApiResponseStatus::UNPROCESSABLE_ENTITY->value);
        }

        return response()->json([
            'status' => ApiResponseStatus::SUCCESS,
            'message' => 'Input validated successfully.',
        ], ApiResponseStatus::SUCCESS->value);
    }
}

在这个例子中，我们使用了 ApiResponseStatus Enum 来设置响应的 HTTP 状态码和 JSON 响应体中的 status 字段。注意 ApiResponseStatus::SUCCESS->value 访问枚举的原始值。

优势：

可读性： 使用 ApiResponseStatus::SUCCESS 比使用数字 200 更加清晰易懂。
类型安全： PHP 会在编译时检查是否使用了有效的 ApiResponseStatus Enum case。如果使用了未定义的 case，会抛出错误。
自动补全： IDE 可以提供 ApiResponseStatus Enum cases 的自动补全，提高开发效率。

前端如何使用 Enum 信息

前端需要知道后端定义的 Enum 以及对应的数值。常见的做法是：

共享 Enum 定义： 可以通过某种方式将 PHP 的 Enum 定义共享给前端。例如，可以创建一个 API 端点，返回一个 JSON 对象，包含 Enum 的名称和值。
生成前端代码： 可以使用脚本将 PHP 的 Enum 定义转换为前端代码 (例如 TypeScript Enum)。

示例：创建 API 端点返回 Enum 定义

<?php

namespace AppHttpControllers;

use AppEnumsApiResponseStatus;
use IlluminateHttpJsonResponse;

class EnumController extends Controller
{
    public function apiResponseStatus(): JsonResponse
    {
        $cases = [];
        foreach (ApiResponseStatus::cases() as $case) {
            $cases[$case->name] = $case->value;
        }

        return response()->json([
            'name' => 'ApiResponseStatus',
            'cases' => $cases,
        ]);
    }
}

这个控制器方法会返回一个 JSON 对象，如下所示：

{
    "name": "ApiResponseStatus",
    "cases": {
        "SUCCESS": 200,
        "CREATED": 201,
        "ACCEPTED": 202,
        "NO_CONTENT": 204,
        "BAD_REQUEST": 400,
        "UNAUTHORIZED": 401,
        "FORBIDDEN": 403,
        "NOT_FOUND": 404,
        "METHOD_NOT_ALLOWED": 405,
        "CONFLICT": 409,
        "UNPROCESSABLE_ENTITY": 422,
        "INTERNAL_SERVER_ERROR": 500,
        "SERVICE_UNAVAILABLE": 503
    }
}

示例：使用 TypeScript 定义 Enum

假设我们使用 TypeScript 作为前端语言。我们可以根据后端返回的 JSON 数据，生成 TypeScript Enum：

enum ApiResponseStatus {
  SUCCESS = 200,
  CREATED = 201,
  ACCEPTED = 202,
  NO_CONTENT = 204,
  BAD_REQUEST = 400,
  UNAUTHORIZED = 401,
  FORBIDDEN = 403,
  NOT_FOUND = 404,
  METHOD_NOT_ALLOWED = 405,
  CONFLICT = 409,
  UNPROCESSABLE_ENTITY = 422,
  INTERNAL_SERVER_ERROR = 500,
  SERVICE_UNAVAILABLE = 503,
}

然后，在前端代码中，我们可以使用这个 TypeScript Enum 来处理 API 响应：

async function fetchUsers(): Promise<void> {
  const response = await fetch('/api/users');

  if (response.status === ApiResponseStatus.SUCCESS) {
    const data = await response.json();
    console.log('Users:', data.data);
  } else if (response.status === ApiResponseStatus.NOT_FOUND) {
    console.error('User not found.');
  } else {
    console.error('An error occurred:', response.status);
  }
}

其他 Enum 用途

除了 API 状态码，Enums 还可以用于表示其他类型的常量集合，例如：

用户角色： ADMIN, EDITOR, VIEWER
订单状态： PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED
支付方式： CREDIT_CARD, PAYPAL, BANK_TRANSFER

使用 Enum 的好处总结

使用 PHP 8.1 Enums 可以带来以下好处：

提高代码可读性和可维护性： 使用具名常量代替魔术数字/字符串，代码更易于理解和维护。
增强类型安全： PHP 会在编译时检查 Enum 类型，避免拼写错误和使用未定义的常量。
改善开发体验： IDE 可以提供自动补全、类型检查等功能，提高开发效率。
促进前后端约定： 通过共享 Enum 定义，可以确保前端和后端对状态码的理解一致，减少集成问题。
减少错误： 明确的状态码定义减少了由于人为错误导致的bug，提升了系统的健壮性。

更高级的使用方式：Backed Enums 与 String Enums

除了简单的 Integer Enums，PHP 8.1 还支持 Backed Enums 和 String Enums。

Backed Enums: 就是我们之前使用的 Enum，它有一个关联的标量值 (integer 或 string)。
String Enums: 类似于 Backed Enums，但其底层类型只能是字符串。

示例：String Enums

<?php

namespace AppEnums;

enum UserRole: string
{
    case ADMIN = 'admin';
    case EDITOR = 'editor';
    case VIEWER = 'viewer';
}

使用 String Enums 的好处是，可以直接使用字符串值，而无需访问 ->value 属性。这在某些情况下可以简化代码。

示例：使用 String Enums

<?php

namespace AppHttpControllers;

use AppEnumsUserRole;
use IlluminateHttpJsonResponse;

class AuthController extends Controller
{
    public function checkRole(string $role): JsonResponse
    {
        try {
            $userRole = UserRole::from($role); // 从字符串创建Enum

            return response()->json([
                'status' => 'success',
                'message' => 'Valid user role.',
                'role' => $userRole, // 直接使用 Enum
            ]);

        } catch (ValueError $e) {
            return response()->json([
                'status' => 'error',
                'message' => 'Invalid user role.',
            ], 400);
        }
    }
}

考虑事项

向后兼容性： 如果你的项目需要兼容 PHP 8.1 之前的版本，你不能直接使用 Enums。你需要使用其他方式来实现类似的功能，例如使用常量类。
序列化： Enum 对象默认情况下不能直接序列化为 JSON。你需要实现 JsonSerializable 接口，或者使用第三方库来处理 Enum 的序列化。
性能： Enum 的性能通常比常量略差，但影响可以忽略不计。

总结

PHP 8.1 Enums 为 API 开发带来了类型安全和语义化的优势。通过定义 Enum 来表示 API 状态码，可以提高代码质量、减少集成错误、并改善开发体验。前后端共享 Enum 定义，确保对状态码的理解一致，大大降低了沟通成本。

使用 Enum 提升 API 开发体验

使用 Enums 可以让我们的 API 代码更清晰、更安全、更容易维护，从而构建更健壮和可靠的系统。

PHP 8.1 Enums 作为 API 响应状态码：实现前端与后端约定的类型安全

发表回复 取消回复

发表回复取消回复