升级API Platform 3.0后实体无法暴露，api:upgrade-resource命令不存在

1. api:upgrade-resource命令未定义的原因 #

API Platform 3.0彻底重构了元数据与注解系统，官方已移除api:upgrade-resource命令——该命令原本用于自动将2.x版本的注解转换为3.x格式，但由于自动转换的准确性无法保障，官方明确建议手动迁移注解，因此命令不存在是预期行为，无需尝试使用。

2. 实体未暴露但手动修改后正常的核心原因及解决方法 #

这种情况大概率是缓存失效不彻底、注解迁移不规范或配置遗漏导致的，以下是具体排查方向：

（1）缓存未彻底清理 #

API Platform 3.0对元数据缓存依赖极强，即使替换了注解，旧的应用缓存、Doctrine元数据缓存仍会生效。手动修改实体时，文件修改时间触发了缓存自动失效，因此该实体能被正确识别。
解决：执行以下命令彻底清理缓存：

# 清理应用缓存（开发环境）
php bin/console cache:clear --env=dev
# 生产环境需添加--env=prod
# 清理Doctrine元数据缓存
php bin/console doctrine:cache:clear-metadata

（2）注解迁移不彻底 #

3.0版本的注解体系与2.x差异极大，仅替换命名空间不足以完成迁移：

• 命名空间变更：从ApiPlatform\Core\Annotation\ApiResource改为ApiPlatform\Metadata\ApiResource
• 操作定义方式变更：2.x的collectionOperations/itemOperations数组结构，需替换为3.x的具体操作类实例（如Get/Post/GetCollection等）
• 部分注解被移除或重命名：如ApiFilter替换为Filter，ApiProperty的参数也有调整

示例对比：
2.x写法：

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(
 *     collectionOperations={"get", "post"},
 *     itemOperations={"get", "put", "delete"}
 * )
 */
class Product {}

3.x正确写法：

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Delete;

#[ApiResource(
    operations: [
        new Get(),
        new GetCollection(),
        new Post(),
        new Put(),
        new Delete()
    ]
)]
class Product {}

若仅替换了命名空间但操作格式未修正，元数据无法被解析，实体不会被注册。

（3）实体自动发现配置错误 #

检查config/packages/api_platform.yaml中的映射配置，确保实体所在目录被正确包含：

api_platform:
    mapping:
        paths: ['%kernel.project_dir%/src/Entity']

若路径配置错误或实体不在指定目录，API Platform无法扫描到对应实体。

（4）残留旧注解导致解析失败 #

若实体中仍存在2.x版本的废弃注解（如旧的ApiFilter、ApiSubresource等），会导致元数据解析失败，实体无法被注册。需逐一清理并替换为3.x的对应注解。

3. 快速排查工具 #

运行以下命令查看已注册的API资源，对比未暴露的实体进行针对性排查：

php bin/console debug:api-resources

内容的提问来源于stack exchange，提问作者MaxPtdr