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

开篇：FastAPI 是什么？能做什么？

作为一名刚接触编程的新手，你可能听说过“网站”、“服务器”、“接口”这些词。其实，这些都是互联网应用的重要组成部分。

那 FastAPI 是什么呢？简单来说：

FastAPI 是一个用 Python 编写的现代、快速（高性能）的 Web 框架，专门用来创建 API 接口。

听起来有点抽象？没关系，我们来打个比方：

想象你在餐馆点餐，服务员会把你的需求告诉厨房，然后厨师做好菜再由服务员送到你面前。
在这个过程中，“服务员”就是“API”的角色，负责前后沟通。

在很多网站或 App 中，前端界面和后端数据之间也是通过 API 来交流的。
而 FastAPI 就是一个可以帮你快速搭建这个“服务员”功能的工具。

---

环境准备：开始之前我们需要装些什么？

要使用 FastAPI，首先你要准备好开发环境。不用担心，这里每一步都很简单，跟着我来做就行。

第一步：安装 Python

FastAPI 是基于 Python 的框架，所以你需要先安装 Python 3.8 或以上版本。

你可以访问官网 https://www.python.org/ 下载对应系统的安装包。

安装完成后，在命令行中输入：

python --version

如果看到类似 Python 3.10.4 这样的输出，说明安装成功了！

📌 新手提示：如果你用的是 Windows，建议勾选“Add to PATH”选项；Mac 和 Linux 用户一般自带 Python，也可以直接升级。

---

第二步：安装 FastAPI

打开命令行工具（Windows 上用 CMD 或 PowerShell，Mac/Linux 用 Terminal），输入以下命令安装 FastAPI：

pip install fastapi

接着我们还需要安装一个叫 Uvicorn 的服务器，它可以帮助我们运行 FastAPI 项目：

pip install uvicorn

---

第三步：安装代码编辑器（推荐 VS Code）

虽然你也可以用任何文本编辑器写代码，但为了更好的体验，推荐你安装 Visual Studio Code (VS Code)。

安装步骤如下：

1. 打开链接，点击“Download”下载安装包；
2. 安装完成后打开软件；
3. 安装一个插件叫 Python（搜索 "Python" 插件并安装）；
4. 如果需要，还可以安装 “FastAPI Snippets” 插件，方便写代码时自动补全。

---

核心概念讲解：理解 FastAPI 的基础结构

学习任何一个新框架，都需要先理解它的几个关键组件。下面我们用最简单的语言解释 FastAPI 的几个核心概念。

---

1. API 接口

前面提到过，API 就是连接前后端的桥梁。例如，当你点击某个按钮时，App 向服务器发送请求获取数据，这就是在调用一个 API。

FastAPI 中我们可以这样定义一个 API：

from fastapi import FastAPI

app = FastAPI()

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

这段代码中，@app.get("/") 表示这是一个 GET 请求，路径是 /（也就是主页）。当有人访问这个地址时，就会触发 read_root() 函数，返回一段消息。

---

2. 请求方法（HTTP Methods）

常见的 HTTP 请求方式有几种，最常见的两种是：

• GET：获取数据（比如浏览网页）
• POST：提交数据（比如登录表单）

在 FastAPI 中，可以用不同的装饰器来处理这些请求：

@app.get("/hello")
def say_hello():
    return {"message": "你好呀！"}

@app.post("/login")
def login_user(username: str):
    return {"status": "登录成功", "user": username}

---

3. 路径参数（Path Parameters）

有时候我们需要让 URL 包含一些参数信息。例如，我们要展示用户 ID 为 5 的资料，URL 可以写成：

/users/5

在 FastAPI 中，我们这样定义路径参数：

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id, "name": "张三"}

注意，这里的 user_id 被声明为 int 类型，FastAPI 会自动帮我们做类型检查。

---

4. 查询参数（Query Parameters）

除了路径，我们还可以通过“查询字符串”传参。例如：

/search?keyword=fastapi

在代码中这样处理：

@app.get("/search")
def search_items(keyword: str):
    return {"results": f"找到关于 {keyword} 的内容..."}

---

5. 自动文档生成

这是 FastAPI 的一大亮点！只要你按标准写了接口，它就能自动生成交互式 API 文档。

运行下面这条命令启动服务：

uvicorn main:app --reload

然后访问：

• http://localhost:8000/docs —— Swagger UI（可视化文档）
• http://localhost:8000/redoc —— ReDoc（另一种风格的文档）

你就可以看到你的所有接口，并且还能测试它们！

---

实战项目：做一个天气查询小程序

现在我们来做一个小项目，名字叫做 《简易天气预报系统》。

这个项目的功能很简单：用户可以通过浏览器输入城市名，服务器返回当前城市的温度。

---

第一步：新建文件夹与文件结构

我们在电脑上新建一个文件夹，比如叫 weather_app，里面放一个文件叫 main.py，这是我们整个程序的核心。

文件夹结构如下：

weather_app/
└── main.py

---

第二步：写主程序

打开 main.py，输入以下内容：

from fastapi import FastAPI

app = FastAPI()

# 模拟数据库中的天气数据
fake_weather_db = {
    "北京": 25,
    "上海": 28,
    "广州": 32,
    "深圳": 30
}

@app.get("/weather/{city_name}")
def get_weather(city_name: str):
    if city_name in fake_weather_db:
        return {"temperature": fake_weather_db[city_name]}
    else:
        return {"error": "暂无该城市天气信息"}

---

第三步：运行服务

回到命令行，进入你的项目文件夹，运行：

uvicorn main:app --reload

你应该能看到这样的信息：

INFO:     Uvicorn running on http://127.0.0.1:8000

---

第四步：测试接口

打开浏览器，访问：

http://localhost:8000/weather/北京

你应该可以看到返回结果：

{"temperature": 25}

试试输入其他城市名，比如“成都”，应该会返回错误信息：

{"error": "暂无该城市天气信息"}

---

第五步：查看文档页面

再次访问：

• http://localhost:8000/docs

你会看到一个漂亮的交互式文档界面，里面有我们刚刚写的 /weather/{city_name} 接口，你可以试着在里面输入城市名进行测试。

---

常见问题解答

作为一个刚开始学的新手，你可能会遇到一些疑问。下面是几个常见问题的解答，希望对你有帮助。

---

Q1：为什么运行的时候出现 ModuleNotFoundError？

这通常是因为你还没有安装 FastAPI 或 Uvicorn。

解决办法： 在命令行中执行：

pip install fastapi
pip install uvicorn

---

Q2：为什么修改代码之后，服务没有更新？

默认情况下，FastAPI 不会自动重新加载代码。但如果你加上 --reload 参数，它会在代码改变后重启服务：

uvicorn main:app --reload

---

Q3：能不能在浏览器里直接调用 POST 接口？

不能直接像 GET 那样用浏览器访问，因为 POST 接口需要发送数据。但你可以使用文档页面里的测试界面（Swagger UI）来模拟发送数据。

例如，假设有一个接口是：

@app.post("/login")
def login(username: str):
    return {"message": f"欢迎回来，{username}"}

你可以在文档页面中点击 “Try it out”，输入 username 再点击“Execute”即可测试。

---

Q4：能不能同时监听多个端口？

默认 FastAPI 在 localhost:8000 上运行。如果你想换端口号，可以这样指定：

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

---

学习建议：接下来该学什么？

恭喜你完成了这篇教程的学习！你现在能够用 FastAPI 搭建简单的后端接口了。

下一步你可以尝试以下几个方向继续深入学习：

---

✅ 学习更多 FastAPI 功能

• 数据验证（Pydantic）
• 异常处理（自定义错误信息）
• 身份验证（OAuth2、JWT）
• 使用中间件（添加日志、权限控制等）

---

✅ 学习数据库操作

学会用 FastAPI 连接真实数据库，比如：

• SQLite（本地轻量级数据库）
• PostgreSQL / MySQL（常用关系型数据库）
• MongoDB（NoSQL 数据库）

推荐阅读课程或文档：

• FastAPI 官方中文文档
• SQLAlchemy 教程（用于数据库操作）

---

✅ 结合前端练习完整项目

尝试用 FastAPI 搭建一个完整的项目，比如：

• 博客网站后端 API
• 图书管理系统
• 天气预报 App 接口
• 注册登录功能接口

---

结语

学习 FastAPI 并不难，只要多动手写代码、多调试，很快你就能掌握基本技能。记住一句话：

写出来的代码，才是属于你的知识。

坚持练习，相信你能成为一位出色的后端开发者！

祝你在编程路上越走越远！💪