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 以前排除產物與秘密:
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"]
四個測試應全數通過。測試驗證計分意義與錯誤契約;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 協作實戰。
參考與來源¶
- 原始家教對話:Python 工程化基礎(chat4,整理於 2026-10-22);補齊原對話尚未提供的 package、測試與可靠性實作。
- Python 3.12:Modules
- Python 3.12:venv
- Python 3.12:dataclasses
- Python 3.12:logging
- pytest:Assertions