注解方式是symfony 8推荐默认路由方案，性能好、ide支持强、重构安全，但需手动清缓存；yaml方式集中配置、适合多语言/权限隔离，但易因缩进错误失效且不支持自动类型转换。
注解方式：代码里写路由，改起来快但容易漏清缓存
注解（PHP Attributes）是 Symfony 8 推荐的默认方式，把 #[Route(...)] 直接写在控制器方法上，开发时一眼看到“这个 URL 对应哪个方法”。它不是运行时解析，而是编译时静态分析生成路由表，所以性能好、IDE 支持强、重构安全。
但要注意：改了注解不等于路由立刻生效。你得手动清缓存，否则旧路由还在用——尤其在开发环境反复增删路由时，php bin/console cache:clear 是必跑命令。如果忘了，就会出现“明明写了新路由，却 404”或“旧路由还响应”的现象。
常见错误场景：
- 升级到 Symfony 8 后仍用旧式
@Route注解（带@符号），会报错：找不到类Sensio\Bundle\FrameworkExtraBundle\Configuration\Route - 没装
sensio/framework-extra-bundle（Symfony 6.2+ 已弃用），或没启用注解加载器（framework.extra_framework.enabled: true） - 控制器类没继承
AbstractController，导致#[Route]不被识别（虽非强制，但推荐）
示例（正确写法）：
#[Route('/blog/{slug}', name: 'app_blog_show', methods: ['GET'], requirements: ['slug' => '[a-z0-9\-]+'])]
public function show(string $slug): Response
{
// ...
}
YAML 方式：集中配置，适合多语言/权限隔离或非开发人员参与
YAML 路由定义在 config/routes.yaml 或按 Bundle 拆分的文件里，结构清晰、易批量修改、支持注释说明，特别适合需要统一管控的场景，比如：
- 给不同角色暴露不同前缀路径（如
admin/和api/v1/分开维护） - 国际化项目中为
en/blog和zh/blog分别配路径（配合host或locale条件） - 运维或产品需临时开关某组路由，直接注释 YAML 行比改 PHP 更安全
但 YAML 的缺点也很实在：路由和逻辑分离，跳转不直观；写错缩进或冒号就整个文件加载失败，报错信息常指向 YamlFileLoader.php 第 X 行，不好定位；而且它不支持参数自动类型转换（比如 User $id 这种 ParamConverter 依赖注解上下文）。
典型配置片段：
app_blog:
resource: '../src/Controller/BlogController.php'
type: annotation
prefix: /blog
admin_routes:
resource: '../config/routes/admin.yaml'
prefix: /admin
什么时候该选哪种？看团队分工和部署流程
如果你的项目是小团队快速迭代，控制器职责单一、URL 结构稳定，注解就是首选——改一个方法，顺手把路由也调好，不用切文件、不用对齐缩进。
但如果你有：
- 多个前端团队共用后端 API，靠路径前缀区分版本或租户（如
/v2/users,/tenant-a/orders）→ YAML 更易做全局 prefix 和条件路由 - CI/CD 流程中需灰度发布某批路由（比如只让内网 IP 访问
/debug/*）→ YAML 可结合condition字段写表达式，注解里写太长影响可读 - 安全审计要求所有入口路径必须显式声明、不可隐式推导 → YAML 文件可纳入 Git 审计，而注解散落在各处难收敛
注意：type: annotation 并不是 YAML 在“定义路由”，而是告诉 Symfony：“去扫描这个 PHP 文件里的 #[Route]”，本质还是注解驱动。真要纯 YAML 定义，得写成：
app_blog_index:
path: /blog
controller: App\Controller\BlogController::index
methods: [GET]
混合用没问题，但得守住边界
实际项目里，90% 的业务路由用注解，管理后台或 API 网关层用 YAML 是合理组合。关键是要避免“同一组功能既在 YAML 里配了，又在控制器里加了 #[Route]”，造成重复注册或匹配冲突。
检查是否重复的最快办法：
- 运行
php bin/console debug:router，看同名 route 是否出现两次 - 访问
http://localhost:8000/_profiler，点 Router 面板，看每条 route 的 “Resource” 列来源是annotation还是yaml
最容易被忽略的一点：YAML 中的 resource 路径是相对于项目根目录的，不是相对于 config/；而注解扫描范围由 kernel.bundles 和 routing 配置共同决定——路径写错一个点，整块路由就静默失效，连 warning 都不报。
