什么是 FastAPI‑Login？
你可能听说过 Flask‑Login，FastAPI‑Login 基本上是它的“兄弟”。它帮你在 FastAPI 项目里搞定 JWT（Json Web Token）生成、校验、存取，甚至还能直接把 token 放进 Cookie，省去自己写一堆鉴权代码的麻烦。说白了，它就是「登录管理器」，让你专注业务，而不是在登录细节里纠结。
它解决了哪些痛点？
| 痛点 | 传统做法 | FastAPI‑Login 的解决方案 |
|---|---|---|
| 手写 JWT 编码/解码 | 要自己写 pyjwt、设置过期、处理异常 | 一行代码 manager.create_access_token，自动加盐、加密、校验 |
| 登录状态保存 | 用 Session、数据库或自行实现 Cookie | 支持 Header 与 Cookie 双模式，use_cookie=True 直接把 token 放进安全 Cookie |
| 鉴权依赖注入 | 每个路由都要手写 Depends，容易忘记 | 只要 Depends(manager)，自动把用户对象注入进来 |
| 异常统一处理 | 每次抛 HTTPException，代码冗余 | 自定义 not_authenticated_exception，统一跳转或返回错误 |
| Token 过期管理 | 手动算时间、写 timedelta | create_access_token(..., expires=timedelta(...))，默认 15 分钟，灵活配置 |
安装 & 入门
pip install fastapi-login
小技巧：想要一个安全的
SECRET，直接跑python -c "import secrets, sys; sys.stdout.write(secrets.token_hex(24))"。
一步步搞定
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordRequestForm
from fastapi_login import LoginManager
from fastapi_login.exceptions import InvalidCredentialsException
SECRET = "你的-secret-key"
app = FastAPI()
manager = LoginManager(SECRET, token_url="/auth/token", use_cookie=True) # 想用 Cookie 就加这行
# 假装有个用户库
fake_db = {"alice@example.com": {"password": "123456"}}
@manager.user_loader()
def load_user(email: str):
return fake_db.get(email)
@app.post("/auth/token")
def login(data: OAuth2PasswordRequestForm = Depends()):
user = load_user(data.username)
if not user or data.password != user["password"]:
raise InvalidCredentialsException
access_token = manager.create_access_token(data={"sub": data.username})
return {"access_token": access_token, "token_type": "bearer"}
@app.get("/protected")
def protected(user=Depends(manager)):
return {"msg": f"你好，{user['email']}，这里是受保护的资源"}
- • Header 方式：直接在
Authorization: Bearer <token>里带 token。 - • Cookie 方式：
manager.set_cookie(response, token)，前端不需要手动加 Header，浏览器会自动带上。
优缺点一览
| 优点 | 缺点 |
|---|---|
| ✅ 只需几行代码即可完成完整的登录/鉴权流程 | ⚠️ 只实现了基于 JWT 的方案，若想要 OAuth2、SSO 需要自行扩展 |
| ✅ 支持 Header 与 Cookie 双模式，灵活适配前端 | ⚠️ 对于大规模用户管理，仍然需要自行接入数据库/ORM |
| ✅ 自动处理 token 过期、异常统一 | ⚠️ 默认 token 只存邮箱（sub），如果业务需要更复杂的 payload，需要自行改写 |
| ✅ 与 FastAPI 的依赖注入体系无缝衔接 | ⚠️ 文档相对简洁，细节（如刷新 token）需要自行实现 |
小结
FastAPI‑Login 真的是「登录即插即用」的好帮手。它把最常见的 JWT 生成、校验、Cookie 存取全包装好，让你几分钟就能搞定登录鉴权。对于中小型项目，它几乎是开箱即用；如果你要做更复杂的权限体系，仍然可以在它的基础上继续扩展。总之，想省事儿、想代码干净、想安全可靠，FastAPI‑Login 值得一试。
