REST API 的無狀態原則：為什麼這個觀念如此重要

有狀態互動（錯誤示範）：
  請求 1: "登入，我是 Alice"
  伺服器: "好的，我記住你了"
  請求 2: "顯示我的訂單"
  伺服器: "你是 Alice，這是你的訂單"
  
無狀態互動（REST 方式）：
  請求 1: "登入，我是 Alice，密碼是 xxx"
  伺服器: "驗證成功，這是你的 token: abc123"
  請求 2: "顯示訂單，我的 token 是 abc123"
  伺服器: "token 有效，這是 Alice 的訂單"

有狀態系統的困境：
  Client A → Server 1（記住了 A）
  Client A → Server 2（不認識 A）❌
  
  解決方案：
  - Session Sticky（會話黏性）
  - Session 共享
  → 複雜且限制擴展

無狀態系統的優勢：
  Client A + Token → Server 1 ✓
  Client A + Token → Server 2 ✓
  Client A + Token → Server N ✓
  → 任意擴展，無需同步

有狀態架構複雜度：
  - 需要 Session 儲存（Redis/資料庫）
  - 需要 Session 同步機制
  - 需要處理 Session 過期
  - 需要清理孤兒 Session

無狀態架構：
  - 每個請求獨立
  - 無需額外儲存
  - 自然的請求隔離

# 有狀態的設計（違反 REST 原則）
class StatefulAPI:
    def __init__(self):
        self.user_sessions = {}  # 伺服器端儲存狀態
    
    @app.route('/login', methods=['POST'])
    def login(self):
        username = request.json['username']
        password = request.json['password']
        
        if authenticate(username, password):
            session_id = generate_session_id()
            # 錯誤：在伺服器端保存狀態
            self.user_sessions[session_id] = {
                'username': username,
                'login_time': datetime.now()
            }
            return {'session_id': session_id}
    
    @app.route('/profile')
    def get_profile(self):
        session_id = request.headers.get('Session-ID')
        # 錯誤：依賴伺服器端狀態
        if session_id in self.user_sessions:
            username = self.user_sessions[session_id]['username']
            return get_user_profile(username)
        return {'error': 'Not authenticated'}, 401

# 無狀態的設計（符合 REST 原則）
import jwt
from datetime import datetime, timedelta

SECRET_KEY = 'your-secret-key'

@app.route('/login', methods=['POST'])
def login():
    username = request.json['username']
    password = request.json['password']
    
    if authenticate(username, password):
        # 生成 JWT token，包含所有必要資訊
        payload = {
            'username': username,
            'exp': datetime.utcnow() + timedelta(hours=24),
            'iat': datetime.utcnow()
        }
        token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')
        return {'token': token}
    
    return {'error': 'Invalid credentials'}, 401

@app.route('/profile')
def get_profile():
    auth_header = request.headers.get('Authorization')
    if not auth_header or not auth_header.startswith('Bearer '):
        return {'error': 'No token provided'}, 401
    
    token = auth_header.split(' ')[1]
    try:
        # 從 token 中解析所有需要的資訊
        payload = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
        username = payload['username']
        return get_user_profile(username)
    except jwt.ExpiredSignatureError:
        return {'error': 'Token expired'}, 401
    except jwt.InvalidTokenError:
        return {'error': 'Invalid token'}, 401

JWT Token 結構：
Header:
  {
    "alg": "HS256",
    "typ": "JWT"
  }

Payload:
  {
    "sub": "1234567890",
    "name": "Alice Chen",
    "role": "admin",
    "iat": 1516239022,
    "exp": 1516325422
  }

Signature:
  HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    secret
  )

GET /api/users/123/orders?page=2&limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Accept: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

資源狀態（Resource State）：
  - 儲存在伺服器端
  - 例如：用戶資料、訂單資料
  - 這些是持久化的業務資料

應用狀態（Application State）：
  - 儲存在客戶端
  - 例如：當前頁面、認證令牌
  - 不應該存在伺服器端

客戶端可以：
  - 儲存 Token（localStorage/Cookie）
  - 自動附加到每個請求
  - 用戶體驗與有狀態系統相同

伺服器端：
  - 不儲存會話
  - 但可以驗證 Token
  - 從 Token 中獲取用戶資訊

1. 水平擴展：
   - 輕鬆增加伺服器
   - 無需考慮會話同步
   - 負載均衡簡單

2. 容錯性：
   - 伺服器故障不影響用戶
   - 無縫故障轉移
   - 高可用性

3. 快取友好：
   - 請求可以被完整快取
   - CDN 可以快取 API 回應
   - 提升效能

4. 簡化部署：
   - 無需處理會話遷移
   - 滾動更新容易
   - 藍綠部署簡單

5. 除錯容易：
   - 每個請求獨立
   - 容易重現問題
   - 日誌分析簡單

✅ 每個請求是否包含所有必要資訊？
✅ 移除這個伺服器，請求能被其他伺服器處理嗎？
✅ 重啟伺服器後，客戶端需要重新操作嗎？
✅ 是否依賴伺服器端的臨時儲存？

Step 1: 識別狀態依賴
  - Session 中儲存了什麼？
  - 哪些是認證資訊？
  - 哪些是臨時資料？

Step 2: 選擇無狀態方案
  - JWT for 認證
  - URL parameters for 分頁
  - Request body for 複雜狀態

Step 3: 客戶端調整
  - 儲存和管理 Token
  - 在每個請求中包含必要資訊

Step 4: 逐步遷移
  - 新 API 使用無狀態
  - 舊 API 逐步改造
  - 保持向後相容

# JWT 最佳實踐
def create_token(user):
    payload = {
        'user_id': user.id,
        'username': user.username,
        'roles': user.roles,
        'exp': datetime.utcnow() + timedelta(hours=1),  # 短期有效
        'iat': datetime.utcnow(),
        'jti': str(uuid.uuid4())  # 唯一標識，用於撤銷
    }
    return jwt.encode(payload, SECRET_KEY, algorithm='HS256')

# Token 黑名單（用於登出）
@app.route('/logout', methods=['POST'])
def logout():
    token = get_token_from_header()
    payload = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
    
    # 將 token 加入黑名單
    redis.setex(
        f"blacklist:{payload['jti']}", 
        payload['exp'] - time.time(),
        '1'
    )
    return {'message': 'Logged out successfully'}