使用API Platform在PHP中构建RESTful Web服务 - Medium

一. 在 PHP 中构建 RESTful 服务概述

在本文中，我们将探讨如何使用 API Platform 框架在 PHP 中构建 RESTful Web 服务。RESTful 服务的核心理念是通过 REST API 公开资源和功能，而 API Platform 提供了一套强大的工具集，能够快速实现这一目标。

二. 为什么选择 API Platform？

在选择框架时，我的目标是找到一个能够快速配置、功能强大且基于 Symfony 构建的解决方案。在尝试了多个框架后，我发现 API Platform 几乎完全符合需求。特别是其“5 分钟快速配置”功能，让我对其充满信心。

API Platform 的核心组件支持通过 HTTP 请求暴露 API 资源，同时提供序列化/反序列化功能，并与 Doctrine 数据库抽象层（DBAL）集成，用于持久化应用状态。

三. 设计架构概述

从领域驱动设计（DDD）的角度来看，代码应划分为以下层级：

1. 接口层

负责处理客户端请求，定义 API 的外部接口。

2. 应用层

协调业务逻辑和接口层之间的交互。

3. 领域层

Ticket 类是领域层的核心，定义了实体数据结构，并独立于 DTO（数据传输对象）。这种设计虽然增加了初始复杂度，但在 API 独立演化时具有显著优势。

在领域层设计中，需要注意以下两点：

a. 避免贫血模型

确保实体能够清晰表达业务规则。

b. 领域资源库独立

领域资源库应独立于基础设施层的实体框架资源库。

4. 基础设施层

提供服务运行所需的支持，包括数据库访问和类库扩展。例如，基础设施层的 Doctrine 资源库扩展了领域资源库，实现数据库查询和数据持久化。

四. 配置与优化

1. 禁用 JSON-LD 和分页功能

为了避免与数据结构耦合，我禁用了 JSON-LD 序列化/反序列化功能，并暂时禁用分页功能。配置如下：

# config/packages/api_platform.yaml
api_platform:
  formats:
    json:
      mime_types: ['application/json']
    html:
      mime_types: ['text/html']
  collection:
    pagination:
      enabled: false

2. 自定义命名空间

如果需要使用自定义命名空间，可按以下步骤操作：

在 composer.json 中添加新的基础目录。
使用 composer dump-autoload 更新自动加载配置。
修改配置文件中的路径和前缀：
- ./config/packages/api_platform.yaml
- ./config/routes/annotations.yaml
- ./config/packages/doctrine.yaml

例如，定义命名空间 Rx\Tickets 后，需要将所有类移动到 /src/rx/tickets 目录，并调整代码中的命名空间引用。

五. API 资源声明

API Platform 使用 Doctrine 框架描述数据库中的实体。为了避免与数据库结构耦合，我们将 DTO 与实体分离。示例：

use ApiPlatformCoreAnnotationApiResource;

/**
 * @ApiResource(
 *     itemOperations={
 *         "get"={"defaults"={"_api_receive"=false}}
 *     }
 * )
 */
class TicketDto
{
    // 定义资源属性
}

注意：由于 DTO 与实体分离，必须禁用自动实体检索功能。

六. 异常处理

在实现过程中，未正确处理异常可能导致误导性的错误类型。例如，当 Doctrine 资源库未找到结果时，会返回 null，触发 HTTP 500 错误。正确做法是将异常映射为 HTTP 状态码：

# config/packages/api_platform.yaml
api_platform:
  exception_to_status:
    RxTicketsDomainModelTicketNotFoundException: 404

通过这种方式，可以为特定异常返回正确的 HTTP 状态码。

七. 总结与下一步

经过实验，我对 API Platform 框架有了深入了解。它文档完善、易于使用，能够快速实现功能。但直接使用框架可能导致数据库结构与 API 资源耦合，增加维护难度。通过额外配置，可克服这一问题。

下一步方向建议：

编写单元测试和集成测试。
实现 CI/CD 流水线，将解决方案部署到云环境。
探索 API 版本管理和多语言支持。

API Platform 是一个功能强大的工具，但仍有改进空间。欢迎分享您的实现经验！

原文链接: https://medium.com/@niko.huber/building-restful-services-in-php-5d9a156cf004