FastAPI 入门：Python 后端开发新手的第一步

大家好，我是团队的后端培训负责人。过去几年里，我带过上百位应届生从零开始学习后端开发。每次新同学加入，总有人问我：“有没有一个简单、现代、又能快速上手的 Python Web 框架？”我的答案几乎从未改变——FastAPI。

为什么？因为它够快（性能高）、够聪明（自动生成文档）、够友好（类型提示 + 自动校验），尤其适合刚接触后端开发的同学。我当初学 Flask 和 Django 时踩过不少坑，而 FastAPI 的设计哲学让我觉得：“如果当年有它，我能少熬多少夜啊！”

今天这篇教程，就是为完全零基础的你量身打造的。我们会用最直白的语言、最实用的代码，一步步带你搭建第一个 FastAPI 应用，并和前端（比如 JavaScript 写的页面）打通。无论你是想做产品原型，还是准备实习面试，这篇文章都能给你实战经验。

---

一、FastAPI 是什么？能用来做什么？

简单说，FastAPI 是一个用 Python 编写的现代 Web 框架，专门用来开发 API（应用程序接口）。

💡 API 是什么？
想象你在点外卖：你打开 App（前端），点击“下单”，App 会向餐厅服务器（后端）发送一个请求。服务器处理完订单，再把结果返回给 App。这个“通信桥梁”就是 API。

FastAPI 的优势：

• 快：基于 Starlette（异步框架）和 Pydantic（数据验证），性能接近 Node.js 或 Go。
• 自动文档：写完代码，自动生成漂亮的交互式 API 文档（Swagger UI）。
• 类型安全：利用 Python 的类型注解，自动校验请求数据，减少 bug。
• 易学：代码简洁，逻辑清晰，非常适合新手。

很多创业公司用 FastAPI 快速验证产品想法，因为它能用最少的代码实现核心功能。

---

二、环境准备：5 分钟搭好开发环境

别被“环境配置”吓到！我们只需要三样东西：

工具	作用	安装方式
Python 3.7+	运行 FastAPI	官网下载或 pyenv
pip	Python 包管理器	随 Python 自带
代码编辑器	写代码的地方	VS Code / PyCharm / Sublime

步骤 1：创建项目文件夹

mkdir my-fastapi-app
cd my-fastapi-app

步骤 2：创建虚拟环境（推荐）

python -m venv venv

• Windows: venv\Scripts\activate
• macOS/Linux: source venv/bin/activate

✅ 为什么用虚拟环境？
避免不同项目之间的依赖冲突。这是我带新人时反复强调的习惯！

步骤 3：安装 FastAPI 和 Uvicorn

pip install fastapi uvicorn[standard]

• fastapi：核心框架
• uvicorn：高性能 ASGI 服务器，用于运行你的应用

---

三、核心概念：用大白话讲清楚

1. 路由（Route） = 网址路径

比如 /users、/items/123，每个路径对应一个功能。

2. 请求方法（HTTP Method）

• GET：获取数据（如查看商品列表）
• POST：创建数据（如提交订单）
• PUT/PATCH：更新数据
• DELETE：删除数据

3. 路径参数 vs 查询参数

• 路径参数：/users/123 中的 123 是用户 ID，固定在 URL 里。
• 查询参数：/search?q=apple&page=2 中的 q 和 page，放在问号后面。

4. 请求体（Request Body）

当你要发送复杂数据（比如 JSON），就放在请求体里，通常用于 POST/PUT。

5. 响应（Response）

后端返回给前端的数据，通常是 JSON 格式。

🧠 我当初学的时候总混淆“路径参数”和“查询参数”。记住：路径参数是资源标识，查询参数是过滤条件。

---

四、动手实战：做一个“待办事项（Todo）”API

我们将实现以下功能：

• GET /todos → 获取所有待办项
• POST /todos → 新增一个待办项
• GET /todos/{id} → 获取某个待办项
• 支持前端（JavaScript）调用

第一步：写最简单的 Hello World

创建文件 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
    return {"message": "Hello, FastAPI!"}

运行：

uvicorn main:app --reload

• --reload：代码修改后自动重启，开发时超方便！

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

{"message": "Hello, FastAPI!"}

再访问 http://127.0.0.1:8000/docs，奇迹出现了——自动生成的 API 文档！你可以直接在网页上测试接口。

---

第二步：定义数据模型（Pydantic）

我们要存储待办项，每个 Todo 有：

• id：唯一编号
• title：标题
• completed：是否完成

在 main.py 顶部添加：

from pydantic import BaseModel

class Todo(BaseModel):
    id: int
    title: str
    completed: bool = False  # 默认未完成

🔍 Pydantic 是什么？
它会自动检查传入的数据是否符合模型。比如你传了个字符串 "abc" 当 id，FastAPI 会立刻报错，而不是让 bug 潜伏到数据库里。

---

第三步：模拟数据库（内存版）

为了简化，我们先用一个 Python 列表当“数据库”：

# 模拟数据库
todos = [
    {"id": 1, "title": "学习 FastAPI", "completed": False},
    {"id": 2, "title": "写前端页面", "completed": True}
]

⚠️ 注意：真实项目要用 SQLite / PostgreSQL 等数据库，但新手先理解流程更重要。

---

第四步：实现 API 接口

1. 获取所有 Todo

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

2. 获取单个 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": "Todo not found"}

3. 创建新 Todo（请求体）

@app.post("/todos")
def create_todo(todo: Todo):
    # 检查 ID 是否重复
    for t in todos:
        if t["id"] == todo.id:
            return {"error": "ID already exists"}
    todos.append(todo.dict())  # 转为字典存入
    return todo

💡 .dict() 是 Pydantic 模型转字典的方法。

---

第五步：测试你的 API

1. 启动服务：uvicorn main:app --reload
2. 打开 http://127.0.0.1:8000/docs
3. 点击 POST /todos → “Try it out”
4. 输入 JSON：

   {
     "id": 3,
     "title": "连接前端",
     "completed": false
   }
   

5. 点击“Execute”，看返回结果！

你会发现，FastAPI 自动做了：

• 类型校验（id 必须是整数）
• 必填字段检查（title 不能少）
• 自动生成请求示例

这就是产品开发中的高效体验——省下大量调试时间。

---

五、如何让 JavaScript 前端调用你的 API？

很多新手卡在这一步：“后端写好了，前端怎么连？”

假设你有个 HTML 页面（或 React/Vue 项目），用 fetch 调用：

// 获取所有 Todo
fetch('http://127.0.0.1:8000/todos')
  .then(res => res.json())
  .then(data => console.log(data));

// 创建新 Todo
fetch('http://127.0.0.1:8000/todos', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: 4,
    title: "来自前端的请求",
    completed: false
  })
})
.then(res => res.json())
.then(data => console.log(data));

⚠️ 跨域问题（CORS）
如果前端运行在 localhost:3000，而后端在 8000，浏览器会阻止请求（安全策略）。解决方法：安装 fastapi.middleware.cors。

在 main.py 添加：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 生产环境要改成具体域名
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

这样前端就能自由调用了。这是我在带实习生时最常见的“拦路虎”之一，务必记住！

---

六、新手常见问题解答

Q1：为什么我的 POST 请求收不到数据？

• 检查前端是否设置了 Content-Type: application/json
• 检查 FastAPI 函数参数是否用了 Pydantic 模型（如 todo: Todo）

Q2：如何处理数据库？

• 初学者可用 sqlite3（Python 内置）
• 进阶推荐 SQLAlchemy + databases（支持异步）
• 更简单：用 TinyDB（纯 Python 的轻量数据库）

Q3：部署到线上怎么办？

• 开发阶段：uvicorn main:app --host 0.0.0.0 --port 8000
• 生产环境：用 gunicorn + uvicorn，或部署到 Vercel / Render / Railway

Q4：FastAPI 和 Flask/Django 有什么区别？

框架	学习曲线	异步支持	自动生成文档	适合场景
Flask	简单	需额外配置	无	小型项目、学习
Django	较陡	有限	无	全栈应用（自带 admin）
FastAPI	平缓	原生支持	有	API 服务、微服务、产品原型

---

七、下一步学习建议

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

1. 深入 Pydantic：学习嵌套模型、校验器、默认值
2. 连接真实数据库：尝试 SQLAlchemy 或 Tortoise ORM
3. 添加用户认证：用 OAuth2 + JWT
4. 写单元测试：FastAPI 官方推荐 pytest
5. 部署上线：用 Docker 容器化，部署到云服务器

🌟 我的教学经验：不要一开始就追求“完美架构”。先做出能跑的产品，再迭代优化。FastAPI 的优势就在于让你快速验证想法。

---

结语

FastAPI 不仅是一个工具，更是一种开发思维：用类型安全减少错误，用自动生成提升效率，用异步支持应对高并发。

作为培训负责人，我见过太多同学因为框架太复杂而放弃后端。希望这篇教程能成为你信心的起点。记住，每一个资深工程师，都曾是从 Hello World 开始的。

现在，打开你的编辑器，敲下第一行代码吧！你离做出自己的产品，只差一个 uvicorn 命令的距离。