API Platform 必须通过 composer create-project 创建标准项目，直接 require api-platform/core 会导致配置缺失、路由404、GraphQL失效等问题；手动集成需补全Bundle注册、GraphQL依赖、api_platform.yaml和路由配置。
API Platform 不是靠 Composer “安装”出来的，而是通过 Composer 创建一个基于它的新项目；直接 composer require 到现有项目里大概率报错或功能不全。
用 create-project 初始化标准 API Platform 项目
API Platform 官方推荐的起点是完整骨架项目（含 Symfony、Doctrine、API Platform、Admin、Client 等），不是零散包。它依赖特定目录结构和预配置，跳过这步硬塞进旧项目，api_platform 配置不生效、doctrine 实体扫描失败、GraphQL 路由 404 是常态。
实操建议：
- 运行
composer create-project api-platform/api-platform my-api（别用require） - 进入
my-api/api目录才是真正的 Symfony 应用根目录（注意这个子路径） - 启动服务用
symfony server:start或php -S localhost:8000 -t public - 访问
http://localhost:8000/api看到 Swagger UI 才算跑通
composer require api-platform/core 在已有项目中会出什么问题
单独 require api-platform/core 只装了核心库，但缺三样关键东西：自动配置（ApiPlatformBundle 没注册）、路由定义（api_platform.yaml 没生成）、实体元数据驱动（@ApiResource 注解不被识别）。结果就是加了 @ApiResource 也看不到接口。
常见错误现象：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
The service "api_platform.action.documentation" has a dependency on a non-existent service "serializer"—— 缺少 Symfony Serializer 配置 - GET /api/books 返回 404 —— 路由没加载，
config/routes/api_platform.yaml不存在 - GraphQL 端点
/api/graphql根本不响应 ——graphql配置块没启用，webonyx/graphql-php也没装
想在现有 Symfony 项目里接入，必须补全的最小配置集
如果真不能新建项目，必须手动补全以下四点，缺一不可：
- 在
config/bundles.php中添加ApiPlatform\Symfony\Bundle\ApiPlatformBundle::class => ['all' => true] - 运行
composer require webonyx/graphql-php（GraphQL 必须显式装） - 创建
config/packages/api_platform.yaml，至少包含api_platform: {enable_nelmio_api_doc: true} - 确保
config/routes/api_platform.yaml存在，内容为api_platform: resource: '%kernel.project_dir%/vendor/api-platform/core/src/Bridge/Symfony/Bundle/Resources/config/routing.yaml'
注意：nelmio_api_doc 包也要 composer require nelmio/api-doc-bundle，否则 Swagger UI 加载空白。
GraphQL 接口不工作？检查 webonyx/graphql-php 版本和 graphql 配置
API Platform 的 GraphQL 支持对 webonyx/graphql-php 版本敏感。v15+ 需要 API Platform v3+，而默认 create-project 用的是 v3。如果手动 require，很容易装错版本。
验证方式：
- 看
composer show webonyx/graphql-php输出是否 ≥15.0 - 检查
config/packages/api_platform.yaml里是否有graphql: true（v3 默认开启，v2 需显式写） - 确认实体类用了
@ApiResource(graphql: true)或更细粒度配置，光有注解不够 - 访问
/api/graphql返回 HTML 页面才算 GraphQL 入口就绪；返回 404 或 JSON 错误说明路由或 bundle 没挂上
复杂点在于：GraphQL schema 生成依赖 Doctrine 实体的完整元数据，如果实体放在非标准目录（比如 src/Domain/），还得配 api_platform: mapping: paths: ['src/Domain']，否则 schema 为空。
