跳轉到

Python 工程化基礎:把履歷分析寫成可測試的套件

摘要

履歷分析函式如果同時讀檔、計分、寫資料庫與寄信,測一次分數也可能寄出郵件。本章先把計算留在純函式,把檔案與顯示交給呼叫端,完成 AI Job Application Assistant 的第一個可執行版本。

完成後能建立 Python package、用 dataclass 回傳結構、替錯誤輸入定義例外,並以測試確認技能比對。已會 pandas、迴圈與基本函式即可開始。系列總覽列出後續 API、資料庫與部署成果。

資料基準:2026-10-22。以下範例採 Python 3.12;使用標準函式庫,測試工具另裝 pytest。

先把責任與資料契約寫清楚

分析腳本常由作者檢查結果;長期服務則要讓其他程式能使用結果、辨認錯誤。兩者都可以有良好結構,差別在於輸入是否受控、是否要多人維護,以及失敗後由誰處理。

函式或邊界 負責 不應順便執行
read_resume() 讀取 UTF-8 文字檔 計分、吞掉檔案錯誤
normalize_text() 統一大小寫與空白 寫檔
extract_resume_skills() 找出履歷提到的已知技能 判定錄取機率
extract_required_skills() 找出職缺提到的已知技能 從全域變數讀取別份 JD
calculate_match_score() 依技能集合算百分比 再次解析履歷、print、存 DB
analyze_resume() 串接解析、比對與計分 寄信
後續 repository/email client 儲存結果/傳送郵件 改變計分規則

履歷與 JD 的解析目前共用同一個 helper,仍保留兩個領域入口。日後 JD 要區分「必要」與「加分」條件,可以單獨替換。這比一開始複製兩份相同解析器容易維護。

本章規則刻意簡單:字典中的技能只要出現在 JD 就視為需求,否定句與加分條件也會被算入。分數是「命中需求技能數/需求技能數 × 100」,不是錄取機率,也不是語意理解。沒有辨認出需求時拒絕計分,避免讓 0 分混淆「不符合」與「無法分析」。

建立隔離環境與套件

在自己的練習目錄執行:

mkdir ai-job-application-assistant
cd ai-job-application-assistant
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install pytest
python -m pip freeze > requirements.txt
mkdir -p app/services tests
touch app/__init__.py app/services/__init__.py

python -m pip 使用目前 Python 對應的 pip。.venv 隔離已安裝套件;它不會固定套件版本,也不會隨 Git 搬到其他電腦。pip freeze 記錄目前環境實際安裝版本,應在乾淨環境產生。這份簡單快照未鎖定下載雜湊、作業系統與 CPU 架構;Docker 章會再處理執行環境。詳見 Python venv 教學。

新增 .gitignore,在第一次 commit 以前排除產物與秘密:

.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.env
.env.*
!.env.example

app 與 app.services 都有 __init__.py,形成一般 package。從根目錄執行 python -m app.cli,Python 才能沿模組路徑找到它。不要靠修改 sys.path 或把模組命名成 json.py、logging.py 解決 import 問題。

完整比對核心

新增 app/services/matching.py:

import re
from dataclasses import dataclass

KNOWN_SKILLS = frozenset({"python", "sql", "pandas", "aws", "docker"})


@dataclass(frozen=True)
class AnalysisResult:
    score: float
    matched_skills: list[str]
    missing_skills: list[str]


def normalize_text(text: str) -> str:
    return " ".join(text.casefold().split())


def extract_skills(text: str, vocabulary: frozenset[str]) -> list[str]:
    normalized = normalize_text(text)
    return sorted(
        skill for skill in vocabulary
        if re.search(rf"(?<!\w){re.escape(skill)}(?!\w)", normalized)
    )


def extract_resume_skills(text: str) -> list[str]:
    return extract_skills(text, KNOWN_SKILLS)


def extract_required_skills(text: str) -> list[str]:
    return extract_skills(text, KNOWN_SKILLS)


def calculate_match_score(
    matched_skills: list[str], required_skills: list[str]
) -> float:
    required = {normalize_text(s) for s in required_skills}
    matched = {normalize_text(s) for s in matched_skills}
    if not required or "" in required or "" in matched:
        raise ValueError("skills must be non-blank; required_skills cannot be empty")
    if not matched <= required:
        raise ValueError("matched_skills must be a subset of required_skills")
    return len(matched) / len(required) * 100.0


def analyze_resume(resume_text: str, job_description: str) -> AnalysisResult:
    if not normalize_text(resume_text) or not normalize_text(job_description):
        raise ValueError("resume_text and job_description cannot be blank")
    required = extract_required_skills(job_description)
    available = set(extract_resume_skills(resume_text))
    matched = sorted(available.intersection(required))
    return AnalysisResult(
        score=calculate_match_score(matched, required),
        matched_skills=matched,
        missing_skills=sorted(set(required) - available),
    )

原始對話直接用兩個 list 的長度相除,遇到重複技能或非需求技能會失真,甚至超過 100 分。這裡先正規化、去重,再驗證子集合。matched_skills 已經是輸入,計分函式不再偷讀未定義的 resume_text。

skill in text 會把 sql 誤配到 postgresql;此處用字元邊界避免這種子字串誤判。它仍有語言限制:連寫的中英文、同義詞與縮寫需要另訂規則。技能陣列排序後,API 與測試才有穩定順序。

dataclass 產生初始化與屬性等樣板,普通型別提示供 IDE 與靜態檢查器使用,兩者都不會自動驗證執行期輸入。frozen=True 阻止欄位重新賦值,但內部 list 仍可修改。第三章 API 會以 Pydantic 驗證外部輸入;核心保持不依賴 HTTP。參考 dataclasses 與 型別提示。

檔案、JSON、例外與 logging 放在呼叫端

新增 app/cli.py:

import json
import logging
import sys
from dataclasses import asdict
from pathlib import Path

from app.services.matching import analyze_resume

logger = logging.getLogger(__name__)


def read_resume(path: Path) -> str:
    return path.read_text(encoding="utf-8")


def main() -> int:
    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s %(message)s")
    if len(sys.argv) != 3:
        logger.error("usage: python -m app.cli RESUME_FILE JOB_FILE")
        return 2
    try:
        result = analyze_resume(
            read_resume(Path(sys.argv[1])),
            Path(sys.argv[2]).read_text(encoding="utf-8"),
        )
    except (OSError, UnicodeError, ValueError) as exc:
        logger.error("analysis failed: %s", exc)
        return 1
    print(json.dumps(asdict(result), ensure_ascii=False))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

建立兩個虛構文字檔並執行:

printf '%s\n' 'Data Analyst with Python, SQL and Pandas experience.' > resume.txt
printf '%s\n' 'We require Python, SQL, AWS and Docker.' > job.txt
python -m app.cli resume.txt job.txt

預期 JSON 的 score 是 50.0,matched_skills 是 python, sql,missing_skills 是 aws, docker。dataclass 先經 asdict() 才送給 JSON encoder;直接 json.dumps(result) 會出現 TypeError。

logging 預設寫 stderr,成果 JSON 寫 stdout,便於管線接續處理。只在程式入口設定 handler,模組內取 logger 即可;不要逐層重複加 handler。這裡的錯誤文字不含履歷內容,API 章也不會把 request body 寫入 log。新增 resume.txt、job.txt 若包含真實資料,應留在 repo 外。

用測試確認契約

新增 tests/test_matching.py:

import pytest

from app.services.matching import analyze_resume, calculate_match_score


def test_half_of_required_skills_match():
    result = analyze_resume("Python SQL Pandas", "Python SQL AWS Docker")
    assert result.score == 50.0
    assert result.matched_skills == ["python", "sql"]
    assert result.missing_skills == ["aws", "docker"]


def test_empty_requirements_are_rejected():
    with pytest.raises(ValueError, match="required_skills"):
        calculate_match_score([], [])


def test_duplicates_do_not_inflate_score():
    assert calculate_match_score(["Python", "python"], ["python", "SQL"]) == 50.0
    with pytest.raises(ValueError, match="subset"):
        calculate_match_score(["aws"], ["python"])


def test_substring_is_not_a_skill_match():
    result = analyze_resume("PostgreSQL", "SQL")
    assert result.score == 0.0
    assert result.missing_skills == ["sql"]
python -m pytest -q
python -m compileall -q app

四個測試應全數通過。測試驗證計分意義與錯誤契約;compileall 只能抓語法錯誤,抓不到未執行路徑裡的 NameError。若失敗,先讀 traceback 最後的例外,再沿 stack 找回自己程式的行號。必要時在該行前用 breakpoint() 檢查變數,而不是加上 except: pass。

環境變數、class 與 async 的使用時機

AnalysisResult(...) 建立一個物件,每次結果各自保存狀態。第三章的 repository class 會持有儲存狀態;純計算仍用函式。我會在需要一起管理資料與生命週期時才用 class。

設定由執行環境提供。第三章會以 os.environ["APP_API_KEY"] 要求必要憑證,缺少就啟動失敗;.env 只是文字檔,Python 不會自動讀它。不要把預設真實金鑰寫進程式。

HTTP 是跨程序邊界,JSON 是其中一種資料格式。第三章啟動服務後,可用這段標準函式庫程式讀取健康狀態,並限制等待時間:

import json
from urllib.request import urlopen

with urlopen("http://127.0.0.1:8000/health", timeout=5) as response:
    payload = json.load(response)
assert payload["status"] == "ok"

呼叫 async def 函式只產生 coroutine 物件,需由 await、asyncio.run() 或 task 排程驅動執行。把同步網路呼叫、time.sleep() 或 CPU 密集計算放進 async def,不會自動讓它們不阻塞。第三章先用同步 def endpoint 配同步 repository;有支援非同步的 I/O client 時再採 async,並明確處理 timeout。詳見 FastAPI 的同步與非同步說明。

常見錯誤與自我檢核

現象 原因與修正
SyntaxError 出現在 ValueError(...) 訊息要加引號;return 要放在函式縮排內
NameError: resume_text 函式用了未傳入、也未定義的變數;修正責任與參數
不同機器匯入結果不同 確認啟用的環境、執行目錄、模組命名與依賴檔
回傳只有分數 API 還需要命中與缺漏;回傳具名結構
所有錯誤都回空結果 保留可預期的例外,讓邊界決定如何呈現
  • [ ] Bug 題:把需求改成空集合。預期是明確 ValueError,不能出現除以零。
  • [ ] 補程式題:為無命中但有需求的案例加測試。預期 0 分,所有需求都在缺漏清單。
  • [ ] 設計題:加入寄信功能。預期新增獨立 client,不改 calculate_match_score() 的副作用。
  • [ ] 實作題:從乾淨 venv 以 python -m pip install -r requirements.txt 重裝,執行 CLI 與測試。預期得到相同的四個測試結果與 50 分 JSON。

下一步:Git 協作實戰。

參考與來源