自定义 Repository 是 Symfony 中实现逻辑隔离的刚性要求，需显式声明并注解实体；应优先使用类型安全的 QueryBuilder 构建查询，Repository 仅封装数据访问，业务逻辑移入 Service 层。
在 Symfony2（及后续版本）中，自定义 Repository 类不是“可选优化”，而是实现代码复用与逻辑隔离的刚性要求。它解决的核心问题是：把数据访问细节从控制器和服务中剥离，让查询可复用、可测试、可维护。
必须显式声明 Repository 类，不能依赖 auto_mapping
Doctrine 的 auto_mapping: true 会为每个实体生成默认仓库，但仅提供 find()、findAll() 等基础方法。它不注入 EntityManager，也不支持自定义 DQL 或 QueryBuilder —— 这意味着你写不了带条件、JOIN、分页或聚合的查询。
- 用命令生成标准骨架：
php bin/console make:repository ProductRepository - 该命令自动完成三件事：创建
src/Repository/ProductRepository.php、注入EntityManagerInterface、在实体类上添加@ORM\Repository("App\Repository\ProductRepository")注解（或 PHP 属性语法） - 若漏掉实体上的注解，
$em->getRepository(Product::class)返回的是 Doctrine 默认仓库，你的自定义方法根本不会被调用
自定义查询优先用 QueryBuilder，不用拼接 DQL 字符串
QueryBuilder 是类型安全、可组合、易调试的首选。字段名写错（如 p.prce）会在编译阶段报错；而 DQL 字符串错误要到运行时才暴露，排查成本高。
- 动态条件应链式构建，参数绑定需紧随对应条件之后：
$qb->where('p.status = :status')->setParameter('status', Product::STATUS_ACTIVE) - 避免在循环中重复
setParameter('id', $id)—— 后值会覆盖前值；批量 IN 查询应使用数组参数：setParameter('ids', [1,2,3], Connection::PARAM_INT_ARRAY) - 原生 DQL 仅用于跨库、MySQL JSON 函数、或性能压测确认瓶颈的场景，且必须用
setParameters()防注入，禁止字符串拼接
Repository 只管“怎么查”，不管“为什么查”
Repository 是数据访问层，职责是封装 SQL 构建与执行。所有业务判断、状态流转、跨实体协调都应移入 Service 层。
- 控制器里不出现
$repo->findActiveByPriceRange(...)—— 应由ProductSearchService封装该调用并补充缓存、权限、日志等逻辑 - Repository 类不应直接依赖
EntityManager（比如通过$this->getEntityManager()），否则单元测试难以 mock；正确做法是构造函数注入EntityManagerInterface，并在测试中用内存 SQLite + SchemaTool 搭建轻量环境 - 复杂查询逻辑（如多表 JOIN + 分组统计）也应抽到 Service，Repository 只暴露原子级查询方法，例如
findByStatusAndCategory()、countByTag()
接口先行，为替换和测试留余地
定义 ProductRepositoryInterface，让具体实现类实现它。这样未来可轻松切换为 ElasticSearch 实现、Mock 实现或读写分离代理。
- 接口只声明契约方法，不暴露 Doctrine 内部类型（如
QueryBuilder），返回类型用array|Collection更通用 - 服务类依赖接口而非具体类：
public function __construct(private ProductRepositoryInterface $productRepo) - 容器配置中用
bind或autowire绑定实现，替换时只需改配置，不碰业务代码
