OpenAPI-TS 项目中 FastAPI 跨域问题的解决方案

问题背景

在使用 OpenAPI-TS 项目生成的前端 SDK 与 FastAPI 后端交互时，开发者遇到了一个典型的跨域问题。当通过 TanStack Query 发起 POST 请求时，请求被自动转换为 OPTIONS 方法，导致后端返回"方法不允许"的错误。

问题现象

前端使用自动生成的 SDK 调用 FastAPI 后端的注册接口时，虽然代码中明确指定了 POST 方法，但实际发出的却是 OPTIONS 请求。即使手动在请求配置中添加 method: "POST" 也无济于事。

根本原因分析

经过深入排查，发现问题的根源在于 FastAPI 的 CORS 中间件配置不当。具体表现为：

1. CORS 中间件没有在 FastAPI 应用初始化时正确添加
2. 前端应用的基地址未被包含在允许的源列表中
3. 中间件位置不当导致无法正确处理预检请求

解决方案

要解决这个问题，需要正确配置 FastAPI 的 CORS 中间件：

1. 中间件位置：必须在 FastAPI 应用实例化的同一文件中添加 CORS 中间件，确保它在应用初始化时就被加载。

2. 允许的源配置：需要明确将前端应用的基地址添加到允许的源列表中。例如，如果前端运行在 localhost:3000，则需要将其包含在允许的源中。

3. 完整配置示例：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# 正确的CORS中间件配置
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # 前端地址
    allow_credentials=True,
    allow_methods=["*"],  # 允许所有方法
    allow_headers=["*"],  # 允许所有头
)

技术要点解析

1. 预检请求机制：浏览器在发送某些跨域请求前会先发送 OPTIONS 请求进行预检，这是正常的安全机制而非错误。

2. 中间件顺序：在 FastAPI 中，中间件的执行顺序很重要，CORS 中间件应该尽早添加以确保它能处理所有请求。

3. SDK 生成的影响：OpenAPI-TS 生成的 SDK 本身没有问题，问题出在后端没有正确处理跨域请求。

最佳实践建议

1. 开发环境配置：在开发阶段可以暂时放宽 CORS 限制，但生产环境应该严格限制允许的源。

2. 错误处理：除了配置 CORS，还应该在后端实现完善的错误处理，返回清晰的错误信息帮助调试。

3. 测试验证：配置完成后，应该使用多种方法(GET/POST/PUT等)测试跨域请求是否都能正常工作。

总结

跨域问题是前后端分离架构中的常见挑战。通过正确配置 FastAPI 的 CORS 中间件，可以确保 OpenAPI-TS 生成的 SDK 能够正常工作。这个案例提醒我们，在遇到类似"方法不允许"的错误时，不仅要检查前端代码，还应该确认后端的跨域配置是否正确。