跳轉到

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 方法與錯誤要一起設計

FastAPI 請求流程:找路由、檢查 API key、驗證輸入、服務層、回傳 JSON,前四步各有提早結束的錯誤碼

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
python -m pytest -q

連同第一章應有六個測試通過。每個 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 設計與整合。

參考與來源