Hyperf的hyperf/api-gateway不是生产级网关，仅支持显式注册的GatewayRoute路由转发，不支持通配、限流、JWT透传等能力；其GatewayRoute::add()中$path和$backend为必填，$methods与$timeout建议显式指定以避免安全与超时风险。
Hyperf 的 hyperf/api-gateway 不适合直接作为生产级网关使用，它本质是「路由层增强」而非「网关中间件」——没有请求限流、JWT 鉴权透传、服务发现集成、动态路由热加载等关键能力，强行用它替代 Kong/Nginx/Gateway API 会踩一堆隐性坑。
为什么 hyperf/api-gateway 启动后不转发请求？
它默认不接管 / 或通配路由，只处理显式注册的 GatewayRoute，且必须配合 hyperf/http-server 的监听端口和 hyperf/dispatcher 的路由分发机制。常见错误是：只配置了 routes.php 却没在 config/autoload/server.php 中启用 http server，或误以为它能像 Nginx 那样代理任意后端地址。
- 确认
config/autoload/server.php中'type' => 'http'已启用，且端口未被占用 -
routes.php中的GatewayRoute::add()必须指定完整匹配路径（如'/api/v1/users'），不支持*或正则通配 - 目标服务地址必须是可直连的 HTTP URL（如
'http://127.0.0.1:9502'），不支持https或域名（DNS 解析需自行保障） - 转发失败时日志里常出现
Connection refused，优先检查目标服务是否已启动并监听对应 IP:PORT
GatewayRoute::add() 的参数哪些不能省略？
该方法签名中只有 $path 和 $backend 是必填，但漏掉 $methods 或 $timeout 会导致行为不可控：前者默认允许所有方法（含危险的 DELETE），后者默认 5 秒超时，在高延迟链路下易触发连接中断。
以 CLI 为先的表单构建器，采用 BYOK 理念。通过JSON Schema 生成美观的 HTML 表单，使用您自己的 SMTP 服务器处理提交，存储响应...
-
$path：必须为绝对路径，开头带/，例如'/v1/orders'，不支持'v1/orders' -
$backend：必须是完整 URL（协议+host+port），例如'http://127.0.0.1:9503'，末尾不加/ -
$methods：建议显式传['GET', 'POST']，避免暴露非预期方法 -
$timeout：建议设为3.0（秒），太短导致正常慢查询失败，太长阻塞协程调度
如何让 hyperf/api-gateway 支持 JWT 透传？
它本身不解析也不校验 JWT，只做透明转发。若需鉴权，必须手动在 Middleware 中拦截请求、提取 Authorization 头、调用 hyperf/jwt 验证，并将解析后的用户 ID 注入到 ServerRequestInterface 的属性中，再通过 $request->withAttribute() 透传给后端服务。
- 在
app/Middleware/AuthMiddleware.php中验证 token，失败直接返回401 - 验证成功后调用
$request->withAttribute('user_id', $payload['uid']) - 后端服务需主动从
$request->getAttribute('user_id')获取，api-gateway不自动注入 header - 注意：JWT 签名密钥必须前后端一致，且
hyperf/jwt的alg配置要与签发方匹配（如HS256）
真正需要网关能力时，建议用 Nginx 做前置反向代理 + 路由分发，Hyperf 服务专注业务逻辑；若坚持用 PHP 层网关，hyperf/api-gateway 只能当简单路由跳转用，别碰鉴权、熔断、监控埋点这些事——它没预留扩展钩子，硬改源码会失去升级能力。
