PythonWeb前后端整合项目教程_FastAPIReact完整实例

FastAPI+React是轻量高效Web开发主流组合，适合中小型项目与MVP验证；后端用FastAPI构建类型安全API并自动生成文档，前端用React+Vite实现组件化开发，通过CORS、代理配置与静态托管完成联调部署。

用 FastAPI 做后端、React 做前端，是当前轻量高效 Web 开发的主流组合之一。它不依赖重框架，启动快、类型安全强、API 文档自动生成，配合 React 的组件化和响应式能力，适合中小型项目、内部工具、MVP 快速验证等场景。

后端：FastAPI 服务搭建与 API 设计

安装并初始化 FastAPI 项目只需几行命令：

• 创建虚拟环境：python -m venv venv && source venv/bin/activate（macOS/Linux）或 venv\Scripts\activate（Windows）
• 安装依赖：pip install fastapi uvicorn python-multipart python-jose[cryptography] passlib[bcrypt] sqlalchemy psycopg2-binary
• 写一个最小 API：在 main.py 中定义路由，例如返回用户列表或处理登录请求，用 Pydantic 模型约束输入输出格式
• 运行服务：uvicorn main:app --reload --host 0.0.0.0:8000，自动提供交互式文档（/docs）和 JSON Schema（/redoc）

建议把数据库操作（如 SQLAlchemy ORM）、认证逻辑（JWT）、配置管理（settings.py）分模块组织，避免全部堆在 main.py 里。

前端：React 项目创建与 API 调用封装

使用 Vite 创建现代 React 项目更轻快：

• 初始化项目：npm create vite@latest my-app -- --template react，进入目录并 npm install
• 封装请求逻辑：新建 src/lib/api.ts，用 fetch 或 axios 封装对 FastAPI 的调用，统一处理 base URL、token 注入、错误提示
• 连接后端接口：例如登录后获取用户信息，调用 /api/v1/users/me，用 React Query 管理异步状态，避免手动写 loading/error 处理
• 跨域注意：开发时 FastAPI 需启用 CORS，加一行 from fastapi.middleware.cors import CORSMiddleware 并注册中间件，允许 http://localhost:5173（Vite 默认端口）

前后端联调与部署要点

本地开发阶段，前后端分离运行没问题；但上线前需考虑路径和资源交付方式：

• 开发代理配置：在 Vite 的 vite.config.ts 中设置 server.proxy，把 /api 请求转发到 http://localhost:8000，避免浏览器跨域报错
• 生产构建：运行 npm run build 生成静态文件（默认在 dist/），FastAPI 可通过 StaticFiles 挂载该目录，将 React 页面作为 SPA 主入口
• 单页路由兼容：React Router 使用 createBrowserRouter 时，FastAPI 需捕获所有非 API 路径（如 /dashboard、/profile），统一返回 index.html，否则刷新页面会 404
• 环境变量区分：React 用 VITE_API_BASE_URL 控制请求地址（开发用 /api，生产用完整域名），FastAPI 用 .env 管理数据库密码、密钥等敏感配置

常见问题与调试技巧

刚整合时常遇到几个典型卡点：

• 401 / 422 错误频出：检查 FastAPI 的 Pydantic 模型字段是否与前端发送的 JSON 字段名、类型完全一致（比如布尔值传字符串 "true" 会失败）
• 登录态丢失：确认 JWT token 存在 localStorage 或 httpOnly cookie，React 请求头是否带 Authorization: Bearer xxx
• 图片或文件上传失败：FastAPI 接收 UploadFile 时，前端必须用 FormData 构造请求，不能直接 JSON 发送二进制
• 热更新不同步：Vite 和 Uvicorn 各自热重载，但修改 FastAPI 的 Pydantic 模型后，前端 TypeScript 类型不会自动更新，建议用 openapi-generator 或 datamodel-code-generator 从 OpenAPI spec 生成 TS 类型

不复杂但容易忽略。