FastAPI 快速入门：从基础搭建到接口开发全攻略

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

1、FastAPI 核心优势

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

原生异步支持：内置 async/await 语法，异步代码可大幅提升接口并发处理效率，相同逻辑下异步执行耗时远低于同步；

自动类型校验：基于 Pydantic 实现参数类型提示与校验，减少手动校验代码，提升开发效率和代码健壮性；

自动生成交互式文档：无需额外开发，框架自动生成可在浏览器中直接调用、测试的 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、项目快速搭建与运行

步骤 1：创建核心文件

新建项目目录，创建 main.py 文件，编写基础代码：
# 导入FastAPI核心类
from fastapi import FastAPI

# 实例化FastAPI对象，作为项目核心入口
app = FastAPI()

# 定义根路由，GET请求方式
@app.get("/")
async def root():
    # 响应JSON数据
    return {"message": "hello world"}
步骤 2：运行项目

FastAPI 项目依赖 uvicorn 作为 ASGI 服务器运行，执行以下命令启动项目：
uvicorn main:app --reload
main：表示运行的 Python 文件为 main.py；

app：表示 main.py 中实例化的 FastAPI 对象；

--reload：开发模式下的热重载，修改代码后服务器自动重启，无需手动重启。

步骤 3：访问项目

访问接口：打开浏览器输入 http://127.0.0.1:8000，可看到返回 {"message":"hello world"}；

访问交互式文档：输入 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 导入，核心类型及用途如下：

响应类型

用途

示例代码

JSONResponse

默认，返回 JSON 数据

return {"key": "value"}

HTMLResponse

返回 HTML 内容

return HTMLResponse("<h1>Hello World</h1>")

PlainTextResponse

返回纯文本

return PlainTextResponse("这是纯文本")

FileResponse

返回文件下载 / 预览

return FileResponse("./files/1.jpeg")

StreamingResponse

流式响应（大文件 / 直播）

结合生成器函数返回数据

RedirectResponse

页面重定向

return RedirectResponse("http://127.0.0.1:8000")

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

方式 1：装饰器中指定 response_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 三个字段，严格遵循响应模型的定义。

响应类型	用途	示例代码
JSONResponse	默认，返回 JSON 数据	`return {"key": "value"}`
HTMLResponse	返回 HTML 内容	`return HTMLResponse("<h1>Hello World</h1>")`
PlainTextResponse	返回纯文本	`return PlainTextResponse("这是纯文本")`
FileResponse	返回文件下载 / 预览	`return FileResponse("./files/1.jpeg")`
StreamingResponse	流式响应（大文件 / 直播）	结合生成器函数返回数据
RedirectResponse	页面重定向	`return RedirectResponse("http://127.0.0.1:8000")`

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、核心参数说明

status_code：HTTP 异常状态码，如 404（资源未找到）、400（请求参数错误）、401（未认证）；

detail：异常描述信息，支持字符串或字典，会作为响应体的 detail 字段返回。

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

Kubernetes CoreDNS 解析超时排查（ndots 与 NodeLocal DNSCache）

CoreDNS 超时先用 ClusterIP 直连排除数据面，再读 Pod的ndots 与 search。默认 ndots:5 让短名查询放大数倍，AAAA 再乘一倍。指标上区分 NXDOMAIN 瀑布和真正的 SERVFAIL/p99。NodeLocal DNSCache 降 RTT、不消灭放大；根上仍是 FQDN 或谨慎的 dnsConfig。改 DNS 全局配置必须可回滚，禁止先停 Core