Slim 4 框架中解决 CORS 预检请求问题的实践指南

问题背景

在使用 Slim 4 框架开发 RESTful API 时，跨域资源共享(CORS)是一个常见需求。当从前端应用(如运行在 localhost:5133 的 React/Vue 应用)向 API 服务器(localhost:8000)发起跨域请求时，浏览器会先发送一个 OPTIONS 方法的预检请求(preflight request)，以确定服务器是否允许实际的跨域请求。

常见错误现象

开发者经常会遇到以下错误：

• 预检请求返回 500 错误
• 控制台显示"Method not allowed. Must be one of: GET"错误
• 即使添加了 CORS 头信息，请求仍然被阻止

错误原因分析

问题的根源在于 Slim 4 的路由系统默认不会自动处理 OPTIONS 请求。当浏览器发送预检请求时，如果没有明确的路由处理 OPTIONS 方法，框架会返回方法不允许的错误。

解决方案对比

方案一：单独处理 OPTIONS 请求(不推荐)

$app->options('/{routes:.+}', function ($request, $response, $args) {
    return $response;
});

这种方法虽然能解决问题，但需要为每个可能的路径单独处理 OPTIONS 请求，维护性差。

方案二：使用中间件处理(推荐)

创建一个专门的 CORS 中间件是更优雅的解决方案：

class CorsMiddleware implements MiddlewareInterface
{
    private ResponseFactoryInterface $responseFactory;

    public function __construct(ResponseFactoryInterface $responseFactory)
    {
        $this->responseFactory = $responseFactory;
    }

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        // 如果是OPTIONS预检请求，直接返回空响应
        if ($request->getMethod() === 'OPTIONS') {
            $response = $this->responseFactory->createResponse();
        } else {
            // 正常请求，继续处理
            $response = $handler->handle($request);
        }

        // 添加CORS头信息
        return $response
            ->withHeader('Access-Control-Allow-Origin', '*')
            ->withHeader('Access-Control-Allow-Headers', 'X-Requested-With, Content-Type, Accept, Origin, Authorization')
            ->withHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
    }
}

实现原理详解

1. 中间件优先处理：中间件在路由之前执行，可以拦截所有请求，包括OPTIONS预检请求。

2. OPTIONS请求特殊处理：当检测到OPTIONS方法时，直接创建空响应，不继续后续处理链。

3. CORS头信息添加：无论是否OPTIONS请求，都会添加必要的CORS头信息，确保浏览器能正确处理跨域请求。

最佳实践建议

1. 生产环境配置：在生产环境中，建议将Access-Control-Allow-Origin设置为具体的域名而非通配符*，以提高安全性。

2. 缓存优化：对于频繁的OPTIONS请求，可以添加Access-Control-Max-Age头来减少预检请求次数。

3. 中间件顺序：确保CORS中间件是第一个被添加的中间件，以便它能处理所有后续中间件可能产生的响应。

4. 错误处理：考虑在中间件中添加错误处理逻辑，确保即使后续处理链抛出异常，CORS头信息也能正确添加。

通过这种中间件方式处理CORS问题，代码更加清晰、可维护，且能正确处理所有类型的跨域请求，是Slim 4框架中解决CORS问题的推荐方案。