Hyperf框架中基于路径前缀的路由转发实现方案

需求背景

在Hyperf框架开发过程中，我们经常会遇到需要根据请求路径前缀来统一处理某些请求的场景。例如，所有以/v1/开头的API请求都需要路由到同一个控制器方法进行处理，无论后续路径如何变化。

常规路由方案的局限性

Hyperf框架提供了多种路由配置方式，包括注解路由和配置文件路由。最直接的方式是使用Router::get('/v1/{name}', 'ApiController@v1')这样的配置。然而，这种方式存在明显局限性：

1. 只能匹配单级路径，如/v1/user，无法处理多级路径如/v1/user/profile
2. 需要为每个可能的路径模式单独配置路由规则
3. 维护成本高，扩展性差

中间件解决方案

针对上述问题，我们可以通过自定义中间件来实现更灵活的路由转发逻辑。下面是一个完整的实现方案：

namespace App\Middleware;

use App\Controller\RestfulController;
use FastRoute\Dispatcher;
use Hyperf\Context\RequestContext;
use Hyperf\Di\Annotation\Inject;
use Hyperf\HttpServer\Router\Dispatched;
use Hyperf\HttpServer\Router\DispatcherFactory;
use Hyperf\HttpServer\Router\Handler;
use Hyperf\Stringable\Str;
use Psr\Container\ContainerInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class RouteMiddleware implements MiddlewareInterface
{
    #[Inject]
    private ContainerInterface $container;

    protected Dispatcher $dispatcher;

    public function __construct()
    {
        $this->dispatcher = $this->createDispatcher('http');
    }

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $uri = $request->getUri()->getPath();
        
        // 检查是否以/v2/开头
        if (Str::startsWith($uri, '/v2/')) {
            // 尝试正常路由匹配
            $routes = $this->dispatcher->dispatch($request->getMethod(), $uri);
            
            // 如果没有匹配到路由
            if ($routes[0] === Dispatcher::NOT_FOUND) {
                // 创建新的路由处理器
                $routeHandler = new Handler(
                    RestfulController::class . '@restfulApi',
                    $uri
                );

                // 构造新的路由匹配结果
                $routes[0] = Dispatcher::FOUND;
                $routes[1] = $routeHandler;
                $routes[2] = [];

                // 设置新的请求分发信息
                $dispatched = new Dispatched($routes, 'http');
                $newRequest = RequestContext::set($request)
                    ->setAttribute(Dispatched::class, $dispatched);
                
                return $handler->handle($newRequest);
            }
        }

        return $handler->handle($request);
    }

    protected function createDispatcher(string $serverName): Dispatcher
    {
        $factory = $this->container->get(DispatcherFactory::class);
        return $factory->getDispatcher($serverName);
    }
}

实现原理

1. 中间件拦截：通过中间件拦截所有HTTP请求
2. 路径检查：检查请求路径是否以特定前缀(如/v2/)开头
3. 路由匹配：先尝试正常路由匹配，如果匹配失败则进入自定义处理
4. 动态路由：构造新的路由处理器，将请求转发到指定控制器方法
5. 请求修改：修改请求对象的路由分发信息，确保后续处理正确

优势分析

1. 灵活性：可以处理任意多级路径，不受路由规则限制
2. 统一入口：所有匹配前缀的请求都进入同一处理方法，便于统一处理
3. 维护简单：只需维护中间件逻辑，无需频繁修改路由配置
4. 兼容性：不影响其他路由的正常工作

应用场景

这种方案特别适用于以下场景：

1. API版本控制：不同版本的API使用不同前缀
2. 微服务网关：统一入口转发到不同服务
3. 遗留系统迁移：逐步迁移老接口时保持路径兼容
4. 多租户系统：根据路径前缀区分租户

注意事项

1. 中间件执行顺序很重要，需要确保在路由中间件之前执行
2. 性能考虑：频繁的路径检查可能影响性能，建议合理设计前缀规则
3. 安全性：确保动态路由不会引入安全问题
4. 日志记录：建议记录所有重定向的路由，便于调试

通过这种中间件方案，我们可以优雅地实现基于路径前缀的统一路由转发，为Hyperf应用提供更灵活的路由控制能力。