FastAPI入门：零基础也能写出第一个Python后端接口

大家好，我是技术团队的培训负责人，过去五年带过上百名应届生入门后端开发。今天之所以写这篇教程，是因为我发现很多刚毕业的同学面对“后端”两个字就望而却步——以为要懂数据库、懂网络协议、懂部署运维……其实，从一个最简单的接口开始，你就能迈出第一步。

我当初学的时候，也是从一行 print("Hello World") 开始的。FastAPI 正是这样一个对新手极其友好的框架：它用 Python 写，语法简洁，自带文档，还能自动校验数据。更棒的是，它和 GitHub 无缝集成，你可以轻松把代码分享出去，或者参与开源项目。

本文将带你从零开始，用一个真实的小例子（一个“待办事项”API），手把手搭建你的第一个 FastAPI 应用。全程只需基础的 Python 知识（会写函数就行！），不需要任何 Web 开发经验。

---

为什么选择 FastAPI？

在众多 Python 后端框架中（比如 Flask、Django），FastAPI 凭借以下优势成为新手首选：

• 超快：性能接近 Node.js 和 Go（官方基准测试）
• 自动文档：启动服务后，自动生成交互式 API 文档（Swagger UI + ReDoc）
• 类型提示友好：利用 Python 的 typing 模块，自动校验请求参数
• 现代标准：基于 ASGI（异步），支持 WebSocket、GraphQL 等新特性

最重要的是——学习曲线平缓。你不需要先理解“中间件”“路由分发”这些概念，写几行代码就能看到效果。

---

第一步：环境准备（5分钟搞定）

💡 提示：以下操作在 Windows / macOS / Linux 上基本一致。建议使用 VS Code 作为编辑器。

1. 安装 Python（3.7+）

确保你已安装 Python 3.7 或更高版本。打开终端（命令提示符 / Terminal），输入：

python --version
# 或
python3 ---version

如果未安装，请前往 python.org 下载并安装。记得勾选 “Add to PATH”（Windows 用户）。

2. 创建虚拟环境（强烈推荐！）

虚拟环境能隔离项目依赖，避免不同项目之间的包冲突。这是专业开发的第一步！

# 创建名为 fastapi-demo 的虚拟环境
python -m venv fastapi-demo

# 激活虚拟环境
# Windows:
fastapi-demo\Scripts\activate
# macOS / Linux:
source fastapi-demo/bin/activate

激活后，命令行前缀会出现 (fastapi-demo)，表示你现在处于该环境中。

3. 安装 FastAPI 和 Uvicorn

FastAPI 本身不包含服务器，需要搭配 ASGI 服务器运行。Uvicorn 是最常用的选择。

pip install fastapi uvicorn[standard]

📌 注意：uvicorn[standard] 中的 [standard] 表示安装额外依赖（如 Gunicorn 兼容层、WebSocket 支持等），新手直接这么装就行。

4. 初始化你的项目文件夹

mkdir todo-api && cd todo-api
code .  # 在 VS Code 中打开（可选）

现在，你的项目结构应该是这样的：

todo-api/
├── fastapi-demo/       # 虚拟环境（可忽略）
└── （空文件夹）

---

第二步：写你的第一个 API —— Hello World

在 todo-api 文件夹中，创建文件 main.py，输入以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def hello():
    return {"message": "Hello, FastAPI 新手！"}

运行服务

在终端中（确保虚拟环境已激活），执行：

uvicorn main:app --reload

• main：指 main.py 文件
• app：指文件中的 app = FastAPI() 实例
• --reload：开发模式，代码修改后自动重启服务（仅用于开发！）

你会看到类似输出：

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Started reloader process [12345]

打开浏览器，访问 http://127.0.0.1:8000，你会看到：

{"message": "Hello, FastAPI 新手！"}

🎉 恭喜！你已经写出了第一个 API 接口！

---

第三步：理解核心概念（用大白话解释）

别被术语吓到，FastAPI 的核心就三件事：

1. 路由（Route） = URL 路径 + HTTP 方法

比如：

• @app.get("/") → 当用户用 GET 方法 访问 / 时，执行 hello() 函数
• 你还可以定义 @app.post("/items")、@app.put("/user") 等

2. 请求与响应

• 请求：用户发来的数据（URL 参数、JSON 体、表单等）
• 响应：你返回的数据（通常是字典，FastAPI 自动转成 JSON）

3. 自动文档：你的 API 说明书

访问 http://127.0.0.1:8000/docs，你会看到一个漂亮的交互式文档页面（Swagger UI）。点“Try it out”还能直接测试接口！

🔍 小实验：把 hello() 函数改成 return ["apple", "banana"]，刷新 /docs，你会发现文档自动更新了返回类型！

---

第四步：实战项目——构建一个“待办事项”API

现在，我们来做一个有实际意义的小项目：管理待办事项（To-Do List）。

功能需求

• 查看所有待办项（GET /todos）
• 添加新待办项（POST /todos）
• 根据 ID 查看单个待办项（GET /todos/{id}）

步骤 1：定义数据模型

在 main.py 开头添加：

from pydantic import BaseModel

class TodoItem(BaseModel):
    id: int
    title: str
    completed: bool = False

💡 BaseModel 是 Pydantic 的核心类，FastAPI 用它做数据校验。
比如：如果前端传 {"title": "买牛奶"} 但没传 id，FastAPI 会自动返回 422 错误，并告诉你缺了哪个字段！

步骤 2：模拟数据库（用列表代替）

# 模拟数据库（实际项目用 SQLite / PostgreSQL 等）
todos = [
    TodoItem(id=1, title="学习 FastAPI", completed=True),
    TodoItem(id=2, title="写第一篇博客", completed=False)
]

步骤 3：实现 API 接口

查看所有待办项

@app.get("/todos")
def get_todos():
    return todos

添加新待办项

@app.post("/todos")
def create_todo(todo: TodoItem):
    todos.append(todo)
    return todo

注意：todo: TodoItem 表示请求体必须是 TodoItem 类型。FastAPI 会自动解析 JSON 并校验！

查看单个待办项

@app.get("/todos/{todo_id}")
def get_todo(todo_id: int):
    for todo in todos:
        if todo.id == todo_id:
            return todo
    return {"error": "Not found"}, 404

🔑 {todo_id} 是路径参数，FastAPI 会自动将其转换为 int 类型（因为声明了 todo_id: int）。

完整代码如下：

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()

class TodoItem(BaseModel):
    id: int
    title: str
    completed: bool = False

# 模拟数据库
todos = [
    TodoItem(id=1, title="学习 FastAPI", completed=True),
    TodoItem(id=2, title="写第一篇博客", completed=False)
]

@app.get("/")
def hello():
    return {"message": "欢迎使用待办事项 API！"}

@app.get("/todos")
def get_todos():
    return todos

@app.post("/todos")
def create_todo(todo: TodoItem):
    todos.append(todo)
    return todo

@app.get("/todos/{todo_id}")
def get_todo(todo_id: int):
    for todo in todos:
        if todo.id == todo_id:
            return todo
    return {"error": "待办项不存在"}, 404

测试你的 API

1. 启动服务：uvicorn main:app --reload
2. 打开 http://127.0.0.1:8000/docs
3. 尝试：
   • 点击 GET /todos → 查看所有待办项
   • 点击 POST /todos → 输入 {"id": 3, "title": "提交 GitHub"} → 点击 Execute
   • 再次调用 GET /todos，你会发现新任务已添加！

---

第五步：把代码推送到 GitHub（新手必学！）

学会用 Git 和 GitHub 是程序员的基本功。以下是简化流程：

1. 初始化 Git 仓库

git init
git add .
git commit -m "feat: 初始待办事项 API"

2. 创建 GitHub 仓库

• 登录 github.com
• 点击右上角 + → New repository
• 仓库名填 fastapi-todo-api，其他默认，点击 Create

3. 关联并推送

# 替换 YOUR_USERNAME 为你的 GitHub 用户名
git remote add origin https://github.com/YOUR_USERNAME/fastapi-todo-api.git
git branch -M main
git push -u origin main

✅ 现在，全世界都能看到你的第一个后端项目了！你可以把它写进简历，也可以邀请朋友来提 Issue。

---

新手常见问题解答

问题	原因	解决方案
ModuleNotFoundError: No module named 'fastapi'	忘记激活虚拟环境	运行 source venv/bin/activate（macOS/Linux）或 venv\Scripts\activate（Windows）
访问 /docs 显示空白	浏览器缓存或网络问题	强制刷新（Ctrl+F5）或换浏览器
POST 请求报 422 错误	请求体不符合 TodoItem 模型	检查是否缺少 id 或 title 字段，或类型错误（如 id 用了字符串）
修改代码后没生效	忘记加 --reload 参数	确保启动命令是 uvicorn main:app --reload

---

下一步学习建议

你已经迈出了关键一步！接下来可以：

1. 深入 FastAPI：

   • 学习数据库集成（SQLAlchemy + SQLite）
   • 添加用户认证（OAuth2 with JWT）
   • 使用 async/await 写异步接口

2. 掌握工程化：

   • 用 .env 管理配置（python-dotenv）
   • 编写单元测试（pytest）
   • 部署到云服务器（Render / Vercel / Railway）

3. 参与开源：

   • 在 GitHub 上找 FastAPI 项目，阅读代码
   • 从修复文档 typo 开始贡献

🌟 最后送你一句话：每个专家都曾是菜鸟。我带过的很多学生，现在已经是大厂后端主力。你缺的不是天赋，而是开始行动的勇气。

快去写你的第一个 API 吧！遇到问题，欢迎在 GitHub 仓库提 Issue（这也是学习的一部分 😄）。