【FastAPI|快速入门】第一个FastAPI程序、路由、参数、相应类型、自定义响应数据格式、异常响应处理

rannn_1112026-04-28 9:56

【FastAPI】

本篇讲解了FastAPI简介 ，如何快速构建一个FastAPI程序 ，路由 ，参数 的分类与实例，响应类型 ，自定义响应数据格式 ，异常响应处理

里面更加入了与java项目的比较，更适合学过Javaweb开发的进行类比理解😃

文章目录

FastAPI 是一个基于 Python 类型提示的现代高性能 Web 框架，以 极快的运行速度 （与 Node.js 和 Go 相当）和 极快的开发速度 著称，能够自动生成交互式 API 文档。

作用：

  1. 自动处理网络通信 (ASGI)
    就像 Spring Boot 内置 Tomcat 一样，FastAPI 基于 Starlette 框架，并与 Uvicorn 服务器无缝集成。你只需定义好路由和处理函数，FastAPI 会自动处理 HTTP 请求的接收、解析和响应的发送。你完全不用关心底层的 socket 连接、请求头解析等繁琐工作。
  2. 自动数据验证与解析
    这是 FastAPI 最核心的便利之一。在传统开发中，你需要手动从请求中提取 JSON 数据，然后写一堆 if-else 来判断字段是否存在、类型是否正确。
    FastAPI 通过 Pydantic 和 Python 的类型提示，让你只需声明数据的结构。框架会自动完成数据验证、类型转换，如果数据有误，还会自动返回清晰、标准的错误信息。这省去了大量的样板代码。
  3. 自动生成 API 文档
    在以往，写完接口后，你需要手动编写和维护一份 API 文档（如使用 Swagger），这是一个非常耗时且容易与代码不同步的工作。
    FastAPI 会根据你的代码和类型声明，实时自动生成一份交互式 API 文档（Swagger UI 和 ReDoc）。你写完代码，文档也同步完成了，前端工程师甚至可以直接在文档页面上测试接口，极大地提升了协作效率。
  4. 自动依赖注入
    FastAPI 提供了一个强大而直观的依赖注入系统。你可以将数据库连接、用户认证等公共逻辑定义为"依赖"，然后在需要使用的地方简单声明。框架会自动处理这些依赖的创建和管理，让你的核心业务代码变得非常简洁和易于测试

与java的SpringBoot框架类比理解

特性 Spring Boot (Java) FastAPI (Python)
核心理念 自动装配：通过 Starter 依赖和注解，自动配置好所有组件。 深度集成：将 Starlette 和 Pydantic 的能力无缝整合，开箱即用。
Web 核心 内置 Tomcat (Servlet 容器) 和 Spring MVC (框架)source_group_web_9。 依赖外部 Uvicorn (ASGI 服务器) 和内置的 Starlette (ASGI 框架)source_group_web_10。
数据验证 通过 @Valid 等注解和 Hibernate Validator 实现。 通过 Pydantic 模型和 Python 类型提示实现source_group_web_11。
启动方式 运行 main 方法，服务器自动启动。 在命令行使用 uvicorn 命令启动服务器source_group_web_12。

基础入门

1.1第一个FastAPI程序

我这里用的是python3.9.7+ PyCharm2023.3.4

项目结构

  • .venv (虚拟环境)

    这是一个 Python 虚拟环境（Virtual Environment）文件夹。可以把它理解为一个独立的、专属于这个项目的"工具箱"。

    • 作用 ：它隔离了这个项目所需的 Python 解释器和所有第三方库（比如你安装的 fastapi 和 uvicorn）。这样做的好处是，不同项目可以使用不同版本的库，互不干扰，避免了版本冲突。

    • 在 PyCharm 中：PyCharm 会自动识别并使用这个环境来运行你的代码。

  • main.py

    主程序文件，也是 FastAPI 应用的核心。

    • 作用 ：你所有的业务逻辑、API 路由定义（比如 @app.get("/")）都会写在这个文件里。它是你项目的入口，Uvicorn 服务器会运行这个文件来启动你的 Web 应用。

    • 类比 ：如果把你的项目比作一个餐厅，main.py 就是厨房的核心操作台，所有菜品的制作都在这里完成。

  • test_main.http

    这是一个HTTP 请求测试文件。

    • 作用 ：PyCharm 支持直接在这个文件里编写和发送 HTTP 请求，用来测试你写好的 API 接口。你不需要打开浏览器或 Postman，直接在 IDE 里就能测试 GET /, POST /items 等接口是否工作正常。
运行项目

  1. 法一：直接点击右上角的运行箭头

  2. 法二：用命令行运行

    shell 复制代码 
    uvicorn main:app --reload
    • uvicorn：FastAPI高性能的服务器，用来运行FastAPI项目
    • main：Python的文件名
    • app： FastAPI 实例变量的名字
    • --reload：自动重启服务器

总结：

1.2路由

路由就是URL地址 和处理函数之间的映射关系，它决定了当用户访问某个特定网址时，服务器该执行哪段代码来返回结果

网址和函数怎么联系起来？

用Python的装饰器实现，FastAPI的路由定义基于Python的装饰器模式

eg：

python 复制代码 
@app.get("/hello")
async def get_hello():
    return {"message": "你好FastAPI"}

类比理解：python的装饰器相当于是一个外壳，而java的@注解就是一个标签

维度 Python 装饰器 (外壳) Java 注解 (标签)
核心本质 函数式编程 (高阶函数) 声明式编程 (元数据)
生效方式 直接替换：func = decorator(func) 被动扫描：框架通过反射读取标签
代码改变 真的注入了代码逻辑 (如 print) 不注入代码，只存数据
执行时机 定义时立即执行 (包装) 运行时或编译时被框架处理
比喻 给枪装了个消音器 (功能变了) 给枪贴了个"禁止使用"的条 (需人来执行)

1.3参数

参数分类

  1. 路径参数

    python 复制代码 
    @app.get("/hello/{id}")
async def get_book(id: int):
    return {"message": f"bookID:{id}"}
    • id: int 不仅仅是个"规定"，它是一个自动化指令。你只写了 5 个字符，FastAPI 就帮你完成了：
    1. 类型转换（字符串 -> 整数）
    2. 数据校验（自动拦截非法输入）
    3. 文档生成（自动告诉别人这是整数）
    • 路径参数和函数参数要同名：FastAPI默认逻辑基于Python 的函数参数签名

    • Path类型注解

      python 复制代码 
      async def get_book(id: int = Path(..., gt=0, lt=101)):
    return {"message": f"bookID:{id}"}

      （限制id的大小为1~100包含1和100）

    ++声明的参数不是路径参数时，路径操作函数会把该参数自动解释为查询参数++

  2. 查询参数

    python 复制代码 
    @app.get("/news/news_list")
async def get_news_list(skip: int, limit: int = 10): #limit默认值为10
    return {"skip": skip, "limit": limit}

    • Query类型注解

      eg：

      python 复制代码 
      @app.get("/news/news_list")
async def get_news_list(skip: int = Query(0, description="跳过的记录数", lt=100), limit: int = 10):
    return {"skip": skip, "limit": limit}

  3. 请求体参数

    1. 定义类型

      python 复制代码 
      # 注册
class User(BaseModel):
    username: str
    password: str

      对比Serializable和BaseModel

      维度 Java Serializable Python BaseModel
      本质 标记接口 (空接口) 基类 (包含大量逻辑)
      核心作用 通行证：允许对象被转成字节流 校验器：确保数据符合类型和规则
      主要场景 RPC、缓存、文件存储 (二进制) API 请求/响应、配置管理 (JSON)
      数据流向 对象 -> 字节流 -> 对象 JSON -> 对象 -> JSON
      版本控制 需要手动维护 serialVersionUID 不需要 (通常是无状态的)
      文档生成 不支持 (需额外工具) 原生支持 (自动生成 Swagger)

    2. 类型注解

      python 复制代码 
      # 请求体参数
@app.post("/register")
async def register(user: User):
    return user

    • 类型注解

1.4响应类型

默认情况下，FastAPI 会自动 将路径操作函数返回的 Python 对象（字典、列表、Pydantic 模型等），经由 jsonable_encoder 转换为 JSON 兼容格式，并包装为 JSONResponse 返回。这省去了手动序列化的步骤，让开发者能更专注于业务逻辑。

如果需要返回非 JSON 数据（如 HTML、文件流），FastAPI 提供了丰富的响应类型来返回不同数据

响应类型设置方式：

  • 装饰器中指定响应类

    • 场景：固定返回类型（HTML、纯文本）
    python 复制代码 
    @app.get("/html", response_class=HTMLResponse)
async def get_html():
    return "<h1>标题</h1>"

  • 返回响应对象

    • 场景：文件下载、图片、流式响应
    python 复制代码 
    @app.get("/file")
async def get_file():
    file_path = "./files/1.jpg"
    return FileResponse(file_path)
JSON格式

eg：

python 复制代码 
@app.get("/")
async def root():
    return {"message": "Hello World"}

{"message": "Hello World"} 就是一个包含一个键值对的 Python 字典

FastAPI 会自动把它变成 JSON

HTML格式

设置响应类为HTMLResponse，当前接口即可返回HTML内容

eg：

python 复制代码 
@app.get("/html", response_class=HTMLResponse)
async def get_html():
    return "<h1>标题</h1>"
文件格式

FileResponse是FastAPI提供的专门用于高效返回文件内容的响应类。它能够智能处理文件路径、媒体类型判断、范围请求和缓存头部，是服务静态文件的推荐方式

eg：

python 复制代码 
@app.get("/file")
async def get_file():
    file_path = "./file/1.jpg"
    return FileResponse(file_path)

1.5自定义响应数据格式

response_model是路径操作装饰器的关键参数，它通过一个Pydantic模型来严格定义和约束API端点的输出格式。这一机制在提供自动化数据验证和序列化的同时，更是保障数据安全性的第一道防线

python 复制代码 
# 自定义响应数据格式
class News(BaseModel):
    id: int
    title: str
    content: str

# 接受请求
@app.get("/news/{id}", response_model=News)
async def get_news(id: int):
    return {
        "id": id,
        "title": f"这是第{id}本书",
        "content": "这是一本书"
    }

与java的Result对比

特性 Java (Result) Python (FastAPI)
控制权 开发者手动控制 你必须写代码去构造这个对象。 框架自动控制 你只管给数据，框架帮你构造 JSON。
灵活性 死板 你必须每次都 Result.success(data)。 灵活 你可以直接返回原始对象，框架自动提取。
安全性 依赖自觉 容易把敏感字段（如密码）误发出去。 自动屏蔽 只返回模型里定义的字段，自动屏蔽多余数据。
报错机制 编译时报错 类型不对编译不过。 运行时报错 数据格式不符合模型定义（如字段缺失），会返回 500 错误。

Python的并不是强制你按照格式写代码，而是强制你按照格式发数据
BaseModel到底是干啥的？

特性 普通 Python 类 / 字典 继承 BaseModel
数据检查 无 (全靠自觉) 自动检查 (类型不对直接报错)
JSON 处理 麻烦 (需手动 json.dumps) 极简 (自带 .json() 方法)
代码提示 弱 (IDE 猜不到字段) 强 (IDE 精准提示)
FastAPI 无法自动生成文档 核心依赖 (自动生成 API 文档)

1.6异常响应处理

对于客户端引发的错误，应使用fastapi.HTTPException来中断正常处理流程，并返回标准错误响应

eg：

python 复制代码 
@app.get("/news/{id}")
async def get_news(id: int):
    id_list = [1, 2, 3, 4, 5]
    if id not in id_list:
        raise HTTPException(status_code=404, detail="当前id不存在")
    return {"id": id}

当程序运行到 raise 语句时，它会立即中断当前的执行流程，并抛出一个错误，等待被捕获处理，或者导致程序终止

相关推荐
茶茶敲代码2 小时前
Simpack的DOE处理
python·pygame·trae·simpack
程序员老邢2 小时前
【重启日记】第五周复盘：持续突破高位，把 “平台期” 变成 “上升期”
java·运维·经验分享·ai·devops
老了,不知天命2 小时前
鳶尾花項目
python·筆記
2301_816660212 小时前
如何在 Telegram Bot 中正确发送 HTML 格式的用户列表消息
jvm·数据库·python
2401_898717662 小时前
CSS如何使得响应式的侧边抽屉附带遮罩渐暗效果
jvm·数据库·python
享客多网络2 小时前
2026年蓟州区GEO软件公司如何引领科技创新潮流
人工智能·python·科技
weixin_458580122 小时前
如何在网页中完整展示数组中所有对象的全部属性
jvm·数据库·python
2403_883261092 小时前
PHP源码能否在Chromebook上运行_ChromeOS硬件限制说明【解答】
jvm·数据库·python
djjdjdjdjjdj2 小时前
golang如何编写DNS查询工具_golang DNS查询工具编写大全
jvm·数据库·python
热门推荐
01近期有什么ai的新消息，新动态？ 2026.4月02GitHub 镜像站点032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot052026年AI前瞻：量子AI、具身智能与科学发现的新纪元06Codex 接入 DeepSeek API 完整配置文档07在Windows 11上安装Docker的踩坑记录08零基础教你claude code 接入 deepseek V409codex app每次打开重连5次Reconnecting问题解决10DeepSeek V4 全面解析：测评、对比、案例及实操指南