安装composer req api仅引入依赖，未自动挂载API Platform主路由；需在config/routes.yaml中显式添加api_platform: resource: '@ApiPlatformBundle/Resources/config/routing.yaml'，否则/api路由不生效。
用 composer req api 安装后为什么没生成 /api 路由？
不是所有 Symfony 项目默认启用 API Platform 的路由入口。安装 api 包只是引入依赖，但 api_platform 的主路由需显式挂载。
检查 config/routes.yaml 是否包含以下配置（无缩进、无注释）：
api_platform:
resource: '@ApiPlatformBundle/Resources/config/routing.yaml'
若缺失，手动添加；若存在但被注释或缩进错误，会导致路由未加载。运行 php bin/console debug:router | grep api 可验证是否生效——没有输出即未注册。
常见干扰项：
-
symfony/skeleton项目默认不带 Web 栈，public/index.php若未正确加载Kernel，/api会 404（尤其在 PHP 内置服务器下） - 使用
php -S启动时，必须确保-t public指向正确文档根，且public/index.php存在并已启用ApiPlatformBundle
make:entity --api-resource 生成的实体为什么没暴露为 API？
API Platform 默认只暴露加了 @ApiResource 注解的类。即使用了 --api-resource 参数，生成器也只在实体顶部写注解，不保证其启用状态。
打开生成的 src/Entity/User.php，确认顶部有类似这样的声明：
#[ApiResource]
如果只有 #[ORM\Entity] 而没有 #[ApiResource]，手动补上；如果已有但加了 output=false 或 enabled=false，删掉这些禁用参数。
注意字段级控制：
-
#[Groups(['read', 'write'])]必须与序列化上下文匹配，否则字段不出现在 JSON 中 - Doctrine 关系字段（如
$posts）默认不自动序列化，需显式加#[Groups]或配置normalizationContext - 未映射的属性（如计算字段）不会自动出现在 API 响应里，需加
#[SerializedName]或自定义序列化器
访问 /api 返回空白页或 404，但 /api/users 能返回数据
这是 Swagger UI（即 API 文档首页）未正确加载的典型表现。API Platform 的 /api 是重定向入口，实际文档页面是 /api/docs 或 /api/swagger.json。
检查几点：
- 是否安装了
nelmio/cors-bundle？开发环境下 CORS 配置缺失可能导致 Swagger JS 请求失败，表现为白屏但网络面板显示 200 -
config/packages/api_platform.yaml中是否禁用了swagger或graphiql？默认应为enable_swagger: true - 浏览器控制台是否有
Failed to load resource: the server responded with a status of 404 (Not Found)指向/api/docs.json？说明 Swagger 静态资源未发布
临时修复：直接访问 http://localhost:8000/api/docs —— 如果能打开，说明只是入口重定向失效，可忽略；若仍 404，运行 php bin/console cache:clear 并重启服务。
为什么 POST 数据校验失败却没返回具体错误字段？
API Platform 默认将验证错误转成 400 Bad Request，但响应体结构取决于你是否启用了 error_formats 配置和是否用了标准异常处理流程。
确保 config/packages/api_platform.yaml 中有：
error_formats:
'application/json': ['json']
更关键的是：校验失败时，API Platform 会抛出 ValidationException，它依赖 symfony/error-handler 渲染为结构化 JSON。若你禁用了该组件或覆盖了异常处理器，就会退化为裸 HTML 或空响应。
快速验证方式：
- 发一个必填字段为空的 POST 请求，看响应头是否含
Content-Type: application/json - 若响应是 HTML 页面，说明
error_handler未启用或被拦截；运行composer require symfony/error-handler并确认config/bundles.php中ErrorHandlerBundle已启用 - DTO 验证需配合
#[MapRequestPayload]（Symfony 6.2+）或手动注入ValidatorInterface，仅靠@Assert注解不触发自动绑定
真正容易被忽略的点是：API Platform 的验证行为高度耦合于请求内容类型。用 application/json 提交才走标准校验流；若误用 application/x-www-form-urlencoded，即使字段名对得上，验证也可能静默跳过。
