一、為什么選 FastAPI + React？
- 性能：FastAPI 基于 Starlette + Uvicorn，QPS 與 Node/Go 同級，實測 3 倍于 Flask；React 虛擬 DOM + 代碼分割，首屏 < 1.2 s。
- 效率：FastAPI 內置 Swagger/OpenAPI，前端可一鍵生成 TypeScript SDK；React 組件化 + Hooks，業務邏輯復用率提升 40 %。
- 生態：FastAPI 原生支持 Pydantic、SQLAlchemy、OAuth2；React 擁有 Ant-Design、Tailwind、Next.js 等全家桶。
- 人才：Python + JavaScript 人才儲備充足，降低招聘成本。
二、整體架構
┌────────────────────────────┐
│ React SPA │
│ (Vite + React-Router 6) │
└────────────┬───────────────┘│ HTTPS/JSON
┌────────────┴───────────────┐
│ FastAPI │
│ (RESTful + WebSocket) │
└────────────┬───────────────┘│ SQLAlchemy
┌────────────┴───────────────┐
│ PostgreSQL │
└────────────────────────────┘
? 前端：BFF 由 React Query 代理，統一緩存、重試、分頁。
? 后端：分層結構 routers → services → repositories → models，單測覆蓋率 90 %。
? 部署：CI/CD 雙流水線，前端 push → GitHub Actions → Cloudflare Pages；后端 push → Docker → AWS ECS Fargate。
三、開發環境 5 分鐘搭好
- 后端
python -m venv venv && source venv/bin/activate
pip install fastapi[all] sqlalchemy alembic passlib[bcrypt] python-jose[cryptography]
uvicorn main:app --reload
- 前端
npm create vite@latest frontend --template react-ts
cd frontend && npm i axios react-query@tanstack/react-query zustand
npm run dev
- 跨域
FastAPI 一行解決：
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(CORSMiddleware,allow_origins=["http://localhost:5173"],allow_credentials=True,allow_methods=["*"],allow_headers=["*"])
四、核心代碼示例
- 后端：用戶注冊 + JWT 登錄
from fastapi import FastAPI, HTTPException, Depends
from sqlalchemy.orm import Session
from passlib.context import CryptContext
from datetime import datetime, timedelta
import jwtpwd = CryptContext(schemes=["bcrypt"], deprecated="auto")
SECRET = "change_me"def create_token(uid: int):return jwt.encode({"sub": str(uid), "exp": datetime.utcnow() + timedelta(days=7)}, SECRET)@app.post("/api/register")
def register(username: str, password: str, db: Session = Depends(get_db)):if db.query(User).filter_by(username=username).first():raise HTTPException(400, "用戶已存在")u = User(username=username, hashed_password=pwd.hash(password))db.add(u); db.commit(); db.refresh(u)return {"access_token": create_token(u.id)}@app.post("/api/login")
def login(form: OAuth2PasswordRequestForm = Depends(), db: Session = Depends(get_db)):u = db.query(User).filter_by(username=form.username).first()if not u or not pwd.verify(form.password, u.hashed_password):raise HTTPException(401, "賬號或密碼錯誤")return {"access_token": create_token(u.id), "token_type": "bearer"}
- 前端：React Query 全局封裝
import axios from 'axios'
import { QueryClient } from '@tanstack/react-query'const api = axios.create({baseURL: '/api',withCredentials: true
})api.interceptors.request.use(cfg => {const token = localStorage.getItem('token')if (token) cfg.headers['Authorization'] = `Bearer ${token}`return cfg
})export const queryClient = new QueryClient({defaultOptions: { queries: { staleTime: 60_000, retry: 1 } }
})
- 頁面：登錄表單 + 路由守衛
import { useMutation } from '@tanstack/react-query'
import { useNavigate } from 'react-router-dom'function Login() {const nav = useNavigate()const { mutate, isLoading } = useMutation({mutationFn: (body: { username: string; password: string }) =>api.post('/login', body).then(r => r.data),onSuccess: data => {localStorage.setItem('token', data.access_token)nav('/dashboard')}})return <form onSubmit={e => { e.preventDefault(); mutate({ username, password }) }}>...</form>
}
五、接口約定與文檔
? RESTful 規范：
GET /items 列表
POST /items 新建
GET /items/{id} 詳情
PATCH /items/{id} 更新
DELETE /items/{id} 刪除
? 自動生成文檔：訪問 http://localhost:8000/docs，前端同學無需等 Mock 即可聯調。
? 變更通知：使用 spectacular 插件，每次 PR 時自動對比 Swagger JSON，若存在破壞性變更則阻斷合并。
六、本地聯調技巧
| 場景 | 前端腳本 | 后端腳本 |
|---|---|---|
| 并行開發 | npm run dev | uvicorn main:app --reload |
| 集成測試 | npm run build && npm run preview | docker compose up |
| 一鍵全棧 | concurrently "npm run dev" "uvicorn main:app --reload" |
七、生產部署
- 前端
# .github/workflows/deploy.yml
- uses: cloudflare/pages-action@v1with:apiToken: ${{ secrets.CF_API_TOKEN }}accountId: ${{ secrets.CF_ACCOUNT_ID }}projectName: myappdirectory: frontend/dist
- 后端
Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
ECS 任務定義設置 CPU 256、內存 512 MiB，自動伸縮到 3 個實例。
- HTTPS + 域名
Cloudflare CDN → ALB → ECS，證書由 ACM 托管，強制 TLS 1.3。
八、常見坑與對策
| 問題 | 現象 | 解決方案 |
|---|---|---|
| CORS 失敗 | 瀏覽器報 403 | 確認 allow_origins 與前端端口一致 |
| 熱更新失效 | React 頁面不刷新 | vite.config.ts 里 server.proxy 指到 FastAPI |
| 大文件上傳 | 413 Request Entity Too Large | FastAPI max_request_size=50MB，Nginx client_max_body_size 50M; |
| 內存泄漏 | ECS 任務 OOM | SQLAlchemy session 未關閉，引入 @contextmanager |
九、進階優化
? 接口緩存：Redis + FastAPI Depends 實現接口級緩存，讀 QPS 提升至 5 k。
? 實時推送：WebSocket /ws/notifications，前端使用 useWebSocket Hook。
? SSR 同構：Next.js + FastAPI 雙棧熱啟動，SEO 提升 60 %。
? 微前端：qiankun 動態加載子應用，統一由 FastAPI Gateway 路由。
十、總結
FastAPI 的高性能、強類型與 React 的組件化、生態豐富相結合，可以覆蓋從小型 MVP 到百萬級 QPS 的業務場景。通過“接口先行 + 自動化文檔 + 雙流水線部署”，團隊交付效率提升 50 % 以上，代碼維護成本下降 30 %。如果你正準備啟動新 Web 項目，這套組合值得你立即嘗試。
