FastAPI 学习总结 - 第一部分基础入门一、FastAPI 简介什么是 FastAPIFastAPI 是一个用于快速构建 API 的现代、快速高性能的 Python Web 框架基于标准 Python 类型提示。它是由 Sebastián Ramírez 创建的首次发布于 2019 年。核心依赖FastAPI 建立在两个强大的库之上Pydantic: 用于数据验证和序列化Starlette: 用于异步 Web 功能主要特点特点说明快速性能极高可与 Node.js 和 Go 媲美基于 Starlette自动文档自动生成交互式 API 文档Swagger UI 和 ReDoc类型提示基于 Python 类型提示进行数据验证异步支持原生支持异步操作依赖注入内置依赖注入系统安全性内置 OAuth2、JWT 等安全功能为什么选择 FastAPI开发效率高: 自动数据验证、自动文档生成性能优秀: 异步支持处理大量并发请求易于学习: 基于 Python 类型提示语法简洁生态完善: 支持 SQLAlchemy、Pydantic、OAuth2 等二、HTTP 协议基础请求结构一个 HTTP 请求由三部分组成POST /api/v1/users HTTP/1.1 Host: example.com Content-Type: application/json Authorization: Bearer token123 {username: john, password: 123456}请求首行:POST /api/v1/users HTTP/1.1请求方法POST请求路径/api/v1/users协议版本HTTP/1.1请求头: 附加信息Host: 目标主机Content-Type: 请求体格式Authorization: 认证信息请求体: 传输的数据主要用于 POST、PUT 请求请求方法HTTP 定义了多种请求方法每种方法对应不同的操作方法用途示例GET获取资源获取用户列表POST创建资源新建用户PUT更新资源更新用户信息DELETE删除资源删除用户PATCH部分更新更新用户密码状态码HTTP 状态码用于表示请求的结果状态码类别含义200成功请求成功201成功创建成功400客户端错误请求参数错误401客户端错误未认证403客户端错误无权限404客户端错误资源不存在500服务器错误服务器内部错误RESTful 规范RESTRepresentational State Transfer是一种软件架构风格核心原则面向资源: 每个资源对应一个 URI统一接口: 使用标准 HTTP 方法无状态: 服务器不保存客户端状态分层系统: 客户端不需要知道服务器内部结构示例操作路径方法获取所有用户/usersGET获取单个用户/users/{id}GET创建用户/usersPOST更新用户/users/{id}PUT删除用户/users/{id}DELETE三、FastAPI 基础安装首先安装 FastAPI 和 ASGI 服务器# 安装 FastAPI 及所有可选依赖pipinstallfastapi[standard]# 安装 ASGI 服务器Uvicornpipinstalluvicorn基本结构创建一个简单的 FastAPI 应用# main.pyfromfastapiimportFastAPIimportuvicorn# 创建 FastAPI 实例appFastAPI(title我的第一个 FastAPI 应用,description这是一个简单的示例应用,version1.0.0)# 定义路由app.get(/)defread_root():根路径返回欢迎信息return{message:Hello, FastAPI!}# 带参数的路由app.get(/hello/{name})defsay_hello(name:str):根据名字返回问候return{message:fHello,{name}!}# 运行服务器if__name____main__:uvicorn.run(main:app,# 模块名:应用实例hostlocalhost,# 主机地址port8000,# 端口号reloadTrue# 开发模式自动重载)运行应用python main.py访问以下地址API 文档http://localhost:8000/docsSwagger UIReDoc 文档http://localhost:8000/redoc自动文档FastAPI 会根据你的代码自动生成交互式文档Swagger UI:http://localhost:8000/docs可以直接在浏览器中测试 API显示请求参数、响应格式支持身份认证ReDoc:http://localhost:8000/redoc更简洁的文档风格适合作为最终文档展示四、路由管理路由装饰器FastAPI 使用装饰器定义路由app.get(/items)# GET 请求app.post(/items)# POST 请求app.put(/items/{id})# PUT 请求app.delete(/items/{id})# DELETE 请求app.patch(/items/{id})# PATCH 请求路由分发APIRouter当应用变得复杂时可以使用APIRouter组织路由步骤 1创建路由文件# app/api/users.pyfromfastapiimportAPIRouter# 创建路由实例routerAPIRouter(prefix/users,# 路径前缀tags[用户管理],# 文档标签responses{404:{description:用户不存在}})# 定义路由router.get(/)defget_users():获取所有用户return[{id:1,name:张三},{id:2,name:李四}]router.get(/{user_id})defget_user(user_id:int):根据ID获取用户return{id:user_id,name:张三}router.post(/)defcreate_user(name:str):创建用户return{id:3,name:name}步骤 2在主应用中注册# main.pyfromfastapiimportFastAPIfromapp.api.usersimportrouterasusers_router appFastAPI()# 注册路由app.include_router(users_router)路由参数说明router.get(/{user_id},summary获取用户详情,# 简短描述description根据用户ID获取用户详细信息,# 详细描述tags[用户管理],# 标签deprecatedFalse# 是否废弃)defget_user(user_id:int):return{id:user_id}五、参数类型路径参数路径参数是 URL 路径的一部分app.get(/items/{item_id})defread_item(item_id:int): 获取商品详情 :param item_id: 商品ID整数 :return: 商品信息 return{item_id:item_id}类型转换: FastAPI 会自动将路径参数转换为声明的类型。访问示例:GET /items/5→{item_id: 5}GET /items/abc→ 422 错误类型不匹配查询参数查询参数是 URL 中?后面的部分app.get(/items)defread_items(skip:int0,limit:int10): 获取商品列表分页 :param skip: 跳过的数量默认0 :param limit: 返回的数量默认10 :return: 商品列表 # 模拟数据items[{id:i,name:fItem{i}}foriinrange(100)]returnitems[skip:skiplimit]访问示例:GET /items→ 返回前10个商品GET /items?skip10limit5→ 返回第11-15个商品请求体参数使用 Pydantic 模型定义请求体frompydanticimportBaseModelclassUser(BaseModel):用户模型username:stremail:strpassword:strage:int18# 默认值app.post(/users)defcreate_user(user:User): 创建用户 :param user: 用户信息 :return: 创建的用户隐藏密码 return{username:user.username,email:user.email,age:user.age}请求示例:curl-XPOSThttp://localhost:8000/users\-HContent-Type: application/json\-d{username: john, email: johnexample.com, password: 123456}响应示例:{username:john,email:johnexample.com,age:18}表单参数使用Form接收表单数据fromfastapiimportFormapp.post(/login)deflogin(username:strForm(...),password:strForm(...)): 用户登录 :param username: 用户名 :param password: 密码 :return: 登录状态 ifusernameadminandpassword123456:return{message:登录成功}return{message:登录失败}注意: 需要安装python-multipartpipinstallpython-multipart请求示例:curl-XPOSThttp://localhost:8000/login\-HContent-Type: application/x-www-form-urlencoded\-dusernameadminpassword123456文件上传使用File和UploadFile处理文件上传fromfastapiimportFile,UploadFileapp.post(/upload)defupload_file(file:UploadFileFile(...)): 上传文件 :param file: 上传的文件 :return: 文件信息 return{filename:file.filename,content_type:file.content_type,size:len(file.file.read())}多文件上传:app.post(/upload-multiple)defupload_files(files:list[UploadFile]File(...)): 上传多个文件 :param files: 文件列表 :return: 所有文件信息 return[{filename:file.filename,content_type:file.content_type}forfileinfiles]请求示例:curl-XPOSThttp://localhost:8000/upload\-HContent-Type: multipart/form-data\-Ffiletest.txt混合参数可以在一个接口中使用多种参数类型fromfastapiimportPath,Queryapp.put(/users/{user_id})defupdate_user(user_id:intPath(...,gt0),# 路径参数name:strQuery(None),# 查询参数user:UserNone# 请求体参数): 更新用户信息 :param user_id: 用户ID必须大于0 :param name: 用户名可选 :param user: 用户对象可选 :return: 更新后的用户 result{id:user_id}ifname:result[name]nameifuser:result.update(user.dict())returnresult
FastAPI 知识点总结 - 第一部分：基础入门
发布时间：2026/6/13 21:04:53
FastAPI 学习总结 - 第一部分基础入门一、FastAPI 简介什么是 FastAPIFastAPI 是一个用于快速构建 API 的现代、快速高性能的 Python Web 框架基于标准 Python 类型提示。它是由 Sebastián Ramírez 创建的首次发布于 2019 年。核心依赖FastAPI 建立在两个强大的库之上Pydantic: 用于数据验证和序列化Starlette: 用于异步 Web 功能主要特点特点说明快速性能极高可与 Node.js 和 Go 媲美基于 Starlette自动文档自动生成交互式 API 文档Swagger UI 和 ReDoc类型提示基于 Python 类型提示进行数据验证异步支持原生支持异步操作依赖注入内置依赖注入系统安全性内置 OAuth2、JWT 等安全功能为什么选择 FastAPI开发效率高: 自动数据验证、自动文档生成性能优秀: 异步支持处理大量并发请求易于学习: 基于 Python 类型提示语法简洁生态完善: 支持 SQLAlchemy、Pydantic、OAuth2 等二、HTTP 协议基础请求结构一个 HTTP 请求由三部分组成POST /api/v1/users HTTP/1.1 Host: example.com Content-Type: application/json Authorization: Bearer token123 {username: john, password: 123456}请求首行:POST /api/v1/users HTTP/1.1请求方法POST请求路径/api/v1/users协议版本HTTP/1.1请求头: 附加信息Host: 目标主机Content-Type: 请求体格式Authorization: 认证信息请求体: 传输的数据主要用于 POST、PUT 请求请求方法HTTP 定义了多种请求方法每种方法对应不同的操作方法用途示例GET获取资源获取用户列表POST创建资源新建用户PUT更新资源更新用户信息DELETE删除资源删除用户PATCH部分更新更新用户密码状态码HTTP 状态码用于表示请求的结果状态码类别含义200成功请求成功201成功创建成功400客户端错误请求参数错误401客户端错误未认证403客户端错误无权限404客户端错误资源不存在500服务器错误服务器内部错误RESTful 规范RESTRepresentational State Transfer是一种软件架构风格核心原则面向资源: 每个资源对应一个 URI统一接口: 使用标准 HTTP 方法无状态: 服务器不保存客户端状态分层系统: 客户端不需要知道服务器内部结构示例操作路径方法获取所有用户/usersGET获取单个用户/users/{id}GET创建用户/usersPOST更新用户/users/{id}PUT删除用户/users/{id}DELETE三、FastAPI 基础安装首先安装 FastAPI 和 ASGI 服务器# 安装 FastAPI 及所有可选依赖pipinstallfastapi[standard]# 安装 ASGI 服务器Uvicornpipinstalluvicorn基本结构创建一个简单的 FastAPI 应用# main.pyfromfastapiimportFastAPIimportuvicorn# 创建 FastAPI 实例appFastAPI(title我的第一个 FastAPI 应用,description这是一个简单的示例应用,version1.0.0)# 定义路由app.get(/)defread_root():根路径返回欢迎信息return{message:Hello, FastAPI!}# 带参数的路由app.get(/hello/{name})defsay_hello(name:str):根据名字返回问候return{message:fHello,{name}!}# 运行服务器if__name____main__:uvicorn.run(main:app,# 模块名:应用实例hostlocalhost,# 主机地址port8000,# 端口号reloadTrue# 开发模式自动重载)运行应用python main.py访问以下地址API 文档http://localhost:8000/docsSwagger UIReDoc 文档http://localhost:8000/redoc自动文档FastAPI 会根据你的代码自动生成交互式文档Swagger UI:http://localhost:8000/docs可以直接在浏览器中测试 API显示请求参数、响应格式支持身份认证ReDoc:http://localhost:8000/redoc更简洁的文档风格适合作为最终文档展示四、路由管理路由装饰器FastAPI 使用装饰器定义路由app.get(/items)# GET 请求app.post(/items)# POST 请求app.put(/items/{id})# PUT 请求app.delete(/items/{id})# DELETE 请求app.patch(/items/{id})# PATCH 请求路由分发APIRouter当应用变得复杂时可以使用APIRouter组织路由步骤 1创建路由文件# app/api/users.pyfromfastapiimportAPIRouter# 创建路由实例routerAPIRouter(prefix/users,# 路径前缀tags[用户管理],# 文档标签responses{404:{description:用户不存在}})# 定义路由router.get(/)defget_users():获取所有用户return[{id:1,name:张三},{id:2,name:李四}]router.get(/{user_id})defget_user(user_id:int):根据ID获取用户return{id:user_id,name:张三}router.post(/)defcreate_user(name:str):创建用户return{id:3,name:name}步骤 2在主应用中注册# main.pyfromfastapiimportFastAPIfromapp.api.usersimportrouterasusers_router appFastAPI()# 注册路由app.include_router(users_router)路由参数说明router.get(/{user_id},summary获取用户详情,# 简短描述description根据用户ID获取用户详细信息,# 详细描述tags[用户管理],# 标签deprecatedFalse# 是否废弃)defget_user(user_id:int):return{id:user_id}五、参数类型路径参数路径参数是 URL 路径的一部分app.get(/items/{item_id})defread_item(item_id:int): 获取商品详情 :param item_id: 商品ID整数 :return: 商品信息 return{item_id:item_id}类型转换: FastAPI 会自动将路径参数转换为声明的类型。访问示例:GET /items/5→{item_id: 5}GET /items/abc→ 422 错误类型不匹配查询参数查询参数是 URL 中?后面的部分app.get(/items)defread_items(skip:int0,limit:int10): 获取商品列表分页 :param skip: 跳过的数量默认0 :param limit: 返回的数量默认10 :return: 商品列表 # 模拟数据items[{id:i,name:fItem{i}}foriinrange(100)]returnitems[skip:skiplimit]访问示例:GET /items→ 返回前10个商品GET /items?skip10limit5→ 返回第11-15个商品请求体参数使用 Pydantic 模型定义请求体frompydanticimportBaseModelclassUser(BaseModel):用户模型username:stremail:strpassword:strage:int18# 默认值app.post(/users)defcreate_user(user:User): 创建用户 :param user: 用户信息 :return: 创建的用户隐藏密码 return{username:user.username,email:user.email,age:user.age}请求示例:curl-XPOSThttp://localhost:8000/users\-HContent-Type: application/json\-d{username: john, email: johnexample.com, password: 123456}响应示例:{username:john,email:johnexample.com,age:18}表单参数使用Form接收表单数据fromfastapiimportFormapp.post(/login)deflogin(username:strForm(...),password:strForm(...)): 用户登录 :param username: 用户名 :param password: 密码 :return: 登录状态 ifusernameadminandpassword123456:return{message:登录成功}return{message:登录失败}注意: 需要安装python-multipartpipinstallpython-multipart请求示例:curl-XPOSThttp://localhost:8000/login\-HContent-Type: application/x-www-form-urlencoded\-dusernameadminpassword123456文件上传使用File和UploadFile处理文件上传fromfastapiimportFile,UploadFileapp.post(/upload)defupload_file(file:UploadFileFile(...)): 上传文件 :param file: 上传的文件 :return: 文件信息 return{filename:file.filename,content_type:file.content_type,size:len(file.file.read())}多文件上传:app.post(/upload-multiple)defupload_files(files:list[UploadFile]File(...)): 上传多个文件 :param files: 文件列表 :return: 所有文件信息 return[{filename:file.filename,content_type:file.content_type}forfileinfiles]请求示例:curl-XPOSThttp://localhost:8000/upload\-HContent-Type: multipart/form-data\-Ffiletest.txt混合参数可以在一个接口中使用多种参数类型fromfastapiimportPath,Queryapp.put(/users/{user_id})defupdate_user(user_id:intPath(...,gt0),# 路径参数name:strQuery(None),# 查询参数user:UserNone# 请求体参数): 更新用户信息 :param user_id: 用户ID必须大于0 :param name: 用户名可选 :param user: 用户对象可选 :return: 更新后的用户 result{id:user_id}ifname:result[name]nameifuser:result.update(user.dict())returnresult
的演进与通信机制)
