PHP搭建PSR-15中间件应用教程

本文深入解析了使用Mezzio（基于PSR-15）搭建PHP中间件应用时最常见、最易踩坑的五大核心问题：从环境初始化失败（如“Class Mezzio\Application not found”）的根源排查与修复，到中间件注册机制中`pipe()`与`pipeRoutingMiddleware()`的本质区别；从FastRoute路由变量匹配失效的约束配置误区，到路由参数无法通过`getAttribute('id')`直接获取的底层原理；最后揭示PSR-15线性链与Mezzio多阶段路由生命周期之间的关键耦合逻辑——每一步错位都可能导致请求中断或数据丢失，而精准调试的关键在于确认`RouteResult`是否存在，而非盲目猜测attribute键名。

Mezzio 项目初始化后为什么 public/index.php 报错 “Class Mezzio\Application not found”

这是 Composer 自动加载没生效的典型表现，不是 Mezzio 本身有问题。新项目跑不起来，90% 是因为没执行安装步骤或 autoloader 没重建。

• 确认已运行 composer install（不是 composer update），且无报错
• 检查 vendor/autoload.php 是否真实存在；如果被 .gitignore 忽略又没重新装，就会找不到类
• 删掉整个 vendor/ 和 composer.lock，再跑一遍 composer install --no-dev（尤其在 CI 或 Docker 环境里）
• 别手动改 public/index.php 的 require 路径——它依赖 Composer 生成的 autoload 机制，硬编码路径只会让问题更隐蔽

注册 PSR-15 中间件时，$app->pipe() 和 $app->pipeRoutingMiddleware() 有什么区别

这两个不是“可互换的写法”，而是职责完全不同：一个挂载通用中间件，一个只负责路由解析前的预处理。

• $app->pipe()：所有请求都会经过，比如日志、CORS、body 解析。它在路由匹配之前和之后都执行（取决于你放的位置）
• $app->pipeRoutingMiddleware()：仅用于把路由信息注入到请求中（比如 RouteResult），必须放在 pipeRoutingMiddleware() 之后才能用 $request->getAttribute('route')
• 常见错误：把鉴权中间件写成 pipeRoutingMiddleware() ——它不会自动获得路由参数，也拦不住未匹配路由
• 正确顺序通常是：pipe()（body 解析）→ pipeRoutingMiddleware() → pipeDispatchMiddleware() → pipe()（鉴权/日志等）

用 Mezzio\Router\FastRouteRouter 时，为什么带变量的路由（如 /user/{id}）总 404

FastRoute 默认不开启占位符解析，需要显式配置参数约束，否则它把 {id} 当字面量字符串匹配。

• 定义路由时不能只写 $router->addRoute('GET', '/user/{id}', ...)，得加上约束：$router->addRoute('GET', '/user/{id:\d+}', ...)
• 如果要用非数字 ID（比如 UUID），约束得写成 {id:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}}
• 别指望 Mezzio\Router\RouteCollector 的快捷方法（如 get()）自动帮你加约束——它们只是语法糖，底层还是靠 FastRoute 的 pattern
• 调试技巧：在中间件里 dump $request->getUri()->getPath() 和 $request->getAttribute('route')，看是否为空

在中间件里获取路由参数，为什么 $request->getAttribute('id') 返回 null

Mezzio 不会自动把路由占位符映射为 request attribute，得靠 Mezzio\Router\Middleware\DispatchMiddleware 或手动提取。

• 确保已调用 $app->pipeDispatchMiddleware()（通常在 pipeRoutingMiddleware() 之后）
• 参数默认存放在 RouteResult 对象里，要这样取：$routeResult = $request->getAttribute(RouteResult::class); $id = $routeResult?->getMatchedParams()['id'] ?? null;
• 别直接用 $request->getAttribute('id')——除非你自己写了中间件把它 set 进去，否则这个 key 不存在
• 如果用了 Mezzio\Handler\NotFoundHandler，注意它可能在 dispatch 前就返回了 404，导致你的参数提取逻辑根本没机会执行

PSR-15 的中间件链是线性的，但 Mezzio 的路由生命周期有明确阶段划分。漏掉一个 pipe* 调用，或者把中间件挂错位置，参数就断在半路。调试时优先看 RouteResult 是否存在，而不是猜 attribute 名。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~