api platform不直接支持传统的url版本控制（如`/v2`），而是推荐采用无版本号api设计，并通过强大的弃用（deprecation）机制来优雅地处理api的破坏性变更。本文将详细介绍如何利用资源弃用和属性弃用功能，平滑地引导客户端过渡，从而实现api的持续演进和维护。
API Platform的无版本号API设计理念
在API开发中，处理破坏性变更（breaking changes）是常见的挑战。传统的做法是引入API版本号，例如/api/v1和/api/v2，以区分不同版本的API行为。然而，API Platform采取了一种不同的策略：它不直接提供内置的URL版本控制支持，而是鼓励开发者构建一个“无版本号”的API，并通过弃用（Deprecation）机制来管理变更。
这种方法的核心思想是，通过明确标记不再推荐使用的资源或属性，来引导客户端逐步迁移到新的实现，而非强制性地维护多个并行的API版本。这有助于简化部署、减少代码冗余，并提供更平滑的API演进路径。API Platform官方文档也推荐了这种做法，详情可参考其关于弃用机制的指南。
核心机制一：弃用整个资源
当一个资源（Resource）被完全替换，或者其功能不再推荐使用时，可以将其标记为弃用。这意味着客户端应该停止使用该资源，并转而使用其替代品。
示例代码：弃用 Parchment 资源
假设我们有一个名为 Parchment 的资源，现在我们希望客户端改用功能更丰富的 Book 资源。我们可以通过在 ApiResource 注解中添加 deprecationReason 属性来实现：
namespace App\Entity;
use ApiPlatform\Core\Annotation\ApiResource; // 注意：对于API Platform 3，注解命名空间可能有所不同
#[ApiResource(deprecationReason: "请改用 Book 资源")]
class Parchment
{
// ... 资源定义，例如ID、内容等
private ?int $id = null;
private ?string $content = null;
public function getId(): ?int
{
return $this->id;
}
public function getContent(): ?string
{
return $this->content;
}
public function setContent(string $content): self
{
$this->content = $content;
return $this;
}
}当客户端尝试访问 Parchment 资源时，API的元数据（例如通过Swagger/OpenAPI文档）会明确显示该资源已被弃用，并提供弃用原因，引导开发者迁移。
核心机制二：弃用资源属性
在许多情况下，破坏性变更仅限于资源的某个特定属性，例如一个字段的名称改变、数据类型变更，或者像问题中提到的，一个字段从可选变为必选（或被新字段替代）。在这种场景下，我们可以弃用单个属性，而不是整个资源。
示例代码：弃用 Review 资源的 letter 属性
假设 Review 资源曾经有一个 letter 属性用于存储评论内容，现在我们引入了一个更具描述性的 rating 属性来替代它，并且可能希望 rating 成为必选。我们可以弃用 letter 属性：
namespace App\Entity;
use ApiPlatform\Core\Annotation\ApiProperty; // 注意：对于API Platform 3，注解命名空间可能有所不同
use ApiPlatform\Core\Annotation\ApiResource;
#[ApiResource]
class Review
{
private ?int $id = null;
#[ApiProperty(deprecationReason: "请改用 rating 属性")]
public $letter; // 旧的评论内容字段
public ?int $rating = null; // 新的评分字段
// ... 其他属性和方法
public function getId(): ?int
{
return $this->id;
}
}通过这种方式，API文档会指示 letter 属性已弃用，并建议使用 rating 属性。这为客户端提供了一个清晰的迁移路径，允许他们在更新代码时逐步替换旧属性。对于“字段从V1的可选变为V2的必选”这类场景，弃用旧字段并引入一个具有新约束（例如 #[Assert\NotNull]）的新字段是推荐的实践。
弃用机制的优势与适用场景
- 平滑过渡： 允许客户端在一段时间内继续使用旧的API部分，同时为他们提供了明确的迁移指示，避免了强制性的即时更新。
- 简化维护： 避免了同时维护多个完整API版本的复杂性，减少了代码库的分叉和合并问题。
- 清晰的沟通： 通过API文档（如OpenAPI/Swagger UI），弃用信息能够直观地传达给API消费者。
-
适用于：
- 字段名称、类型或约束的轻微变更。
- 某个功能或资源被更优的方案替代。
- 逐步淘汰不再需要的API部分。
局限性与注意事项
尽管弃用机制非常强大，但它并非万能药。
- 不适用于大规模重构： 对于API的根本性重构，例如整个数据模型或核心业务逻辑发生巨大变化，可能需要更复杂的策略，甚至考虑在特定情况下引入子域或独立的微服务。
- 客户端配合： 弃用机制依赖于客户端开发者阅读并遵守弃用通知。如果客户端没有及时更新，他们仍然可能使用已弃用的功能。
- 弃用周期： 弃用并不意味着立即删除。通常会有一个“弃用周期”，在此期间，旧功能仍然可用，但在周期结束后可能会被移除。开发者需要明确告知客户端这个周期。
- API Platform版本： 上述示例基于API Platform 2.x 的注解语法。对于API Platform 3.x，注解已迁移到PHP属性（Attributes），但核心概念和用法是相似的。请根据您使用的API Platform版本调整注解命名空间和语法。
总结
API Platform通过其独特的弃用机制，为开发者提供了一种优雅且高效的方式来管理API的演进和破坏性变更。通过合理地使用资源弃用和属性弃用，我们可以避免传统版本控制带来的复杂性，实现API的平滑过渡和持续优化，同时保持与现有客户端的兼容性。理解并掌握这一策略，是构建健壮、可维护的API Platform应用的关键。
