https://github.com/twtrubiks/graphql-python-blog
練習 GraphQL-First TDD tutorial
https://github.com/twtrubiks/graphql-python-blog
fastapi graphql postgresql strawberry tdd-python
Last synced: 3 months ago
JSON representation
練習 GraphQL-First TDD tutorial
- Host: GitHub
- URL: https://github.com/twtrubiks/graphql-python-blog
- Owner: twtrubiks
- Created: 2025-10-05T06:30:05.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-10-05T06:32:31.000Z (3 months ago)
- Last Synced: 2025-10-05T08:33:30.057Z (3 months ago)
- Topics: fastapi, graphql, postgresql, strawberry, tdd-python
- Language: Python
- Homepage:
- Size: 328 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GraphQL Blog Platform
本專案目標是透過 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 測試客戶端
## 📋 專案文件
### 核心文件
| 文件 | 說明 | 用途 |
|------|------|------|
| [產品需求文件](./docs/prd.md) | 定義專案功能與需求 | 了解要做什麼 |
| [系統架構文件](./docs/architecture.md) | C4 模型架構圖與技術決策 | 了解怎麼做 |
| [任務清單](./docs/tasks.md) | 詳細的開發任務分解 | 追蹤執行進度 |
### 開發指南
| 文件 | 說明 | 用途 |
|------|------|------|
| [TDD 完整指南](./docs/tdd-guide.md) | 測試驅動開發實踐方法 | 學習 TDD 方法論 |
| [Alembic 指南](./docs/alembic-guide.md) | 資料庫遷移管理 | 管理資料庫版本 |
### GraphQL 專題
| 文件 | 說明 | 用途 |
|------|------|------|
| [DataLoader 實作](./docs/dataloader-implementation.md) | N+1 查詢問題解決方案 | 效能優化指南 |
| [Union Types 指南](./docs/union-types-guide.md) | GraphQL Union Types 完整說明 | 多型返回值處理 |
| [Fragment 指南](./docs/fragment-guide.md) | GraphQL Fragment 重用機制 | 減少重複查詢 |
| [權限控制指南](./docs/permissions-guide.md) | GraphQL 權限控制機制 | 實作授權與權限管理 |
| [Relay Connection Pattern](./docs/relay-connection-pattern.md) | 標準化分頁實作 | 實現游標分頁 |
### 參考資料
| 文件 | 說明 | 用途 |
|------|------|------|
| [GraphQL 介紹](./docs/graphql-intro.md) | GraphQL 基礎概念 | 入門學習 |
| [GraphQL vs REST](./docs/graphql-vs-rest.md) | API 設計比較 | 技術選型參考 |
### 專案模組文件
| 模組 | 文件連結 | 說明 |
|------|---------|------|
| 前端 | [Frontend README](./frontend/README.md) | SvelteKit + Houdini 前端專案 |
| 後端 | [Backend README](./backend/README.md) | FastAPI + Strawberry 後端專案 |
## 🚀 快速開始
### 環境需求
- Python 3.13+
- Node.js 22+
- Docker 和 Docker Compose
### 啟動
db `blog_db`
```bash
docker-compose up -d
```
後端
```bash
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](http://localhost:8000)
後端 API 文檔 [http://localhost:8000/docs](http://localhost:8000/docs)
GraphQL [http://localhost:8000/graphql](http://localhost:8000/graphql)
前端
```bash
cd frontend
npm install
# 確保後端已經運行, 目的是要產生 schema.graphql
npm run codegen:pull
npm run dev
```
前端入口 [http://localhost:5173](http://localhost:5173)
### 生成資料
會使用 db `blog_db`
```bash
cd backend
# 創建測試用戶和文章
python3 ../scripts/seed-data.py
```
## 測試執行
### 測試腳本
會使用 db `test_blog`
```bash
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"
```
### 測試標記
```python
@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** 開發方法：
1. **寫測試**：先寫 GraphQL API 測試
2. **實作功能**：實作 resolver 讓測試通過
3. **重構**：優化程式碼保持測試綠燈
4. **文件**：更新相關文件
## 核心功能
### ✅ 已實現功能
**後端 (90%+ 完成)**
- ✅ 完整的 GraphQL API (Query, Mutation, Subscription)
- ✅ JWT 認證授權系統
- ✅ 文章 CRUD 操作
- ✅ 評論系統（即時推送）
- ✅ 按讚和追蹤功能
- ✅ 標籤和搜尋系統
- ✅ DataLoader 優化（解決 N+1）
- ✅ WebSocket 即時通訊
- ✅ 完整的測試覆蓋
**前端 (60%+ 完成)**
- ✅ SvelteKit + Houdini 整合
- ✅ 用戶註冊和登入
- ✅ 文章瀏覽和發布
- ✅ 即時評論更新
- ✅ Svelte 5 Runes 響應式系統
### GraphQL API 範例
完整的 API 查詢範例請參考：[GraphQL 範例文檔](./docs/graphql-examples.md)
```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 查詢介面，支援即時文檔探索和查詢測試*
前端頁面
## Donation
文章都是我自己研究內化後原創，如果有幫助到您，也想鼓勵我的話，歡迎請我喝一杯咖啡 :laughing:
綠界科技ECPAY ( 不需註冊會員 )
[贊助者付款](http://bit.ly/2F7Jrha)
歐付寶 ( 需註冊會員 )
[贊助者付款](https://payment.opay.tw/Broadcaster/Donate/9E47FDEF85ABE383A0F5FC6A218606F8)
## 贊助名單
[贊助名單](https://github.com/twtrubiks/Thank-you-for-donate)