使用 Symfony 5.4.54 搭建 API 应用应聚焦稳结构、清边界、防踩坑：通过 composer create-project symfony/website-skeleton myapi "5.4.54" 初始化，composer require api 安装 API Platform，移除 Twig 等冗余组件，用 @ApiResource 声明资源，DTO 处理非数据库字段，Path::join() 安全拼接路径，cache.app 管理缓存，并用 ApiTestCase 覆盖核心流程。
用 Symfony 5.4.54 搭建一个可用的 API 应用，核心不是堆功能，而是稳结构、清边界、防踩坑。版本 5.4.54 是 5.4 系列的最终稳定补丁版，兼容性好，适合生产级 API 项目。下面按真实开发节奏分步说明，不跳步、不假设前置环境。
初始化项目与基础配置
别用过时的 installer（已弃用），改用 Composer 官方推荐方式：
- 运行
composer create-project symfony/website-skeleton myapi "5.4.54"—— 这会拉取带 Web 服务器和基础 Bundle 的完整骨架，比symfony/skeleton更适合 API 开发（自带 Twig、Doctrine、Security 等可选组件） - 进入目录后执行
composer require api安装 API Platform Core（它专为 Symfony 5.4 优化，自动注册路由、序列化、数据提供器） - 删掉不需要的 Web 组件：在
config/packages/twig.yaml中注释或删除整个文件；移除templates/目录；确保APP_ENV=prod时不会加载 TwigBundle - 确认
config/packages/framework.yaml中启用了serializer和validator，API 响应和校验依赖它们
定义资源与数据模型
API Platform 以“资源（Resource）”为中心，推荐直接用 PHP 类 + 注解声明：
- 在
src/Entity/下创建Product.php，加上@ApiResource注解，并设置collectionOperations和itemOperations显式控制端点 - 字段验证写在实体上：
@Assert\NotBlank、@Assert\Positive等，校验逻辑随数据模型走，不散落在控制器里 - 如需自定义响应格式（比如加
_links或分页元信息），在@ApiResource中配normalizationContext，例如："groups"={"product:read"} - 运行
php bin/console doctrine:database:create和php bin/console doctrine:schema:update --force初始化数据库表
处理非数据库字段与表单验证
API 常有不落库但需校验的字段，比如 confirmPassword 或 acceptTerms：
- 不要在实体里加这些属性——会污染数据模型。改用独立的 DTO 类（如
src/Dto/RegisterInput.php） - DTO 类不继承任何东西，只加
@Assert注解；在 Controller 或自定义 Data Provider 中用$this->serializer->deserialize()转成对象 - 若用表单类（
AbstractType），对非映射字段设'mapped' => false，并通过'constraints'传入验证器，例如：new Assert\IsTrue()验证勾选条款 - 控制器中统一用
$form->handleRequest($request)->isValid()触发全部校验，失败时$form->getErrors(true)可提取结构化错误数组供 JSON 返回
安全路径拼接与缓存管理
API 常涉及文件上传路径拼接、临时缓存键生成，必须防越界和冲突：
- 拼接路径一律用
Symfony\Component\Filesystem\Path::join()，例如：Path::join($this->getParameter('kernel.project_dir'), 'var', 'uploads', $userId, $filename)—— 自动处理..、.、斜杠归一化 - 拼完后做白名单校验：检查结果是否仍以你允许的根目录开头（如
/var/www/myapi/var/uploads），否则抛AccessDeniedHttpException - 缓存用
cache.app池（默认基于 FilesystemAdapter），清理时用php bin/console cache:pool:clear cache.app --env=prod，别用旧的cache:clear（它只清编译缓存，不影响运行时数据） - 敏感操作（如令牌刷新、密码重置）建议搭配
cache.system或 Redis，避免文件锁争用
不复杂但容易忽略：每一步都该有对应测试（至少单元+功能测试），API Platform 自带的 ApiTestCase 可快速断言状态码和 JSON 结构。搭建完成后的最小可用 API，应能通过 curl -H "Accept: application/json" http://localhost:8000/api/products 返回标准 HAL+JSON 响应。
