06.5.5.4 路由与中间件
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.5 Hyperf
06.5.5.4-001 Hyperf 路由有哪两种定义方式?
一句话结论
路由可通过控制器方法上的路由注解定义,也可在路由配置文件中以闭包/控制器引用方式定义;注解适合按控制器组织,配置文件适合集中声明与分组管理。
概念解释
注解路由在扫描期被收集进路由表;配置路由在启动加载注册。两种方式可共存,同一方法优先按实际注册结果匹配,重复定义的覆盖顺序需结合版本机制确认。
原理流程
- 启动期扫描控制器注解,生成路由元数据。
- 读取路由配置文件,追加闭包与控制器路由。
- 路由表按 Server 名分组保存。
- 请求到达后按方法与路径匹配对应处理器。
代码或图示
// 配置文件路由示例(文件位置与写法以版本骨架为准,待确认)
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;自动控制器省注解,方法名即路由,适合内部快速原型。生产对外接口建议使用显式控制器。
原理流程
#[Controller]标注类前缀,方法上再标#[GetMapping]等。#[AutoController]扫描公共方法,按方法名生成默认路由。- 两类路由都进入对应 Server 路由表。
- 请求匹配后调用控制器方法。
代码或图示
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 指定动词集合;其余注解对应单一动词。路径可包含占位参数与正则约束。
原理流程
- 扫描期读取方法注解的动词、路径、中间件属性。
- 注册到路由表对应动词下。
- 请求按动词与路径匹配。
- 命中后解析路径参数并调用方法。
代码或图示
#[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 或参数错误流程。
原理流程
- 路由模板定义占位符
{id}与可选正则。 - 请求路径匹配后提取占位值。
- 按方法参数名与类型绑定。
- 控制器方法拿到类型化参数。
代码或图示
#[GetMapping(path: 'user/{id:\d+}')]
public function info(int $id): array
{
return ['id' => $id];
}
常见误区
- 参数名写成
$userId而路径是{id}:绑定不到,参数为默认值或报错。 - 在控制器里重复从请求对象取路径参数:应直接用方法参数,保持签名明确。
追问
- 路径参数缺失默认值怎么处理?答:方法参数给默认值;必填参数缺失时按框架错误流程处理(待确认:具体状态码)。
- 多个同类参数如何区分?答:占位符分别命名,方法参数一一对应,不要依赖位置顺序。
06.5.5.4-005 路由分组与前缀如何组织?
一句话结论
通过控制器 prefix 与路由配置分组两个维度组织路径:控制器前缀统一模块路径,配置分组按版本/模块挂载中间件与子路由;分层前缀拼接成完整路径。
概念解释
分组便于统一管理版本号、模块名与组级中间件。层级通常为:全局前缀 → 分组前缀 → 控制器前缀 → 方法路径。命名保持一致可避免路径拼接混乱。
原理流程
- 配置文件按模块创建路由分组。
- 分组内挂载组级中间件与子路由。
- 控制器
prefix叠加在分组路径后。 - 方法
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 的表内匹配。
原理流程
- 注解/配置标注
server名(或使用默认值)。 - 启动期路由按 Server 名分组保存。
- 请求进入某 Server 回调,只在该 Server 路由表匹配。
- 中间件按同名 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 注入、基础校验。注册顺序即洋葱外层到内层的顺序,前置逻辑先执行数组靠前的。
原理流程
- 在
middlewares.php对应 Server 键下填中间件类数组。 - 启动期注册到该 Server 中间件栈。
- 每个请求先经过全局中间件,再进入路由匹配。
- 响应沿栈逆向返回。
代码或图示
// config/autoload/middlewares.php
return [
'http' => [
\App\Middleware\RequestLogMiddleware::class,
\App\Middleware\CorsMiddleware::class,
],
];
常见误区
- 中间件类未被容器解析:注册类名需可由容器创建,否则执行时报解析错误。
- 把重业务校验放全局中间件:所有请求都承担该开销,应下沉到必要路由。
追问
- 全局中间件能按条件跳过吗?答:中间件内部可按路径/方法判断短路或放行;更细粒度应使用路由级中间件。
- 中间件顺序错了有什么表现?答:后置日志拿不到鉴权结果,CORS 头被后续响应覆盖等,需按链路重排。
06.5.5.4-008 路由与方法级中间件如何挂载?
一句话结论
在控制器或方法上使用 #[Middleware]/#[Middlewares] 注解挂载路由级中间件,仅对对应控制器或方法生效;与全局中间件叠加执行。
概念解释
路由级中间件用于单接口定制职责:某接口的鉴权方式、参数加解密、频控。注解属性指定中间件类,多个中间件用 #[Middlewares] 包裹数组。
原理流程
- 方法/控制器标注中间件注解。
- 扫描期把中间件绑定到对应路由元数据。
- 请求匹配路由后,全局中间件先执行,再执行路由中间件。
- 响应逆向经过两组中间件。
代码或图示
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) 之前的代码,再执行之后的代码。顺序决定谁先看到请求、谁最后包装响应。
原理流程
- 全局中间件 A 前置 → 全局中间件 B 前置 → 路由中间件 C 前置。
handle进入控制器执行。- 响应返回:C 后置 → B 后置 → A 后置。
- 任一层抛出异常,沿外层反向传递到异常处理器。
代码或图示
// 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 原生对象,保持框架抽象层兼容。
原理流程
- 类实现中间件接口并写
process()方法。 - 前置逻辑读取/校验请求。
- 调用
$handler->handle($request)获取内层响应。 - 后置逻辑加工响应并返回。
代码或图示
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() 直接返回响应对象即短路;也可在内层响应基础上追加头、改状态码或包装响应体,返回加工后的响应。
概念解释
短路用于鉴权失败、频控拦截等场景:不再进入控制器。响应改写用于统一包装、追加跨域头、压缩等后置处理。短路与改写都必须返回合法响应对象。
原理流程
- 前置校验不通过:构造错误响应,直接
return。 - 校验通过:调用
handle()取得内层响应。 - 后置对响应对象追加头/状态/body。
- 返回最终响应进入外层中间件。
代码或图示
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。
原理流程
- 请求经过中间件与控制器,未捕获异常向上抛出。
- 框架按 Server 查找注册的异常处理器列表。
- 处理器
isValid()判断是否处理该异常,handle()构造响应。 - 无匹配处理器时走默认错误响应。
代码或图示
// 异常处理器接口形态(方法签名以版本为准,待确认)
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 场景,状态码行为以框架实现为准。
原理流程
- 请求进入 Server 回调,按动词与路径查路由表。
- 未命中:触发未匹配流程。
- 默认生成 404 响应,或交给自定义处理器。
- 命中但参数校验失败走参数错误流程。
代码或图示
// 未匹配处理的定制入口需按版本文档确认(待确认:默认回调与配置项)
// 常见做法:在异常处理器中匹配路由缺失类异常,返回统一 JSON 结构
常见误区
- 把 404 当成控制器内判断:多数未匹配在进入控制器前已确定。
- 路径末尾斜杠差异导致 404:路由规则是否归一化尾部斜杠需确认(待确认)。
追问
- 405 如何返回?答:框架对动词不匹配的处理行为需核对版本;如需严格 405 与 Allow 头,可在中间件或处理器补充。
- 怎么调试路由没命中?答:核对完整路径拼接、动词、Server 归属,打印/查看注册路由表逐项比对。
06.5.5.4-014 生产环境是否需要路由缓存?
一句话结论
Hyperf 常驻模式在启动期一次性扫描注册路由,不像 FPM 框架每请求重建路由;启动缓存与代理缓存可加快二次启动,是否提供独立“路由缓存”命令以版本为准。
概念解释
路由表在启动后常驻内存,请求匹配无重复解析成本。生产关注的是启动期扫描耗时与缓存复用,而非请求期路由缓存机制。
原理流程
- 启动期扫描注解与配置,构建路由表常驻内存。
- 命中扫描/代理缓存时跳过重复生成。
- 请求直接查内存路由表。
- 发布新版本时重启进程重建路由表。
代码或图示
// # 启动即注册全部路由;具体缓存命令以框架提供为准(待确认)
// php bin/hyperf.php start
常见误区
- 照搬 FPM 框架的
route:cache经验:常驻模型没有请求期路由重建,机制不同。 - 改路由后不重启:旧路由表仍在内存,新路径访问不到。
追问
- 路由表占内存吗?答:大型项目路由条目多时占用一定内存,但相对进程总体通常有限;条目数量可在启动调试时统计。
- 动态路由(数据库定义)怎么实现?答:通过启动监听器或自定义路由注册源加载;常驻后不随请求变化,需刷新机制配合。
06.5.5.4-015 请求参数从哪里获取?
一句话结论
通过注入的 RequestInterface 获取 query、body、路径参数、头与全部输入;方法参数绑定只负责路径段,其余输入从请求对象读取。
概念解释
请求对象是单例代理,内部数据从协程上下文取,保证协程隔离。参数读取方法覆盖查询串、JSON body、表单与头部,使用时注意默认值与类型转换。
原理流程
- 控制器/中间件注入请求契约接口。
- 调用
query()、input()、route()、header()等读取对应来源。 - 框架从上下文请求对象取值并按默认值返回。
- 业务层使用规范化后的参数。
代码或图示
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 参数校验放在路由链路的哪一层?
一句话结论
基础格式校验可在中间件做通用约束,业务规则校验建议在服务层或独立校验类完成;控制器负责编排,路由层不堆砌复杂校验逻辑。
概念解释
中间件适合鉴权、格式类型等通用前置校验;字段级业务规则(唯一性、状态流转)属于领域逻辑,放服务层便于复用与测试。框架是否提供表单请求类以组件为准。
原理流程
- 中间件完成通用校验:令牌、签名、内容类型。
- 控制器读取参数并调用校验器/服务。
- 校验失败抛出业务异常,由异常处理器转错误响应。
- 校验通过进入业务处理。
代码或图示
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 中间件宜放在外层。允许来源不能盲目设为 * 并携带凭证,需按安全策略配置。
原理流程
- 请求为 OPTIONS 预检:中间件直接返回 200 并追加 CORS 头。
- 正常请求:执行内层链路,响应追加跨域头。
- 错误响应同样经过外层中间件,保证 CORS 头不丢失。
- 配置按环境区分允许来源。
代码或图示
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 需对照文档确认,避免凭其他框架经验写方法。
原理流程
- 路由定义时声明名称。
- 业务需要跳转/拼接 URL 时按名称与参数生成。
- 参数替换进路径占位符。
- 生成完整路径或带域名 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 直接托管。服务端生成的报表、导出文件通过流式响应返回,避免一次性读入内存。
原理流程
- 控制器准备文件路径或数据流。
- 响应设置
Content-Disposition与类型。 - 以流式方式输出文件内容。
- 大文件分批读取,控制内存占用。
代码或图示
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 传递。中间件不要把请求态数据存成员变量,所有跨层数据走上下文键值。
原理流程
- 前置:从请求解析追踪 ID/用户标识,
Context::set写入。 - 内层控制器、服务、日志从上下文读取。
- 后置:读取上下文组装响应头或日志字段。
- 协程结束上下文自动释放。
代码或图示
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 中间件怎么办?答:消费者/任务入口手动初始化所需上下文键,不能依赖请求中间件链路。