api-platform不推荐传统的url路径版本化（如`/v1`、`/v2`），而是提倡通过资源和属性的弃用机制来管理api的演进和破坏性变更。这种策略有助于维护单一的api接口，并通过明确的弃用理由指导客户端平滑过渡，从而简化api维护并提升兼容性。
API-Platform的推荐策略：弃用而非版本化
在API开发中，处理破坏性变更（Breaking Changes）是常见的挑战。许多API框架会采用URL路径版本化（如api/v1、api/v2）来区分不同版本的API。然而，API-Platform对此持有不同的观点，其官方推荐的策略是避免显式的URL版本化，转而通过弃用（Deprecation）机制来管理API的演进。
这种策略的核心理念是维护一个单一、持续演进的API接口。当需要引入破坏性变更时，例如更改字段的必填性、数据类型或移除某个资源，API-Platform建议将旧的资源或属性标记为弃用，并提供清晰的弃用理由，指引客户端迁移到新的实现。这样做的好处包括：
- 简化维护：无需同时维护多个版本的API代码库和路由。
- 平滑过渡：客户端可以有充足的时间根据弃用通知进行调整，而不是强制立即升级到新版本。
- 清晰的文档：API-Platform会自动将弃用信息整合到其生成的API文档中，方便客户端查阅。
接下来，我们将详细介绍如何在API-Platform中实现资源和属性的弃用。
如何弃用API资源
当你需要完全替换或移除一个旧的资源时，可以通过在#[ApiResource]注解中添加deprecationReason属性来将其标记为弃用。
示例代码：
假设你有一个名为Parchment的资源，现在你希望客户端使用新的Book资源来代替它。你可以这样标记Parchment资源：
// src/Entity/Parchment.php
namespace App\Entity;
use ApiPlatform\Metadata\ApiResource; // 注意：ApiPlatform 3.x 使用 ApiPlatform\Metadata\ApiResource
#[ApiResource(deprecationReason: "请使用Book资源代替Parchment资源")]
class Parchment
{
// ... 资源属性和方法
}说明：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 通过设置deprecationReason，API-Platform会在生成的API文档（如Swagger/OpenAPI）中明确指出Parchment资源已被弃用，并提供客户端应采取的行动（即使用Book资源）。
- 尽管被弃用，Parchment资源仍然可以通过其原有端点访问，这为客户端提供了缓冲期。
如何弃用API属性
当一个资源的某个属性发生变化，例如被重命名、数据类型改变、或者其必填性发生变化时，你可以弃用旧的属性，并指导客户端使用新的属性。
示例代码：
假设Review资源中有一个letter属性，现在你希望客户端改用更具描述性的rating属性。
// src/Entity/Review.php
namespace App\Entity;
use ApiPlatform\Metadata\ApiProperty; // 注意：ApiPlatform 3.x 使用 ApiPlatform\Metadata\ApiProperty
use ApiPlatform\Metadata\ApiResource;
#[ApiResource]
class Review
{
// ... 其他属性
#[ApiProperty(deprecationReason: "请使用rating属性代替letter属性")]
public $letter;
public $rating; // 新的推荐属性
// ...
}说明：
- 与弃用资源类似，#[ApiProperty(deprecationReason: "...")会在API文档中标记letter属性为弃用，并告知客户端使用rating属性。
- 对于“字段在V1中非必填，在V2中必填”的场景，APIP的弃用策略通常意味着：
- 引入一个新的属性（例如newField），并将其设置为必填。
- 弃用旧的、非必填的属性（例如oldField）。
- 在文档中明确说明客户端应迁移到newField。 这样，客户端在调用API时，如果使用了newField，则必须提供它；如果仍使用oldField，则保持原有行为（非必填），直到oldField被完全移除。
实践考量与最佳实践
采用弃用策略管理API变更时，有几个关键点需要注意：
- 明确的弃用理由：deprecationReason应尽可能具体和有帮助，明确指出客户端应该做什么，以及是否有替代方案。
- 过渡期管理：弃用并不意味着立即移除。你应该为客户端提供一个合理的过渡期（例如几个月），在此期间，被弃用的资源或属性应继续正常工作。
- 持续沟通：除了API文档，还应通过发布说明、开发者博客等渠道主动通知客户端API变更和弃用计划。
- 最终移除：在过渡期结束后，一旦确认绝大多数客户端已完成迁移，被弃用的资源或属性可以被安全地移除。移除前，应再次发布通知。
- 监控与分析：监控弃用资源的访问量，以了解客户端的迁移进度。这有助于决定何时可以安全地移除旧的实现。
- 极端情况：对于非常重大的、无法通过弃用单个资源或属性来优雅处理的架构级变更，可能需要考虑其他策略，例如基于内容协商（Content Negotiation）的版本控制（例如通过Accept头部的version参数），但API-Platform的核心哲学仍然倾向于简化和单一接口。
总结
API-Platform通过其强大的弃用机制，提供了一种优雅且易于维护的API演进方式，避免了传统URL版本化带来的复杂性。通过合理利用#[ApiResource(deprecationReason: ...)]和#[ApiProperty(deprecationReason: ...)]，开发者可以有效地管理API的破坏性变更，确保客户端平滑过渡，同时保持API接口的简洁和一致性。这种策略不仅简化了开发和维护工作，也提升了API的长期可用性和可扩展性。
