FastAPI API 實作:從 HTTP 請求走到履歷分析結果¶
摘要¶
GET /healthy 得到 404,和 /health 函式除以零得到 500,修正的位置不同。先追蹤請求經過哪個邊界,再加入資料驗證與業務邏輯,才能知道該修 URL、輸入格式,還是 Python 程式。
本章把第一章的比對核心接成完整記憶體 API。完成後能新增 route、分開 router/service/repository、處理 PATCH、保護資料端點,並用測試檢查 HTTP 契約。先完成 Git 分支練習,在練習專案的 feature branch 工作。
資料基準:2026-10-22。採 FastAPI 與 Pydantic 2 API;以下檔案均在 ai-job-application-assistant/ 內。
HTTP 方法與錯誤要一起設計¶
API key 這類 dependency 會先於 body 驗證執行:key 錯、body 也錯時,回的是 401,不是 422(FastAPI 0.159.1 實測)。
依賴與驗證可能在進入 endpoint 前就結束請求,不應假定所有失敗都經過 service。GET /health 只觀察狀態,不需 body;GET 的安全語意是讀取不要求改變資源。POST 用於建立或執行操作;PUT 通常完整替換,PATCH 只修改提供的欄位,DELETE 刪除。HTTP 方法的語意不會自動替應用完成冪等或權限管理。參考 HTTP Semantics。
| 情況 | 本系列回應 |
|---|---|
| 建立成功 | 201,帶新資源 ID |
| GET/PATCH 成功 | 200 |
| 規則無法分析,例如 JD 沒有已知技能 | 400 |
| 缺少或錯誤操作者 key | 401,帶 Bearer challenge |
| 路由不存在/資源不存在 | 404;兩者要靠 log 與 route 判斷 |
| 路徑存在但方法不支援 | 405 |
| email 或申請重複、資源所有者不一致 | 409 |
| 輸入型別、欄位限制不符 | 422 |
| 未處理程式錯誤/回應結構錯誤 | 500;修伺服器,不回傳 traceback 給 client |
安裝依賴與分層¶
啟用第一章的 venv 後執行:
python -m pip install fastapi 'pydantic[email]>=2,<3' uvicorn httpx httpx2
python -m pip freeze > requirements.txt
mkdir -p app/routers
touch app/routers/__init__.py
FastAPI 使用 Pydantic 處理輸入與輸出;EmailStr 另需 email 驗證套件,由 extra 安裝。以下用同步 def,FastAPI 會把同步 endpoint 放到 thread pool;直接從 async def 呼叫同步工具函式時,工具函式不會自動搬到 thread pool。計分若變成長時間 CPU 工作,應交給背景工作系統。參考 FastAPI async。
新版 Starlette 的 TestClient 已改以 httpx2 為主,舊 httpx 後端已標示 deprecated;這裡安裝 httpx2 供測試,另保留 httpx 給部署章的 HTTP 驗收工具。以 Starlette TestClient 文件與實際安裝版本核對,不只依賴仍示範舊後端的教學頁。
新增 app/errors.py:
class DomainError(Exception):
status_code = 400
class NotFound(DomainError):
status_code = 404
class Conflict(DomainError):
status_code = 409
class Unavailable(DomainError):
status_code = 503
新增 app/schemas.py:
from typing import Annotated
from pydantic import BaseModel, ConfigDict, EmailStr, Field, model_validator
ShortText = Annotated[str, Field(min_length=1, max_length=200)]
Document = Annotated[str, Field(min_length=1, max_length=20000)]
PositiveId = Annotated[int, Field(gt=0)]
class InputModel(BaseModel):
model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
class UserCreate(InputModel):
email: EmailStr
name: ShortText
class UserOut(UserCreate):
model_config = ConfigDict(extra="ignore")
id: int
class ResumeCreate(InputModel):
user_id: PositiveId
title: ShortText
text: Document
class ResumeOut(ResumeCreate):
model_config = ConfigDict(extra="ignore")
id: int
class ResumePatch(InputModel):
title: ShortText | None = None
text: Document | None = None
@model_validator(mode="after")
def reject_null_and_empty(self):
if not self.model_fields_set:
raise ValueError("provide at least one field")
if any(getattr(self, key) is None for key in self.model_fields_set):
raise ValueError("explicit null is not allowed")
return self
class JobCreate(InputModel):
user_id: PositiveId
company_name: ShortText
job_title: ShortText
description: Document
class JobOut(JobCreate):
model_config = ConfigDict(extra="ignore")
id: int
class ApplicationCreate(InputModel):
user_id: PositiveId
resume_id: PositiveId
job_description_id: PositiveId
class AnalysisOut(BaseModel):
score: float
matched_skills: list[str]
missing_skills: list[str]
class ApplicationOut(ApplicationCreate):
model_config = ConfigDict(extra="ignore")
id: int
status: str
match_score: float
analysis: AnalysisOut
輸入 model 拒絕未知欄位,輸出 model 則忽略 repository 額外回傳的欄位,例如第四章的 created_at。否則把 extra="forbid" 原封不動繼承到輸出,PostgreSQL 的完整資料列會觸發回應驗證錯誤。
Pydantic 預設可能轉換型別,例如把可解析的字串轉成整數;若契約要求禁止轉換,另用 strict 設定並加測試。extra="forbid" 拒絕未知欄位。PATCH 透過 model_dump(exclude_unset=True) 區分未提供與有提供的欄位,本系列再拒絕顯式 null,因為資料庫不允許清空它們。詳見 Pydantic models 與 FastAPI 部分更新。
記憶體 repository:先練契約¶
新增 app/repositories.py:
from copy import deepcopy
from threading import Lock
from app.errors import Conflict
class MemoryRepository:
def __init__(self):
self.tables = {name: {} for name in (
"users", "resumes", "job_descriptions", "applications"
)}
self.lock = Lock()
def create(self, table: str, data: dict) -> dict:
with self.lock:
rows = self.tables[table]
if table == "users" and any(
row["email"] == data["email"] for row in rows.values()
):
raise Conflict("email already exists")
if table == "applications" and any(
all(row[key] == data[key] for key in (
"user_id", "resume_id", "job_description_id"
)) for row in rows.values()
):
raise Conflict("application already exists")
row = {**deepcopy(data), "id": max(rows, default=0) + 1}
rows[row["id"]] = row
return deepcopy(row)
def get(self, table: str, record_id: int) -> dict | None:
with self.lock:
return deepcopy(self.tables[table].get(record_id))
def list_resumes(self, user_id: int, limit: int) -> list[dict]:
with self.lock:
rows = sorted(self.tables["resumes"].values(), key=lambda row: row["id"])
return deepcopy([r for r in rows if r["user_id"] == user_id][:limit])
def patch_resume(self, record_id: int, changes: dict) -> dict | None:
with self.lock:
row = self.tables["resumes"].get(record_id)
if row is None:
return None
row.update(changes)
return deepcopy(row)
鎖保護單次操作,並回傳副本,避免呼叫端直接改壞儲存內容。它沒有跨多個 method 的 transaction,也不跨 process 共用。重啟、reload 或開多 worker 都會產生資料遺失或彼此不同的狀態;這個階段只開一個 worker,第四章換成 PostgreSQL。
Service 保留產品規則¶
新增 app/services/assistant.py:
from dataclasses import asdict
from app.errors import Conflict, DomainError, NotFound
from app.services.matching import analyze_resume
class AssistantService:
def __init__(self, repository):
self.repository = repository
def get(self, table: str, record_id: int) -> dict:
row = self.repository.get(table, record_id)
if row is None:
raise NotFound("record not found")
return row
def create_user(self, data: dict) -> dict:
data = {**data, "email": str(data["email"]).strip().lower()}
return self.repository.create("users", data)
def create_resume(self, data: dict) -> dict:
self.get("users", data["user_id"])
return self.repository.create("resumes", data)
def create_job(self, data: dict) -> dict:
self.get("users", data["user_id"])
return self.repository.create("job_descriptions", data)
def patch_resume(self, record_id: int, changes: dict) -> dict:
row = self.repository.patch_resume(record_id, changes)
if row is None:
raise NotFound("resume not found")
return row
def create_application(self, data: dict) -> dict:
self.get("users", data["user_id"])
resume = self.get("resumes", data["resume_id"])
job = self.get("job_descriptions", data["job_description_id"])
if resume["user_id"] != data["user_id"] or job["user_id"] != data["user_id"]:
raise Conflict("resume and job must belong to the selected user")
try:
result = analyze_resume(resume["text"], job["description"])
except ValueError as exc:
raise DomainError(str(exc)) from exc
return self.repository.create("applications", {
**data, "status": "draft", "match_score": result.score,
"analysis": asdict(result),
})
Application 代表一份履歷對一份職缺的申請。本系列把同一組合限制為一筆;若產品允許多輪申請,應新增 attempt 或版本欄位,再改 unique 規則。分析存的是建立當下的結果,日後 PATCH 履歷不會改寫舊分數。並行修改時要對應更嚴格的版本快照,第四章會說明限制。
注入儲存與操作者憑證¶
新增 app/dependencies.py:
import os
import secrets
from typing import Annotated
from fastapi import Depends, HTTPException
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from app.repositories import MemoryRepository
memory = MemoryRepository()
bearer = HTTPBearer(auto_error=False)
def get_repository():
return memory
def require_api_key(
credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer)],
):
expected = os.environ["APP_API_KEY"]
valid = (
credentials is not None
and secrets.compare_digest(credentials.credentials.encode(), expected.encode())
)
if not valid:
raise HTTPException(
status_code=401, detail="invalid API key",
headers={"WWW-Authenticate": "Bearer"},
)
Depends 讓測試與後續資料庫章能替換 repository。HTTPBearer 解析 header 並讓 /docs 顯示授權入口;實際憑證判斷仍由應用完成。參考 FastAPI security tools。
這個 key 是單一操作者權限,可管理所有求職者。它不是每位 user 的登入 token,不能靠 body 裡的 user_id 授權;若發展成多人 SaaS,service 必須從可信登入憑證取得身分,再限制每筆讀寫。不要把這個操作者 key 放進公開前端 JavaScript。
Router 與入口¶
新增 app/routers/api.py:
from typing import Annotated
from fastapi import APIRouter, Depends, Path, Query
from app import schemas as s
from app.dependencies import get_repository, require_api_key
from app.services.assistant import AssistantService
router = APIRouter(dependencies=[Depends(require_api_key)])
RecordId = Annotated[int, Path(gt=0)]
def get_service(repository=Depends(get_repository)):
return AssistantService(repository)
Service = Annotated[AssistantService, Depends(get_service)]
@router.post("/users", response_model=s.UserOut, status_code=201)
def create_user(body: s.UserCreate, service: Service):
return service.create_user(body.model_dump())
@router.post("/resumes", response_model=s.ResumeOut, status_code=201)
def create_resume(body: s.ResumeCreate, service: Service):
return service.create_resume(body.model_dump())
@router.get("/resumes", response_model=list[s.ResumeOut])
def list_resumes(
service: Service,
user_id: Annotated[int, Query(gt=0)],
limit: Annotated[int, Query(ge=1, le=100)] = 20,
):
service.get("users", user_id)
return service.repository.list_resumes(user_id, limit)
@router.get("/resumes/{id}", response_model=s.ResumeOut)
def get_resume(id: RecordId, service: Service):
return service.get("resumes", id)
@router.patch("/resumes/{id}", response_model=s.ResumeOut)
def patch_resume(id: RecordId, body: s.ResumePatch, service: Service):
return service.patch_resume(id, body.model_dump(exclude_unset=True))
@router.post("/jobs", response_model=s.JobOut, status_code=201)
def create_job(body: s.JobCreate, service: Service):
return service.create_job(body.model_dump())
@router.get("/jobs/{id}", response_model=s.JobOut)
def get_job(id: RecordId, service: Service):
return service.get("job_descriptions", id)
@router.post("/applications", response_model=s.ApplicationOut, status_code=201)
def create_application(body: s.ApplicationCreate, service: Service):
return service.create_application(body.model_dump())
@router.get("/applications/{id}", response_model=s.ApplicationOut)
def get_application(id: RecordId, service: Service):
return service.get("applications", id)
新增 app/main.py:
import logging
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from app.errors import DomainError
from app.routers.api import router
@asynccontextmanager
async def lifespan(app: FastAPI):
if not os.environ.get("APP_API_KEY", "").strip():
raise RuntimeError("APP_API_KEY is required")
logging.basicConfig(level=logging.INFO)
yield
app = FastAPI(title="AI Job Application Assistant", lifespan=lifespan)
origins = [s.strip() for s in os.getenv("CORS_ORIGINS", "").split(",") if s.strip()]
if origins:
app.add_middleware(
CORSMiddleware, allow_origins=origins, allow_credentials=False,
allow_methods=["GET", "POST", "PATCH"],
allow_headers=["Authorization", "Content-Type"],
)
app.include_router(router)
@app.exception_handler(DomainError)
async def domain_error_handler(request: Request, exc: DomainError):
return JSONResponse(status_code=exc.status_code, content={"detail": str(exc)})
@app.get("/health")
def health_check():
return {"status": "ok", "service": "job-application-assistant"}
CORS 以 scheme、host、port 的組合判斷 origin,限制的是瀏覽器跨來源讀取,不能取代伺服器認證。預設不開跨來源存取;本機前端若是 http://localhost:5173,要明確加入 CORS_ORIGINS,http://127.0.0.1:5173 是另一個 origin。詳見 FastAPI CORS。
啟動與實際送請求¶
第一個終端啟用 venv,在根目錄執行;key 每次產生不同,不要提交:
export APP_API_KEY=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
app.main 是 module,冒號後的 app 是其中的 FastAPI 物件。ModuleNotFoundError 先查執行目錄、檔案與環境;--reload 只供開發。第二個終端需設定相同的 APP_API_KEY,不要重新產生另一把;在第二個終端以 export APP_API_KEY='同一把實際的 key' 設定。依序送請求:
curl -i http://127.0.0.1:8000/health
curl -i -H "Authorization: Bearer $APP_API_KEY" -H 'Content-Type: application/json' \
-d '{"email":"learner@example.com","name":"Learner"}' http://127.0.0.1:8000/users
curl -i -H "Authorization: Bearer $APP_API_KEY" -H 'Content-Type: application/json' \
-d '{"user_id":1,"title":"Backend Resume","text":"Python SQL Pandas"}' http://127.0.0.1:8000/resumes
curl -i -H "Authorization: Bearer $APP_API_KEY" -H 'Content-Type: application/json' \
-d '{"user_id":1,"company_name":"Example","job_title":"Backend Engineer","description":"Python SQL AWS Docker"}' http://127.0.0.1:8000/jobs
curl -i -H "Authorization: Bearer $APP_API_KEY" -H 'Content-Type: application/json' \
-d '{"user_id":1,"resume_id":1,"job_description_id":1}' http://127.0.0.1:8000/applications
curl -i -X PATCH -H "Authorization: Bearer $APP_API_KEY" -H 'Content-Type: application/json' \
-d '{"title":"Updated Resume"}' http://127.0.0.1:8000/resumes/1
curl -i -H "Authorization: Bearer $APP_API_KEY" 'http://127.0.0.1:8000/resumes?user_id=1&limit=20'
上例 ID 只在全新記憶體程序成立;已有資料時用實際回傳 ID。POST 應回 201;申請分數 50,PATCH 只改標題,履歷文字保留。也可開 /docs,在 Authorize 輸入 key,再用產生的 OpenAPI 文件呼叫。把 Python 物件回傳後,FastAPI 會驗證 response model、序列化並建立 HTTP response;函式 return 本身並不是網路傳輸。
自動驗證完整流程¶
新增 tests/test_api.py:
import pytest
from fastapi.testclient import TestClient
from app.dependencies import get_repository
from app.main import app
from app.repositories import MemoryRepository
@pytest.fixture
def client(monkeypatch):
monkeypatch.setenv("APP_API_KEY", "test-operator-key")
repository = MemoryRepository()
app.dependency_overrides[get_repository] = lambda: repository
try:
with TestClient(app) as client:
client.headers["Authorization"] = "Bearer test-operator-key"
yield client
finally:
app.dependency_overrides.clear()
def test_create_patch_and_analyze(client):
user = client.post("/users", json={"email": "learner@example.com", "name": "Learner"})
assert user.status_code == 201
uid = user.json()["id"]
resume = client.post("/resumes", json={"user_id": uid, "title": "Resume", "text": "Python SQL"})
assert resume.status_code == 201
rid = resume.json()["id"]
job = client.post("/jobs", json={
"user_id": uid, "company_name": "Example", "job_title": "Engineer",
"description": "Python SQL AWS Docker",
})
assert job.status_code == 201
data = {"user_id": uid, "resume_id": rid, "job_description_id": job.json()["id"]}
result = client.post("/applications", json=data)
assert result.status_code == 201
assert result.json()["match_score"] == 50.0
assert client.post("/applications", json=data).status_code == 409
patched = client.patch(f"/resumes/{rid}", json={"title": "Updated"})
assert patched.status_code == 200
assert patched.json()["text"] == "Python SQL"
assert client.get(f"/applications/{result.json()['id']}").json()["match_score"] == 50.0
def test_errors_and_auth(client):
assert client.get("/healthy").status_code == 404
assert client.get("/resumes/999").status_code == 404
assert client.get("/resumes/not-an-int").status_code == 422
assert client.post("/users", json={"email": "bad", "name": "A"}).status_code == 422
assert client.patch("/resumes/1", json={"text": None}).status_code == 422
assert client.patch("/resumes/1", json={}).status_code == 422
client.headers.pop("Authorization")
assert client.get("/resumes/1").status_code == 401
assert client.get("/health").status_code == 200
連同第一章應有六個測試通過。每個 API 測試使用全新 repository,不能依賴執行順序。測試預設會把未處理的伺服器例外重新拋給測試端;若刻意檢查 500 HTTP 回應,用 TestClient(app, raise_server_exceptions=False),並在 context manager 中啟動 lifespan。
常見錯誤與自我檢核¶
- [ ] 路由題:呼叫
/healthy、POST /health。預期分別 404、405,health_check()都不會以該方法執行。 - [ ] 驗證題:送空白文字、負數 ID、
limit=101。預期 422;將路徑參數、query 與 body 的來源說清楚。 - [ ] 商業規則題:建立兩位 user,混用其中一人的履歷與另一人的 job。預期 409;不存在的 user 先回 404。
- [ ] Bug 題:在暫時的測試 route 中除以零。預期 log 有 traceback,client 收到 500;完成後移除故障 route。
- [ ] 設計題:把同步 DB 呼叫改包在
async def。預期指出 event loop 仍會被阻塞,不能只改宣告。 - [ ] 實作題:新增 API 前,先寫 method、輸入、狀態碼、service 規則與測試。預期 router 不直接計分,也不自己操作 SQL。
下一步:PostgreSQL 設計與整合。
參考與來源¶
- 原始家教對話:開始學習 FastAPI API(chat6,整理於 2026-10-22);補齊原對話停在
/health後的全部資源流程。 - FastAPI:Tutorial
- FastAPI:Body Updates
- FastAPI:Testing
- FastAPI:Security Tools
- Pydantic:Models
