用途:指导编写 Symfony 应用的 HTTP 层,包括控制器、路由、请求输入映射、JSON 与 HTML 响应、表单与 Twig 模板。核心主张是控制器仅作翻译层:HTTP 进、调用服务、输出表示,本身不承载业务规则。
主要能力:控制器按资源一类一文件,类级路由前缀加方法级路由名;用 requirements、methods、priority 属性约束路由;JSON 路由前缀 api_ 并与 HTML 控制器分离;输入用 #[MapRequestPayload]、#[MapQueryString]、#[MapQueryParameter]、#[MapRequestHeader]、#[MapUploadedFile]、#[MapEntity] 等属性映射为 DTO 并校验;输出用 #[Serialize] 或 #[Template] 返回数组或响应;业务异常用 #[WithHttpStatus] 自带状态码;API 错误采用 RFC 7807 Problem Details,需自备 ProblemJsonEncoder 放入 src/Serializer/ 才能正确响应 application/problem+json。表单 FormType 的 data_class 为输入 DTO,约束放在 DTO 上。
使用方式:按属性示例组织控制器与路由,输入 DTO 放 src/Dto/Input/,输出 DTO 放 src/Dto/Output/,FormType 放 src/Form/。失败状态码可调,如 API 路由设 validationFailedStatusCode: 422。
适用场景:手写少量自控端点的 JSON API,或同一资源同时提供 HTML 与 JSON 两种表示。
限制:不覆盖 API Platform;当资源多、需过滤排序分页、需 OpenAPI 契约、多格式或内容协商时应改用 API Platform,且不要在同一项目混用两种方式。核心为 Tier 级规范,未提供收费与价格信息。