Backend Silk:共享後端標準 是做什麼的?
以資深 Python 後端工程師的角色撰寫簡單、符合生產環境等級的程式碼。此技能旨在防止的兩種失敗是錯誤的結構(邏輯放在錯誤的分層,或存在不必要的檔案)和過度工程化(在應用程式運作之前就建立抽象層)。第三種較不明顯但同樣代價高昂的失敗是:重構時無聲地遺失原本可正常運作的行為。
搭配技能
命名規則:*-spider 技能用於建立特定類型的專案;*-silk 技能是每個 spider 都會使用的共享標準。此技能包含所有後端專案共同遵循的原則。請同時載入對應的搭配技能:
| 情境 | 同時使用 |
|---|---|
| Flask / FastAPI / Django 專案 | flask-spider / fastapi-spider / django-spider |
| Node.js / Express 專案 | node-spider(此處的規則同樣適用;Python 程式碼範例請參考 Python 部分) |
| MCP 伺服器或 MCP 用戶端 | mcp-spider |
| PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM、嵌入、向量儲存、RAG | rag-spider |
框架技能決定框架的實作細節;此技能決定架構原則。若兩者看似衝突,請在語法上遵循框架技能,在結構上遵循此技能。
修改程式碼之前
- 先閱讀實際程式碼。 檢查資料夾結構、模型、設定檔以及您即將修改的檔案。切勿猜測欄位名稱、函式簽章、檔案名稱或匯入路徑;請直接閱讀。(曾有人猜測
date而非實際的expense_date,結果一次破壞了 schema、輔助程式和回應。)若不確定已安裝函式庫的運作方式,請查閱其實際 API,而非自行假設。 - 先決定路由。 對於一項功能,請在實作之前列出每個端點(方法、路徑、請求、回應、狀態碼、驗證)。
- 範圍來自需求。 僅建構問題陳述所需的內容。未經要求的多餘端點、分析、快取、速率限制、重新排名、成本追蹤、下載/搜尋端點:僅以一行文字提及「可能之後再實作」,請勿實際建構。
- 保留正常運作的行為。 重寫函式時,請列出其目前的所有行為(篩選、分頁、驗證、日誌記錄、回應欄位),並確保新版本仍能完成這些行為。
分層架構
routes -> helpers -> services -> database / external systems
| |
utils utils
| 資料夾 | 負責 | 不得包含 |
|---|---|---|
routes/(Flask blueprints、FastAPI routers、Django views.py + urls.py、MCP tools/) | URL、方法、驗證依賴/裝飾器、狀態碼、回應模型、一次對輔助程式的呼叫 | 商業邏輯、查詢、驗證程式碼、try/except、日誌記錄 |
helpers/ | 單一功能的商業邏輯,類似控制器:超越 schema 的驗證、所有權檢查、特定功能的查詢與篩選、服務的編排、將預期失敗對應到 HTTP 錯誤、建構回應 | 開啟/關閉資料庫連線、commit/rollback、建立 LLM 或 SDK 用戶端 |
services/ | 每個外部系統或基礎設施元件:資料庫連線與通用 CRUD(db_service.py)、LLM、嵌入、向量儲存、PDF、電子郵件、另一個儲存庫的 API | 特定功能的商業規則、HTTP 知識(HTTPException、狀態碼)、對 helpers 的呼叫 |
utils/ | 被多個模組重複使用的基於類別的程式碼:LogUtils、ErrorHandlers、AuthUtils、純轉換器 | 僅被單一功能使用的程式碼、外部 API 呼叫 |
schemas/ | Pydantic 請求/回應模型(Django:serializers.py) | 資料庫模型 |
models/ | 持久化模型 | 商業邏輯 |
prompts/ | 以程式碼形式呈現的提示模板(僅在使用 LLM 時) | .env 中的提示 |
config.py | 從 .env 載入的單一設定物件 | 邏輯 |
根據上表衍生的規則:
- 方向是單向的。 Routes 呼叫 helpers,helpers 呼叫 services。Service 絕不呼叫 helper;utility 絕不呼叫 helper。
- 資料庫分離。 Helper 建構功能查詢(篩選、搜尋、所有權);DB service 執行這些查詢,並負責連線、連線階段、commit 和 rollback。詳細資訊請參閱
sql-silk/mongodb-silk。使用 Django 時,ORM 即為資料庫層,因此沒有db_service。 - 無穿堂層。 如果一個 helper 僅是將請求轉發給 service,請刪除該 helper 並直接呼叫 service。每個檔案都必須有其存在的價值。
- Utils 與 helpers 的區別。 在多處使用 →
utils/。僅被一個功能使用 → 該功能的 helper。 - 僅在真正需要時才建立資料夾和檔案,不要預先建立。一個函式絕不構成新建一個資料夾的理由(
errors/、exceptions.py、core/);請將其加入現有的合適類別中。 - 命名規則:
<domain>_routes.py(包含<domain>_router,或 Flask 中的<domain>_bp)、<domain>_helper.py→XHelper、<domain>_service.py→XService、<domain>_schema.py、<domain>_utils.py→XUtils、<name>_prompt.py→NAME_PROMPT。類別名稱必須與其資料夾名稱相符(例如,helpers/中的class ExpenseService是錯誤的)。
完整的資料夾職責與起始目錄結構:請參閱 references/architecture.md。
程式碼規則
- 基於類別的模組。 Helpers、services 和 utils 都是類別。對無狀態的程式碼使用
@staticmethod/@classmethod,僅在類別持有依賴(例如注入的連線階段或用戶端)時才使用實例。Route 檔案和 Django 的urls.py保持為模組層級。在沒有兩個實際實作的情況下,不要強制使用繼承、抽象基底類別或介面。 - 函式維持在約 40-50 行。 將長函式拆分為同一個類別中具有意義的方法(例如,
list_expenses→parse_filter_parameters+apply_expense_filters),而不是任意地切割。 - 函式名稱不能以
_開頭。函式內部不得定義函式。 透過明確的呼叫(例如app.add_exception_handler(...))來註冊處理常式,而不是使用巢狀的裝飾器函式。 - 所有匯入都放在檔案頂端,分組順序為:標準函式庫 → 第三方套件 →
app.*。透過將程式碼移至正確的模組來解決循環匯入,而不是在函式內部進行匯入。唯一的例外是 Flask blueprint 在create_app()內的匯入。 - 使用成熟的函式庫而非手寫邏輯:例如
password-validator、email-validator/EmailStr、PyJWT、bcrypt、LangChain 的載入器和分割器、httpx。 - 只驗證一次。 如果 Pydantic schema 已經強制執行某個規則,就不要在 helper 中再次檢查。
- 在單一請求中不要重複計算相同結果,並盡早失敗。 先執行成本較低的檢查,再執行成本較高的檢查(例如,先檢查電子郵件是否重複,再進行 bcrypt 雜湊運算)。
- 無硬編碼設定:URL、模型名稱、限制值、top_k、溫度設定和機密資料都來自
config.py。 - 無死碼:未使用的函式、未使用的匯入、空的佔位檔案以及
startapp的殘留檔案都應被移除。 - 每個類別和公開方法都應有型別提示和一行 documentation string。 僅在原因不明顯的地方加入註解。
- 絕不吞噬例外。 捕捉您可以處理的特定例外;讓其餘例外到達全域處理常式。
過度工程化檢查
在新增一個檔案、類別、層次、依賴項或模式之前,請捫心自問:當前的需求是否需要它,以及是否存在現有的事物已經能完成它?以下這些都是曾被建構而後被移除的案例:
- 在應用程式運行之前使用 pydantic-settings 或驗證框架(一個凍結的 dataclass 設定就足夠了)
- 為單一錯誤新增一個例外模組或類別
- 僅呼叫 service 的 helpers
- 在您擁有的兩個服務之間使用 RS256 金鑰對(一個 HS256 共享祕密就已足夠)
- 儲存衍生值(當輸入和輸出都存在時,儲存
total_tokens) - 使用兩個集合或資料表,但實際上一個帶有嵌入式列表的集合或資料表即可
- 過長的提示和過長的工具描述
當有多種設計方案可行時,請選擇最簡單但仍符合生產安全標準的那一個。
請求和回應 schema(摘要)
- 每個端點都應使用請求 schema 來驗證其主體和查詢參數,該 schema 會拒絕未知欄位和伺服器擁有的欄位;驗證後的程式碼僅使用驗證過的物件。
- 每個成功的回應都應從回應 schema 建構:資源本身(
XResponse)、列表{"items", "page", "page_size", "total", "total_pages"},或動作結果 schema(TokenResponse)。無信封結構,無在處理常式中組合的物件字面值。 - 狀態碼區分成功與失敗:200 代表讀取/更新、201 代表建立、204 代表刪除且無主體,錯誤時使用
ErrorResponse。絕不用 200 表示失敗。
完整的合約以及 schema 在不同框架中的位置:請參閱 references/api-design.md。
錯誤處理(摘要)
- 每個錯誤回應只有一種格式,來自
assets/common_schema.py:{"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(僅在有欄位錯誤時包含details) - Services 拋出一般或函式庫異常;Helpers 對預期的情況拋出 HTTP 錯誤;
utils/error_handlers.py中的ErrorHandlers類別負責對應依賴項的錯誤,並將其他所有錯誤捕捉為 500 錯誤。 - 狀態碼:400 錯誤輸入、401 未驗證、404 找不到或其他使用者的記錄、409 重複、413 內容過大、422 schema 驗證、424 我方依賴項故障(資料庫、向量儲存)、429 上游速率限制、502 上游回傳錯誤、503 其他服務無法連線、504 上游超時、500 非預期錯誤。絕不用 200 表示失敗。
- 使用者只會看到簡短的、安全的訊息,絕不會看到回溯追蹤、主機、連線字串或金鑰。
邊緣案例檢查清單和處理常式模式:請參閱 references/errors-and-edge-cases.md。儲存庫間的呼叫:請參閱 references/cross-repo-communication.md。
日誌記錄(摘要)
使用一個 LogUtils 類別(assets/log_utils.py),在啟動時根據 .env 中的 LOG_LEVEL 和 LOG_TO_FILE 設定一次;其他所有模組僅需執行 logger = LogUtils.get_logger(__name__)。格式為 %(asctime)s | %(levelname)s | %(name)s | %(message)s,訊息格式為 Event | key=value,不包含機密或個人資料,每個失敗僅記錄一次。詳細資訊:請參閱 references/logging.md。
設定與安全性(摘要)
config.py使用從.env載入的凍結 dataclass(assets/config.py);.env.example提交至版本控制,包含佔位符和註解(assets/env.example),.env絕不提交(assets/gitignore)。- 密碼:僅在註冊時使用
password-validator設定密碼政策,使用 bcrypt/werkzeug 進行雜湊,登入時使用通用的「電子郵件或密碼無效。」訊息。 - JWT:secret 來自
.env,使用者 ID 僅從驗證過的 token 中取得,絕不從請求主體中取得。 - 每個查詢都範圍限定於目前使用者;其他使用者的記錄回傳 404。
詳細資訊:請參閱 references/security.md。API 慣例(方法、分頁、過濾、搜尋參數):請參閱 references/api-design.md。
Git 與測試(摘要)
- 絕不提交:
.env、金鑰、憑證、上傳檔案、向量資料、本地資料庫、日誌、虛擬環境、產生的報告。資料庫遷移檔案應與產生它們的模型變更一起提交。 - 提交訊息遵循 Conventional Commits 規範(
feat:、fix:、refactor:、chore:、test:、docs:、perf:),每次提交只關注一個事項,每個儲存庫一個提交。 - 測試涵蓋關鍵路徑:驗證、使用者間的所有權、驗證、錯誤回應、依賴項故障(模擬)。外部服務(LLM、其他儲存庫)應使用模擬。
- 評估(黃金資料集、評估腳本、報告)僅在明確要求時才存在;請參閱
rag-spider/mcp-spider。
詳細資訊:請參閱 references/git-and-testing.md。
程式碼檢查清單
- 分層架構符合規範;無穿堂檔案;類別名稱與資料夾名稱相符
- 無底線開頭或巢狀函式;匯入皆位於檔案頂端;函式不超過約 50 行
- 保留現有行為(篩選、分頁、驗證、回應欄位)
- 每個端點都有請求 schema 和回應 schema;無臨時建構的回應物件
- 處理
references/errors-and-edge-cases.md中定義的邊緣案例,並使用正確的狀態碼 - 新的設定已加入
config.py和.env.example;無硬編碼;程式碼或日誌中無機密資訊 - 在合適的位置加入日誌記錄,並使用正確的層級
- 無未使用的匯入或殘留的死碼
參考文件(僅在需要時閱讀)
| 檔案 | 閱讀時機 |
|---|---|
references/architecture.md | 建立專案、新增功能資料夾、不確定程式碼歸屬時 |
references/errors-and-edge-cases.md | 撰寫端點、錯誤處理常式或審查失敗路徑時 |
references/cross-repo-communication.md | 一個服務呼叫另一個儲存庫、MCP 伺服器或外部 API 時 |
references/logging.md | 設定或審查日誌記錄時 |
references/security.md | 處理驗證、密碼、JWT、上傳、機密、CORS 時 |
references/api-design.md | 設計端點、請求/回應 schema、分頁、過濾、搜尋時 |
references/git-and-testing.md | 處理提交、PR 描述、永不提交的內容、測試、除錯方法時 |
資產檔案(複製到專案中並進行調整)
選擇性地複製模板:僅保留此專案目前會用到的部分(.gitignore 的段落、.env.example 的金鑰、設定欄位)。專案中不存在的功能所遺留的行數是冗餘的,會誤導之後的閱讀者。
| 檔案 | 成為 |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore(「Always」區塊加上僅有標記的適用區塊) |