【超详细】Python FastAPI 入门：写给新手的“保姆级”教程

Ne0inhk

20 Mar 2026 — 7 min read

前言

作为一名大学生，最近在做 Python Web 开发时发现了一个“宝藏”框架——FastAPI。以前学 Django 光配置就头大，学 Flask 又不知道怎么写规范。直到遇到了 FastAPI，我才体会到什么叫“写代码像呼吸一样自然”。这篇文章不讲复杂的原理，只讲最基础、最实用的操作，带你从 0 到 1 跑通第一个 API 接口！

一、FastAPI 是什么

在 Python 的世界里，做网站后台（Web 开发）主要有三巨头：

1. Django：老大哥，功能全但笨重，像一辆重型卡车。 2. Flask：二哥，轻便灵活但插件多，像一辆自行组装的赛车。 3. FastAPI：新晋顶流，快、自动生成文档、代码这种查错，像一辆自动驾驶的特斯拉。

为什么新手首选 FastAPI？不写文档：代码写完，接口文档自动生成（Swagger UI）。少写 Bug：利用 Python 的类型提示，参数传错了直接报错，不会等到运行一半才崩溃。简单：Hello World 只需要 5 行代码。

二、环境搭建（避坑指南）

1. 安装

很多新手第一步就倒在了环境上，跟着我做，保证没问题。

FastAPI 依赖 Python 3.8 及更⾼版本,需要Python3.8以上的解释器,第一步是下载FastAPI模块(如果已经下载可以忽略)

pip install fastapi -i https://mirrors.aliyun.com/pypi/simple/

-i https://mirrors.aliyun.com/pypi/simple/ 是使用了国内的镜像，加快下载

第二步是需要⼀个 ASGI 服务器，⽣产环境可以使⽤ Uvicorn 或者 Hypercorn

pip install "uvicorn[standard]" -i https://mirrors.aliyun.com/pypi/simple/

2.运行与启动

新建一个 `main.py` 文件，写入最简单的代码：

from fastapi import FastAPI import uvicorn # 1. 创建应用实例 app = FastAPI() # 2. 定义路由 @app.get("/") def root(): return {"message": "Hello World"} # 3. 启动入口（也可以在命令行运行） if __name__ == "__main__": uvicorn.run(app="main:app", host="127.0.0.1", port=8000)

这里的 "main:app" 意思是：运行 main.py 文件里的 app 对象

启动服务的方式有2个：

第一个是在代码上面写入if __name__ == "__main__":
uvicorn.run(app="main:app", host="127.0.0.1", port=8000)语句直接运行启动

第二个是点开终端

然后输入下面的代码启动服务

uvicorn main:app

个人推荐第一个^_^

启动后访问 `http://127.0.0.1:8000`，你会看到返回的JSON数据:

恭喜你！你的第一个 Web 接口已经跑通了！🎉

三、FastAPI的核心魔法：自动文档

这是 FastAPI 最让隔壁 Java 同学羡慕哭的功能。因为你不需要写任何一行文档代码，FastAPI 已经帮你写好了。打开浏览器，访问：http://127.0.0.1:8000/docs

你会看到一个狂拽酷炫的 Swagger UI界面。这是 FastAPI 根据你的代码自动生成的接口文档。以前：写完接口 -> 打开 Postman -> 填 URL -> 填参数 -> 发送 -> 报错 -> 改代码... 现在：直接在网页上点 `Try it out`，填参数，执行

四、怎么接收数据？（核心基础）

做后端最主要的工作就是：接收前端的数据 -> 处理数据 -> 返回结果。 FastAPI 接收数据主要有两种方式，新手必须掌握。

1. 路径参数 (Path Parameters)

场景：你要查询 ID 为 5 的学生信息，网址通常是 `http://.../student/5`。代码这样写：

from fastapi import FastAPI import uvicorn app = FastAPI() @app.get("/student/{student_id}") # 注意花括号 {} def get_student(student_id: int): # 注意这里写了 : int return { "学生ID": student_id, "类型": str(type(student_id)) } if __name__=="__main__": uvicorn.run(app="main:app",host="127.0.0.1",port=8088)

新手看细节：我在函数参数里写了 `student_id: int`。如果你访问 `/student/5`，FastAPI 会自动把 `5` 转换成整数，如果你访问 `/student/abc`，FastAPI 会直接给你报错，提示你“我们要的是整数，你给的是字符串”。这就是类型检查的强大之处！

2. 查询参数 (Query Parameters)

场景：类似百度的搜索，网址是 `http://.../search?keyword=python&page=1`。在 FastAPI 里，只要函数参数里写的变量，没在路径里出现，就是查询参数。

from fastapi import FastAPI import uvicorn app = FastAPI() @app.get("/search") def search_data(keyword: str, page: int = 1): # page=1 是默认值 return { "你搜的词": keyword, "当前页码": page } if __name__=="__main__": uvicorn.run(app="main:app",host="127.0.0.1",port=8088)

访问 /search?keyword=apple 返回 `keyword=apple`, `page=1` (默认值)。

访问 /search?keyword=apple&page=5 返回 `keyword=apple`, `page=5`。

五、最强功能：Pydantic 数据模型

如果你要做注册功能，前端会发来一堆数据（用户名、密码、年龄...）。如果参数太多，一个一个写在函数里太乱了。FastAPI 引入了Pydantic来定义数据的“形状”。这是重点中的重点，一定要看懂！

from fastapi import FastAPI import uvicorn from pydantic import BaseModel # 1. 导入 BaseModel app = FastAPI() # 2. 定义一个类，继承 BaseModel # 这就像是制定一个“表格”，前端传来的数据必须符合这个表格 class UserInfo(BaseModel): username: str password: str age: int = 18 # 默认18，如果没传就是18 is_student: bool = True # 是否是学生 # 3. 在接口中使用这个模型 @app.post("/register") def register(user: UserInfo): # 核心：参数类型指定为 UserInfo # FastAPI 会自动把前端传来的 JSON 塞进 user 变量里 # 我们可以直接用 user.username 取值 if user.age < 18: return {"message": "未成年人禁止注册", "code": 400} return { "message": "注册成功", "用户": user.username, "身份": "学生" if user.is_student else "社会人" } if __name__=="__main__": uvicorn.run(app="main:app",host="127.0.0.1",port=8088)

怎么测试这个 POST 接口？

1. 打开 `/docs` 文档页面。 2. 找到 `/register` 接口。 3. 点击 `Try it out`。 4. 在 Request body 里修改 JSON 数据。 5. 点击 `Execute`。

你完全不用写解析 JSON 的代码，FastAPI 全部帮你做好了！

六、总结与建议

对于新手来说，掌握以上内容，你已经算是一个合格的 FastAPI 入门者了。

回顾一下今天学到的： 1. 安装：pip install fastapi。 2. 启动：uvicorn是启动引擎。 3. 文档：`/docs` 自动生成文档，是测试神器。 4. 参数：利用 Python 的类型提示（`int`, `str`）来约束参数。 5. 模型：用 `BaseModel` 来处理复杂的 POST 数据（如注册登录）。

FastAPI 就像一把趁手的兵器，不仅让你写代码变快，更让你写出规范、健壮的代码。

博主后记

这一篇是基础篇，下一篇博客我会结合 SQLite 数据库，带大家手写一个真正的“用户登录注册系统”，包含数据库增删改查等实战内容,如果你觉得这篇教程对你有帮助，欢迎点赞、收藏、关注！有问题随时在评论区提问，必回！