FastAPI 中 JWT 的基本使用与实践

1. 引言JWTJSON Web Token是目前最流行的无状态认证方案之一。在 FastAPI 中结合python-jose与passlib可以快速实现基于 JWT 的用户认证与授权。本文将从零开始带你掌握 FastAPI 中 JWT 的基本使用与实践。2. 环境准备首先安装所需依赖pipinstallfastapi uvicorn python-jose[cryptography]passlib[bcrypt]python-multipart各依赖的作用如下fastapiWeb 框架。uvicornASGI 服务器用于运行应用。python-jose负责 JWT 的生成与校验。passlib用于密码哈希配合bcrypt算法。python-multipart处理 OAuth2 表单登录请求。3. JWT 核心概念JWT 由三部分组成用点号分隔header.payload.signatureHeader声明令牌类型与签名算法。Payload存放用户信息与过期时间等声明。Signature由 Header、Payload 与密钥共同签名生成用于防篡改。JWT 是无状态的服务端无需保存会话信息令牌本身携带了用户身份适合分布式与前后端分离场景。4. 项目结构我们采用清晰的分层结构project/ ├── main.py # 应用入口 ├── auth.py # JWT 与密码工具 ├── schemas.py # Pydantic 模型 └── requirements.txt # 依赖清单5. 编写认证工具模块创建auth.py封装密码哈希与 JWT 生成、校验逻辑fromdatetimeimportdatetime,timedeltafromtypingimportOptionalfromjoseimportJWTError,jwtfrompasslib.contextimportCryptContext# 密钥与算法配置生产环境务必使用环境变量保存密钥SECRET_KEYyour-secret-key-change-meALGORITHMHS256ACCESS_TOKEN_EXPIRE_MINUTES30pwd_contextCryptContext(schemes[bcrypt],deprecatedauto)defverify_password(plain_password:str,hashed_password:str)-bool:校验明文密码与哈希是否匹配returnpwd_context.verify(plain_password,hashed_password)defget_password_hash(password:str)-str:生成密码哈希returnpwd_context.hash(password)defcreate_access_token(data:dict,expires_delta:Optional[timedelta]None)-str:生成 JWT 访问令牌to_encodedata.copy()expiredatetime.utcnow()(expires_deltaortimedelta(minutesACCESS_TOKEN_EXPIRE_MINUTES))to_encode.update({exp:expire})returnjwt.encode(to_encode,SECRET_KEY,algorithmALGORITHM)defdecode_token(token:str)-Optional[dict]:解析并校验 JWT失败返回 Nonetry:returnjwt.decode(token,SECRET_KEY,algorithms[ALGORITHM])exceptJWTError:returnNone6. 定义 Pydantic 模型创建schemas.pyfrompydanticimportBaseModelclassToken(BaseModel):登录成功返回的令牌access_token:strtoken_type:strbearerclassUserCreate(BaseModel):注册请求体username:strpassword:strclassUserOut(BaseModel):用户信息响应体username:str7. 编写主应用创建main.py实现注册、登录与受保护接口fromtypingimportOptionalfromfastapiimportDepends,FastAPI,HTTPException,statusfromfastapi.securityimportOAuth2PasswordBearer,OAuth2PasswordRequestFormfromauthimportcreate_access_token,decode_token,get_password_hash,verify_passwordfromschemasimportToken,UserCreate,UserOut appFastAPI(titleJWT 实践示例)# 模拟用户存储生产环境请使用数据库fake_users_db{}# OAuth2 密码模式从 Authorization 头提取 Bearer Tokenoauth2_schemeOAuth2PasswordBearer(tokenUrl/login)app.post(/register,response_modelUserOut)defregister(user:UserCreate):用户注册ifuser.usernameinfake_users_db:raiseHTTPException(status_code400,detail用户名已存在)fake_users_db[user.username]get_password_hash(user.password)returnUserOut(usernameuser.username)app.post(/login,response_modelToken)deflogin(form_data:OAuth2PasswordRequestFormDepends()):用户登录返回 JWThashedfake_users_db.get(form_data.username)ifnothashedornotverify_password(form_data.password,hashed):raiseHTTPException(status_codestatus.HTTP_401_UNAUTHORIZED,detail用户名或密码错误,headers{WWW-Authenticate:Bearer},)tokencreate_access_token({sub:form_data.username})returnToken(access_tokentoken)app.get(/users/me,response_modelUserOut)defread_current_user(token:strDepends(oauth2_scheme)):受保护接口解析令牌并返回当前用户payloaddecode_token(token)ifpayloadisNoneorpayload.get(sub)isNone:raiseHTTPException(status_codestatus.HTTP_401_UNAUTHORIZED,detail无效或过期的令牌,headers{WWW-Authenticate:Bearer},)usernamepayload[sub]ifusernamenotinfake_users_db:raiseHTTPException(status_code404,detail用户不存在)returnUserOut(usernameusername)8. 运行与测试启动服务uvicorn main:app--reload8.1 注册用户curl-XPOST http://127.0.0.1:8000/register\-HContent-Type: application/json\-d{username: alice, password: secret123}8.2 登录获取令牌curl-XPOST http://127.0.0.1:8000/login\-HContent-Type: application/x-www-form-urlencoded\-dusernamealicepasswordsecret123返回示例{access_token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...,token_type:bearer}8.3 访问受保护接口curlhttp://127.0.0.1:8000/users/me\-HAuthorization: Bearer 你的access_token9. 完整流程图失败成功无效/过期有效客户端发起登录POST /login校验用户名密码返回 401生成 JWT返回 access_token客户端携带 Token 请求受保护接口服务端解析并校验 JWT令牌有效?返回 401返回用户数据10. 实践建议与安全注意事项密钥管理SECRET_KEY务必通过环境变量或密钥管理服务注入切勿硬编码在代码中。过期时间根据业务设置合理的exp敏感操作可配合刷新令牌Refresh Token机制。密码存储使用bcrypt等强哈希算法切勿明文存储。HTTPS生产环境必须启用 HTTPS防止令牌在传输中被窃取。权限控制可在 Payload 中加入role字段结合依赖注入实现基于角色的访问控制RBAC。11. 总结本文从环境搭建、核心概念到完整代码带你走通了 FastAPI 中 JWT 的基本使用与实践。通过python-jose生成与校验令牌、passlib管理密码哈希再配合 FastAPI 的OAuth2PasswordBearer依赖注入即可快速构建安全可靠的无状态认证体系。后续可在此基础上扩展刷新令牌、角色权限与数据库持久化打造更完善的生产级认证方案。