Stack/Cors源码深度剖析：从请求处理到响应头设置的完整流程

【免费下载链接】stack-cors Cross-origin resource sharing library and stack middleware. 项目地址: https://gitcode.com/gh_mirrors/st/stack-cors

Stack/Cors是一款功能强大的跨域资源共享（CORS）库和中间件，它能够帮助开发者轻松解决Web应用中的跨域请求问题。本文将深入剖析Stack/Cors的源码实现，带你了解从请求处理到响应头设置的完整流程，帮助你更好地理解和使用这个优秀的开源工具。

项目概述：Stack/Cors是什么？

Stack/Cors（项目路径：gh_mirrors/st/stack-cors）是一个基于PHP的CORS库和中间件，它遵循Symfony HttpKernelInterface接口，能够无缝集成到各种PHP Web应用中。该项目的核心功能是处理跨域请求，包括预检请求（Preflight Request）的处理和实际请求的响应头设置，从而确保Web应用能够安全地接受来自不同域的请求。

从composer.json文件中可以看到，Stack/Cors依赖于Symfony的http-foundation和http-kernel组件，要求PHP版本为7.3及以上，这保证了它的稳定性和广泛的兼容性。

核心架构：两大核心类的分工与协作

Stack/Cors的核心架构由两个主要类组成：Cors类和CorsService类。这两个类分工明确，协同工作，共同完成CORS请求的处理。

Cors类：请求处理的入口

Cors类（src/Cors.php）实现了Symfony的HttpKernelInterface接口，是整个中间件的入口点。它的主要职责是接收HTTP请求，判断请求类型，并根据请求类型调用相应的处理方法。

在Cors类的构造函数中，它接收一个HttpKernelInterface实例和一个配置选项数组。配置选项包括允许的源（allowedOrigins）、允许的方法（allowedMethods）、允许的头部（allowedHeaders）等，这些选项会被合并到默认配置中，并传递给CorsService实例。

Cors类的handle方法是处理请求的核心。它首先判断请求是否为预检请求（通过调用CorsService的isPreflightRequest方法）。如果是预检请求，则直接调用CorsService的handlePreflightRequest方法处理，并返回处理后的响应。如果不是预检请求，则先让应用处理请求，然后调用CorsService的addActualRequestHeaders方法为响应添加CORS相关头信息。

CorsService类：CORS逻辑的实现核心

CorsService类（src/CorsService.php）是实现CORS逻辑的核心。它包含了判断请求类型、处理预检请求、为响应添加CORS头信息等关键功能。

CorsService的构造函数接收配置选项，并通过normalizeOptions方法对选项进行标准化处理。例如，将允许所有源（['*']）转换为布尔值true，将允许的方法转换为大写，将允许的头部转换为小写等。

该类提供了多个关键方法：

• isCorsRequest：判断是否为CORS请求（即是否包含Origin头）。
• isPreflightRequest：判断是否为预检请求（即是否为OPTIONS方法且包含Access-Control-Request-Method头）。
• handlePreflightRequest：处理预检请求，返回一个204状态码的响应，并添加必要的CORS头信息。
• addActualRequestHeaders：为实际请求的响应添加CORS头信息。
• isOriginAllowed：判断请求的源是否被允许。

请求处理流程：从接收请求到返回响应

Stack/Cors处理请求的流程可以分为以下几个关键步骤：

1. 请求接收与类型判断

当一个请求到达时，首先由Cors类的handle方法接收。该方法会调用CorsService的isPreflightRequest方法判断请求是否为预检请求。

预检请求通常是OPTIONS方法，并且包含Access-Control-Request-Method头，用于询问服务器是否允许后续的实际请求。

2. 预检请求处理

如果是预检请求，Cors类会调用CorsService的handlePreflightRequest方法。该方法会创建一个204（No Content）状态码的响应，并调用addPreflightRequestHeaders方法为响应添加CORS相关头信息。

addPreflightRequestHeaders方法会依次配置允许的源（Access-Control-Allow-Origin）、允许的凭证（Access-Control-Allow-Credentials）、允许的方法（Access-Control-Allow-Methods）、允许的头部（Access-Control-Allow-Headers）和预检请求的缓存时间（Access-Control-Max-Age）。

3. 实际请求处理

如果不是预检请求，Cors类会先让应用（即构造函数中传入的HttpKernelInterface实例）处理请求，得到响应后，再调用CorsService的addActualRequestHeaders方法为响应添加CORS头信息。

addActualRequestHeaders方法会配置允许的源、允许的凭证和暴露的头部（Access-Control-Expose-Headers）。暴露的头部指定了哪些响应头可以被客户端的JavaScript访问。

4. 响应返回

处理完成后，Cors类会返回添加了CORS头信息的响应，客户端即可根据这些头信息判断是否允许跨域访问。

关键功能实现：深入代码细节

允许源（Allowed Origins）的判断与处理

CorsService的isOriginAllowed方法负责判断请求的源是否被允许。它首先检查配置的allowedOrigins是否为true（即允许所有源），如果是则直接返回true。否则，它会检查请求的Origin是否在allowedOrigins列表中，或者是否匹配allowedOriginsPatterns中的正则表达式。

在configureAllowedOrigin方法中，会根据不同情况设置Access-Control-Allow-Origin头：

• 如果允许所有源且不支持凭证，则设置为'*'。
• 如果只允许单个源，则直接设置该源。
• 否则，动态设置为请求的Origin（如果该Origin被允许），并添加Vary: Origin头。

允许方法（Allowed Methods）的处理

在configureAllowedMethods方法中，如果allowedMethods配置为true（即允许所有方法），则会从Access-Control-Request-Method头中获取请求方法，并设置为允许的方法。否则，会使用配置的allowedMethods列表。

允许头部（Allowed Headers）的处理

configureAllowedHeaders方法与configureAllowedMethods方法类似。如果allowedHeaders配置为true，则从Access-Control-Request-Headers头中获取请求头部，并设置为允许的头部。否则，使用配置的allowedHeaders列表。

总结：Stack/Cors的价值与应用

Stack/Cors通过清晰的架构设计和完善的功能实现，为PHP Web应用提供了可靠的CORS解决方案。它的核心价值在于：

1. 简单易用：通过简洁的API和灵活的配置选项，开发者可以轻松集成和使用。
2. 功能完善：全面支持CORS规范，包括预检请求处理、各种头信息的设置等。
3. 兼容性好：基于Symfony组件构建，能够与各种PHP框架和应用无缝集成。

要开始使用Stack/Cors，你可以通过Composer安装：

composer require asm89/stack-cors

然后，根据你的应用框架，将Cors中间件注册到请求处理流程中，并配置相应的CORS选项。

通过深入理解Stack/Cors的源码实现，你不仅可以更好地使用这个工具，还能学习到如何设计和实现一个功能完善的中间件，以及如何处理复杂的HTTP协议细节。希望本文对你有所帮助！

【免费下载链接】stack-cors Cross-origin resource sharing library and stack middleware. 项目地址: https://gitcode.com/gh_mirrors/st/stack-cors