FastAPI 基础指南：从入门到实战

FastAPI 基础从入门到实战 这是一份超详细的 FastAPI 学习笔记涵盖基础到实战适合想要快速上手 FastAPI 的开发者目录FastAPI 简介同步与异步机制FastAPI 特点与优势创建第一个 FastAPI 项目路由详解参数详解路径参数、查询参数、请求体请求与响应处理异常处理1. FastAPI 简介FastAPI是一个基于 Python 的高性能 Web 框架专门用于快速构建 API 接口服务。核心特性特性说明高性能原生支持异步释放真正性能潜力自动文档自动生成交互式 API 文档类型提示完整的 Pydantic 数据验证开发者友好优秀的 IDE 支持和调试体验2. 同步与异步机制同步同步执行是指任务按顺序依次执行一个任务完成后才能开始下一个任务。请求1 → 处理 → 响应1 → 请求2 → 处理 → 响应2异步异步执行允许同时处理多个任务通过async/await关键字实现非阻塞操作。请求1 → 处理(同时等待) → 响应1 请求2 → 处理(同时等待) → 响应2FastAPI 原生支持异步这意味着它可以高效处理大量并发请求。3. FastAPI 特点与优势特点✅开发体验好- 简洁的 API 设计代码量少✅类型提示与验证- 自动数据校验错误提示清晰✅可交互式文档- 自动生成 Swagger UI 和 ReDoc优点⚡异步性能好- 高并发处理能力强开发效率高- 快速构建原型到生产级应用自动生成文档- 减少文档维护成本4. 创建第一个 FastAPI 项目4.1 创建项目使用 PyCharm 创建 FastAPI 项目FastAPI→ 存储位置及项目名称 → 创建虚拟环境 → Create4.2 运行项目有两种运行方式方式一点击运行按钮效果方式二命令行运行uvicorn main:app--reloaduvicorn main:app --reload是 FastAPI/Starlette 框架最常用的启动命令命令解析uvicorn- 一个轻量、高性能的 Python ASGI 服务器main:app- 格式固定模块名:应用实例main→ Python 文件名main.pyapp→ 代码里创建的 FastAPI 实例--reload- 开发模式自动重载修改代码保存即生效只在开发时用4.3 修改代码fromfastapiimportFastAPI# 创建FastAPI实例appFastAPI()app.get(/)asyncdefroot():return{message:Hello World}app.get(/hello)asyncdefget_hello():return{msg:你好 FastAPI}4.4 访问交互式文档浏览器输入地址http://127.0.0.1:8000/docs4.5 小结问题答案为什么要创建虚拟环境隔离项目运行环境避免依赖冲突保持全局环境的干净和稳定怎么运行 FastAPI 项目run按钮 或uvicorn main:app --reload怎么访问交互式文档http://127.0.0.1:8000/docs5. 路由详解路由是 URL 地址和处理函数之间的映射关系决定了当用户访问某个特定网址时服务器应该执行哪段代码来返回结果。FastAPI 的路由定义基于 Python 的装饰器模式。5.1 基础路由fromfastapiimportFastAPI appFastAPI()app.get(/)asyncdefroot():return{message:hello world}app.get(/hello)asyncdefget_hello():return{msg:你好 FastAPI}app.get(/hello/{name})asyncdefsay_hello(name:str):return{message:fHello{name}}5.2 小结问题答案什么是路由路由是 URL 地址和处理函数之间的映射关系装饰器app.get(/)的含义定义根路径的 GET 请求处理函数5.3 练习需求访问路径/user/hello响应结果是{ msg: 我正在学习 FastAPI ...... }app.get(/user/hello)asyncdefget_user_hello():return{msg:我正在学习 FastAPI ......}6. 参数详解参数是客户端发送请求时附带的额外信息和指令让同一个接口能根据不同的输入返回不同的输出。6.1 路径参数Path Parameter位置URL 路径的一部分格式为/资源/{参数名}作用指向唯一的、特定的资源常用方法GETapp.get(/book/{id})asyncdefget_book(id:int):return{id:id,title:f这是第{id}本书}使用 Path 进行类型注解fromfastapiimportFastAPI,Pathapp.get(/book/{id})asyncdefget_book(id:intPath(...,gt0,lt101,description书籍id取值范围为1-100)):return{id:id,title:f这是第{id}本书}⚠️ 注意参数校验时必须填一个值否则会报错字符串路径参数app.get(/book/{name})asyncdefget_name(name:strPath(...,min_length2,max_length10,description书籍名称长度范围为2-10)):return{msg:f这是{name}的信息}6.2 小结问题答案路径参数出现在什么位置URL 路径的一部分如何为路径参数添加类型注解Python 原生注解 和 Path 注解6.3 练习需求定义两个接口携带路径参数使用 Path 实现类型注解fromfastapiimportFastAPI,Path appFastAPI()# 接口1新闻分类 ID范围 1~100app.get(/news/category/{category_id})asyncdefget_news_by_id(category_id:intPath(...,title新闻分类ID,description新闻分类的唯一标识符,ge1,le100)):return{category_id:category_id,message:成功获取该分类下的新闻}# 接口2新闻分类名称长度 2~10app.get(/news/search/{category_name})asyncdefget_news_by_name(category_name:strPath(...,title新闻分类名称,description新闻分类的名称关键字,min_length2,max_length10)):return{category_name:category_name,message:成功搜索该分类相关的新闻}6.4 查询参数Query Parameter位置URL 中?之后格式为key1value1key2value2作用对资源集合进行过滤、排序、分页等操作常用方法GET声明的参数不是路径参数时路径操作函数会自动解释为查询参数。app.get(/news/news_list)asyncdefget_news_list(skip:int,limit:int10):return{skip:skip,limit:limit}使用 Query 进行类型注解fromfastapiimportFastAPI,Queryapp.get(/news/news_list)asyncdefget_news_list(skip:intQuery(0,description跳过的记录数,lt100),limit:intQuery(10,description返回的记录数,lt100)):return{skip:skip,limit:limit}6.5 小结问题答案查询参数出现在什么位置URL?之后如?page1sortdesc如何为查询参数添加类型注解Python 原生注解 和 Query 注解6.6 练习需求设计接口查询图书要求携带两个查询参数图书分类默认值为 “Python开发”长度限制 5~255价格限制大小范围 50~100fromfastapiimportFastAPI,Query appFastAPI()app.get(/books/)asyncdefread_books(category:strQuery(Python开发,min_length5,max_length255,description图书的分类名称),price:floatQuery(...,ge50,le100,description图书的价格范围)):return{category:category,price:price,message:查询成功}6.7 请求体Request Body位置HTTP 请求的消息体body中常以 JSON 格式携带数据作用用于创建、更新资源或携带大量数据常用方法POST、PUT在 HTTP 协议中请求体是实际要发送的数据内容。基础用法frompydanticimportBaseModelclassUser(BaseModel):username:strpassword:strapp.post(/register)asyncdefregister(user:User):returnuser6.8 练习需求设计接口新增图书图书信息包含书名、作者、出版社、售价fromfastapiimportFastAPIfrompydanticimportBaseModel appFastAPI()classBookItem(BaseModel):title:str# 书名author:str# 作者publisher:str# 出版社price:float# 售价app.post(/books/,summary新增图书)asyncdefcreate_book(book:BookItem):return{message:图书新增成功,book_info:book}使用 Field 进行类型注解frompydanticimportBaseModel,FieldclassUser(BaseModel):username:strField(default张三,min_length2,max_length10,description用户名长度范围为2-10)password:strField(min_length6,max_length20,description密码长度范围为6-20)app.post(/register)asyncdefregister(user:User):returnuser6.9 小结问题答案请求体参数的作用是什么创建、更新资源如何定义、使用请求体参数使用 Pydantic BaseModel 定义数据模型如何为请求体参数添加类型注解Python 原生注解 和 Field 注解6.10 练习需求设计接口新增图书书名不能为空长度 2~20作者长度 2~10出版社默认值黑马出版社售价不能为空价格大于0元fromfastapiimportFastAPIfrompydanticimportBaseModel,Field appFastAPI()classBook(BaseModel):book_name:strField(...,min_length2,max_length20,description书名必填2-20字)author:strField(...,min_length2,max_length10,description作者必填2-10字)publisher:strField(default黑马出版社,description出版社默认黑马出版社)price:floatField(...,gt0,description价格必填大于0)app.post(/books,summary新增图书)asyncdefcreate_book(book:Book):return{message:图书新增成功,book_data:book}6.11 核心区别总结参数类型位置作用常用方法路径参数URL 路径的一部分指向特定资源GET查询参数URL?之后过滤、排序、分页GET请求体HTTP body创建、更新资源POST、PUT6.12 完整代码示例fromfastapiimportFastAPI,Path,QueryfrompydanticimportBaseModel,Field appFastAPI()app.get(/)asyncdefroot():return{message:Hello World}app.get(/hello/{name})asyncdefsay_hello(name:str):return{message:fHello{name}}app.get(/book/{id})asyncdefget_book(id:intPath(...,gt0,lt101,description书籍id取值范围为1-100)):return{id:id,title:f这是第{id}本书}app.get(/news/news_list)asyncdefget_news_list(skip:intQuery(0,description跳过的记录数,lt100),limit:intQuery(10,description返回的记录数,lt100)):return{skip:skip,limit:limit}classUser(BaseModel):username:strField(default张三,min_length2,max_length10,description用户名)password:strField(min_length6,max_length20,description密码)app.post(/register)asyncdefregister(user:User):returnuser7. 请求与响应处理7.1 响应类型默认情况下FastAPI 会自动将路径操作函数返回的 Python 对象字典、列表、Pydantic 模型等转换为 JSON 格式返回。如需返回非 JSON 数据HTML、文件流FastAPI 提供了丰富的响应类型。7.2 响应类型设置方式方式一装饰器中指定响应类app.get(/html,response_classHTMLResponse)asyncdefget_html():returnh1这是标题/h1方式二返回响应对象app.get(/file)asyncdefget_file():returnFileResponse(./files/1.jpeg)7.3 响应 HTML 格式fromfastapiimportFastAPIfromfastapi.responsesimportHTMLResponse appFastAPI()app.get(/html,response_classHTMLResponse)asyncdefget_html():html html head titleHTML响应/title /head body h1这是HTML响应/h1 /body /html returnhtml7.4 响应文件格式FileResponse 是 FastAPI 专门用于高效返回文件内容的响应类支持图片、PDF、Excel、音视频等。fromfastapi.responsesimportFileResponseapp.get(/file)asyncdefget_file():file_path./files/1.jpegreturnFileResponse(file_path) 需要提前准备文件项目目录/files/1.jpeg7.5 自定义响应数据格式response_model通过 Pydantic 模型严格定义 API 端点的输出格式保障数据安全。frompydanticimportBaseModelclassNews(BaseModel):id:inttitle:strcontent:strapp.get(/news/{id},response_modelNews)asyncdefget_news(id:int):return{id:id,title:f这是第{id}本书,content:这是一本好书}⚠️ 注意如果 response_model 定义了字段return 时必须返回所有字段否则会报错8. 异常处理对于客户端引发的错误4xx应使用HTTPException来中断正常处理流程。fromfastapiimportFastAPI,HTTPExceptionapp.get(/news/{id})asyncdefget_news(id:int):id_list[1,2,3,4,5,6]ifidnotinid_list:raiseHTTPException(status_code404,detail当前id不存在)return{id:id}总结本文详细介绍了 FastAPI 框架的核心知识点知识点关键内容路由URL 与处理函数的映射通过装饰器定义路径参数URL 路径的一部分使用Path注解查询参数URL?后的参数使用Query注解请求体JSON 格式数据使用 Pydantic BaseModel响应格式HTMLResponse、FileResponse、response_model异常处理HTTPException 处理 4xx 错误推荐学习资源官方文档https://fastapi.tiangolo.com/交互式教程 http://127.0.0.1:8000/docs