FastAPI 自動續簽 Token 與刷新機制詳解：讓用戶登錄更持久！
作者：Ss肥魚
Refresh Token 是一種用于刷新 Access Token 的憑證。它不用于訪問受保護資源，只用于生成新的 Access Token。
在 Web 應用中，JWT（JSON Web Token）常用于身份認證。但 JWT 通常有固定的過期時間，一旦過期就會導致用戶強制重新登錄 —— 這顯然影響體驗。
解決方案？
引入 Refresh Token（刷新令牌）機制，實現 Access Token 的自動續簽！
一句話理解 Refresh Token
Refresh Token 是一種用于刷新 Access Token 的憑證。 它不用于訪問受保護資源，只用于生成新的 Access Token。
整體流程圖
登錄成功后返回：
├── access_token（短期有效） → 用于訪問接口
└── refresh_token（長期有效） → 用于刷新 access_token
?? 客戶端邏輯：
1. 每次請求攜帶 access_token
2. 如果接口返回 401（token 過期）：
- 使用 refresh_token 請求刷新接口，換一個新的 access_token
- 自動重試原請求數據模型設計
新增 refresh_token 存儲字段（也可以存 Redis 中）。
models/user.py 示例： from tortoise import fields, models
from tortoise import fields, models
class User(models.Model):
id = fields.IntField(pk=True)
username = fields.CharField(max_length=50, unique=True)
hashed_password = fields.CharField(max_length=128)
refresh_token = fields.CharField(max_length=512, null=True) # 新增JWT 工具函數封裝（包含 refresh 支持）
from jose import jwt
from datetime import datetime, timedelta
SECRET_KEY = "your-access-token-secret"
REFRESH_SECRET = "your-refresh-token-secret"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 15
REFRESH_TOKEN_EXPIRE_DAYS = 7
def create_access_token(data: dict, expires_delta: timedelta = None):
to_encode = data.copy()
expire = datetime.utcnow() + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
def create_refresh_token(data: dict):
expire = datetime.utcnow() + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
to_encode = data.copy()
to_encode.update({"exp": expire})
return jwt.encode(to_encode, REFRESH_SECRET, algorithm=ALGORITHM)
def verify_refresh_token(token: str):
try:
payload = jwt.decode(token, REFRESH_SECRET, algorithms=[ALGORITHM])
return payload
except Exception:
return None登錄接口返回雙 token
@router.post("/login")
async def login(user: UserLoginSchema):
user_obj = await authenticate(user.username, user.password)
if not user_obj:
raise HTTPException(status_code=401, detail="賬號或密碼錯誤")
data = {"sub": user_obj.username, "uid": user_obj.id}
access_token = create_access_token(data)
refresh_token = create_refresh_token(data)
# 保存 refresh_token 到數據庫
user_obj.refresh_token = refresh_token
await user_obj.save()
return {
"access_token": access_token,
"refresh_token": refresh_token,
"token_type": "bearer"
}提供刷新接口 /refresh
@router.post("/refresh")
async def refresh_token(refresh_token: str = Body(...)):
payload = verify_refresh_token(refresh_token)
if not payload:
raise HTTPException(status_code=401, detail="Refresh token 失效")
# 確認數據庫中 refresh_token 是否匹配（防止偽造）
user = await User.get(id=payload["uid"])
if user.refresh_token != refresh_token:
raise HTTPException(status_code=401, detail="Refresh token 不合法")
new_token = create_access_token({"sub": user.username, "uid": user.id})
return {"access_token": new_token, "token_type": "bearer"}小結
結合兩個 token，我們實現了：
- 安全性：短時 Access Token 暴露后影響有限
- 易用性：Refresh Token 自動續期，無需頻繁登錄
責任編輯：趙寧寧
來源：
Ssoul肥魚
