本專案目標是透過 Claude 學習, GraphQL API 和 Python 後端,
練習 GraphQL-First TDD 開發方法的最佳實.
建立一個功能完整的部落格平台，作為 GraphQL + Python 的教學範例，展示：
- GraphQL API 設計與實作
- Test-Driven Development (TDD) 實踐
- 現代化的前後端架構
- 向量搜尋與 AI 功能整合 (尚未實做)
- Python 3.13 - 最新版 Python
- FastAPI - 現代化 Web 框架
- Strawberry - Python GraphQL 函式庫
- 選擇理由：原生 Type Hints 支援、與 FastAPI 完美整合、簡潔的裝飾器語法
- 相比 Graphene 更現代化、更 Pythonic、開發效率更高
- SQLAlchemy 2.0 - ORM 與資料庫操作
- PostgreSQL 16 - 主要資料庫
- pgvector - 向量搜尋擴充套件（進階功能）(尚未實做)
- SvelteKit 2.41+ - 全端框架
- Svelte 5 - 使用最新的 Runes 系統
- Houdini v2.0.0-next.9 - GraphQL 客戶端（完整支援 Svelte 5）
- Tailwind CSS - 樣式框架
- Vite 7 - 建置工具
- pytest - 測試框架
- pytest-asyncio - 異步測試支援
- httpx - API 測試客戶端
| 文件 | 說明 | 用途 |
|---|---|---|
| 產品需求文件 | 定義專案功能與需求 | 了解要做什麼 |
| 系統架構文件 | C4 模型架構圖與技術決策 | 了解怎麼做 |
| 任務清單 | 詳細的開發任務分解 | 追蹤執行進度 |
| 文件 | 說明 | 用途 |
|---|---|---|
| TDD 完整指南 | 測試驅動開發實踐方法 | 學習 TDD 方法論 |
| Alembic 指南 | 資料庫遷移管理 | 管理資料庫版本 |
| 文件 | 說明 | 用途 |
|---|---|---|
| DataLoader 實作 | N+1 查詢問題解決方案 | 效能優化指南 |
| Union Types 指南 | GraphQL Union Types 完整說明 | 多型返回值處理 |
| Fragment 指南 | GraphQL Fragment 重用機制 | 減少重複查詢 |
| 權限控制指南 | GraphQL 權限控制機制 | 實作授權與權限管理 |
| Relay Connection Pattern | 標準化分頁實作 | 實現游標分頁 |
| 文件 | 說明 | 用途 |
|---|---|---|
| GraphQL 介紹 | GraphQL 基礎概念 | 入門學習 |
| GraphQL vs REST | API 設計比較 | 技術選型參考 |
| 模組 | 文件連結 | 說明 |
|---|---|---|
| 前端 | Frontend README | SvelteKit + Houdini 前端專案 |
| 後端 | Backend README | FastAPI + Strawberry 後端專案 |
- Python 3.13+
- Node.js 22+
- Docker 和 Docker Compose
db blog_db
docker-compose up -d後端
cd backend
# 設定你的環境
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-test.txt # 如果要跑測試
# migrate
alembic upgrade head
# 在 debug 中會自動 init_db()
uvicorn app.main:app --host 0.0.0.0 --port 8000
# 也可以使用 FastAPI CLI
# fastapi dev app/main.py後端 API http://localhost:8000
後端 API 文檔 http://localhost:8000/docs
GraphQL http://localhost:8000/graphql
前端
cd frontend
npm install
# 確保後端已經運行, 目的是要產生 schema.graphql
npm run codegen:pull
npm run dev會使用 db blog_db
cd backend
# 創建測試用戶和文章
python3 ../scripts/seed-data.py會使用 db test_blog
cd backend
# 建立 pytest 跑得測試 db
python3 ../scripts/setup-test-db.py
# 執行所有測試
pytest
=========== 229 passed in 94.34s (0:01:34) =======================
# 只執行 GraphQL 測試
pytest tests/graphql/
# 執行特定測試檔案
pytest tests/graphql/queries/test_post_queries.py
# 顯示覆蓋率
pytest --cov=app --cov-report=html
# 執行快速測試（跳過慢速測試）
pytest -m "not slow"@pytest.mark.slow # 慢速測試（如整合測試）
@pytest.mark.unit # 單元測試
@pytest.mark.integration # 整合測試
@pytest.mark.graphql # GraphQL API 測試GraphQL/
├── backend/
│ ├── app/
│ │ ├── api/ # API 端點
│ │ ├── graphql/ # GraphQL schema 和 resolvers
│ │ ├── models/ # SQLAlchemy models
│ │ ├── services/ # 業務邏輯
│ │ ├── core/ # 核心設定
│ │ └── utils/ # 工具函數
│ ├── tests/ # 測試檔案
│ ├── alembic/ # 資料庫遷移
│ └── requirements.txt
├── frontend/
│ ├── src/
│ │ ├── routes/ # SvelteKit 路由
│ │ ├── lib/ # 共用元件
│ │ └── $houdini/ # GraphQL 生成檔案
│ └── package.json
├── docker-compose.yml
└── docs/ # 專案文件
├── prd.md
├── architecture.md
└── tasks.md
本專案採用 GraphQL-First TDD 開發方法：
- 寫測試：先寫 GraphQL API 測試
- 實作功能：實作 resolver 讓測試通過
- 重構：優化程式碼保持測試綠燈
- 文件：更新相關文件
後端 (90%+ 完成)
- ✅ 完整的 GraphQL API (Query, Mutation, Subscription)
- ✅ JWT 認證授權系統
- ✅ 文章 CRUD 操作
- ✅ 評論系統（即時推送）
- ✅ 按讚和追蹤功能
- ✅ 標籤和搜尋系統
- ✅ DataLoader 優化（解決 N+1）
- ✅ WebSocket 即時通訊
- ✅ 完整的測試覆蓋
前端 (60%+ 完成)
- ✅ SvelteKit + Houdini 整合
- ✅ 用戶註冊和登入
- ✅ 文章瀏覽和發布
- ✅ 即時評論更新
- ✅ Svelte 5 Runes 響應式系統
完整的 API 查詢範例請參考：GraphQL 範例文檔
# 查詢文章列表
query GetPosts {
posts(limit: 10, status: PUBLISHED) {
edges {
node {
id
title
author {
username
}
likesCount
commentsCount
}
}
}
}
# 即時訂閱評論
subscription OnCommentAdded($postId: ID!) {
commentAdded(postId: $postId) {
id
content
author {
username
}
}
}GraphQL Playground
互動式 GraphQL 查詢介面，支援即時文檔探索和查詢測試
前端頁面
文章都是我自己研究內化後原創，如果有幫助到您，也想鼓勵我的話，歡迎請我喝一杯咖啡 😆
綠界科技ECPAY ( 不需註冊會員 )
歐付寶 ( 需註冊會員 )
