FastAPI跨域请求：终极预检请求处理指南-CSDN博客

FastAPI跨域请求：终极预检请求处理指南

【免费下载链接】fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

FastAPI是一个高性能、易于学习且快速编码的现代Python Web框架，专为生产环境设计。在前后端分离的架构中，跨域资源共享（CORS）是常见需求，而预检请求（Preflight Request）处理则是确保API安全通信的关键环节。本文将详细介绍如何在FastAPI中配置CORS中间件，轻松解决跨域请求问题。

什么是跨域请求与预检请求？

当浏览器从一个域名的网页向另一个域名的API发送请求时，就会触发跨域请求。为了安全起见，浏览器会先发送一个预检请求（OPTIONS方法），检查服务器是否允许实际请求。只有通过预检后，浏览器才会发送真实的业务请求。

常见的跨域场景包括：

前端应用部署在http://localhost:3000，API部署在http://localhost:8000
生产环境中不同子域名之间的资源访问
第三方网站调用你的API服务

FastAPI中的CORS中间件配置

FastAPI提供了内置的CORSMiddleware来处理跨域请求，只需简单配置即可实现完整的预检请求处理。核心配置文件位于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_origins=origins,  # 允许的源列表
    allow_credentials=True,  # 允许携带Cookie
    allow_methods=["*"],  # 允许的HTTP方法
    allow_headers=["*"],  # 允许的HTTP头
)

@app.get("/")
async def main():
    return {"message": "Hello World"}

关键配置参数详解

allow_origins：指定允许的源域名列表
- 使用["*"]允许所有源（不推荐生产环境）
- 生产环境应明确指定可信域名，如["https://yourfrontend.com"]
allow_credentials：是否允许跨域请求携带Cookie
- 设为True时，allow_origins不能使用"*"通配符
allow_methods：允许的HTTP方法
- 使用["*"]允许所有方法（GET, POST, PUT, DELETE等）
- 也可指定具体方法，如["GET", "POST"]
allow_headers：允许的请求头
- 使用["*"]允许所有头信息
- 如需自定义头，可指定如["X-Custom-Header"]

高级CORS场景配置

1. 动态允许源

对于需要动态验证来源的场景，可以通过回调函数实现：

def allow_origin(origin: str) -> bool:
    # 实现自定义验证逻辑
    return origin in ["https://trusted-domain.com", "https://another-trusted.com"]

app.add_middleware(
    CORSMiddleware,
    allow_origins=allow_origin,  # 传入回调函数
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

2. 限制预检请求缓存时间

通过max_age参数设置预检请求结果的缓存时间（秒）：

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    max_age=600,  # 缓存10分钟
)

常见问题与解决方案

问题1：仍然收到跨域错误

可能原因：

配置的allow_origins与实际请求源不匹配
未正确设置allow_credentials参数
服务器部署在反向代理后，未正确配置转发头

解决方案：

使用浏览器开发者工具的Network面板检查预检请求响应头
确保Access-Control-Allow-Origin头正确返回请求源
检查behind-a-proxy文档配置代理

问题2：复杂请求预检失败

可能原因：

请求使用了非简单方法（如PUT、DELETE）
请求包含自定义头信息
Content-Type为application/json（非简单类型）

解决方案：

确保allow_methods包含所有使用的HTTP方法
在allow_headers中显式包含自定义头
确认allow_headers包含Content-Type

FastAPI接口测试与CORS验证

配置CORS后，可以通过FastAPI自动生成的Swagger UI测试接口。访问http://localhost:8000/docs即可打开交互式API文档：

在测试跨域请求时，可以使用以下方法：

从前端应用直接调用API
使用Postman设置不同的Origin头进行测试
通过浏览器控制台观察网络请求和响应头

生产环境最佳实践

严格限制允许的源：避免使用"*"通配符，明确指定可信域名
最小权限原则：只允许必要的HTTP方法和头信息
启用凭据支持：仅在需要时设置allow_credentials=True
配置适当的缓存时间：减少预检请求次数提升性能
监控跨域请求：记录异常跨域尝试，及时发现安全问题

通过合理配置FastAPI的CORSMiddleware，可以轻松处理各种跨域场景，确保前后端应用安全高效地通信。完整的CORS配置示例可参考官方文档和示例代码。

【免费下载链接】fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考