通过 Symfony 开始使用 API Platform

API Platform 是任何框架或语言中最先进的 API 平台。

——Fabien Potencier（Symfony 的创建者）

API Platform 是一个功能强大且易于使用的全栈框架，专用于 API 驱动的项目和实现 Jamstack 架构。

介绍

API 平台包含一个 PHP 库（内核）， 用于创建功能齐全的超媒体（或 GraphQL）Web API，支持行业领先的标准：带有 Hydra 的 JSON-LD、OpenAPI等等

API Platform 还提供了雄心勃勃的 JavaScript 工具，可以快速创建基于最流行的前端技术的 Web 和移动应用程序。这些工具解析 API（或支持 Hydra 或 OpenAPI 的任何其他 API）的文档。

API Platform 附带 Docker 和 Kubernetes ，可在云上即时开发和部署。

最简单、最强大的入门方法是下载 API Platform 发行版 。它包含：

• API 骨架，包括 Core 库 、Symfony 框架 （可选）和 Doctrine ORM（ 可选 ）
• 客户端脚手架工具， 用于从 API 文档生成 Next.js Web 应用程序（还支持 Nuxt、Vue、Create React App、React Native、Quasar 和 Vuetify）
• 一个漂亮的管理界面 ，建立在 React Admin 之上，通过解析 API 文档动态创建
• 使用 Mercure 协议创建实时和异步 API 所需的一切
• Docker 定义，用于在单个命令中启动工作开发环境，为 API 和 Next.js Web 应用程序提供容器
• 用于在任何 Kubernetes 集群中部署 API 的 Helm 图表

书店 API

为了了解该框架的工作原理，我们将创建一个 API 来管理书店。

要使用 Next.js 创建功能齐全的 API、管理界面和渐进式 Web 应用程序，您只需设计我们 API 的公共数据模型并将其手工制作为普通旧 PHP 对象 。

API Platform 使用这些模型类来公开和记录具有一系列内置功能的 Web API：

• 创建、检索、更新和删除 （CRUD） 资源
• 数据验证
• 分页
• 滤波
• 排序
• 超媒体/HATEOAS 和内容协商支持（JSON-LD 和 Hydra、JSON：API、HAL…)
• GraphQL 支持
• 漂亮的 UI 和机器可读的文档（Swagger UI/OpenAPI、GraphiQL…)
• 身份验证（基本 HTTP、cookie 以及通过扩展的 JWT 和 OAuth）
• CORS 标头
• 安全检查和标头（根据 OWASP 建议进行测试）
• 基于失效的 HTTP 缓存
• 以及构建现代 API 所需的一切。

在我们开始之前，还有一件事：由于 API 平台发行版包括 Symfony 框架 ，因此它与大多数 Symfony 插件兼容，并受益于这个坚如磐石的基础提供的众多扩展能力（事件、依赖注入容器……），向 API 添加自定义或面向服务的 API 端点、JWT 或 OAuth 身份验证、HTTP 缓存、邮件发送或异步作业等功能非常简单。

安装框架

# 使用 API 平台分发（推荐）

首先下载 API Platform 发行版 ，或从我们提供的模板生成 GitHub 存储库 。您将在此骨架中添加自己的代码和配置。

注意 ：避免下载 .zip 存档，因为它可能会导致潜在的权限问题 ，最好使用 .tar.gz 存档。

API Platform 附带了一个 Docker 定义，可以轻松启动和运行容器化开发环境。如果您的计算机上还没有 Docker，那么现在是安装它的正确时机。

注意 ：在 Mac 上，仅支持 Docker for Mac。同样，在 Windows 上，仅支持 Docker for Windows。开箱即用不支持 Docker Machine。

打开终端，然后导航到包含项目骨架的目录。运行以下命令以使用 Docker Compose 启动所有服务：

生成映像：

docker compose build --no-cache

然后，以分离模式启动 Docker Compose：

docker compose up --wait

💡 提示

确保主机的端口 80、443 和 5432 尚未使用。常见会占用的是 Apache、NGINX 和 Postgres。如果它们正在运行，请停止它们并再次运行 docker compose up --wait。

或者，运行以下命令在端口 8080 上启动 Web 服务器，并禁用 HTTPS：

SERVER_NAME=localhost:80 HTTP_PORT=8080 TRUSTED_HOSTS=localhost docker compose up --wait`

这将启动以下服务：

名字	描述
php	由 FrankenPHP（基于 Caddy Web 服务器构建的现代 PHP 应用程序服务器，本机支持 Mercure 实时 、Vulcain 关系预加载和 XDebug）、Composer 和敏感配置
PWA 公司	Next.js 项目与创建客户端兼容并预装了 Admin
数据库	PostgreSQL 数据库服务器

以下组件可用：

URL	路径	语言	描述
https://localhost/docs/	api/	PHP	API 文档
https://localhost/	pwa/	TypeScript	Next.js 应用程序
https://localhost/admin/	pwa/pages/admin/	TypeScript	管理员

若要查看容器的日志，请运行：

docker compose logs -f

-f 选项是跟踪日志。

由于预配置的 Docker 卷 ，项目文件会在本地主机和容器之间自动共享。这意味着您可以使用您首选的 IDE 或代码编辑器在本地编辑项目文件，它们将会透明地传递到容器中。说到 IDE，我们最喜欢的开发 API 平台应用程序的软件是 PhpStorm 及其令人敬畏的 Symfony 和 Php Inspections 插件。试一试，您将获得几乎所有内容的自动完成和出色的质量分析。

PHP Intelephense for Visual Studio Code 也运行良好，并且是免费和开源的。

API Platform 发行版附带了一个用于测试目的的虚拟实体：api/src/Entity/Greeting.php。我们稍后会删除它。

如果你习惯了 PHP 生态系统，你可能会猜到这个测试实体使用了行业领先的 Doctrine ORM 库作为持久化系统。它在 API Platform 发行版中发布。

Doctrine ORM 是在 API Platform 项目中持久化和查询数据的最简单方法，这要归功于发行版附带的桥接器，但它也完全是可选的， 你可能更愿意插入自己的持久化系统 。

Doctrine Bridge 针对性能和开发便利性进行了优化。例如，在使用 Doctrine 时，API Platform 能够通过添加适当的 JOIN 子句来自动优化生成的 SQL 查询。它还提供了许多强大的内置过滤器 。Doctrine ORM 及其桥接器支持最流行的 RDBMS，包括 PostgreSQL、MySQL、MariaDB、SQL Server、Oracle 和 SQLite。还有一个附带的 Doctrine MongoDB ODM 可选支持。

话虽如此，请记住 API Platform 是 100% 独立于持久化系统。您可以通过实现正确的接口来使用最适合您需求的接口（包括 NoSQL 数据库或远程 Web 服务）。API Platform 甚至支持在同一项目中同时使用多个持久化系统。

💡 提示

php 容器是您的 API 应用程序所在的位置。在命令前加上 docker compose exec php 允许在此容器中执行给定的命令。您可能想要创建一个别名以使您的生活更轻松。因此，例如，您可以运行如下命令： docker compose exec php <command> 。

使用 Symfony CLI

或者，API Platform 服务器组件也可以直接安装在本地计算机上（不依赖容器）。仅建议希望完全控制目录结构和已安装依赖项的用户使用此方法。

为了获得良好的介绍，请观看如何在 SymfonyCasts 上安装 API Platform 而无需分发 。

本教程的其余部分假设您已使用官方发行版安装了 API 平台。如果是您的情况，请直接进入下一部分。

API 平台有一个官方的 Symfony Flex 配方。这意味着您可以使用 Symfony 二进制文件从任何 Symfony 应用程序轻松安装它：

创建一个新的 Symfony 项目：

symfony new bookshop-api

进入项目目录：

cd bookshop-api

在此骨架中安装 API 平台的服务器组件：

symfony composer require api

安装完成以后显示以下提示：

首先应根据你的数据库，修改.env文件中的数据库链接。

链接中需要准确的填写数据库的版本。

然后，创建数据库及其表结构（初始化的时候，实际只是创建了数据库，没有元数据的类，所以没有创建表结构。在完成后续插入持久性系统的ORM定义以后，执行该命令可以创建对应的表。）：

symfony console doctrine:database:create
symfony console doctrine:schema:create

并启动内置的 PHP 服务器：

symfony serve

所有 TypeScript 组件也可作为独立库使用 可使用 npm（或任何其他包管理器）安装。

注意： 以这种方式安装 API 平台时，API 将在 /api/ 路径下打开。您需要打开 http://localhost:8000/api/ 才能查看 API 文档。如果您直接在 Apache 或 NGINX Web 服务器上部署 API 平台，并在打开此链接时收到 404 错误，则需要为您的特定 Web 服务器软件启用重写规则 。

准备就绪

在您最喜欢的网络浏览器中打开 https://localhost

需要在浏览器中添加安全例外，以接受安装框架时为此容器生成的自签名 TLS 证书。

稍后，您可能会将此欢迎屏幕替换为 Next.js 应用程序的主页。如果您不打算创建渐进式 Web 应用程序，您可以删除 pwa/ 目录以及 docker-compose*.yml 和 api/frankenphp/Caddyfile 中的相关行（现在不要这样做，我们将在本教程后面使用此容器）。

单击“API”按钮，或转到 https://localhost/docs/

API Platform 以 OpenAPI 格式（以前称为 Swagger）公开 API 的描述。它还集成了 Swagger UI 的自定义版本，这是一个渲染 OpenAPI 文档的漂亮界面。单击作以显示其详细信息。您还可以直接从 UI 向 API 发送请求。尝试使用 POST 作创建新的 Greeting 资源，然后使用 GET 作访问它，最后通过执行 DELETE 作将其删除。如果您访问任何附加了 .html 扩展的 API URL，API Platform 会在 UI 中显示相应的 API 请求。通过浏览 https://localhost/greetings.html 自己尝试一下。如果不存在扩展名，API Platform 将使用 Accept 标头来选择要使用的格式。默认情况下，将发送 JSON-LD 响应（可配置行为）。

因此，如果您想访问原始数据，您有两种选择：

• 添加正确的 Accept 标头（或者如果您不关心安全性，则根本不设置任何 Accept 标头） – 在编写 API 客户端时首选
• 添加所需的格式作为资源的扩展 – 仅用于调试目的

例如，转到 检索 https://localhost/greetings.jsonld JSON-LD 中的问候语资源列表。

当然，你也可以使用你喜欢的 HTTP 客户端来查询 API。我们喜欢 Hoppscotch，这是一个免费的开源 API 客户端，对 API 平台有很好的支持。

使项目与 API 平台模板保持同步

您已经使用 API 平台模板启动了一个项目，并且您希望创建的项目来引入最新更新（即 FrankenPHP）。只需使用这个基于 Git 的工具模板同步项目可以满足您的需求。

运行以下命令以导入自上次更新以来的更改：

curl -sSL https://raw.githubusercontent.com/coopTilleuls/template-sync/main/template-sync.sh| sh -s -- https://github.com/api-platform/api-platform

解决潜在的冲突，运行 git cherry-pick --continue 就完成了！

有关更多详细信息，请参阅 coopTilleuls/template-sync 文档

自带模型

您的 API 平台项目现在 100% 正常运行。让我们公开我们自己的数据模型。我们的书店 API 将从简单开始。它将由“书籍”对象和“评论”对象组成。

书籍有 ID、ISBN、标题、描述、作者、出版日期，并与评论列表相关。评论有 ID、评分（0 到 5 之间）、正文、作者、出版日期，并且与一本书相关。

让我们将此数据模型描述为一组普通的 PHP 对象：

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\Common\Collections\ArrayCollection;

/** A book. */
#[ApiResource]
class Book
{
    /** The ID of this book. */
    private ?int $id = null;

    /** The ISBN of this book (or null if doesn't have one). */
    public ?string $isbn = null;

    /** The title of this book. */
    public string $title = '';

    /** The description of this book. */
    public string $description = '';

    /** The author of this book. */
    public string $author = '';

    /** The publication date of this book. */
    public ?\DateTimeImmutable $publicationDate = null;

    /** @var Review[] Available reviews for this book. */
    public iterable $reviews;

    public function __construct()
    {
        $this->reviews = new ArrayCollection();
    }

    public function getId(): ?int
    {
        return $this->id;
    }
}

<?php
// api/src/Entity/Review.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;

/** A review of a book. */
#[ApiResource]
class Review
{
    /** The ID of this review. */
    private ?int $id = null;

    /** The rating of this review (between 0 and 5). */
    public int $rating = 0;

    /** The body of the review. */
    public string $body = '';

    /** The author of the review. */
    public string $author = '';

    /** The date of publication of this review.*/
    public ?\DateTimeImmutable $publicationDate = null;

    /** The book this review is about. */
    public ?Book $book = null;

    public function getId(): ?int
    {
        return $this->id;
    }
}

我们使用相应的 PHPDoc 创建了两个典型的 PHP 对象，它们都标有 #[ApiResource] 属性。为了方便起见，我们还使用了 Doctrine Collection 库（独立于 Doctrine ORM），但它不是强制性的。

重新加载 https://localhost/docs/，API Platform 使用这些类生成 OpenAPI 文档（还公开了 Hydra 文档），并为我们注册了典型的 REST 路由 。

适用于 2 种对象的操作显示在 UI 中。我们还可以看到很棒的 Web 调试工具栏 。

请注意，实体和属性的描述在 API 文档中，并且 API Platform 使用 PHP 类型生成适当的 JSON 架构。

该框架还使用这些元数据将数据从 JSON（和其他格式）序列化和反序列化为 PHP 对象（来回）！

为简单起见，在此示例中，我们使用了公共属性（ID 除外，见下文）。API 平台（以及 Symfony 和 Doctrine）也支持访问器方法（getter/setter），如果需要，可以使用它们。我们使用 ID 的私有属性和 getter 来强制执行它是只读的事实（我们将让 DBMS 生成它）。API Platform 还对 UUID 提供一级支持。 您可能应该使用它们而不是自动递增的 ID。

因为 API Platform 为我们提供了所有的基础设施，所以我们的 API 几乎准备就绪！

接下来API 的唯一剩余任务是能够查询和持久化数据。

插入持久性系统

为了检索和保存数据，API Platform 提出了两个主要选项（我们可以混合使用它们）：

1. 编写我们自己的状态提供者和状态处理器来获取和保存任何持久化系统中的数据，并触发我们的自定义业务逻辑。如果您想将 API 公开的公共数据模型与内部数据模型分开，并实现分层架构（例如 Clean Architecture 或 Hexagonal Architecture），我们建议这样做;
2. 使用各种现有状态提供者和状态处理器之一，允许使用流行的持久性库自动获取和持久化数据。开箱即用，为 Doctrine ORM 和 Doctrine MongoDB ODM 提供了状态提供者和处理器。状态提供程序（但尚无处理器）也可用于 Elasticsearch。Pomm 和 PHP 扩展 SQL 还为 API 平台提供了状态提供程序和处理器。我们建议将此方法用于快速应用程序开发。

请务必阅读一般设计注意事项文档，详细了解 API Platform 的架构以及如何在这两种方法之间进行选择。

在这里，我们将在本教程的其余部分使用内置的 Doctrine ORM 状态提供程序。

修改类以使用 Doctrine ORM 提供的属性将它们映射到数据库表。

按照以下补丁中的说明修改这些文件：

api/src/Entity/Book.php

use ApiPlatform\Metadata\ApiResource;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\ORM\Mapping as ORM;

/** A book. */
#[ORM\Entity]
#[ApiResource]
class Book
{
    /** The ID of this book. */
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    private ?int $id = null;

    /** The ISBN of this book (or null if doesn't have one). */
    #[ORM\Column(nullable: true)]
    public ?string $isbn = null;

    /** The title of this book. */
    #[ORM\Column]
    public string $title = '';

    /** The description of this book. */
    #[ORM\Column(type: 'text')]
    public string $description = '';

    /** The author of this book. */
    #[ORM\Column]
    public string $author = '';

    /** The publication date of this book. */
    #[ORM\Column]
    public ?\DateTimeImmutable $publicationDate = null;

    /** @var Review[] Available reviews for this book. */
    #[ORM\OneToMany(targetEntity: Review::class, mappedBy: 'book', cascade: ['persist', 'remove'])]
    public iterable $reviews;

    public function __construct()

api/src/Entity/Review.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

/** A review of a book. */
#[ORM\Entity]
#[ApiResource]
class Review
{
    /** The ID of this review. */
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    private ?int $id = null;

    /** The rating of this review (between 0 and 5). */
    #[ORM\Column(type: 'smallint')]
    public int $rating = 0;

    /** The body of the review. */
    #[ORM\Column(type: 'text')]
    public string $body = '';

    /** The author of the review. */
    #[ORM\Column]
    public string $author = '';

    /** The date of publication of this review.*/
    #[ORM\Column]
    public ?\DateTimeImmutable $publicationDate = null;

    /** The book this review is about. */
    #[ORM\ManyToOne(inversedBy: 'reviews')]
    public ?Book $book = null;

    public function getId(): ?int

提示 ： 由于 --api-resource 选项，您可以使用 Symfony MakerBundle 生成一个 Doctrine 实体，该实体也是一个资源：

docker compose exec php bin/console make:entity --api-resource

Doctrine 的属性将这些实体映射到数据库中的表。为了向后兼容，仍然支持通过注释进行映射，但它们被视为已弃用，现在推荐使用属性。这两种方法都很方便，因为它们允许对代码和配置进行分组，但是，如果要将类与其元数据分离，可以切换到 XML 或 YAML 映射。它们也受到支持。

在项目的官方文档中了解有关如何使用 Doctrine ORM 映射实体的更多信息 或者在 Kévin 的书《Persistence in PHP with the Doctrine ORM》中。

现在，删除文件 api/src/Entity/Greeting.php。此演示实体不再有用。最后，使用 Doctrine Migrations 生成一个新的数据库迁移并应用它：

docker compose exec php bin/console doctrine:migrations:diff
docker compose exec php bin/console doctrine:migrations:migrate

我们现在有一个具有读写功能的工作 API！

在 Swagger UI 中，单击 Book 资源类型的 POST 作，单击“试用”并将以下 JSON 文档作为请求正文发送：

{
  "isbn": "9781782164104",
  "title": "Persistence in PHP with the Doctrine ORM",
  "description": "This book is designed for PHP developers and architects who want to modernize their skills through better understanding of Persistence and ORM.",
  "author": "Kévin Dunglas",
  "publicationDate": "2013-12-01"
}

您刚刚通过书店 API 保存了一个新的图书资源！API Platform 会自动将 JSON 文档转换为相应 PHP 实体类的实例，并使用 Doctrine ORM 将其持久化到数据库中。

默认情况下，API 支持 GET（检索，在集合和项目上）、POST（创建）、PATCH（部分更新）和 DELETE（不言自明）HTTP 方法。不要忘记禁用您不想要的那些 ！

还支持 PUT（替换或创建）方法，但默认情况下未启用。

尝试对集合执行 GET 作。出现我们添加的书。当集合包含超过 30 个项目时，分页将自动显示， 这是完全可配置的。您可能还有兴趣添加一些过滤器并向集合添加排序 。

您可能已经注意到，在生成的 JSON 响应中，某些键以 @ 符号开头（@id、@type、@context…）？API 平台完全支持 JSON-LD 格式（及其 Hydra 扩展名）。它允许构建具有自动发现功能的智能客户端，例如 API 平台管理员 我们将在几行中发现。 它对于开放数据、SEO 和互作性非常有用，尤其是与 Schema.org 等开放词汇一起使用时 并允许向 Google 授予对结构化数据的访问权限 或使用 Apache Jena 在 SPARQL 中查询您的 API）。

我们认为 JSON-LD 是新 API 的最佳默认格式。但是，API Platform 本机支持许多其他格式 ，包括 GraphQL（我们会开始）、JSON：API、HAL、原始 JSON、 XML（实验性）甚至 YAML 和 CSV。您还可以轻松添加对其他格式的支持 ，您可以选择要启用和默认使用的格式。

现在，使用评论资源的 POST 作为本书添加评论：

{
  "book": "/books/1",
  "rating": 5,
  "body": "Interesting book!",
  "author": "Kévin",
  "publicationDate": "September 21, 2016"
}

注意： 如果您已在使用 composer 的现有项目中安装了 API 平台，则密钥书的内容必须为 “/api/books/1”

关于这个请求，有两件有趣的事情要提：

首先，我们学会了如何处理关系。在超媒体 API 中，每个资源都由（唯一的）IRI 标识。URL 是有效的 IRI，它是 API Platform 使用的。每个 JSON-LD 文档的 @id 属性都包含标识它的 IRI。您可以使用此 IRI 从其他文档中引用此文档。在之前的请求中，我们使用了之前创建的书的 IRI 将其与我们正在创建的评论链接起来。API 平台足够智能，可以处理 IRI。顺便说一句，您可能希望嵌入文档而不是引用它们（例如，减少 HTTP 请求的数量）。您甚至可以让客户端仅选择它需要的属性 。

另一个有趣的事情是 API Platform 如何处理日期（publicationDate 属性）。API Platform 了解 PHP 支持的任何日期格式 。在生产中，我们强烈建议使用 RFC 3339 指定的格式，但如您所见，可以使用大多数常见格式，包括 2016年9月21日。

总而言之，如果您想公开任何实体，您只需：

1. 将其放在 App\Entity\ 命名空间下
2. 编写你的数据提供者和持久化器，或者如果你使用 Doctrine，请将其与数据库映射
3. 用 #[ApiPlatform\Metadata\ApiResource] 属性标记它

还能简单吗？！

验证数据

现在尝试通过向具有以下正文的 /books 发出 POST 请求来添加另一本书：

{
  "isbn": "2815840053",
  "description": "Hello",
  "author": "Me",
  "publicationDate": "today"
}

这本书创作成功，但存在问题;我们没有给它一个标题。创建没有标题的书本记录是没有意义的，因此我们确实应该采取一些验证措施来防止这种情况发生。

API 平台带有一个与 Symfony 验证器组件的桥接器。添加其众多验证约束中的一些 （或创建自定义的） 足以验证用户提交的数据。让我们向数据模型添加一些验证规则。

按照这些补丁中的说明修改以下文件：

api/src/Entity/Book.php

use ApiPlatform\Metadata\ApiResource;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

    #[ORM\Column(nullable: true)]
    #[Assert\Isbn]
    public ?string $isbn = null;

    #[ORM\Column]
    #[Assert\NotBlank]
    public string $title = '';

    #[ORM\Column(type: 'text')]
    #[Assert\NotBlank]
    public string $description = '';

    #[ORM\Column]
    #[Assert\NotBlank]
    public string $author = '';

    #[ORM\Column]
    #[Assert\NotNull]
    public ?\DateTimeImmutable $publicationDate = null;

api/src/Entity/Review.php

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

    #[ORM\Column(type: 'smallint')]
    #[Assert\Range(min: 0, max: 5)]
    public int $rating = 0;

    #[ORM\Column(type: 'text')]
    #[Assert\NotBlank]
    public string $body = '';

    #[ORM\Column]
    #[Assert\NotBlank]
    public string $author = '';

    #[ORM\Column]
    #[Assert\NotNull]
    public ?\DateTimeImmutable $publicationDate = null;

    #[ORM\ManyToOne(inversedBy: 'reviews')]
    #[Assert\NotNull]
    public ?Book $book = null;

    public function getId(): ?int

通过添加这些 #[Assert\*] 属性更新实体后（与 Doctrine 一样，您也可以使用 XML 或 YAML），重试之前的 POST 请求。

{
  "@context": "/contexts/ConstraintViolationList",
  "@type": "ConstraintViolationList",
  "title": "An error occurred",
  "description": "isbn: This value is neither a valid ISBN-10 nor a valid ISBN-13.\ntitle: This value should not be blank.",
  "violations": [
    {
      "propertyPath": "isbn",
      "message": "This value is neither a valid ISBN-10 nor a valid ISBN-13."
    },
    {
      "propertyPath": "title",
      "message": "This value should not be blank."
    }
  ]
}

您现在会收到正确的验证错误消息，这些消息始终使用 Hydra 错误格式 （RFC 7807 也支持）。 这些错误很容易在客户端解析。通过添加适当的验证约束，我们还注意到提供的 ISBN 无效…

添加 GraphQL 支持

API 平台不是 REST 和 GraphQL 框架吗？这是真的！默认情况下，不启用 GraphQL 支持。要添加它，我们需要安装 graphql-php 库。运行以下命令：

composer require api-platform/graphql

您现在拥有了一个 GraphQL API！打开 https://localhost/graphql（如果您使用 Symfony Flex 安装 API 平台，则打开 https://localhost/api/graphql）以使用漂亮的 GraphiQL 来使用它 API Platform 附带的 UI：

通过创建问候语来尝试一下：

mutation {
  createGreeting(input: { name: "Test2" }) {
    greeting {
      id
      name
    }
  }
}

并通过宣读问候语：

{
  greeting(id: "/greetings/1") {
    id
    name
    _id
  }
}

您也可以尝试更复杂的事情：

{
  books {
    totalCount
    edges {
      node {
        id
        title
        reviews {
          totalCount
          edges {
            node {
              author
              rating
            }
          }
        }
      }
    }
  }
}

GraphQL 实现支持查询、突变、100%的 Relay 服务器规范、分页、过滤器和访问控制规则 。您可以将其与流行的 RelayJS 和 Apollo 一起使用 客户。

管理员

有一个管理后端来管理 API 公开的数据不是很好吗？等等，你已经有一个了！

在浏览器中打开 https://localhost/admin/

此 Material Design 管理员是一个渐进式 Web 应用程序 使用 API Platform Admin 构建（内部有 React Admin！它功能强大且完全可定制。请参阅其文档以了解更多信息。它利用 API 组件公开的 Hydra 文档来构建自身。它是 100% 动态的 – 不生成代码 。

Next.js Web 应用程序

API Platform 还有一个很棒的客户端生成器 ，能够搭建完全工作的 Next.js、Nuxt.js、 React/Redux、Vue.js、Quasar 和 Vuetify 渐进式 Web 应用程序/单页应用程序，您可以轻松调整和自定义。如果您更喜欢利用移动设备的所有功能，该生成器还支持 React Native。

该发行版带有一个骨架，随时可以欢迎生成代码的 Next.js 风格。若要引导应用，请运行：

docker compose exec pwa \
    pnpm create @api-platform/client

在浏览器中打开 https://localhost/books/

您还可以选择使用 --resource 参数为特定资源生成代码（例如：pnpm create @api-platform/client --resource books ）。

生成的代码包含列表（包括分页）、删除按钮、创建和编辑表单。它还包括 Tailwind CSS 类和 ARIA 角色 使残障人士可以使用该应用程序。

如果您更喜欢生成基于另一个前端堆栈构建的 PWA，请阅读专用文档。

钩住你自己的业务逻辑

现在您已经了解了基础知识，请务必阅读一般设计注意事项以及如何扩展 API 平台 ，以了解 API 平台的设计方式，以及如何挂钩您的自定义业务逻辑！

其他功能

首先，您可能想了解如何使用内置的 Kubernetes 集成在云中部署应用程序 。

然后，还有更多功能需要学习！阅读完整文档 ，了解如何使用它们以及如何扩展 API Platform 以满足您的需求。API 平台对于原型设计和快速应用程序开发 （RAD） 非常高效，但该框架主要设计用于创建复杂的 API 驱动项目，远远超出简单的 CRUD 应用程序。它受益于强大的扩展点 并且它不断针对性能进行优化。 它为众多高流量网站提供支持。

API Platform 具有内置的 HTTP 缓存失效系统，允许使用 Varnish 使 API Platform 应用程序快速运行。在章节中阅读更多内容 API 平台核心库：启用内置的 HTTP 缓存失效系统 。

请记住，您可以使用您最喜欢的客户端技术：API Platform 为流行的 JavaScript 框架提供生成器，但您也可以直接使用您喜欢的客户端技术，包括 Angular、Ionic 和 Swift。任何能够发送 HTTP 请求的语言都可以（甚至 COBOL 也可以这样做）。

为了更进一步，API 平台团队维护了一个演示应用程序，展示了更高级的用例，例如利用序列化组、用户管理或 JWT 和 OAuth 身份验证。查看 GitHub 上的演示代码源代码 并在线浏览 。