目录一、前言二、 FastAPI 响应介绍与使用2.1 响应类型2.2 手动设置响应2.2.1 设置响应类型为Html格式2.2.2 设置文件类型的响应格式2.2.3 自定义响应数据格式2.3 返回重定向2.4 自定义响应头三、FastAPI Pydantic 模型3.1 Pydantic 是什么3.2 Pydantic 使用3.2.1 定义 Pydantic3.2.2 使用 Pydantic3.2.3 访问和操作模型数据四、异常处理五、写在文末一、前言上一篇中我们详细分享了FastAPI 编写接口中请求以及请求参数相关的使用本篇将继续分享在FastAPI 框架中是如何使用响应的响应也就是接口如何将数据、异常等信息返回给前端从而让前端更好的处理本次接口的过程。二、 FastAPI 响应介绍与使用如下是一次完整的接口请求基本流程说明了请求和响应的过程2.1 响应类型默认情况下FastAPl会自动将路径操作函数返回的Python 对象(字典、列表、Pydantic模型等)经由jsonable_encoder 转换为JSON兼容格式并包装为JSONResponse返回。这省去了手动序列化的步骤让开发者能更专注于业务逻辑。如果需要返回非 JSON数据(如HTML、文件流)FastAPI提供了丰富的响应类型来返回不同数据下图中列举了FastAPI中支持的常用返回数据类型在下面这段基础代码中我们指定返回了一个jso对象from fastapi import FastAPI app FastAPI() app.get(/) async def root(): return {message: Hello World}通过调用接口在swagger中可以看到这个返回的数据结构为json类型而我们在代码中并没有显式定义框架自动帮我们做了适配2.2 手动设置响应一般可以通过下面2种方式进行设置2.2.1 设置响应类型为Html格式下面的代码中设置返回数据类型为Html格式的只需要在装饰器请求路径中增加 设置响应类为HTMLResponse当前接口即可返回HTML内容如下代码from fastapi import FastAPI from fastapi.responses import HTMLResponse app FastAPI() app.get(/html, response_classHTMLResponse) async def get_html(): return h1Hello World/h1运行服务请求一下接口可以看到展示了HTML形式的效果从Swagger中也可以看出来响应的是html格式2.2.2 设置文件类型的响应格式接口响应文件类型的格式也是日常开发中高频使用的场景比如一些下载文件的场景下载PDFexcel等在这种情况下可以使用FileResponse这个对象。FileResponse 是FastAPl提供的专门用于高效返回文件内容(如图片、PDF、Excel、音视频等)的响应类。它能够智能处理文件路径 、媒体类型推断、范围请求和缓存头部是服务静态文件的推荐方式。如下代码中提前在工程目录下准备一个图片参考下面的代码from fastapi import FastAPI from fastapi.responses import HTMLResponse,FileResponse app FastAPI() app.get(/html, response_classHTMLResponse) async def get_html(): return h1Hello World/h1 app.get(/file) async def get_file(): return FileResponse(./cat.jpeg)运行服务调用一下接口可以看到能够在浏览器中直接看到图片文件2.2.3 自定义响应数据格式在日常项目开发中自定义接口的返回数据格式算是最常见的比如从表中查询了10个字段前端只需要使用3个字段此时就可以自定义一个返回数据对象来做。自定义响应数据格式说明response_model 是路径操作装饰器如app.get或app.post的关键参数它通过一个Pydantic模型来严格定义和约束API端点的输出格式。这一机制在提供自动数据验证和序列化的同时更是保障数据安全性的第一道防线。如下代码中自定义一个Item类然后在接口路径中使用response_model指定返回的对象为这个Itemfrom fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): id:int title:str content:str app.get(/items/{item_id},response_modelItem) async def read_item(id:int): return { id: id, title: fItem {id}, content: NBA最新新闻 }运行一下调用接口效果如下使用自定义类对象的返回各个字段必须都有对应上才可以如果对应不起来比如在接口返回的时候少一个字段如下app.get(/items/{item_id},response_modelItem) async def read_item(id:int): return { id: id, title: fItem {id} }再次调用的时候会报错从后台日志中可以看到意思是返回的数据结构少了一个字段也就是在这种自定义输出对象的情况下返回值的结果必须要跟自定义的对象字段对上2.3 返回重定向使用RedirectResponse可以实现重定向的效果在下面的代码中使用RedirectResponse实现重定向将客户端重定向到/items/路由from fastapi import Header, Cookie from fastapi import FastAPI from fastapi.responses import RedirectResponse app FastAPI() app.get(/items/) def read_item(user_agent: str Header(None), session_token: str Cookie(None)): return {User-Agent: user_agent, Session-Token: session_token} app.get(/redirect) def redirect(): return RedirectResponse(url/items/)以上代码在浏览器访问http://127.0.0.1:8000/redirect/会自动跳转到http://127.0.0.1:8000/items/页面2.4 自定义响应头在某些场景下需要将接口返回的数据放在response中可以使用JSONResponse自定义响应头from fastapi import FastAPI from fastapi.responses import JSONResponse app FastAPI() app.get(/items/{item_id}) def read_item(item_id: int): content {item_id: item_id} headers {X-Custom-Header: custom-header-value} return JSONResponse(contentcontent, headersheaders)三、FastAPI Pydantic 模型Pydantic 是 FastAPI 的核心依赖用于做数据校验和序列化。它让你使用标准的 Python 类型注解来定义数据模型自动完成数据校验、类型转换和文档生成。3.1 Pydantic 是什么Pydantic 是一个 Python 数据校验库它的核心思想是用 Python 类型注解定义数据结构Pydantic 自动负责校验和转换。在 FastAPI 中Pydantic 主要作用如下用途说明请求体校验自动校验客户端发送的 JSON 数据是否符合模型定义响应体序列化将模型数据自动转换为 JSON 响应自动文档模型的字段、类型和校验规则自动出现在 API 文档中编辑器支持模型属性在编辑器中获得完整的自动补全3.2 Pydantic 使用3.2.1 定义 Pydantic创建一个继承BaseModel的类使用 Python 标准类型声明字段如下代码中自定义了一个Item类并包含了4个属性每个属性可以进一步约束from pydantic import BaseModel class Item(BaseModel): name: str # 必填商品名称 description: str | None None # 可选商品描述 price: float # 必填商品价格 tax: float | None None # 可选税费字段是否必填取决于是否有默认值字段声明方式是否必填namename: str必填descriptiondescription: str | None None可选priceprice: float必填taxtax: float | None None可选3.2.2 使用 Pydantic最常见的用法是将模型声明为路径操作函数的参数将其作为请求体from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Item(BaseModel): name: str description: str | None None price: float tax: float | None None app.post(/items/) async def create_item(item: Item): # FastAPI 自动校验请求体校验通过后赋值给 item 参数 return item3.2.3 访问和操作模型数据如下的代码中可以进一步操作请求对象的参数和数据app.post(/items/) async def create_item(item: Item): # 访问模型属性 print(item.name) # 直接访问属性 print(item.price) # 编辑器提供自动补全 # 序列化为字典 item_dict item.model_dump() print(item_dict) # {name: Foo, description: None, price: 45.2, tax: None} # 序列化为 JSON 字符串 item_json item.model_dump_json() print(item_json) # {name:Foo,description:null,price:45.2,tax:null} return item_dict通过控制台可以看到相应的输出参数在上面代码中使用了Pydantic v2 的一些方法比如使用 model_dump() 和 model_dump_json() 替代了 v1 的 dict() 和 json() 方法。新方法性能更好底层使用 Rust 实现。Pydantic v2 常用方法方法v2推荐v1已弃用说明序列化为字典item.model_dump()item.dict()将模型转为 Python 字典序列化为 JSONitem.model_dump_json()item.json()将模型转为 JSON 字符串从字典创建Item.model_validate(data)Item.parse_obj(data)从字典创建并校验模型从 JSON 创建Item.model_validate_json(json_str)Item.parse_raw(json_str)从 JSON 字符串创建模型获取 JSON SchemaItem.model_json_schema()Item.schema()获取模型的 JSON SchemaPydantic 模型继承Pydantic 模型支持继承可以方便地创建输入模型和输出模型from pydantic import BaseModel, EmailStr # 基础模型 class UserBase(BaseModel): username: str # 必填 email: EmailStr # 必填自动校验邮箱格式 full_name: str | None None # 可选 # 创建用户时的输入模型包含密码 class UserCreate(UserBase): password: str # 必填 # 返回用户信息时的输出模型不包含密码 class UserOut(UserBase): id: int # 由服务器生成 # 使用示例 app.post(/users/, response_modelUserOut) async def create_user(user: UserCreate): # 函数接收 UserCreate含密码但响应使用 UserOut不含密码 # 这样密码就不会出现在 API 响应中 return {id: 1, **user.model_dump(exclude{password})}四、异常处理对于客户端引发的错误(4xx如资源未找到、认证失败)应使用fastapi.HTTPException来中断正常处理流程并返回标准错误响应。通过下面这种自定义异常的写法可以让客户端在出现问题的时候客户端展示更友好参考下面的示例代码from fastapi import FastAPI, HTTPException app FastAPI() app.get(/news) def get_new(id: int): ids [1,2,3,4,5,6] if id not in ids: raise HTTPException(status_code404, detailItem not found) return {item_id: id}当代码逻辑判定为异常的时候返回的就是自定义的数据格式五、写在文末本篇详细介绍了FastAPI 中接口响应的常用功能并通过实际案例演示了详细的操作过程希望对看到的同学有用本篇到此结束感谢观看。