## 🛠️ 核心技能與知識體系

### Flask 應用架構（Application Factory Pattern）

```python
# app/__init__.py — 標準 Application Factory
from flask import Flask
from app.config import config_by_name
from app.extensions import db, migrate, login_manager, cors

def create_app(config_name: str = 'development') -> Flask:
    app = Flask(__name__)
    app.config.from_object(config_by_name[config_name])

    # 初始化擴展
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)
    cors.init_app(app, resources={r"/api/*": {"origins": "*"}})

    # 註冊 Blueprints
    from app.routes.auth import auth_bp
    from app.routes.api import api_bp
    app.register_blueprint(auth_bp, url_prefix='/auth')
    app.register_blueprint(api_bp, url_prefix='/api/v1')

    # 註冊 CLI 指令
    register_commands(app)

    # 註冊錯誤處理
    register_error_handlers(app)

    return app
```

### 推薦專案結構

```
flask_project/
├── app/
│   ├── __init__.py          # create_app() 工廠函式
│   ├── config.py            # 環境設定類別
│   ├── extensions.py        # 擴展實例化（避免循環引用）
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── base.py          # 共用 Mixin（TimestampMixin 等）
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── auth.py          # 認證 Blueprint
│   │   └── api.py           # API Blueprint
│   ├── services/
│   │   ├── __init__.py
│   │   └── user_service.py  # 業務邏輯層
│   ├── schemas/
│   │   └── user_schema.py   # Marshmallow 序列化
│   └── utils/
│       ├── decorators.py    # 自訂裝飾器（權限檢查等）
│       └── responses.py     # 統一 JSON 回應格式
├── migrations/              # Flask-Migrate (Alembic)
├── tests/
│   ├── conftest.py          # pytest fixtures（app, client, db）
│   ├── test_auth.py
│   └── test_api.py
├── .env.example
├── .flaskenv
├── requirements.txt
├── wsgi.py                  # 生產環境入口
└── run.py                   # 開發環境入口
```

### 擴展選型指南

| 需求 | 推薦擴展 | 備註 |
|------|----------|------|
| ORM | Flask-SQLAlchemy 3.x | 搭配 Flask-Migrate 管理 schema 變更 |
| 表單驗證 | Flask-WTF | CSRF 保護內建 |
| API 序列化 | Flask-Marshmallow 或 Pydantic | REST API 推薦 Pydantic v2 |
| 認證 | Flask-Login（Session）/ PyJWT（Token） | 前後端分離用 JWT |
| CORS | Flask-CORS | 注意 `supports_credentials` 設定 |
| 快取 | Flask-Caching | 支援 Redis、Memcached backend |
| 速率限制 | Flask-Limiter | 基於 Redis 的分散式限流 |
| 背景任務 | Celery + Redis/RabbitMQ | 長時間任務、定時任務 |
| WebSocket | Flask-SocketIO | 需搭配 eventlet 或 gevent |
| 郵件 | Flask-Mail | 搭配 Celery 異步發送 |
| 管理後台 | Flask-Admin | 快速搭建內部管理介面 |

### RESTful API 設計規範

```python
# 統一回應格式
def success_response(data=None, message="OK", status_code=200):
    return jsonify({"success": True, "data": data, "message": message}), status_code

def error_response(message, status_code=400, errors=None):
    return jsonify({"success": False, "message": message, "errors": errors}), status_code

# 標準 CRUD 路由命名
# GET    /api/v1/users          → 列表
# POST   /api/v1/users          → 建立
# GET    /api/v1/users/<id>     → 詳情
# PUT    /api/v1/users/<id>     → 完整更新
# PATCH  /api/v1/users/<id>     → 部分更新
# DELETE /api/v1/users/<id>     → 刪除
```

### 資料庫最佳實踐

- 使用 SQLAlchemy 2.0 風格的 `Mapped` 型別提示與 `mapped_column`。
- 所有 model 繼承共用 `BaseModel`，內建 `id`、`created_at`、`updated_at`。
- 遷移流程：`flask db migrate -m "description"` → 審查 migration 檔案 → `flask db upgrade`。
- 避免 N+1 查詢：使用 `joinedload()` 或 `selectinload()` eager loading。

### 認證授權模式

**Session-based（傳統 Web App）**
```python
from flask_login import LoginManager, login_required, current_user

@login_manager.user_loader
def load_user(user_id):
    return User.query.get(int(user_id))
```

**JWT-based（前後端分離 API）**
```python
from functools import wraps
from flask import request, g
import jwt

def token_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        if not token:
            return error_response('Missing token', 401)
        try:
            g.current_user = jwt.decode(token, current_app.config['JWT_SECRET'], algorithms=['HS256'])
        except jwt.InvalidTokenError:
            return error_response('Invalid token', 401)
        return f(*args, **kwargs)
    return decorated
```

### 測試策略

```python
# tests/conftest.py
import pytest
from app import create_app
from app.extensions import db

@pytest.fixture
def app():
    app = create_app('testing')
    with app.app_context():
        db.create_all()
        yield app
        db.session.remove()
        db.drop_all()

@pytest.fixture
def client(app):
    return app.test_client()

@pytest.fixture
def auth_headers(client):
    """取得已認證的請求標頭"""
    response = client.post('/auth/login', json={'email': 'test@example.com', 'password': 'password'})
    token = response.json['data']['token']
    return {'Authorization': f'Bearer {token}'}
```

### 生產環境部署

```dockerfile
# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt gunicorn
COPY . .
EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "--timeout", "120", "wsgi:app"]
```

```python
# wsgi.py
from app import create_app
app = create_app('production')
```

**Gunicorn 調校參考**：
- Workers 數量：`2 * CPU核心數 + 1`
- 搭配 Nginx 反向代理處理靜態檔案與 SSL 終止
- 使用 Docker Compose 編排：`web`（Gunicorn）+ `db`（PostgreSQL）+ `redis`（快取/任務佇列）

### 效能優化清單

1. **快取**：`@cache.cached(timeout=300)` 快取高頻讀取端點。
2. **資料庫連線池**：設定 `SQLALCHEMY_ENGINE_OPTIONS = {'pool_size': 10, 'max_overflow': 20}`。
3. **回應壓縮**：使用 `Flask-Compress` 啟用 gzip。
4. **靜態資源**：生產環境交由 Nginx/CDN 處理，不走 Flask。
5. **Profiler**：開發環境使用 `flask-debugtoolbar` 或 `py-spy` 定位瓶頸。