前言：

FastAPI 是一款基于 Python 的高性能 Web 框架，主打原生异步支持、自动类型校验和交互式文档生成，专为快速构建 API 接口服务设计，是搭建后端服务、开发内部系统、部署 AI 大模型、构建微服务 API 的优选框架。本文将从基础入门到核心功能，手把手教你掌握 FastAPI 的核心用法，快速实现接口开发。

1.FastAPI的核心优势

相比传统 Python Web 框架，FastAPI 有三大核心亮点，也是其成为当下热门框架的关键：

1. 原生异步支持：内置 async/await 语法，异步代码可大幅提升接口并发处理效率，相同逻辑下异步执行耗时远低于同步；
2. 自动类型校验：基于 Pydantic 实现参数类型提示与校验，减少手动校验代码，提升开发效率和代码健壮性；
3. 自动生成交互式文档：无需额外开发，框架自动生成可在浏览器中直接调用、测试的 API 文档，地址为 http://127.0.0.1:8000/docs，极大降低接口调试成本。

此外，FastAPI 还具备高性能、轻量、易扩展的特点，完美适配现代 Web 开发和 AI 场景的需求。

2.环境准备与第一个FastAPI程序

2.1 环境搭建

详情参考下面这篇博客

https://blog.csdn.net/2301_79964758/article/details/155424180?spm=1001.2014.3001.5502

2.2 项目快速搭建与运行 

步骤一：创建核心文件

新建项目目录，创建main.py文件，编写基础代码：

# 导入FastAPI核心类
from fastapi import FastAPI
 
# 实例化FastAPI对象，作为项目核心入口
app = FastAPI()
 
# 定义根路由，GET请求方式
@app.get("/")
async def root():
    # 响应JSON数据
    return {"message": "hello world"}

步骤二：运行项目

FastAPI项目依赖uvicorn作为ASGI服务器运行，执行以下命令启动项目：

uvicorn main:app --reload

• main：表示运行的 Python 文件为 main.py；
• app：表示 main.py 中实例化的 FastAPI 对象；
• --reload：开发模式下的热重载，修改代码后服务器自动重启，无需手动重启。

步骤三：访问项目

1. 访问接口：打开浏览器输入 http://127.0.0.1:8000，可看到返回 {"message":"hello world"}；
2. 访问交互式文档：输入 http://127.0.0.1:8000/docs，可看到自动生成的 API 文档，支持在线调试接口。

3.路由

3.1 路由的定义

路由是URL地址和处理函数之间的映射关系，决定了当用户访问特定某个网址的时候，服务器执行哪段代码并返回结果。FastAPI的路由基于Python装饰器模式实现，核心语法为：

# 装饰器：FastAPI实例 + 请求方法 + 请求路径
@app.请求方法("请求路径")
async def 处理函数():
    # 响应结果
    return 响应数据

3.2 基础路由实例

实现访问 /user/hello 路径，返回指定提示信息：

@app.get("/user/hello")
async def get_user_hello():
    return {"msg": "我正在学习FastAPI......"}

3.3 核心请求方法

FastAPI支持所有HTTP常用请求方法，如 @app.get( )、@app.post( )、@app.put( )、@app.delete( )，分别对应查询、创建、更新、删除资源的操作。

4.接口参数

参数是客户端发送请求时附带的额外信息，让同一个接口能根据不同输入返回不同输出，实现动态交互。FastAPI 按参数位置和用途，将参数分为路径参数、查询参数、请求体参数三类，各自适用于不同场景。

4.1 路径参数

核心特点

• 位置：URL 路径的一部分，格式为 /路径/{参数名}；
• 作用：指向唯一的、特定的资源；
• 适用请求方法：GET；
• 核心能力：支持 Python 原生类型注解和 Path 高级注解（含参数校验、描述）。

基础用法（原生类型注解）
以图书 ID 为路径参数，查询指定图书信息：

@app.get("/book/{id}")
async def get_book(id: int):
    return {"id": id, "title": f"这是第{id}本书"}

访问 http://127.0.0.1:8000/book/666，将返回 {"id":666,"title":"这是第666本书"}，框架会自动将路径参数转换为注解的 int 类型。

高级用法（Path 注解，含参数校验）

通过 Path 函数为参数添加校验规则（如范围、长度）和描述，需先导入 Path：

from fastapi import FastAPI, Path
 
@app.get("/book/{id}")
async def get_book(id: int = Path(..., gt=0, lt=100, description="图书编号必填，范围1-100")):
    return {"id": id, "title": f"这是第{id}本书"}

• ...：表示参数为必填；
• gt/lt：大于 / 小于，适用于数值类型；
• min_length/max_length：长度范围，适用于字符串类型；
• description：参数描述，会在交互式文档中显示。

实战示例：按作者名查询
要求作者名长度 2-10，必填：

@app.get("/author/{name}")
async def get_author(name: str = Path(..., min_length=2, max_length=10, description="作者名称必填，长度2-10")):
    return {"name": name}

4.2 查询参数

核心特点

• 位置：URL 中 ? 之后，格式为 k1=v1&k2=v2；
• 作用：对资源集合进行过滤、排序、分页等操作；
• 适用请求方法：GET；
• 核心能力：支持 Python 原生类型注解和 Query 高级注解，用法与 Path 基本一致。

基础用法
以新闻分页为例，skip 为跳过的记录数，limit 为返回的记录数（默认 10）：

@app.get("/news/news_list")
async def get_news_list(skip: int, limit: int = 10):
    return {"skip": skip, "limit": limit}

访问 http://127.0.0.1:8000/news/news_list?skip=0&limit=20，框架会自动解析查询参数。

高级用法（Query 注解，含参数校验）

为查询参数添加校验规则，需先导入 Query：

from fastapi import FastAPI, Path, Query
 
@app.get("/news/news_list")
async def get_news_list(skip: int = Query(..., gt=0, lt=100, description="跳过记录数，1-99"), limit: int = Query(10, gt=0, lt=50)):
    return {"skip": skip, "limit": limit}

实战示例：查询图书（多条件过滤）

要求：图书分类默认值为 Python 开发，长度 5-255；价格范围 50-100：

@app.get("/book/query")
async def query_book(
    category: str = Query("Python开发", min_length=5, max_length=255),
    price: float = Query(..., gt=50, lt=100)
):
    return {"category": category, "price": price}

4.3 请求体参数

核心特点

• 位置：HTTP 请求的消息体（body）中，不在 URL 中；
• 作用：创建、更新资源，可携带大量数据（如 JSON 格式）；
• 适用请求方法：POST、PUT 等；
• 核心能力：基于 Pydantic 的 BaseModel 定义参数结构，支持 Field 高级注解做参数校验。

基础用法（定义 Pydantic 模型）
需先导入 BaseModel，通过类定义请求体参数的结构和类型：

from pydantic import BaseModel
 
# 定义用户注册模型
class User(BaseModel):
    username: str
    password: str
 
# 注册接口，POST请求
@app.post("/register")
async def register(user: User):
    # 直接返回请求体数据，框架自动解析JSON
    return user

高级用法（Field 注解，含参数校验）

为请求体参数添加校验规则和默认值，需先导入 Field：

from pydantic import BaseModel, Field
 
# 定义新增图书模型
class Book(BaseModel):
    book_name: str = Field(..., min_length=2, max_length=20, description="书名，必填，2-20字")
    author: str = Field(..., min_length=2, max_length=10, description="作者，必填，2-10字")
    publisher: str = Field(default="黑马出版社", description="出版社，默认黑马出版社")
    price: float = Field(..., gt=0, description="价格，必填，大于0")
 
# 新增图书接口
@app.post("/book")
async def add_book(book: Book):
    return book

5.响应类型

FastAPI 支持多种响应类型，默认返回 JSON 数据，也可根据需求返回 HTML、纯文本、文件、流式数据等，同时支持通过 response_model 自定义响应数据格式，实现响应结果的严格约束。

5.1 内置响应类型

FastAPI 提供了丰富的响应类，需从 fastapi.responses 导入，核心类型及用途如下：

5.2 响应类型的两种设置方式

方式一：装饰器中指定respons_class(固定返回类型)

适用于接口始终返回某一种类型数据的场景，如返回HTML：

from fastapi.responses import HTMLResponse
 
@app.get("/html", response_class=HTMLResponse)
async def get_html():
    # 直接返回HTML代码，框架自动封装为HTMLResponse
    return """
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>FastAPI HTML</title>
    </head>
    <body>
        <h1>这是FastAPI返回的HTML页面</h1>
    </body>
    </html>
    """

方式2：直接返回响应对象(动态返回类型)

适用于文件下载、图片预览等场景，直接返回响应类的实例：

先按照路径存入一张照片：

from fastapi.responses import FileResponse
 
@app.get("/file/img")
async def get_img():
    # 返回图片文件，框架自动处理文件类型和下载
    return FileResponse("./img/城市图片.jpg")

5.3 自定义响应格式（response_model）

通过 response_model 参数结合 Pydantic 模型，可严格约束接口的返回数据结构，实现自动数据校验和序列化，同时隐藏多余字段，提升接口安全性。

from pydantic import BaseModel
 
# 定义新闻响应模型
class News(BaseModel):
    id: int
    title: str
    content: str
 
# 新闻查询接口，指定响应模型
@app.get("/news/{id}", response_model=News)
async def get_news(id: int):
    # 即使返回额外字段，框架也会按response_model过滤
    return {
        "id": id,
        "title": f"这是第{id}条新闻",
        "content": f"这是第{id}条新闻的详细内容",
        "create_time": "2026-01-01"  # 该字段会被过滤，不返回
    }

访问接口时，仅会返回 id、title、content 三个字段，严格遵循响应模型的定义。

6.异常处理

FastAPI 提供 HTTPException 用于处理客户端引发的错误（4xx 状态码），可手动抛出异常并返回指定的状态码和错误信息，中断正常的代码执行流程，实现标准化的异常响应。

6.1 基础用法

需先导入 HTTPException，核心语法：

from fastapi import FastAPI, HTTPException
 
@app.get("/news/{id}")
async def get_news(id: int):
    # 模拟有效新闻ID列表
    valid_ids = [1,2,3,4,5,6]
    # 判断ID是否有效，无效则抛出404异常
    if id not in valid_ids:
        raise HTTPException(status_code=404, detail="当前新闻ID不存在")
    # 有效则返回新闻信息
    return {"id": id, "title": f"第{id}条新闻"}

6.2 异常响应效果

访问 http://127.0.0.1:8000/news/10，框架会返回标准的 JSON 格式异常响应：

同时 HTTP 状态码为 404，交互式文档中也会自动识别异常状态码。

6.3 核心参数说明

1. status_code：HTTP 异常状态码，如 404（资源未找到）、400（请求参数错误）、401（未认证）；
2. detail：异常描述信息，支持字符串或字典，会作为响应体的 detail 字段返回。