fastapi-templates

## fastapi-templates skill 概覽

fastapi-templates 是用來生成可上線的 FastAPI 專案結構的 skill，內建 async 模式、依賴注入、middleware 與錯誤處理慣例。它最適合需要乾淨起手式的後端工程師，尤其在意可維護的目錄配置、分層架構（API → services → repositories）與可預期的可擴展性。

### fastapi-templates 能幫你建立什麼
使用 fastapi-templates 可以草擬完整專案骨架，包含清楚的 app/ 目錄、版本化路由、Pydantic schemas，以及將商業邏輯與資料存取分離。

### 最適合的使用者與工作目標
這個 skill 面向想要可重複使用的 FastAPI 起始模板、偏好 async-first 慣例、且重視結構化藍圖勝過單檔 Demo 的開發者。

### 相較泛用 FastAPI prompt 的差異點
這個 skill 強調一致的專案布局、使用 `Depends` 的 DI，以及偏向 production 的關注點分離，而不是隨手的 endpoint 範例。

### 不適合使用 fastapi-templates 的情況
如果你只需要極小的 proof-of-concept 或單一 endpoint，完整結構可能反而拖慢速度。

## 如何使用 fastapi-templates skill

### fastapi-templates 安裝與呼叫方式
安裝與呼叫：
`npx skills add https://github.com/wshobson/agents --skill fastapi-templates`

### 讓 skill 發揮效果的必要輸入
提供你的 API 範圍、資料庫選擇（例如 PostgreSQL、MongoDB）、同步或非同步偏好，以及你預期的高階領域模組（users、auth、items）。

### 把模糊目標變成強 prompt
弱： “Create a FastAPI project.”
強： “Create a FastAPI project scaffold for a multi-tenant SaaS. Use async, PostgreSQL, versioned API routes, and a user/auth module. Include `api/v1/endpoints`, `services`, `repositories`, `schemas`, and DI with `Depends`.”

### fastapi-templates 使用建議流程
1. 用清楚的架構簡述執行 skill。  
2. 檢視產生的 `app/` 目錄樹，依你的領域調整命名。  
3. 確認路由布局後，再補上真正的 models 與依賴連線。

### 優先閱讀的 repository 檔案
先看 `SKILL.md`，了解預期的專案結構與依賴注入模式。

### 提升輸出品質的實用技巧
- 指定資料庫類型，讓 scaffold 反映正確的 async 套件。  
- 列出核心模組（users、auth、items），幫助端點目錄成形。  
- 如果預期 API 會演進，請要求版本化路由（`api/v1`）。

## fastapi-templates skill 常見問題

### fastapi-templates 是用於 API 開發還是僅限 scaffold？
它主要用於快速且結構化的 scaffolding。商業邏輯與持久層仍需自行實作。

### 初學者可以用 fastapi-templates skill 嗎？
可以，但需已熟悉 FastAPI 基礎。此布局比教學更進階，並假設你了解 DI 與 schemas。

### fastapi-templates 和一般 FastAPI prompt 相比如何？
一般 prompt 常產生單檔 Demo。這個 skill 會推進成 production 等級的結構，具有清楚分層與目錄慣例。

### 如果我的專案是同步的呢？
你可以要求同步模式，但此 skill 最佳化的是 async FastAPI 與高效能 API 使用情境。

## 如何改善 fastapi-templates skill

### 事先提供領域導向模組
列出具體模組（users、auth、billing、inventory）。可讓 scaffold 更貼近真實領域，減少後續重構。

### 明確指定資料層限制
說明 PostgreSQL 或 MongoDB、ORM 或 raw SQL、以及 async drivers。這會影響 repositories 與資料庫設定的位置與方式。

### 避免過度 scaffolding
若你的 MVP 很小，可要求精簡布局（例如省略 repositories 或 services），避免不必要的複雜度。

### 第一版 scaffold 後再迭代
檢視生成的資料夾樹後，提出明確調整，例如「合併 `repositories` 和 `services`」或「現在就加入 `api/v2`」。

### 常見失敗模式要避免
- 需求含糊會產生泛化結構。  
- 未命名模組會導致 placeholder 檔案。  
- 忽略 DI 慣例會讓後續依賴接線不一致。

### fastapi-templates 提升輸出品質指南
在 prompt 裡加入簡短「架構規則」段落，例如：「Pydantic schemas 放在 `schemas/`、models 放在 `models/`、DI 放在 `dependencies.py`，所有 endpoints 放在 `api/v1/endpoints/`。」