1. 為什么 2025 依舊選 FastAPI

一句話總結：寫更少，跑更快，文檔自動生成。

2. 極速起步：官方模板深度改造

官方 cookiecutter：
https://github.com/tiangolo/full-stack-fastapi-template
我們做了 3 個升級：

1. 默認 Python 3.12 + Pydantic v2.8
2. pyproject.toml + Poetry 鎖版本
3. 內置 pre-commit + ruff + mypy，Ctrl+S 自動格式化

2.1 一鍵克隆 & 運行

pip install cookiecutter
cookiecutter gh:vulcan2025/fastapi-2025-template --checkout v2.5
cd myapi && poetry install
make dev

# 4 分鐘后 http://localhost:8000/docs

3. 路由層：從路徑參數到依賴注入

3.1 RESTful 路由最佳實踐

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from app.db import get_session
from app.models import ItemCreate, ItemOut

router = APIRouter(prefix="/items", tags=["items"])@router.post("", response_model=ItemOut, status_code=201)
async def create_item(
    obj_in: ItemCreate,
    db: AsyncSession = Depends(get_session),
):
    item = await crud.item.create(db, obj_in)
    return item

亮點：
? Depends(get_session) 自動管理事務 & 連接池
? response_model=ItemOut 自動生成 JSON Schema

3.2 全局依賴：權限校驗

from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")

async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(status_code=401, detail="Invalid token")
    return await verify_token(token, credentials_exception)@router.get("/protected")
async def protected_route(user=Depends(get_current_user)):
    return {"hello": user.username}

4. 異步驗證：Pydantic v2.8 新魔法

4.1 字段級異步校驗

from pydantic import BaseModel, field_validator
from httpx import AsyncClient

class UserCreate(BaseModel):
    email: str    @field_validator("email")
    @classmethod
    async def email_must_be_unique(cls, v: str) - > str:
        async with AsyncClient() as client:
            res = await client.get(f"https://api.mailgun.net/validate/{v}")
            if res.json()["is_valid"] is False:
                raise ValueError("郵箱無效")
        return v

? FastAPI 原生支持 異步校驗器，無需同步阻塞
? 配合 rich 返回 422 詳細錯誤：

{
  "detail": [
    {"loc": ["body", "email"], "msg": "郵箱無效", "type": "value_error"}
  ]
}

5. 自動生成文檔：Swagger / ReDoc / Scalar 三殺

FastAPI 2.5 新增 Scalar 引擎，顏值炸裂：
http://localhost:8000/scalar

5.1 自定義文檔

from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html

app = FastAPI(
    title="2025 FastAPI 極速模板",
    description="一鍵高性能 RESTful API",
    version="2.5.0",
    docs_url=None,# 關閉默認
)@app.get("/docs", include_in_schema=False)
async def custom_swagger():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title="?? 2025 FastAPI 文檔",
        swagger_favicon_url="https://fastapi.tiangolo.com/img/favicon.png",
    )

6. 數據層：SQLModel + AsyncEngine 全異步

6.1 模型定義

from sqlmodel import SQLModel, Field
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession

DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/db"engine = create_async_engine(DATABASE_URL, echo=True)async def init_db():
    async with engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.create_all)async def get_session() - > AsyncSession:
    async with AsyncSession(engine) as session:
        yield session

6.2 事務回滾測試

@pytest.mark.asyncio
async def test_create_item_rollback(client: AsyncClient):

# 模擬異常
    with patch("app.crud.item.create", side_effect=Exception("boom")):
        res = await client.post("/items/", json={"name": "test"})
        assert res.status_code == 500

7. 安全加固：JWT + OAuth2 Password Flow

from datetime import datetime, timedelta
from jose import jwt

SECRET_KEY = "your-super-secret-key"
ALGORITHM = "HS256"def create_access_token(data: dict, expires_delta: timedelta = None):
    to_encode = data.copy()
    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=30))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

? 自動文檔顯示 Authorize 按鈕，支持 Swagger 直接登錄測試。

8. 測試體系：Pytest-asyncio + FastAPI TestClient

8.1 全程異步測試

from httpx import AsyncClient
import pytest

@pytest.mark.asyncio
async def test_read_item(ac: AsyncClient):
    res = await ac.get("/items/1")
    assert res.status_code == 200

運行：

make test

# 覆蓋率 98 %

9. 部署流水線：Docker、K8s、CI/CD 一網打盡

9.1 Dockerfile（多階段）

FROM python:3.12-slim AS builder
WORKDIR /code
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry install --no-dev

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /code/.venv /app/.venv
COPY app app
ENV PATH="/app/.venv/bin:$PATH"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]

鏡像大小僅 87 MB。

9.2 GitHub Actions CI/CD

name: Deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/build-push-action@v5
      - uses: azure/k8s-deploy@v1
        with:
          manifests: |
            k8s/deployment.yaml
            k8s/service.yaml

27 秒完成：代碼推送 → Docker 構建 → K8s 滾動更新。

10. 彩蛋：AI 自動生成用例 & 性能調優清單

10.1 AI 生成測試

pip install schemathesis
st run http://localhost:8000/openapi.json --checks all

自動生成 500+ 邊界用例，Ctrl+S 即回歸。

10.2 性能調優清單

一鍵體驗

git clone https://github.com/vulcan2025/fastapi-2025-template
cd fastapi-2025-template
make all

# 4 min 后訪問 http://localhost:8000/docs