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

---

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

你可能听说过 Python 可以用来做网站、处理数据、写小程序等等。今天我们要学的 FastAPI，是用 Python 来开发“后端接口”的利器。

简单来说：

• 前端（Frontend）：指的是网页或 App 的界面部分。
• 后端（Backend）：负责接收用户的请求、处理数据、返回结果给前端使用。

比如你在购物网站上点了一个按钮想查看商品详情，前端会向后端发出请求说：“请给我这个商品的信息”。后端就要接收到这个请求，查询数据库，然后把结果返回回去。

这就是 FastAPI 所擅长做的事情——帮你快速地写出这些“接受请求、处理逻辑、返回结果”的程序。

FastAPI 有什么优点？

1. 速度快：它基于 Python 异步特性，执行效率高。
2. 自动生成文档：你可以直接通过浏览器看到你写的 API 接口说明。
3. 类型提示支持好：让你代码更清晰、更容易调试。
4. 上手快：对新手友好，语法简洁。

接下来我们就一步步从零开始，掌握 FastAPI。

---

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

在开始写代码之前，我们需要准备好一个运行环境。这里我们使用标准的 Python + FastAPI 开发工具链。

第一步：安装 Python

确认你电脑上已安装了 Python。打开命令行（Windows 是 CMD 或 PowerShell，Mac 是终端），输入：

python --version

如果你看到类似 Python 3.8 或更高的版本，说明已经安装好了。如果没有，请去 Python官网 安装。

✅ 建议版本：Python 3.7+

---

第二步：创建项目目录和虚拟环境

我们可以先为我们的项目新建一个文件夹，比如叫 fastapi_demo。

进入这个目录并创建虚拟环境：

mkdir fastapi_demo
cd fastapi_demo
python -m venv venv

激活虚拟环境（注意不同系统命令不同）：

• Windows：

  venv\Scripts\activate
  

• Mac/Linux：

  source venv/bin/activate
  

你现在应该看到命令行前面多了 (venv) 字样，说明进入了虚拟环境。

---

第三步：安装 FastAPI 和 Uvicorn

FastAPI 本身需要一个服务器来运行，我们推荐使用 uvicorn。

在命令行中运行以下命令进行安装：

pip install fastapi uvicorn

安装完成后检查一下是否成功：

pip list

你应该能看到 fastapi 和 uvicorn 出现在列表里。

🎉 到这一步，我们的开发环境就准备好了！

---

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

我们不会一开始就讲各种复杂的概念，而是用最直白的方式告诉你：FastAPI 程序是如何工作的。

FastAPI 的基本结构包括以下几个关键点：

1. 创建一个 FastAPI 应用实例

就像你要建一座房子，得先有个地基。我们先写一个最简单的 FastAPI 程序：

from fastapi import FastAPI

app = FastAPI()

这里的 app 就是一个“应用”，你可以理解为你的整个后端服务。

---

2. 编写一个路由（Route）

路由就像一张地图，告诉别人访问哪个地址可以得到什么样的回应。

举个例子：用户访问 /hello 这个地址，我们让他看到一句话：

@app.get("/hello")
def say_hello():
    return {"message": "你好，欢迎来到我的网站！"}

这段代码的意思是：

• 当有人用浏览器访问 /hello 地址时，就会执行 say_hello() 函数。
• 返回的是一个 JSON 对象，格式为 { "message": "..." }

---

3. 运行你的应用

保存上面代码到一个 .py 文件中，比如叫做 main.py。然后在命令行中运行：

uvicorn main:app --reload

解释一下这个命令的参数：

• main: 是指当前目录下的 main.py 文件。
• app: 是你定义的那个 FastAPI 实例变量名。
• --reload: 让服务器在代码变动后自动重启，方便开发。

运行之后，你会看到如下信息：

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

---

4. 浏览器访问看看结果

打开浏览器，在地址栏输入：

http://127.0.0.1:8000/hello

你会看到类似这样的一段 JSON 内容：

{
  "message": "你好，欢迎来到我的网站！"
}

✅ 成功！恭喜你完成了第一个 FastAPI 接口！

---

小结一下核心概念：

概念	作用
FastAPI 实例	构建后端服务的基础
路由函数	处理特定 URL 请求的功能
Uvicorn	启动服务的工具

---

实战项目：构建一个简易的天气预报接口

接下来我们来做一个小项目：写一个简单的“天气预报接口”，让它根据不同的城市名返回对应的天气情况。

步骤 1：添加 GET 接口，带参数的城市名称

修改 main.py 文件内容如下：

from fastapi import FastAPI

app = FastAPI()

@app.get("/weather/{city}")
def get_weather(city: str):
    # 模拟数据
    weather_data = {
        "北京": "晴",
        "上海": "多云",
        "广州": "雨",
        "深圳": "雷阵雨"
    }
    
    if city in weather_data:
        return {"city": city, "weather": weather_data[city]}
    else:
        return {"error": f"没有找到 {city} 的天气信息"}

在这个例子中：

• 我们定义了一个新的路由 /weather/{city}，其中 {city} 是动态参数。
• 使用字典 weather_data 存储模拟数据。
• 如果有这个城市的天气信息，就返回具体天气；否则返回错误信息。

在浏览器中访问例如：

http://127.0.0.1:8000/weather/北京

你会看到返回：

{"city": "北京", "weather": "晴"}

尝试访问一个不存在的城市：

http://127.0.0.1:8000/weather/拉萨

返回：

{"error": "没有找到 拉萨 的天气信息"}

---

步骤 2：让接口也支持 POST 请求

现在我们再增加一个功能：让用户可以通过表单提交一个新的城市天气信息。

from fastapi import FastAPI
from pydantic import BaseModel

class WeatherData(BaseModel):
    city: str
    weather: str

weather_data = {}

@app.post("/weather")
def add_weather(data: WeatherData):
    weather_data[data.city] = data.weather
    return {"status": "新增成功", "data": data}

这段代码中涉及几个新知识点：

• BaseModel 是 Pydantic 提供的类，用于定义请求体的数据结构。
• @app.post 表示这是一个 POST 类型的请求。
• data: WeatherData 表示接收的请求数据必须符合这个结构。

试着发送一个 POST 请求（可以在 Swagger 界面操作）：

{
  "city": "成都",
  "weather": "阴天"
}

发送成功后，访问：

http://127.0.0.1:8000/weather/成都

你会看到：

{"city": "成都", "weather": "阴天"}

---

步骤 3：查看所有城市天气

我们再来加一个查看所有记录的功能：

@app.get("/weathers")
def get_all_weather():
    return weather_data

访问：

http://127.0.0.1:8000/weathers

就可以看到你添加的所有天气记录啦！

---

自动接口文档测试功能

FastAPI 最棒的一个功能就是：自动生成交互式接口文档！

启动服务之后，你可以在浏览器中访问：

http://127.0.0.1:8000/docs

你会看到一个漂亮的交互页面（Swagger UI），在这里你可以：

• 查看所有接口
• 直接调用接口，发送 GET、POST 请求
• 查看返回结果

这对于初学者调试非常友好，不用每次都要开 Postman 或者手动测试。

---

常见问题解答（FAQ）

下面是一些刚入门的同学经常遇到的问题，一起来看看吧！

❓Q1：为什么我在运行 FastAPI 的时候报错说找不到模块？

可能是你还没激活虚拟环境或者 pip 安装有问题。

👉 解决方法：

• 检查是否运行了 source venv/bin/activate 或 venv\Script\activate
• 运行 pip list 查看你有没有安装 fastapi 和 uvicorn
• 重新运行安装命令：pip install fastapi uvicorn

---

❓Q2：我改完代码为什么浏览器显示没变？

默认情况下，FastAPI 不会在代码修改后自动刷新服务。

👉 解决方法：启动时加上 --reload 参数：

uvicorn main:app --reload

---

❓Q3：为什么不能访问本地 IP 外网访问？

默认 FastAPI 只允许本地访问，如果你想让其他人也能访问你的接口：

👉 解决方法：指定 host 为 0.0.0.0：

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

---

❓Q4：如何测试 POST 接口？

可以用两种方式：

1. 使用内置的 Docs 文档界面（推荐）
2. 使用第三方工具如 Postman、curl 或 VS Code REST Client 插件

---

下一步学习建议：成为进阶开发者

你已经成功完成了 FastAPI 的第一步学习旅程！下面是你可以继续深入学习的方向建议：

🔹 1. 数据库集成（如 SQLite、MySQL、PostgreSQL）

现在的项目数据都是存在内存里的，实际开发中要用数据库来持久化数据。

推荐学习：

• SQL 数据库基本语句
• ORM 工具：SQLAlchemy / Tortoise ORM（特别适合异步）

🔹 2. 用户登录与权限控制（认证和授权）

了解 JWT、OAuth2 等技术，实现安全的用户管理系统。

🔹 3. 部署上线知识

学会将你开发好的 FastAPI 项目部署到服务器，比如：

• 使用 Gunicorn + Nginx 部署生产环境
• 使用 Docker 容器打包服务
• 部署到免费平台（如 Render、Heroku、Railway）

🔹 4. 深入学习 async/await

因为 FastAPI 是异步框架，理解异步编程会让你充分发挥它的性能优势。

---

结语：开启你的后端开发之旅！

FastAPI 为我们提供了一条轻松通往后端开发的路径，尤其适合 Python 入门开发者。这篇文章从零开始带你搭建环境、编写最简单的接口，并完成了一个完整的实战项目。

只要你愿意持续练习和探索，相信很快你就能写出功能强大、响应迅速的后端服务！

加油吧，未来的全栈开发者 🚀！

---

📌 完整源码参考 GitHub 示例
（你可以在自己的项目中参考上述完整代码，也可以自己扩展功能）

如果你喜欢这种风格的新手教程，欢迎留言告诉我们你想学的主题 😊