一、FastAPI框架简介FastAPI是一个基于 Python 的高性能 Web 框架专门用于快速构建 API 接口服务PythonWeb对比图对比维度FastAPIFlaskDjango性能高异步支持中较低同步异步支持✔ 内置 async/await❌ 需扩展❌ 不原生数据验证✔ Pydantic 自动校验❌ 手动处理✔ ORM 级验证自动文档✔ 自动生成❌ 需插件❌ 需扩展适用场景API、微服务、AI 推理小型 web 项目大型网站二、第一个Fast小程序from fastapi import FastAPI # 导入 FastAPI 框架用于创建 Web API app FastAPI() # 创建一个 FastAPI 应用实例 app.get(/) # 定义一个 GET 请求路由路径为根路径 / def read_root(): # 定义处理根路径请求的函数 return {Hello: World} # 返回一个 JSON 响应内容为 {Hello: World} app.get(/items/{item_id}) # 定义一个 GET 请求路由路径包含动态参数 {item_id} def read_item(item_id: int, q: str | None None): # 定义处理该路径请求的函数接收两个参数 # item_id: 路径参数类型为整数int # q: 查询参数类型为字符串或 None默认值为 None return {item_id: item_id, q: q} # 返回一个包含 item_id 和 q 的 JSON 响应三、路由路由就是 URL 地址和处理函数之间的映射关系它决定了当用户访问某个特定网址时服务器应该执行哪段代码来返回结果。FastAPI的路由定义基于 Python 的装饰器模式四、参数简介同一段接口逻辑根据参数不同返回不同的数据参数就是客户端发送请求时附带的额外信息和指令参数的作用是让同一个接口能根据不同的输入返回不同的输出实现动态交互参数分类路径参数位置URL 路径的一部分 /look/{id}作用指向唯一的特定的资源方法GET查询参数位置URL 之后 k1v1k2v2作用对资源集合进行过滤、排序、分页等操作方法GET请求体位置HTTP 请求的消息体body中作用创建、更新资源 携带大量数据如JSON方法POST、PUT 等五、路径参数_Path类型注解FastAPI 允许为参数声明额外的信息和校验Path 参数说明...必填gt/ge lt/le大于/大于等于 小于/小于等于description描述min_length max_length长度限制六、查询参数_Query类型注解声明的参数不是路径参数时路径操作函数会把该参数自动解释为查询参数参数形式与Path相同Query 参数说明...必填gt/ge lt/le大于/大于等于 小于/小于等于description描述min_length max_length长度限制七、请求体参数_Field类型注解在HTTP协议中一个完整的请求由三部分组成① 请求行包含方法、URL、协议版本 ② 请求头元数据信息Content-Type、Authorization等 ③ 请求体实际要发送的数据内容请求体参数的作用创造、更新资源Field 参数说明...必填gt/ge大于/大于等于lt/le小于/小于等于default默认值description描述min_length最小长度限制max_length最大长度限八、响应类型请求响应响应类型默认情况下FastAPI 会自动将路径操作函数返回的Python 对象字典、列表、Pydantic 模型等经由jsonable_encoder转换为JSON兼容格式并包装为JSONResponse返回。这省去了手动序列化的步骤让开发者能更专注于业务逻辑。如果需要返回非 JSON 数据如 HTML、文件流FastAPI 提供了丰富的响应类型来返回不同数据。响应类型用途示例JSONResponse默认响应返回JSON数据return {key: value}HTMLResponse返回HTML内容return HTMLResponse(html_content)PlainTextResponse返回纯文本return PlainTextResponse(text)FileResponse返回文件下载return FileResponse(path)StreamingResponse流式响应生成器函数返回数据RedirectResponse重定向return RedirectResponse(url)响应类型设置方式装饰器中指定响应类场景固定返回类型HTML、纯文本等app.get(/html, response_classHTMLResponse) async def get_html(): return h1这是标题/h1返回响应对象场景文件、图片、流式响应app.get(/file) async def get_file(): file_path ./files/1.jpeg return FileResponse(file_path)响应 HTML 格式设置响应类为 HTMLResponse当前接口即可返回 HTML 内容from fastapi.responses import HTMLResponse app.get(/html, response_classHTMLResponse) async def get_html(): return h1Hello World/h1响应文件格式FileResponse 是 FastAPI 提供的专门用于高效返回文件内容如图片、PDF、Excel、音视频等的响应类。它能够智能处理文件路径、媒体类型推断、范围请求和缓存头部是服务静态文件的推荐方式。from fastapi.responses import FileResponse app.get(/file) async def get_file(): file_path ./files/1.jpeg return FileResponse(file_path)九、自定义响应数据格式response_model是路由操作装饰器如 app.get 或 app.post的关键参数它通过一个Pydantic 模型来严格定义和约束 API 端点的输出格式。这一机制在提供自动数据验证和序列化的同时更是保障数据安全性的第一道防线。from pydantic import BaseModel class News(BaseModel): id: int title: str content: str app.get(/news/{id}, response_modelNews) async def get_news(id: int): return { id: id, title: f这是第{id}本书, content: 这是一本好书 }注意设定好的数据格式响应的数据就必须是这个格式否则会报错十、异常处理对于客户端引发的错误4xx如资源未找到、认证失败应使用 fastapi.HTTPException 来中断正常处理流程并返回标准错误响应。from fastapi import FastAPI, HTTPException app.get(/news/{id}) async def get_news(id: int): id_list [1, 2, 3, 4, 5, 6] if id not in id_list: raise HTTPException(status_code404, detail当前id不存在) return {id: id}本文为原创技术分享欢迎转载请注明出处作者heggng日期2026年3月22日
5分钟带你过FastAPI基础知识
发布时间：2026/7/10 9:18:49
一、FastAPI框架简介FastAPI是一个基于 Python 的高性能 Web 框架专门用于快速构建 API 接口服务PythonWeb对比图对比维度FastAPIFlaskDjango性能高异步支持中较低同步异步支持✔ 内置 async/await❌ 需扩展❌ 不原生数据验证✔ Pydantic 自动校验❌ 手动处理✔ ORM 级验证自动文档✔ 自动生成❌ 需插件❌ 需扩展适用场景API、微服务、AI 推理小型 web 项目大型网站二、第一个Fast小程序from fastapi import FastAPI # 导入 FastAPI 框架用于创建 Web API app FastAPI() # 创建一个 FastAPI 应用实例 app.get(/) # 定义一个 GET 请求路由路径为根路径 / def read_root(): # 定义处理根路径请求的函数 return {Hello: World} # 返回一个 JSON 响应内容为 {Hello: World} app.get(/items/{item_id}) # 定义一个 GET 请求路由路径包含动态参数 {item_id} def read_item(item_id: int, q: str | None None): # 定义处理该路径请求的函数接收两个参数 # item_id: 路径参数类型为整数int # q: 查询参数类型为字符串或 None默认值为 None return {item_id: item_id, q: q} # 返回一个包含 item_id 和 q 的 JSON 响应三、路由路由就是 URL 地址和处理函数之间的映射关系它决定了当用户访问某个特定网址时服务器应该执行哪段代码来返回结果。FastAPI的路由定义基于 Python 的装饰器模式四、参数简介同一段接口逻辑根据参数不同返回不同的数据参数就是客户端发送请求时附带的额外信息和指令参数的作用是让同一个接口能根据不同的输入返回不同的输出实现动态交互参数分类路径参数位置URL 路径的一部分 /look/{id}作用指向唯一的特定的资源方法GET查询参数位置URL 之后 k1v1k2v2作用对资源集合进行过滤、排序、分页等操作方法GET请求体位置HTTP 请求的消息体body中作用创建、更新资源 携带大量数据如JSON方法POST、PUT 等五、路径参数_Path类型注解FastAPI 允许为参数声明额外的信息和校验Path 参数说明...必填gt/ge lt/le大于/大于等于 小于/小于等于description描述min_length max_length长度限制六、查询参数_Query类型注解声明的参数不是路径参数时路径操作函数会把该参数自动解释为查询参数参数形式与Path相同Query 参数说明...必填gt/ge lt/le大于/大于等于 小于/小于等于description描述min_length max_length长度限制七、请求体参数_Field类型注解在HTTP协议中一个完整的请求由三部分组成① 请求行包含方法、URL、协议版本 ② 请求头元数据信息Content-Type、Authorization等 ③ 请求体实际要发送的数据内容请求体参数的作用创造、更新资源Field 参数说明...必填gt/ge大于/大于等于lt/le小于/小于等于default默认值description描述min_length最小长度限制max_length最大长度限八、响应类型请求响应响应类型默认情况下FastAPI 会自动将路径操作函数返回的Python 对象字典、列表、Pydantic 模型等经由jsonable_encoder转换为JSON兼容格式并包装为JSONResponse返回。这省去了手动序列化的步骤让开发者能更专注于业务逻辑。如果需要返回非 JSON 数据如 HTML、文件流FastAPI 提供了丰富的响应类型来返回不同数据。响应类型用途示例JSONResponse默认响应返回JSON数据return {key: value}HTMLResponse返回HTML内容return HTMLResponse(html_content)PlainTextResponse返回纯文本return PlainTextResponse(text)FileResponse返回文件下载return FileResponse(path)StreamingResponse流式响应生成器函数返回数据RedirectResponse重定向return RedirectResponse(url)响应类型设置方式装饰器中指定响应类场景固定返回类型HTML、纯文本等app.get(/html, response_classHTMLResponse) async def get_html(): return h1这是标题/h1返回响应对象场景文件、图片、流式响应app.get(/file) async def get_file(): file_path ./files/1.jpeg return FileResponse(file_path)响应 HTML 格式设置响应类为 HTMLResponse当前接口即可返回 HTML 内容from fastapi.responses import HTMLResponse app.get(/html, response_classHTMLResponse) async def get_html(): return h1Hello World/h1响应文件格式FileResponse 是 FastAPI 提供的专门用于高效返回文件内容如图片、PDF、Excel、音视频等的响应类。它能够智能处理文件路径、媒体类型推断、范围请求和缓存头部是服务静态文件的推荐方式。from fastapi.responses import FileResponse app.get(/file) async def get_file(): file_path ./files/1.jpeg return FileResponse(file_path)九、自定义响应数据格式response_model是路由操作装饰器如 app.get 或 app.post的关键参数它通过一个Pydantic 模型来严格定义和约束 API 端点的输出格式。这一机制在提供自动数据验证和序列化的同时更是保障数据安全性的第一道防线。from pydantic import BaseModel class News(BaseModel): id: int title: str content: str app.get(/news/{id}, response_modelNews) async def get_news(id: int): return { id: id, title: f这是第{id}本书, content: 这是一本好书 }注意设定好的数据格式响应的数据就必须是这个格式否则会报错十、异常处理对于客户端引发的错误4xx如资源未找到、认证失败应使用 fastapi.HTTPException 来中断正常处理流程并返回标准错误响应。from fastapi import FastAPI, HTTPException app.get(/news/{id}) async def get_news(id: int): id_list [1, 2, 3, 4, 5, 6] if id not in id_list: raise HTTPException(status_code404, detail当前id不存在) return {id: id}本文为原创技术分享欢迎转载请注明出处作者heggng日期2026年3月22日
