Community程式設計與開發github.com

Python 技能:避免靜默錯誤與專案建置

撰寫與除錯 Python 程式碼,特別留意那些會產生靜默錯誤行為的陷阱,例如可變預設值、晚期綁定閉包、淺層複製、被吞沒的例外等,並涵蓋型別標註、使用 uv 或 venv 的環境與套件管理,以及 pytest 測試結構。適用於撰寫 Python 腳本、服務或函式庫、設定 Python 專案,或除錯看似不可能發生的行為時。

Python 技能:避免靜默錯誤與專案建置 是什麼?

此技能提供一套完整的 Python 開發指引,重點在於避免那些不會引發錯誤、卻會導致行為異常的常見陷阱,例如可變預設引數、閉包晚期綁定、淺層複製、以及迭代時修改集合等問題。透過具體的程式碼範例與對比,幫助開發者撰寫更可靠且可預測的程式碼。 此外,技能也涵蓋專案環境與套件管理的最佳實務,強調使用虛擬環境(如 uv 或 venv)來隔離專案相依性,並透過 `pyproject.toml` 與鎖定檔案確保環境可重現。型別標註方面,提倡為函式邊界(參數與回傳值)加上型別,並在 CI 中執行型別檢查,避免標註過時成爲誤導文件。 此技能適用於任何 Python 開發情境,無論是撰寫腳本、服務或函式庫,都能協助開發者避開潛在的錯誤模式,建立穩固的專案基礎。其指引基於 Python 社群長期累積的經驗與慣例,能夠有效提升程式碼品質與開發效率。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-python

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Python

Python 容易撰寫,但也容易在不知不覺中出錯。以下內容涵蓋那些會靜默失敗的陷阱,以及能避免環境損毀的專案設定方式。

靜默失敗的陷阱

可變預設引數只會在定義時被評估一次,並在每次呼叫時共用:

def add(item, bucket=[]):   # 錯誤:bucket 在多次呼叫間持續存在
def add(item, bucket=None): # 正確
    bucket = [] if bucket is None else bucket

閉包會晚期綁定。 在迴圈中建立的 lambda 捕捉的是變數本身,而非其當下的值,因此每個 lambda 看到的都是最終的值。請使用預設引數或 functools.partial 來明確綁定。

is 是身分比較,而非相等比較。 它只適用於 None、True 和 False,對其他物件都不適用。它對小型整數或短字串看似有效,是因為這些物件被實習化(interned),這正是讓 Bug 在測試中存活下來的原因。

複製是淺層的。 list(xs)、xs[:] 和 dict(d) 只複製了容器本身,但元素仍被共用。巢狀結構需要使用 copy.deepcopy。

裸露的 except: 會捕捉所有例外,包括 KeyboardInterrupt 和 SystemExit。請捕捉特定的例外,且永遠不要寫 except Exception: pass——如果某個例外真的可以忽略,請記錄它並說明原因。

整數除法與浮點數相等比較。 / 總是產生浮點數;// 則會往負無窮大方向取整,因此 -7 // 2 的結果是 -4。絕對不要使用 == 比較浮點數;請使用 math.isclose,處理金錢相關則用 Decimal。

在迭代集合的同時對其進行修改會跳過元素。請建立一個新的列表,或迭代一個副本。

生成器只會被消耗一次。 對同一個生成器進行第二次迭代將不會產生任何結果,這會被解讀為空結果,而非錯誤。

環境與套件管理

永遠不要將套件安裝到系統直譯器中。請為每個專案建立一個虛擬環境並啟動它,或者讓 uv 來管理:

uv venv && uv pip install -e ".[dev]"     # 或:python -m venv .venv

在 pyproject.toml 中宣告相依性,並提交鎖定檔案(lock file),以確保環境可重現。包含未固定版本號的 requirements.txt 是無法重現的,並會在未來的機器上失效。

請固定專案所支援的 Python 版本,並在 pyproject.toml 中宣告。 Python 在不同次要版本之間的行為差異,比人們預期的還要大。

當某個模組在一個地方可以匯入,在另一個地方卻不行時,原因幾乎總是出在直譯器而不是程式碼。在除錯匯入問題前,請先檢查 which python 和 python -c "import sys; print(sys.executable)"。

型別

請為函式簽名加上型別標註——包括參數和回傳值。函式本體通常不需要標註,但邊界(介面)一定需要,因為那是其他程式碼所依賴的。

在 CI 中執行型別檢查器。未經驗證的標註會逐漸過時,變成誤導人的文件。

使用 X | None 而非傳統的「依慣例可選」方式,並讓可選性在簽名中清楚可見。優先使用具體的型別而非 Any;當型別確實未知時,請使用 unknown 的等義詞——object——並透過型別窄化(narrowing)來限定它,這樣型別檢查器會強制進行窄化。

對於結構化資料,優先使用 dataclass,或在資料從外部進入的邊界處使用驗證模型。在函式間傳遞的字典型別會在第一個拼寫錯誤時失去所有保證。

重要的慣用寫法

當需要進行映射或篩選時,使用推導式;當需要做其他事情時,使用迴圈。帶有副作用或包含三個子句的推導式,往往比它所取代的迴圈更難閱讀。

使用 pathlib.Path 而非字串路徑,並對任何需要關閉的東西——檔案、連線、鎖、臨時目錄——使用情境管理器(context manager)。

當輸入資料量很大或無上限時,從生成器中 yield 而非建立列表;這正是串流處理腳本與耗盡記憶體腳本之間的差異。

使用 enumerate、zip 以及帶有預設值的 dict.get,而非索引數學運算和成員資格檢查。它們更快,並且消除了某一類的「差一錯誤」(off-by-one)。

測試

使用 pytest 搭配單純的 assert。針對表格驅動的測試案例,請使用 @pytest.mark.parametrize,而非在一個測試函式中寫迴圈,這樣每個案例可以獨立回報結果。

將共用的設定放在 scope(作用域)最窄的 fixture 中。一個持有可變狀態的 session-scoped fixture 會在測試之間洩漏,並產生依賴執行順序的失敗。

使用 pytest.raises 來斷言特定的例外,並在必要時斷言其訊息內容。

效能(當它很重要時)

在最佳化之前先進行測量——使用 time.perf_counter 取得粗略數字,使用 cProfile 找出瓶頸所在。

通常的優化方式是將工作移出直譯器:使用內建函式、推導式、str.join 取代重複的字串串接、使用 set 或 dict 查詢取代掃描列表、或使用向量化函式庫進行數值運算。

對於 I/O 密集型並行處理,使用 asyncio 或執行緒;對於 CPU 密集型工作,請使用行程(process),因為全域直譯器鎖(GIL)會讓執行緒無法提供幫助。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

相關技能