罗罗编程学习记录
本页内容 展开查看

06.5.5.4 路由与中间件

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.5 Hyperf

06.5.5.4-001 Hyperf 路由有哪两种定义方式?

一句话结论

路由可通过控制器方法上的路由注解定义,也可在路由配置文件中以闭包/控制器引用方式定义;注解适合按控制器组织,配置文件适合集中声明与分组管理。

概念解释

注解路由在扫描期被收集进路由表;配置路由在启动加载注册。两种方式可共存,同一方法优先按实际注册结果匹配,重复定义的覆盖顺序需结合版本机制确认。

原理流程

  1. 启动期扫描控制器注解,生成路由元数据。
  2. 读取路由配置文件,追加闭包与控制器路由。
  3. 路由表按 Server 名分组保存。
  4. 请求到达后按方法与路径匹配对应处理器。

代码或图示

// 配置文件路由示例(文件位置与写法以版本骨架为准,待确认)
Router::get('/hello', [\App\Controller\HelloController::class, 'index']);
Router::addGroup('/api', function () {
    Router::post('/login', [\App\Controller\AuthController::class, 'login']);
});

常见误区

  • 注解与配置重复定义同一路径:匹配结果不确定,应保持单一来源。
  • 把配置路由写在业务控制器内:路由声明集中在配置文件,控制器只处理请求。

追问

  • 路由配置文件路径是什么?答:常见为 config/routes.php;3.x 骨架的实际位置以安装结果为准(待确认)。
  • 两种方式如何选型?答:业务模块多用注解就近声明;开放平台、版本化接口适合配置文件集中分组。

06.5.5.4-002 #[Controller] 与 #[AutoController] 有什么区别?

一句话结论

#[Controller] 需要为每个方法显式标注 HTTP 方法路由注解;#[AutoController] 按方法名自动推导路由路径,减少注解但路径约定较隐式。

概念解释

显式控制器路径与方法由开发者控制,适合对外稳定 API;自动控制器省注解,方法名即路由,适合内部快速原型。生产对外接口建议使用显式控制器。

原理流程

  1. #[Controller] 标注类前缀,方法上再标 #[GetMapping] 等。
  2. #[AutoController] 扫描公共方法,按方法名生成默认路由。
  3. 两类路由都进入对应 Server 路由表。
  4. 请求匹配后调用控制器方法。

代码或图示

use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;

#[Controller(prefix: 'user')]
class UserController
{
    #[GetMapping(path: 'profile')]
    public function profile(): array
    {
        return ['name' => 'ann'];
    }
}

常见误区

  • 把自动控制器直接暴露到公网:方法名推导的路径可能暴露未预期的动作。
  • 修改 #[AutoController] 方法名导致路由变化:路径随方法名漂移,外部调用方受影响。

追问

  • 自动控制器支持限定 HTTP 方法吗?答:默认按推导规则生成;需要精确动词时应改用显式控制器注解(待确认:自动控制器的方法映射规则)。
  • 控制器前缀怎么写?答:prefix 属性指定路径前缀,与方法注解 path 拼接成完整路由。

06.5.5.4-003 常用路由方法注解有哪些?

一句话结论

常用 #[GetMapping]、#[PostMapping]、#[PutMapping]、#[PatchMapping]、#[DeleteMapping] 与通用 #[RequestMapping],分别绑定对应 HTTP 动词,path 指定路径。

概念解释

方法注解命名空间在 Hyperf\HttpServer\Annotation 下。#[RequestMapping] 可通过 methods 指定动词集合;其余注解对应单一动词。路径可包含占位参数与正则约束。

原理流程

  1. 扫描期读取方法注解的动词、路径、中间件属性。
  2. 注册到路由表对应动词下。
  3. 请求按动词与路径匹配。
  4. 命中后解析路径参数并调用方法。

代码或图示

#[PostMapping(path: 'order/create')]
public function create(): array
{
    return ['ok' => true];
}

#[RequestMapping(path: 'item/{id:\d+}', methods: ['GET', 'HEAD'])]
public function item(int $id): array
{
    return ['id' => $id];
}

常见误区

  • 路径占位名与方法参数名不一致:参数绑定失败,按版本绑定规则确认(待确认)。
  • 用 GET 执行写操作:破坏 HTTP 语义,也会被缓存与代理误处理。

追问

  • 路由正则怎么写?答:占位符内用 :正则 形式约束,如 {id:\d+};具体语法以路由组件实现为准(待确认)。
  • HEAD/OPTIONS 方法需要单独标注吗?答:按框架动词支持情况确认;常见 GET 链路可自动兼容 HEAD(待确认)。

06.5.5.4-004 路由路径参数如何绑定到控制器方法?

一句话结论

路径占位符名称与控制器方法参数名对应,框架在匹配后把路径值传入参数;可配合类型声明与正则约束完成基础校验。

概念解释

路径参数属于路由段,区别于 query 与 body 参数。类型声明标量由框架按规则转换;转换失败或不匹配正则时进入 404 或参数错误流程。

原理流程

  1. 路由模板定义占位符 {id} 与可选正则。
  2. 请求路径匹配后提取占位值。
  3. 按方法参数名与类型绑定。
  4. 控制器方法拿到类型化参数。

代码或图示

#[GetMapping(path: 'user/{id:\d+}')]
public function info(int $id): array
{
    return ['id' => $id];
}

常见误区

  • 参数名写成 $userId 而路径是 {id}:绑定不到,参数为默认值或报错。
  • 在控制器里重复从请求对象取路径参数:应直接用方法参数,保持签名明确。

追问

  • 路径参数缺失默认值怎么处理?答:方法参数给默认值;必填参数缺失时按框架错误流程处理(待确认:具体状态码)。
  • 多个同类参数如何区分?答:占位符分别命名,方法参数一一对应,不要依赖位置顺序。

06.5.5.4-005 路由分组与前缀如何组织?

一句话结论

通过控制器 prefix 与路由配置分组两个维度组织路径:控制器前缀统一模块路径,配置分组按版本/模块挂载中间件与子路由;分层前缀拼接成完整路径。

概念解释

分组便于统一管理版本号、模块名与组级中间件。层级通常为:全局前缀 → 分组前缀 → 控制器前缀 → 方法路径。命名保持一致可避免路径拼接混乱。

原理流程

  1. 配置文件按模块创建路由分组。
  2. 分组内挂载组级中间件与子路由。
  3. 控制器 prefix 叠加在分组路径后。
  4. 方法 path 形成最终完整路径。

代码或图示

Router::addGroup('/api/v1', function () {
    Router::get('/users/{id}', [\App\Controller\UserController::class, 'show']);
}, ['middleware' => [\App\Middleware\AuthMiddleware::class]]);

常见误区

  • 前缀重复拼接导致路径多段 /api/api:上线前打印路由表核对完整路径。
  • 组级中间件与控制器中间件职责重叠:区分组级通用校验与方法级定制校验。

追问

  • 如何查看全部注册路由?答:框架提供路由列表命令或调试入口;命令名以版本为准(待确认:核对 bin/hyperf.php 可用命令)。
  • 子域名路由支持吗?答:按 Server 配置与路由组件能力确认;多站点场景通常按域名分流到不同 Server 或中间件判断。

06.5.5.4-006 不同 Server 的路由如何隔离?

一句话结论

路由注解与配置可通过 server 属性指定所属 Server,HTTP、RPC、WebSocket 等不同端口服务的路由互不串扰;中间件注册也按 Server 名分组。

概念解释

同一进程内多 Server 各自维护路由表。默认路由归属默认 HTTP Server;显式指定 server 后,请求只在对应 Server 的表内匹配。

原理流程

  1. 注解/配置标注 server 名(或使用默认值)。
  2. 启动期路由按 Server 名分组保存。
  3. 请求进入某 Server 回调,只在该 Server 路由表匹配。
  4. 中间件按同名 Server 配置执行。

代码或图示

#[Controller(prefix: 'order', server: 'http')]
class OrderController
{
    #[GetMapping(path: 'list')]
    public function list(): array
    {
        return [];
    }
}

常见误区

  • RPC 服务方法误挂到 HTTP Server:外部按协议访问不到,排查时先核对 server 归属。
  • 中间件只在默认 Server 注册:指定 Server 的请求不会执行默认组中间件。

追问

  • Server 名在哪里定义?答:config/autoload/server.php 的服务节点配置中声明;注解 server 属性与之对应。
  • 一个控制器能挂多个 Server 吗?答:按版本能力确认;通常一个控制器归属一个 Server,跨服务场景拆为不同类(待确认)。

06.5.5.4-007 全局中间件在哪里注册?

一句话结论

全局中间件在 config/autoload/middlewares.php 按 Server 名注册数组,对该 Server 下所有路由生效,执行顺序按数组顺序排列。

概念解释

全局中间件承担跨切面通用职责:请求日志、CORS、追踪 ID 注入、基础校验。注册顺序即洋葱外层到内层的顺序,前置逻辑先执行数组靠前的。

原理流程

  1. 在 middlewares.php 对应 Server 键下填中间件类数组。
  2. 启动期注册到该 Server 中间件栈。
  3. 每个请求先经过全局中间件,再进入路由匹配。
  4. 响应沿栈逆向返回。

代码或图示

// config/autoload/middlewares.php
return [
    'http' => [
        \App\Middleware\RequestLogMiddleware::class,
        \App\Middleware\CorsMiddleware::class,
    ],
];

常见误区

  • 中间件类未被容器解析:注册类名需可由容器创建,否则执行时报解析错误。
  • 把重业务校验放全局中间件:所有请求都承担该开销,应下沉到必要路由。

追问

  • 全局中间件能按条件跳过吗?答:中间件内部可按路径/方法判断短路或放行;更细粒度应使用路由级中间件。
  • 中间件顺序错了有什么表现?答:后置日志拿不到鉴权结果,CORS 头被后续响应覆盖等,需按链路重排。

06.5.5.4-008 路由与方法级中间件如何挂载?

一句话结论

在控制器或方法上使用 #[Middleware]/#[Middlewares] 注解挂载路由级中间件,仅对对应控制器或方法生效;与全局中间件叠加执行。

概念解释

路由级中间件用于单接口定制职责:某接口的鉴权方式、参数加解密、频控。注解属性指定中间件类,多个中间件用 #[Middlewares] 包裹数组。

原理流程

  1. 方法/控制器标注中间件注解。
  2. 扫描期把中间件绑定到对应路由元数据。
  3. 请求匹配路由后,全局中间件先执行,再执行路由中间件。
  4. 响应逆向经过两组中间件。

代码或图示

use Hyperf\HttpServer\Annotation\Middleware;
use Hyperf\HttpServer\Annotation\Middlewares;

#[Middlewares([\App\Middleware\SignCheckMiddleware::class])]
class PayController
{
    #[Middleware(\App\Middleware\RateLimitMiddleware::class)]
    #[PostMapping(path: 'notify')]
    public function notify(): array
    {
        return ['ok' => true];
    }
}

常见误区

  • 中间件注解只标在类上以为方法继承:按注解作用域确认,类注解对类内方法生效,方法注解只对当前方法。
  • 路由中间件重复注册全局已有项:同一链路重复执行,需去重。

追问

  • 配置文件路由如何挂中间件?答:路由分组或路由定义时传中间件参数(见 005 题示例);参数键名以版本为准(待确认)。
  • 中间件能传参数吗?答:注解/配置可携带参数,中间件内读取;具体传参形式以注解定义为准(待确认)。

06.5.5.4-009 中间件的洋葱模型执行顺序是怎样的?

一句话结论

中间件按注册顺序形成嵌套管道:请求前置逻辑由外到内执行,调用处理器进入内层;响应后置逻辑由内到外返回,异常沿管道反向传递。

概念解释

每个中间件包裹下一层:先执行 $handler->handle($request) 之前的代码,再执行之后的代码。顺序决定谁先看到请求、谁最后包装响应。

原理流程

  1. 全局中间件 A 前置 → 全局中间件 B 前置 → 路由中间件 C 前置。
  2. handle 进入控制器执行。
  3. 响应返回:C 后置 → B 后置 → A 后置。
  4. 任一层抛出异常,沿外层反向传递到异常处理器。

代码或图示

// A 前置 → B 前置 → C 前置 → 控制器 → C 后置 → B 后置 → A 后置
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    $response = $handler->handle($request); // 进入内层中间件与控制器
    return $response;
}

常见误区

  • 以为后置代码在 handle() 之前写:后置逻辑必须放在 handle() 调用之后。
  • 在中间件后置阶段修改请求对象:请求已进入内层,修改不影响已执行逻辑。

追问

  • 鉴权中间件应放在哪层?答:放在靠近外层的位置,未认证请求尽早短路,不进入内层与控制器。
  • 响应头在哪个中间件加?答:后置阶段统一追加;CORS 中间件需在最外层覆盖错误响应场景。

06.5.5.4-010 中间件接口的签名是什么样的?

一句话结论

中间件实现中间件接口,process 方法接收 PSR-7 请求与请求处理器,调用 $handler->handle($request) 进入内层并返回响应对象。

概念解释

接口基于 PSR 规范抽象:请求为 ServerRequestInterface,处理器为 RequestHandlerInterface,返回 ResponseInterface。中间件不直接操作 Swoole 原生对象,保持框架抽象层兼容。

原理流程

  1. 类实现中间件接口并写 process() 方法。
  2. 前置逻辑读取/校验请求。
  3. 调用 $handler->handle($request) 获取内层响应。
  4. 后置逻辑加工响应并返回。

代码或图示

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

class AuthMiddleware implements \Hyperf\HttpServer\Contract\MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $token = $request->getHeaderLine('Authorization');
        return $handler->handle($request);
    }
}

常见误区

  • 忘记返回响应对象:管道后续中间件拿不到响应,报错。
  • 在中间件里直接输出内容:应通过响应对象返回,由框架统一发送。

追问

  • 接口命名空间在不同版本有变化吗?答:以当前版本 Hyperf\HttpServer\Contract 下接口为准;2.x/3.x 迁移时需核对(待确认)。
  • 中间件能读写协程上下文吗?答:可以,请求/响应与自定义链路数据都存 Context,中间件是上下文传递的关键环节。

06.5.5.4-011 中间件如何短路与改写响应?

一句话结论

中间件不调用 $handler->handle() 直接返回响应对象即短路;也可在内层响应基础上追加头、改状态码或包装响应体,返回加工后的响应。

概念解释

短路用于鉴权失败、频控拦截等场景:不再进入控制器。响应改写用于统一包装、追加跨域头、压缩等后置处理。短路与改写都必须返回合法响应对象。

原理流程

  1. 前置校验不通过:构造错误响应,直接 return。
  2. 校验通过:调用 handle() 取得内层响应。
  3. 后置对响应对象追加头/状态/body。
  4. 返回最终响应进入外层中间件。

代码或图示

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    if (! $this->auth->check($request)) {
        return $this->response->json(['code' => 401])->withStatus(401);
    }
    $response = $handler->handle($request);
    return $response->withHeader('X-Request-Id', (string) Context::get('request_id'));
}

常见误区

  • 短路后仍调用 handle():内层继续执行,拦截失效。
  • 改写响应时新建对象丢失原有头:应基于内层响应 with* 方法加工。

追问

  • 响应对象如何注入?答:通过 ResponseInterface 契约注入或容器获取;响应对象内部数据来自上下文(待确认具体实现)。
  • 短路响应能触发后续中间件后置吗?答:不会经过被跳过的内层,但外层中间件后置仍会执行。

06.5.5.4-012 异常处理器与中间件如何分工?

一句话结论

中间件负责请求链路的通用编排与短路,异常处理器负责接管未捕获异常并生成错误响应;中间件内抛出的异常同样进入异常处理器栈,二者按职责分层。

概念解释

异常处理器按类型匹配,统一记录日志、转换错误码与报文结构。中间件不吞异常,让异常冒泡到处理器;处理器注册在 config/autoload/exceptions.php。

原理流程

  1. 请求经过中间件与控制器,未捕获异常向上抛出。
  2. 框架按 Server 查找注册的异常处理器列表。
  3. 处理器 isValid() 判断是否处理该异常,handle() 构造响应。
  4. 无匹配处理器时走默认错误响应。

代码或图示

// 异常处理器接口形态(方法签名以版本为准,待确认)
interface ExceptionHandlerInterface
{
    public function handle(Throwable $throwable, ResponseInterface $response): ResponseInterface;
    public function isValid(Throwable $throwable): bool;
}

常见误区

  • 在每个中间件里 catch 所有异常:重复包装且日志分散,应统一交给异常处理器。
  • 处理器内再次抛出未捕获异常:导致错误响应生成失败,需兜底处理。

追问

  • 异常处理器注册顺序?答:exceptions.php 中按 Server 登记数组,匹配顺序按注册顺序;先注册的优先 isValid 命中。
  • 业务异常与系统异常如何区分?答:定义业务异常类,专门处理器映射业务错误码;未预期异常走系统错误处理器并记录完整堆栈。

06.5.5.4-013 路由匹配失败与 404 如何处理?

一句话结论

请求动词或路径未匹配到路由时进入框架的未匹配处理流程,返回 404 响应;可通过默认路由、异常处理器或自定义回调定制 404 报文。

概念解释

匹配失败发生在路由表查找阶段,尚未进入控制器。路径存在但动词不匹配属于另一类 405 场景,状态码行为以框架实现为准。

原理流程

  1. 请求进入 Server 回调,按动词与路径查路由表。
  2. 未命中:触发未匹配流程。
  3. 默认生成 404 响应,或交给自定义处理器。
  4. 命中但参数校验失败走参数错误流程。

代码或图示

// 未匹配处理的定制入口需按版本文档确认(待确认:默认回调与配置项)
// 常见做法:在异常处理器中匹配路由缺失类异常,返回统一 JSON 结构

常见误区

  • 把 404 当成控制器内判断:多数未匹配在进入控制器前已确定。
  • 路径末尾斜杠差异导致 404:路由规则是否归一化尾部斜杠需确认(待确认)。

追问

  • 405 如何返回?答:框架对动词不匹配的处理行为需核对版本;如需严格 405 与 Allow 头,可在中间件或处理器补充。
  • 怎么调试路由没命中?答:核对完整路径拼接、动词、Server 归属,打印/查看注册路由表逐项比对。

06.5.5.4-014 生产环境是否需要路由缓存?

一句话结论

Hyperf 常驻模式在启动期一次性扫描注册路由,不像 FPM 框架每请求重建路由;启动缓存与代理缓存可加快二次启动,是否提供独立“路由缓存”命令以版本为准。

概念解释

路由表在启动后常驻内存,请求匹配无重复解析成本。生产关注的是启动期扫描耗时与缓存复用,而非请求期路由缓存机制。

原理流程

  1. 启动期扫描注解与配置,构建路由表常驻内存。
  2. 命中扫描/代理缓存时跳过重复生成。
  3. 请求直接查内存路由表。
  4. 发布新版本时重启进程重建路由表。

代码或图示

// # 启动即注册全部路由;具体缓存命令以框架提供为准(待确认)
// php bin/hyperf.php start

常见误区

  • 照搬 FPM 框架的 route:cache 经验:常驻模型没有请求期路由重建,机制不同。
  • 改路由后不重启:旧路由表仍在内存,新路径访问不到。

追问

  • 路由表占内存吗?答:大型项目路由条目多时占用一定内存,但相对进程总体通常有限;条目数量可在启动调试时统计。
  • 动态路由(数据库定义)怎么实现?答:通过启动监听器或自定义路由注册源加载;常驻后不随请求变化,需刷新机制配合。

06.5.5.4-015 请求参数从哪里获取?

一句话结论

通过注入的 RequestInterface 获取 query、body、路径参数、头与全部输入;方法参数绑定只负责路径段,其余输入从请求对象读取。

概念解释

请求对象是单例代理,内部数据从协程上下文取,保证协程隔离。参数读取方法覆盖查询串、JSON body、表单与头部,使用时注意默认值与类型转换。

原理流程

  1. 控制器/中间件注入请求契约接口。
  2. 调用 query()、input()、route()、header() 等读取对应来源。
  3. 框架从上下文请求对象取值并按默认值返回。
  4. 业务层使用规范化后的参数。

代码或图示

public function search(RequestInterface $request): array
{
    $keyword = (string) $request->input('keyword', '');
    $page = (int) $request->query('page', 1);
    $token = $request->getHeaderLine('Authorization');
    return compact('keyword', 'page', 'token');
}

常见误区

  • 直接读 $_GET/$_POST:绕过框架抽象,协程化与代理场景下不可靠。
  • 不做类型转换直接使用输入:字符串参与数值比较导致类型问题。

追问

  • JSON body 怎么取?答:input() 按解析后的输入数组取值;原始 body 可通过请求对象获取(方法名以版本为准,待确认)。
  • 文件上传如何接收?答:通过请求对象的上传文件接口;具体 API 对照 HTTP 组件文档(待确认)。

06.5.5.4-016 参数校验放在路由链路的哪一层?

一句话结论

基础格式校验可在中间件做通用约束,业务规则校验建议在服务层或独立校验类完成;控制器负责编排,路由层不堆砌复杂校验逻辑。

概念解释

中间件适合鉴权、格式类型等通用前置校验;字段级业务规则(唯一性、状态流转)属于领域逻辑,放服务层便于复用与测试。框架是否提供表单请求类以组件为准。

原理流程

  1. 中间件完成通用校验:令牌、签名、内容类型。
  2. 控制器读取参数并调用校验器/服务。
  3. 校验失败抛出业务异常,由异常处理器转错误响应。
  4. 校验通过进入业务处理。

代码或图示

public function create(RequestInterface $request, OrderService $service): ResponseInterface
{
    $rules = ['goods_id' => 'required|integer', 'quantity' => 'required|integer|min:1'];
    $validated = $this->validator->validate($request->all(), $rules);
    return $this->response->json($service->create($validated));
}

常见误区

  • 校验规则散落在多个控制器:重复且不一致,应抽校验类复用。
  • 只在前端校验:服务端必须重复校验,不能依赖客户端约束。

追问

  • 框架有内置校验组件吗?答:Hyperf 生态提供校验相关组件(如 hyperf/validation 类包,待确认当前名称与版本);未引入时手写规则校验。
  • 校验异常如何返回?答:抛出自定义校验异常,异常处理器映射为 422/400 与字段错误列表。

06.5.5.4-017 跨域(CORS)如何在 Hyperf 中处理?

一句话结论

CORS 通常通过全局中间件处理:识别预检 OPTIONS 请求直接返回,为正常响应追加跨域头;也可使用生态 CORS 组件,配置允许来源、方法与头。

概念解释

跨域头必须覆盖正常响应与错误响应,因此 CORS 中间件宜放在外层。允许来源不能盲目设为 * 并携带凭证,需按安全策略配置。

原理流程

  1. 请求为 OPTIONS 预检:中间件直接返回 200 并追加 CORS 头。
  2. 正常请求:执行内层链路,响应追加跨域头。
  3. 错误响应同样经过外层中间件,保证 CORS 头不丢失。
  4. 配置按环境区分允许来源。

代码或图示

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    $response = $request->getMethod() === 'OPTIONS'
        ? $this->response->withStatus(204)
        : $handler->handle($request);
    return $response
        ->withHeader('Access-Control-Allow-Origin', (string) config('cors.allow_origin', '*'))
        ->withHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,OPTIONS');
}

常见误区

  • CORS 头只加在成功响应:预检或错误响应缺头,浏览器仍拦截。
  • 允许来源 * 同时携带凭证:浏览器规范下二者不能随意组合,需按文档配置具体来源。

追问

  • 有官方 CORS 组件吗?答:生态组件名称与配置项待确认,核对 hyperf/cors 类包是否存在;自研中间件注意覆盖预检与错误分支。
  • 凭证 cookie 跨域怎么配?答:允许来源具体化,配合 Allow-Credentials 头;具体头名与取值按浏览器规范。

06.5.5.4-018 路由命名与 URL 生成如何使用?

一句话结论

框架可对路由命名,通过名称反生成 URL;是否提供命名路由助手及方法名以当前版本为准,未提供时按控制器/路径约定拼接。

概念解释

命名路由让视图或下游调用方不硬编码路径,路由调整时只改定义。Hyperf 路由组件的命名 API 需对照文档确认,避免凭其他框架经验写方法。

原理流程

  1. 路由定义时声明名称。
  2. 业务需要跳转/拼接 URL 时按名称与参数生成。
  3. 参数替换进路径占位符。
  4. 生成完整路径或带域名 URL。

代码或图示

// 命名路由概念示例;具体 API 名以版本为准(待确认)
Router::get('/users/{id}', [UserController::class, 'show'])->name('user.show');
// $url = Router::url('user.show', ['id' => 1]);

常见误区

  • 照搬 Laravel/ThinkPHP 的 route() 助手名:Hyperf 助手函数不同,需核对实际可用函数。
  • 生成 URL 时忽略前缀分组:拼出的路径缺少模块/版本段。

追问

  • 站内跳转多吗?答:API 服务通常不需要 URL 生成;页面型服务才关注命名路由。
  • 外部回调地址怎么拼?答:结合请求 Host 或配置的站点域名组装,不要依赖客户端传参。

06.5.5.4-019 静态资源与文件下载如何响应?

一句话结论

文件下载通过响应对象附加文件流或下载头返回;静态资源通常由前置 Web 服务器处理,PHP 常驻服务只负责动态接口与文件下载接口。

概念解释

Hyperf 服务专注应用逻辑,图片、JS、CSS 等静态资源建议由 Nginx 直接托管。服务端生成的报表、导出文件通过流式响应返回,避免一次性读入内存。

原理流程

  1. 控制器准备文件路径或数据流。
  2. 响应设置 Content-Disposition 与类型。
  3. 以流式方式输出文件内容。
  4. 大文件分批读取,控制内存占用。

代码或图示

public function export(): ResponseInterface
{
    $file = BASE_PATH . '/runtime/export/orders.csv';
    return $this->response->download($file, 'orders.csv');
}

常见误区

  • 大文件 file_get_contents 读入内存:常驻进程内存被撑高,应流式输出。
  • 把静态资源请求打到 PHP 服务:增加 Worker 压力,应在 Web 层分流。

追问

  • 下载方法名以什么为准?答:响应契约提供的文件下载/流式方法名需核对当前版本(待确认)。
  • 临时文件何时清理?答:下载完成后按策略删除或加入定时清理任务,避免 runtime 堆积。

06.5.5.4-020 中间件中如何读写协程上下文?

一句话结论

中间件是上下文初始化与传递的关键位置:前置阶段写入追踪 ID、用户态等数据,供后续层读取;后置阶段从上下文补充响应信息,请求结束随协程自动回收。

概念解释

请求对象本身的数据来自上下文,自定义链路数据也通过 Context 传递。中间件不要把请求态数据存成员变量,所有跨层数据走上下文键值。

原理流程

  1. 前置:从请求解析追踪 ID/用户标识,Context::set 写入。
  2. 内层控制器、服务、日志从上下文读取。
  3. 后置:读取上下文组装响应头或日志字段。
  4. 协程结束上下文自动释放。

代码或图示

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    $requestId = (string) ($request->getHeaderLine('X-Request-Id') ?: uniqid('req-'));
    Context::set('request_id', $requestId);

    $response = $handler->handle($request);
    return $response->withHeader('X-Request-Id', $requestId);
}

常见误区

  • 中间件成员变量保存当前用户:单例中间件跨协程污染。
  • 上下文键名散落硬编码:应集中定义常量,避免拼写不一致导致读不到。

追问

  • 子协程能读到中间件写入的上下文吗?答:上下文按协程隔离,派生协程的复制规则需结合框架上下文机制确认(见上下文专题)。
  • 队列消费者没有 HTTP 中间件怎么办?答:消费者/任务入口手动初始化所需上下文键,不能依赖请求中间件链路。