DTO 用于明确分层边界，防止 Entity 泄露数据库结构、敏感字段及 N+1 隐患；应定义为 readonly 类，字段严格匹配视图需求，不继承 Entity、不实现序列化方法，命名用小驼峰，可空字段显式声明；构建器作为独立服务注入依赖，专注 Entity→DTO 转换。
控制器里直接 new Entity() 或 return $repository->find() 就是错的起点——DTO 不是用来“多写一个类”的，而是为了把“谁该知道什么”这件事划清楚。
为什么不能在控制器里直接返回 Entity
Entity 是数据访问层的产物，带 ORM 映射、生命周期回调、可能还有未加载的关联对象。一旦把它塞进 Response 或传给模板，就等于把数据库结构、持久化细节、甚至 N+1 查询隐患全暴露给了表示层。
常见错误现象包括：
- 模板里调用
$user->getPosts()触发意外查询 - JSON 响应中泄漏敏感字段（如
$user->getPasswordHash()） - 前端改个字段名，后端要改 Entity + Repository + Controller + FormType 四处
DTO 类怎么定义才不踩坑
用 readonly 类（PHP 8.2+）最省心，它天然不可变、自动构造、无 setter 污染。字段必须严格对应视图需要，不加任何业务逻辑或 getter/setter 方法。
示例（只暴露前端真正要的字段）：
readonly class UserPublicDto
{
public function __construct(
public string $email,
public string $firstname,
public string $lastname,
public ?string $avatarUrl,
) {}
}注意点：
- 不要继承 Entity，不要实现
__toString()或jsonSerialize() - 字段命名用小驼峰（
avatarUrl），别照抄数据库下划线（avatar_url） - 可空字段显式声明为
?string，避免运行时Notice: Trying to access array offset on value of type null
DTO 构建器该放在哪、怎么注入
构建逻辑属于领域行为，不是基础设施，所以它应该是一个服务，注册进容器，用构造函数注入所需依赖（比如 UserRepository 或 UrlGeneratorInterface）。
配置示例（config/services.yaml）：
services:
AppDtoBuilderUserPublicDtoBuilder:
arguments:
- '@AppRepositoryUserRepository'构建器本身不处理 HTTP 请求或响应，只做一件事：从 Entity / QueryResult → DTO。它不该有 Request 或 Response 依赖。
控制器中用法：
public function show(User $user, UserPublicDtoBuilder $builder): Response
{
return $this->render('user/show.html.twig', [
'user' => $builder->build($user),
]);
}路由参数和表单验证仍走 Symfony 原生机制
DTO 解耦的是「输出」，不是「输入」。路由参数校验依然靠 requirements 和类型约束：
#[Route('/user/{id<\d+>}', name: 'user_show')]表单绑定仍用 UserRegistrationDto 作为 data_class，配合 @NotBlank 等注解验证——但这个 DTO 是输入专用，和输出 DTO 分开定义，字段也不必一一对应。
最容易被忽略的一点：DTO 不是银弹。如果某个页面只需要 $user->getEmail()，硬写一个 UserEmailOnlyDto 反而增加维护成本。优先按使用场景聚类，而不是按实体粒度拆分。
