一、用户模块ORM模型相关知识点
1. User 用户表模型
- 字段约束要点
-
username设置唯一索引,保证数据库用户名不能重复,注册重复会触发数据库完整性异常。 - 密码字段绝对不能存储明文,存储bcrypt加密之后的哈希字符串,字段长度需要足够容纳加密结果。
-
avatar、nickname、bio、gender、phone均为可选字段,允许为空,设置业务默认值。 -
created_at、updated_at设置自动时间,新增/更新自动维护时间戳。
-
-
__table_args__:定义索引,用户名、手机号建立唯一索引,提升查询速度,同时数据库层面强制唯一性。
2. UserToken 用户令牌表模型
- 作用:保存用户登录生成的token、所属用户id、过期时间,实现登录状态持久化。
- 索引配置
- token字段建立唯一索引,根据token查询用户效率极高。
-
user_id建立普通外键索引,关联User用户表。
- 关键字段
-
token:登录凭证字符串; -
user_id:外键关联用户主键; -
expires_at:token过期时间,业务逻辑可以用来判断令牌是否失效。
-
业务逻辑:每次登录生成新token存入本表;接口鉴权时根据请求头的token查询本表,校验是否存在、是否过期,再拿到对应的用户信息。
二、密码加密 passlib‑bcrypt
1. 安装依赖
pip install "passlib[bcrypt]==1.7.4"
指定固定版本避免版本更新带来的加密算法兼容性问题。
2. CryptContext加密上下文
- 上下文对象统一管理加密算法配置,全局只实例化一次。
-
schemes=["bcrypt"]:指定使用bcrypt哈希算法;bcrypt是单向哈希,不可逆向解密。 -
deprecated="auto":自动处理废弃算法。
3. 两个核心方法
-
pwd_context.hash(明文密码):传入原始明文,返回加密后的哈希字符串。注册时使用,存入数据库。 -
pwd_context.verify(明文密码,数据库哈希密码):比对明文和数据库存储哈希,返回布尔True/False。登录校验密码使用。
⚠️重点:数据库永远不保存明文密码;就算数据库泄露,攻击者也无法直接拿到用户原始密码。bcrypt单向哈希,不能解密还原原始密码。
三、Token身份认证机制
1. HTTP无状态特性
HTTP协议本身是无状态,服务器不会记住上一次请求是谁。需要借助Token实现登录身份识别。
2. Token概念
Token是服务器生成的随机字符串,下发给客户端;客户端后续每一次请求带上该字符串,服务器识别这个字符串代表哪一个登录用户。
3. UUID生成Token
str(uuid.uuid4()):生成随机不重复字符串,作为登录令牌。
本项目实现:token存储在MySQL
user_token表,不是JWT;属于数据库存储式令牌。
4. Token请求头传输格式
Authorization: Bearer <token字符串>
-
Authorization:HTTP标准请求头,专门携带身份凭证。 -
Bearer:固定关键字,代表持有者令牌,后面空格拼接真实token值。
5. FastAPI获取请求头参数
from fastapi import Header
authorization: str = Header(...),从请求头读取Authorization字段。拿到字符串后需要分割,去掉Bearer前缀,得到纯token。
6. 鉴权业务流程
- 接口请求携带Authorization请求头;
- 后端取出token,查询
user_token表; - 判断token是否存在、是否超过过期时间;
- 校验通过,拿到关联user_id,查询用户完整信息;
- 校验失败直接抛出异常,拒绝访问接口。>
保护接口:获取个人信息、修改资料、修改密码都必须走这套鉴权逻辑。
四、Pydantic请求、响应模型分层思想
-
请求模型(Request):接收前端post/put提交的json参数,做字段校验、长度校验。
-
UserRegisterRequest:注册入参(username、password) -
UserLoginRequest:登录入参 -
UserUpdateRequest:更新用户信息入参,所有字段全部非必填,实现局部更新 -
UserChangePwdRequest:修改密码入参(旧密码、新密码)
-
- 响应模型(Response):控制返回给前端的字段,过滤数据库敏感字段(例如密码哈希绝对不能返回前端)。
- 基础基类复用:
UserInfoBase抽取公共用户返回字段,其他响应模型继承基类,减少重复代码。
注意:v1版本使用
class Config: orm_mode=True,直接把ORM对象交给pydantic模型解析。
五、封装统一成功响应工具函数
1. 作用
整个项目所有接口返回格式统一:{"code":200,"message":"xxx","data":xxx},方便前端统一解析处理。
2. jsonable_encoder
- 很多对象不能直接转JSON:ORM模型对象、datetime时间对象、Pydantic模型实例。
-
fastapi.encoders.jsonable_encoder():把上述特殊对象转换成Python基础类型(字典、字符串),保证可以被JSON序列化。
3. 函数模板逻辑
def success_response(message: str = "success", data=None):
content = {"code": 200, "message": message, "data": data}
return JSONResponse(content=jsonable_encoder(content))
业务接口不要直接return字典,调用该工具函数返回响应。
六、全局异常处理器
1. 概念
FastAPI应用级别注册的异常捕获函数。当接口内部代码抛出异常,会交给对应处理器处理,返回统一格式JSON,而不是返回默认500堆栈HTML页面。
2. 不同异常分类
-
HTTPException:业务代码主动抛出的业务异常,例如:token无效、用户名密码错误。 -
IntegrityError:数据库完整性约束异常,比如用户名重复(唯一索引冲突)、外键约束失败。 -
SQLAlchemyError:所有数据库相关父类异常,数据库连接、SQL执行出错都会触发。 -
Exception:兜底处理器,捕获所有其他未被处理的异常。
3. 注册方式
app.add_exception_handler(异常类, 处理函数)
注册顺序:子类异常先注册,父类异常放后面;父类写前面会拦截掉子类异常,导致细分处理器不会执行。
4. DEBUG_MODE调试开关
-
DEBUG_MODE=True开发环境:返回完整错误详情、堆栈信息、请求路径,方便排查bug。 -
DEBUG_MODE=False生产环境:只返回简短提示,不对外暴露内部报错细节,保障安全。
5. traceback模块
traceback.format_exc(),格式化异常堆栈为字符串,用于开发环境返回或者记录日志。
七、用户模块各个接口业务逻辑要点
1. 用户注册 POST /api/user/register
- 使用Pydantic模型接收前端用户名密码;
- 查询数据库判断用户名是否已经存在;存在抛出异常;
- 将明文密码通过bcrypt加密;
- 创建User模型对象,存入数据库;
- uuid生成token,创建UserToken记录存入数据库;
- 返回token和用户信息,密码哈希绝对不能返回前端。
两种重复用户名报错来源:①代码手动查询判断抛出;②数据库唯一索引触发IntegrityError全局异常捕获。
2. 用户登录 POST /api/user/login
- Pydantic接收用户名、明文密码;
- 查询User表,根据username拿到用户以及数据库存储的加密密码;查不到抛出账号错误;
-
pwd_context.verify()校验传入明文密码和数据库哈希;校验失败抛出密码错误; - 生成新的uuid token,写入user_token表;
- 返回token与用户信息。
3. 获取用户信息 GET /api/user/info
- 需要鉴权,从请求头拿到Authorization token;
- 校验token有效性、是否过期;
- 查询用户数据,过滤掉密码字段,返回用户个人资料。
4. 更新用户信息 PUT /api/user/update
- 需要token鉴权,识别当前登录用户;
- 请求模型字段全部非必填,支持只传部分字段做局部更新;
- ORM update更新数据库用户表对应字段;
- 返回更新后的用户信息。
5. 修改密码 PUT /api/user/password
- 需要token鉴权;
- 接收旧密码、新密码;
- verify校验旧密码是否和数据库存储哈希匹配;
- 将新密码加密,update更新user表password字段。
八、分层开发流程回顾(用户模块复用)
- routers层定义APIRouter,编写接口装饰器,接收请求参数;
- schemas编写Request、Response Pydantic模型;
- models编写ORM数据表模型;
- crud封装数据库查询新增更新逻辑;
- 接口函数Depends注入db会话;鉴权逻辑封装成Depends依赖;
- 调用工具函数
success_response()返回统一格式; - main.py注册路由、注册全局异常处理器、配置CORS中间件。
九、依赖注入扩展:鉴权封装为Depends
鉴权逻辑可以封装成一个async函数,内部读取Header、查询token、校验、返回当前登录用户对象。
接口中:
async def func(db:AsyncSession=Depends(get_db), current_user:User = Depends(get_current_user))
优势:所有需要登录的接口,只需要写一行Depends,不需要每个接口重复写token解析查询代码。鉴权失败会直接抛出异常,接口业务代码不会执行。
十、常见坑点总结
- bcrypt加密,千万不要存储明文密码;
- 响应模型必须过滤password字段,不能把哈希密码返回前端;
- 全局异常注册顺序,子类在前父类在后;
- 区分JWT和数据库存储token:本项目token存在MySQL表,可以手动删除token实现强制用户下线;JWT无状态无法主动作废;
- 时间判断token过期:拿到
expires_at,和服务器本机datetime做对比;注意时区统一,避免时间判断错乱; - jsonable_encoder处理datetime、ORM对象,否则直接返回会报JSON序列化失败。