FastAPI入门：Python后端开发新手指南

CtrlC工程师

2025-06-18 06:53

阅读 655

开篇：FastAPI是什么，能用来做什么？

如果你刚开始学习编程，可能对“后端”这个概念还有点模糊。我们可以简单理解为：“前端”是用户看到的界面，比如网页或APP的外观；而“后端”就是支撑这些界面运行的部分，比如处理用户的登录、获取数据、保存信息等。

FastAPI 是一个用 Python 编写的高性能 Web 框架，专门用于创建 API（Application Programming Interface）。你可以把它想象成是一种让不同程序之间可以互相交流的方式。比如你在一个天气APP上看到今天的天气信息，其实是APP向某个服务器发送请求，服务器再把数据返回给APP显示出来——这背后靠的就是API。

FastAPI 的特点有：

速度快：性能几乎和 Go 或 Node.js 相当
易于使用：语法简洁清晰
支持自动文档生成：写完代码后，它会自动生成交互式接口文档
基于现代 Python 语法（Type Hints）
非常适合做微服务或RESTful API开发

这篇文章的目标，是带你从零开始了解 FastAPI，并动手做一个简单的项目。即使你是完全零基础的新手，也能跟着一步步完成。

环境准备：搭建你的第一个 FastAPI 开发环境

步骤1：安装 Python

注意：FastAPI 只能在 Python 3.6+ 版本中运行。

推荐你下载并安装最新的 Python 官方版本（建议选3.9以上），记得在安装过程中勾选 “Add to PATH”，这样可以更方便地在命令行调用 Python。

安装完成后，在终端输入：

python --version

你应该能看到类似这样的输出：

Python 3.10.11

步骤2：安装 FastAPI 和 Uvicorn

我们将使用 pip 来安装所需的库：

pip install fastapi uvicorn

解释一下这两个工具：

fastapi：核心框架包
uvicorn：一个 ASGI 服务器，用来运行 FastAPI 应用程序

步骤3：测试是否安装成功

我们先来写一个最简单的 FastAPI 示例，检查环境是否正常。

创建一个文件，命名为 main.py，输入以下内容：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "欢迎来到我的第一个FastAPI应用！"}

然后，在终端中运行：

uvicorn main:app --reload

说明：

uvicorn 是启动服务器的命令
main:app 表示运行的是 main.py 文件中的 app 实例
--reload 表示修改代码后自动重载，适合开发时使用

运行后，你会看到类似如下提示：

INFO:     Will watch for changes in these directories: /path/to/your/project
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

打开浏览器访问：http://localhost:8000

你应该能看到页面上显示：

{
  "message": "欢迎来到我的第一个FastAPI应用！"
}

恭喜！你已经完成了环境搭建并运行了第一个 FastAPI 应用！

核心概念：什么是 FastAPI 的基本组成部分？

为了让你更容易理解，下面我会用生活中的例子类比 FastAPI 的几个核心概念。

路由（Route）

类比：门牌号

在现实生活中，每家每户都有自己的门牌号。快递员通过门牌号找到目的地。在网站中，“URL 地址”就相当于门牌号。

@app.get("/hello")
def say_hello():
    return {"greeting": "你好，世界！"}

上面这段代码定义了一个路由 /hello，表示当你访问 http://localhost:8000/hello 时，就会执行 say_hello 函数。

请求方法（HTTP Methods）

不同的动作对应不同的 HTTP 方法，最常见的几种是：

方法	含义	类比
GET	获取数据	去图书馆借书
POST	提交数据（新建）	注册新账号
PUT	更新数据	修改个人资料
DELETE	删除数据	注销账户

例如：

@app.post("/create-user")
def create_user():
    return {"status": "新用户已创建"}

访问方式为：使用 POST 方法请求 /create-user 接口

请求参数（Query Parameters）

有些时候，我们需要传入一些参数。比如搜索商品时，可能需要带关键词。

@app.get("/search")
def search_product(query: str):
    return {"result": f"搜索关键词：{query}"}

访问地址如：http://localhost:8000/search?query=手机

路径参数（Path Parameters）

路径参数就像是一级目录下的子页。

@app.get("/user/{user_id}")
def get_user(user_id: int):
    return {"id": user_id, "name": f"用户_{user_id}"}

访问地址如：http://localhost:8000/user/123

数据模型（Data Model）

很多情况下，我们希望接收结构化的数据。这时就需要定义一个数据模型。

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_available: bool = False

@app.post("/items/")
def create_item(item: Item):
    return item

这段代码定义了一个叫 Item 的模型，包含名称、价格和是否可用三个字段。

你可以在 Postman 或 curl 中发送如下 JSON：

{
  "name": "笔记本",
  "price": 999.9,
  "is_available": true
}

FastAPI 会自动帮你验证数据格式是否正确。

自动文档（Swagger UI）

FastAPI 的一大特色就是自带交互式 API 文档。

运行上面的代码之后，访问：

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

你会看到所有接口的详细文档，并可以直接进行测试！

实战项目：制作一个简单的“待办事项”管理应用

数据库设计模型-2

现在我们来实战一个完整的项目：待办事项管理器（To-do App）

目标功能：

获取所有任务
添加新任务
删除指定任务
标记任务完成状态

第一步：定义任务数据模型

创建一个新的文件，比如叫 todo.py，内容如下：

from pydantic import BaseModel
from typing import Optional

class TaskCreate(BaseModel):
    title: str
    description: Optional[str] = None
    done: bool = False

第二步：初始化任务列表与路由

from fastapi import FastAPI
from typing import List, Optional

app = FastAPI()

# 模拟数据库，存放所有任务
tasks_db = []

# 首页问候语
@app.get("/")
def home():
    return {"message": "欢迎使用简易待办事项管理系统"}

第三步：实现获取任务接口

@app.get("/tasks/", response_model=List[TaskCreate])
def get_tasks():
    return tasks_db

访问：http://localhost:8000/tasks/

第四步：添加新任务接口

@app.post("/tasks/add")
def add_task(task: TaskCreate):
    tasks_db.append(task)
    return {"message": "任务已添加", "task": task}

第五步：删除任务接口

@app.delete("/tasks/delete/{index}")
def delete_task(index: int):
    if index >= len(tasks_db) or index < 0:
        return {"error": "索引超出范围"}
    removed = tasks_db.pop(index)
    return {"message": "任务已删除", "removed": removed}

API接口文档-1

第六步：更新任务完成状态

@app.put("/tasks/update/{index}")
def update_task(index: int, task: TaskCreate):
    if index >= len(tasks_db) or index < 0:
        return {"error": "索引超出范围"}
    tasks_db[index] = task
    return {"message": "任务已更新", "task": task}

测试你的应用

你可以使用浏览器访问 /docs 页面，尝试测试各个接口功能，也可以用 Postman 发送请求进行验证。

常见问题：新手常遇到的问题及解答

1. 🤔 我运行 `uvicorn` 时报错说找不到模块怎么办？

可能是没有安装 FastAPI 或 uvicorn，请重新运行：

pip install fastapi uvicorn

或者考虑升级 pip：

python -m pip install --upgrade pip

2. 🧐 为什么我修改代码后服务器没有更新？

确保你在运行时加了 --reload 参数：

uvicorn main:app --reload

这个选项会让服务器在代码修改后自动重启，只适用于本地开发阶段。

3. 📡 我想让别人访问我的服务怎么做？

默认只能在你本机访问。如果你想局域网内其他人也访问，可以用：

uvicorn main:app --host 0.0.0.0 --port 8000

注意：这是临时开放，不适合部署生产环境。

4. ⚠️ 请求参数报错“Invalid ‘None’ for field ‘description’”

这是因为 Pydantic 默认不允许某些类型为空，除非你特别指明是可选字段（Optional），比如：

description: Optional[str] = None

5. ✅ 如何查看 API 文档？

直接访问：

http://localhost:8000/docs（Swagger）
http://localhost:8000/redoc（Redoc）

学习建议：下一步该学什么？

恭喜你完成了 FastAPI 的基础入门！接下来你可以沿着以下几个方向继续深入：

✅ 扩展你的技能树

学习连接真实数据库（如 SQLite、PostgreSQL、MongoDB）
使用 JWT 实现用户身份认证
学习异步编程（async/await）
使用 Docker 容器化部署项目
掌握单元测试与自动化部署流程

📘 推荐的学习资源

FastAPI 官方文档：https://fastapi.tiangolo.com/zh/
Python 官方教程：https://docs.python.org/3/tutorial/index.html
异步编程入门：Real Python Async 教程
Docker 入门指南：Docker Hub 官方文档

💡 小建议

多动手实践，每个新知识点都尽量自己写一遍代码
把代码上传到 GitHub 上，养成版本管理习惯
加入社区（如掘金、知乎专栏、Stack Overflow）提问和分享经验

总结

本文介绍了 FastAPI 是什么、如何搭建环境、其核心概念以及实际动手做了个小项目。FastAPI 是一个非常适合初学者学习现代后端技术的框架，既强大又友好。

希望你能继续探索这个充满潜力的领域，成为一位优秀的开发者！🚀

文章字数统计：约3773字
写作风格：循序渐进，语言通俗易懂，注重实践性，配合示例代码与结构化表达

标签:PythonSpringbootJavascript

最热最新

暂无评论

为你推荐

暂无相关推荐

FastAPI入门：Python后端开发新手指南

开篇：FastAPI是什么，能用来做什么？

环境准备：搭建你的第一个 FastAPI 开发环境

步骤1：安装 Python

步骤2：安装 FastAPI 和 Uvicorn

步骤3：测试是否安装成功

核心概念：什么是 FastAPI 的基本组成部分？

路由（Route）

请求方法（HTTP Methods）

请求参数（Query Parameters）

路径参数（Path Parameters）

数据模型（Data Model）

自动文档（Swagger UI）

实战项目：制作一个简单的“待办事项”管理应用

第一步：定义任务数据模型

第二步：初始化任务列表与路由

第三步：实现获取任务接口

第四步：添加新任务接口

第五步：删除任务接口

第六步：更新任务完成状态

测试你的应用

常见问题：新手常遇到的问题及解答

1. 🤔 我运行 `uvicorn` 时报错说找不到模块怎么办？

2. 🧐 为什么我修改代码后服务器没有更新？

3. 📡 我想让别人访问我的服务怎么做？

4. ⚠️ 请求参数报错“Invalid ‘None’ for field ‘description’”

5. ✅ 如何查看 API 文档？

学习建议：下一步该学什么？

✅ 扩展你的技能树

📘 推荐的学习资源

💡 小建议

总结

评论 0

为你推荐

精选内容

FastAPI入门：Python后端开发新手指南

开篇：FastAPI是什么，能用来做什么？

环境准备：搭建你的第一个 FastAPI 开发环境

步骤1：安装 Python

步骤2：安装 FastAPI 和 Uvicorn

步骤3：测试是否安装成功

核心概念：什么是 FastAPI 的基本组成部分？

路由（Route）

请求方法（HTTP Methods）

请求参数（Query Parameters）

路径参数（Path Parameters）

数据模型（Data Model）

自动文档（Swagger UI）

实战项目：制作一个简单的“待办事项”管理应用

第一步：定义任务数据模型

第二步：初始化任务列表与路由

第三步：实现获取任务接口

第四步：添加新任务接口

第五步：删除任务接口

第六步：更新任务完成状态

测试你的应用

常见问题：新手常遇到的问题及解答

1. 🤔 我运行 uvicorn 时报错说找不到模块怎么办？

2. 🧐 为什么我修改代码后服务器没有更新？

3. 📡 我想让别人访问我的服务怎么做？

4. ⚠️ 请求参数报错“Invalid ‘None’ for field ‘description’”

5. ✅ 如何查看 API 文档？

学习建议：下一步该学什么？

✅ 扩展你的技能树

📘 推荐的学习资源

💡 小建议

总结

评论 0

为你推荐

相关推荐

精选内容

1. 🤔 我运行 `uvicorn` 时报错说找不到模块怎么办？