FastAPI 中 CORSMiddleware 配置指南跨域请求、Origin 规则与预检流程解析【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本篇技术指南围绕 FastAPI 官方文档中的 CORSCross-Origin Resource Sharing跨源资源共享章节展开讲解浏览器同源策略下前端与后端跨域通信的工作原理并结合当前仓库的示例代码与源码结构完整覆盖CORSMiddleware的全部配置参数、预检Preflight请求与简单请求Simple Request两种处理路径。读完后你可以为自己的 FastAPI 应用正确配置跨域策略理解通配符*与凭据Credentials之间的限制关系并知道 FastAPI 的中间件与 Starlette 之间的关系。什么是 CORS以及它解决什么问题CORS 指的是这样一种场景运行在浏览器中的前端包含 JavaScript 代码需要与某个后端通信而该后端与前端处于不同的“源Origin”。由于浏览器的同源策略Same-Origin Policy默认阻止这类跨域请求后端必须显式声明允许哪些源访问自己浏览器才会放行请求并允许前端读取响应。Origin源的构成一个Origin由三部分的组合唯一确定协议Protocolhttp、https域名Domain如myapp.com、localhost、localhost.tiangolo.com端口Port如80、443、8080。因此下面三个地址虽然都指向localhost但它们是三个不同的 Origin因为它们使用了不同的协议或端口http://localhosthttps://localhosthttp://localhost:8080这一点在配置allow_origins列表时尤其关键——必须把前端实际运行的完整地址含协议与端口逐项列出。跨域请求的完整流程假设你的前端运行在浏览器的http://localhost:8080上其 JavaScript 尝试与运行在http://localhost未指定端口时浏览器默认使用80端口上的后端通信流程如下浏览器先向:80后端发送一个 HTTPOPTIONS预检Preflight请求如果该后端返回了授权该跨源http://localhost:8080通信的相应响应头浏览器才允许前端的 JavaScript 把真正的请求发往:80后端为此:80后端必须持有一份“允许的来源allowed origins”列表在这个例子中该列表必须包含http://localhost:8080:8080上的前端才能正常工作。通配符*的能力与边界可以把允许列表声明为*通配符表示允许任意源。但需要注意通配符只允许某些类型的通信一切涉及凭据的场景都被排除在外包括 Cookies、Authorization请求头例如 Bearer Token 使用的头等。因此如果要保证所有场景都正确工作最好显式列出允许的 Origins。使用CORSMiddleware配置跨域在 FastAPI 应用中跨域策略通过CORSMiddleware配置只需三步导入CORSMiddleware创建一个允许的 Origins 列表字符串形式把它作为“中间件Middleware”添加到 FastAPI 应用中。你还可以指定后端是否允许凭据CredentialsAuthorization头、Cookies 等特定的 HTTP 方法POST、PUT或用通配符*表示全部特定的 HTTP 头或用通配符*表示全部。当前仓库中的官方示例 docs_src/cors/tutorial001_py310.py 完整演示了这一配置方式from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware app FastAPI() origins [ http://localhost.tiangolo.com, https://localhost.tiangolo.com, http://localhost, http://localhost:8080, ] app.add_middleware( CORSMiddleware, allow_originsorigins, allow_credentialsTrue, allow_methods[*], allow_headers[*], ) app.get(/) async def main(): return {message: Hello World}注意示例中allow_origins是逐条列出的完整 Origin协议 域名 端口端口缺省时省略并与allow_credentialsTrue搭配——这正是前文“显式列出允许的 Origins”建议的直接体现。CORSMiddleware实现所使用的默认参数是偏严格的默认情况下你必须显式启用特定的 Origins、方法或 Headers浏览器才会在跨域上下文中允许使用它们。CORSMiddleware支持的参数CORSMiddleware支持以下参数默认值与约束参数默认值说明allow_origins()空允许发起跨源请求的 Origin 列表例如[https://example.org, https://www.example.org]。可用[*]允许任意源。allow_origin_regexNone一个正则字符串用于匹配允许发起跨源请求的 Origin例如https://.*\.example\.org。适合“同一主域下的所有子域/HTTPS 源”这类规则。allow_methods[GET]允许用于跨源请求的 HTTP 方法列表。可用[*]允许全部标准方法。allow_headers[]跨源请求中应被支持的 HTTP 请求头列表。可用[*]允许全部头。Accept、Accept-Language、Content-Language和Content-Type这 4 个头对简单 CORS 请求总是被允许。allow_credentialsFalse声明是否支持跨源请求携带 Cookies 等凭据。expose_headers[]声明允许浏览器 JS 访问哪些响应头。max_age600浏览器可缓存 CORS 预检响应的最长时间秒。关键约束当allow_credentials为True时allow_origins、allow_methods、allow_headers三者都不能设置为[*]它们必须被显式指定——这是浏览器规范对“凭据 通配符”组合的硬性限制。上面的仓库示例正是遵守了这一点Origins 显式列出方法与头才允许使用*。中间件的两种请求处理路径从中间件的实际实现行为看CORSMiddleware的实现在 Starlette 中FastAPI 通过 fastapi/middleware/cors.py 直接重导出该文件仅一行from starlette.middleware.cors import CORSMiddleware as CORSMiddleware中间件对两类特殊 HTTP 请求分别处理CORS 预检请求Preflight Requests即任何同时带有Origin和Access-Control-Request-Method头的OPTIONS请求。此时中间件会拦截该入站请求直接返回带相应 CORS 头的响应状态码为200通过校验或400校验失败响应体为形如Disallowed CORS origin/method/headers的纯文本供开发者排错仅作信息性用途——请求不会继续转发到后端路由。对应源码结构预检响应逻辑preflight_response会依次检查 Origin 是否被允许、请求方法是否在allow_methods内、请求头是否在允许列表内任何一项失败都会收集到failures并返回 400。简单请求Simple Requests即任何带有Origin头的普通请求。此时中间件不会拦截请求而是让它照常通过继续调用你的路由但会在出站响应中写入相应的 CORS 头。对应实现细节若允许所有 Originallow_origins含*简单请求的响应头会固定携带Access-Control-Allow-Origin: *但如果该请求本身携带了 Cookie 头则必须改为回显具体的请求 Origin即allow_explicit_origin同时追加Vary: Origin以满足凭据场景下“不允许通配符”的规范若只允许特定 Origin且当前请求的 Origin 命中白名单精确匹配或allow_origin_regex全匹配同样回显具体的 Origin 并附加Vary: Origin请求中未带Origin头时中间件完全放行不做任何处理——同源请求不受影响allow_headers为[*]时预检响应的Access-Control-Allow-Headers会镜像回显请求中Access-Control-Request-Headers的头而不是返回字面量*。默认值的来源与“始终允许”的请求头文档中提到的默认值allow_methods[GET]、allow_headers[]、allow_credentialsFalse、max_age600与 Starlette 中CORSMiddleware.__init__的函数签名一致Allow与通配符*的展开逻辑也与之对应allow_methods中的*会被展开为全部标准方法DELETE、GET、HEAD、OPTIONS、PATCH、POST、PUT而Allow-Headers侧总会自动并入 4 个“白名单头”Accept、Accept-Language、Content-Language、Content-Type对应文档中“简单请求总是允许这 4 个头”的说明。FastAPI 的中间件与 Starlette 的关系技术细节文档末尾还给出了一条技术细节说明值得单独记录你同样可以直接使用from starlette.middleware.cors import CORSMiddleware效果相同FastAPI 在fastapi.middleware包中提供了若干中间件如 fastapi/middleware/ 目录下的cors.py、gzip.py、httpsredirect.py、trustedhost.py、wsgi.py等主要是为了方便开发者但其中绝大多数中间件直接来自 Starlette。换句话说CORSMiddleware的行为细节预检拦截、头镜像、Vary: Origin等由 Starlette 的实现决定FastAPI 提供的是便捷的导入路径升级 FastAPI/Starlette 版本时中间件的实际行为以对应 Starlette 版本为准。更多资料关于 CORS 规范的更多细节简单请求定义、凭据请求与通配符的限制等可以查阅浏览器的官方 CORS 文档本仓库中该主题相关的可查证路径包括文档正文docs/de/docs/tutorial/cors.md英文版为 docs/en/docs/tutorial/cors.md配置示例代码docs_src/cors/tutorial001_py310.py中间件重导出fastapi/middleware/cors.py。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考