fastApi知识体系梳理04

一、用户模块ORM模型相关知识点

1. User 用户表模型

  1. 字段约束要点
    • username 设置唯一索引,保证数据库用户名不能重复,注册重复会触发数据库完整性异常。
    • 密码字段绝对不能存储明文,存储bcrypt加密之后的哈希字符串,字段长度需要足够容纳加密结果。
    • avatar、nickname、bio、gender、phone均为可选字段,允许为空,设置业务默认值。
    • created_at、updated_at设置自动时间,新增/更新自动维护时间戳。
  2. __table_args__:定义索引,用户名、手机号建立唯一索引,提升查询速度,同时数据库层面强制唯一性。

2. UserToken 用户令牌表模型

  1. 作用:保存用户登录生成的token、所属用户id、过期时间,实现登录状态持久化。
  2. 索引配置
    • token字段建立唯一索引,根据token查询用户效率极高。
    • user_id建立普通外键索引,关联User用户表。
  3. 关键字段
    • 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. 两个核心方法

  1. pwd_context.hash(明文密码):传入原始明文,返回加密后的哈希字符串。注册时使用,存入数据库。
  2. 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. 鉴权业务流程

  1. 接口请求携带Authorization请求头;
  2. 后端取出token,查询user_token表;
  3. 判断token是否存在、是否超过过期时间;
  4. 校验通过,拿到关联user_id,查询用户完整信息;
  5. 校验失败直接抛出异常,拒绝访问接口。>

保护接口:获取个人信息、修改资料、修改密码都必须走这套鉴权逻辑。

四、Pydantic请求、响应模型分层思想

  1. 请求模型(Request):接收前端post/put提交的json参数,做字段校验、长度校验。
    • UserRegisterRequest:注册入参(username、password)
    • UserLoginRequest:登录入参
    • UserUpdateRequest:更新用户信息入参,所有字段全部非必填,实现局部更新
    • UserChangePwdRequest:修改密码入参(旧密码、新密码)
  2. 响应模型(Response):控制返回给前端的字段,过滤数据库敏感字段(例如密码哈希绝对不能返回前端)。
  3. 基础基类复用: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. 不同异常分类

  1. HTTPException:业务代码主动抛出的业务异常,例如:token无效、用户名密码错误。
  2. IntegrityError:数据库完整性约束异常,比如用户名重复(唯一索引冲突)、外键约束失败。
  3. SQLAlchemyError:所有数据库相关父类异常,数据库连接、SQL执行出错都会触发。
  4. 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

  1. 使用Pydantic模型接收前端用户名密码;
  2. 查询数据库判断用户名是否已经存在;存在抛出异常;
  3. 将明文密码通过bcrypt加密;
  4. 创建User模型对象,存入数据库;
  5. uuid生成token,创建UserToken记录存入数据库;
  6. 返回token和用户信息,密码哈希绝对不能返回前端。

两种重复用户名报错来源:①代码手动查询判断抛出;②数据库唯一索引触发IntegrityError全局异常捕获。

2. 用户登录 POST /api/user/login

  1. Pydantic接收用户名、明文密码;
  2. 查询User表,根据username拿到用户以及数据库存储的加密密码;查不到抛出账号错误;
  3. pwd_context.verify()校验传入明文密码和数据库哈希;校验失败抛出密码错误;
  4. 生成新的uuid token,写入user_token表;
  5. 返回token与用户信息。

3. 获取用户信息 GET /api/user/info

  1. 需要鉴权,从请求头拿到Authorization token;
  2. 校验token有效性、是否过期;
  3. 查询用户数据,过滤掉密码字段,返回用户个人资料。

4. 更新用户信息 PUT /api/user/update

  1. 需要token鉴权,识别当前登录用户;
  2. 请求模型字段全部非必填,支持只传部分字段做局部更新;
  3. ORM update更新数据库用户表对应字段;
  4. 返回更新后的用户信息。

5. 修改密码 PUT /api/user/password

  1. 需要token鉴权;
  2. 接收旧密码、新密码;
  3. verify校验旧密码是否和数据库存储哈希匹配;
  4. 将新密码加密,update更新user表password字段。

八、分层开发流程回顾(用户模块复用)

  1. routers层定义APIRouter,编写接口装饰器,接收请求参数;
  2. schemas编写Request、Response Pydantic模型;
  3. models编写ORM数据表模型;
  4. crud封装数据库查询新增更新逻辑;
  5. 接口函数Depends注入db会话;鉴权逻辑封装成Depends依赖;
  6. 调用工具函数success_response()返回统一格式;
  7. main.py注册路由、注册全局异常处理器、配置CORS中间件。

九、依赖注入扩展:鉴权封装为Depends

鉴权逻辑可以封装成一个async函数,内部读取Header、查询token、校验、返回当前登录用户对象。
接口中:

async def func(db:AsyncSession=Depends(get_db), current_user:User = Depends(get_current_user))

优势:所有需要登录的接口,只需要写一行Depends,不需要每个接口重复写token解析查询代码。鉴权失败会直接抛出异常,接口业务代码不会执行。

十、常见坑点总结

  1. bcrypt加密,千万不要存储明文密码;
  2. 响应模型必须过滤password字段,不能把哈希密码返回前端;
  3. 全局异常注册顺序,子类在前父类在后;
  4. 区分JWT和数据库存储token:本项目token存在MySQL表,可以手动删除token实现强制用户下线;JWT无状态无法主动作废;
  5. 时间判断token过期:拿到expires_at,和服务器本机datetime做对比;注意时区统一,避免时间判断错乱;
  6. jsonable_encoder处理datetime、ORM对象,否则直接返回会报JSON序列化失败。
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

友情链接更多精彩内容