controller是面向业务的路由入口，httprequesthandler是框架内部请求分发环节，二者非替代关系；前者适用于95%接口开发，后者仅用于深度定制分发流程等极少数场景。
Hyperf里控制器和RequestHandler本质不是二选一
控制器（Controller）是面向业务逻辑的入口，而HttpRequestHandler是框架内部请求分发链路中的一环——它不替代控制器，而是承载控制器执行前后的中间件调度与生命周期控制。你不会“选一个不用另一个”，而是得理解它们在洋葱模型里的位置。
常见误解是把HttpRequestHandler当成控制器的低层替代品，试图绕过@GetMapping等注解直接写 handler 处理请求。这会导致路由丢失、中间件不生效、依赖注入失效，且无法享受Hyperf的AOP、验证、参数绑定等能力。
-
Controller：用注解声明路由，自动绑定参数、校验、转换响应；适合95%的HTTP接口开发 -
HttpRequestHandler：仅在需要深度定制分发流程时使用，比如实现统一灰度路由拦截、动态加载控制器类、或嵌入非标准协议解析逻辑 - 框架启动后，每个请求最终都会进入
HttpRequestHandler->handle()，但它内部仍会调用你写的Controller方法
什么时候真要动HttpRequestHandler
除非你正在做框架层扩展，否则不需要直接实现或替换HttpRequestHandler。真实可落地的场景极有限：
- 需要在所有控制器执行前插入一次「全链路预检」，且该逻辑不能用中间件完成（比如必须修改
$request的底层rawContent并重算签名） - 对接遗留系统，请求体不是标准HTTP格式（如自定义二进制头+JSON payload），需在分发前做协议透传解析
- 构建网关型服务，需根据域名/路径前缀动态切换整个
Controller命名空间，而非靠路由注解匹配
注意：HttpRequestHandler本身没有生命周期钩子，也不参与DI容器管理。若在里面手动new Controller()，将丢失依赖注入、AOP代理、上下文隔离等关键特性。
Controller写法错误导致你以为要换Handler
很多开发者想“换Handler”，实际只是Controller没写对，或误用了中间件机制：
- 在
Controller方法里用Co::sleep()或协程IO却没开启hook（如SWOOLE_HOOK_ALL），结果阻塞整个进程 → 应检查php --ri swoole输出是否coroutine => enabled - 想给某个接口加特殊日志/权限，却在
Controller里硬编码逻辑 → 正确做法是写专用中间件，用use ($handler)确保调用链完整 - 需要返回非JSON响应（如流式下载、SSE），但直接
echo或fopen→ 应返回StreamResponse或SseResponse实例，由框架接管输出
Hyperf的Controller完全支持协程IO、连接池、上下文传递，只要别在方法里混用同步函数（如file_get_contents未被hook）或全局变量，就无需逃向HttpRequestHandler。
自定义Handler的隐性成本你可能没算清
一旦决定实现自己的HttpRequestHandler，以下问题立刻浮现：
- 不再兼容
@Middleware注解：你得手动构造中间件数组并维护offset计数，$this->next()调用极易出错 - 丢失异常自动捕获：框架默认的
ExceptionHandler只监听Controller抛出的异常，自定义handler内抛错会直接崩掉协程 - 测试困难：单元测试需模拟完整
HttpRequestHandler调用链，而Controller可直接实例化+注入依赖 - 升级风险：Hyperf 3.2.3起
HttpRequestHandler内部结构微调过多次，自定义实现容易随小版本更新失效
真正需要它的项目，往往已脱离“用Hyperf写业务”的阶段，进入“基于Hyperf造轮子”的范畴。多数人卡住的地方，其实是没吃透Controller的协程安全写法和中间件组合能力。
