symfony 8.2可以用mapquerystring的key选项,将某一个查询参数内的json映射为dto,同时保留原有验证规则。适用于已经安装frameworkbundle、serializer和validator的8.2测试应用;本文以8.2.0-beta2源码为依据,php要求至少8.4.1。它不是把整个请求体改成json,也不会在未设置key时自动解析所有查询值。
先定义筛选对象
示例将term设为必填,category可省略。将文件放入应用的常规src目录,并保持App命名空间自动加载配置有效:
<?php // src/Dto/SearchDto.php
namespace App\Dto;
use Symfony\Component\Validator\Constraints as Assert;
final readonly class SearchDto
{
public function __construct(
#[Assert\NotBlank] public string $term = '',
public string $category = '',
) {}
}
让控制器读取search参数
控制器映射search这一项,而不是整个查询字符串。示例显式将约束验证失败设置为422,避免与MapQueryString默认的404混淆:
<?php // src/Controller/ProductSearchController.php
namespace App\Controller;
use App\Dto\SearchDto;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\Routing\Attribute\Route;
final class ProductSearchController extends AbstractController
{
#[Route('/products', name: 'product_search', methods: ['GET'], format: 'json')]
public function __invoke(
#[MapQueryString(key: 'search', validationFailedStatusCode: Response::HTTP_UNPROCESSABLE_ENTITY)]
SearchDto $search,
): JsonResponse {
return $this->json(['term' => $search->term, 'category' => $search->category]);
}
}

官方公告展示数组式和JSON式查询映射到同一对象。
发送前由客户端做URL编码
在本地测试应用使用实际监听地址。以下curl命令通过data-urlencode编码参数,避免手工拼接引号、空格和特殊字符:
curl -G 'http://127.0.0.1:8000/products' --data-urlencode 'search={"term":"keyboard","category":"accessories"}'
按上方控制器,成功请求应得到包含term与category的JSON对象。数组式参数search[term]和search[category]仍可映射到同一个DTO;业务方法无需分别实现两套筛选逻辑。
一个基于官方 Mailtrap Node.js SDK 构建的 ASE 技能,用于发送事务邮件并与 Mailtrap 沙盒或生产流程协作。它非常适合需要 API 驱动邮件投递、测试邮箱验证和结构化消息自动化的代理工作流。

官方8.2文档的浏览器翻译视图,说明默认404和自定义验证状态。
区分JSON解码与约束验证
用畸形JSON测试时,应返回400;当前文档还将传入对象未定义属性列为400情况。传入合法JSON但term为空时,NotBlank约束失败,按示例配置返回422。完整参数缺失或类型不符时,还要核对参数默认值与映射配置,不能把所有异常都归为JSON格式错误。
若请求仍提示期望array却收到string,先核对实际安装的http-kernel及相关组件是否包含8.2实现,而不是只改项目根目录的版本描述。此能力对应PR64368,已于8月合入8.2并存在于BETA2标签中;11月17日是功能介绍日期。










