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

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

大家好！如果你是第一次接触“后端开发”，或者对“Web接口”、“API服务”这些词感到陌生，不用担心。今天我们来一起学习一个非常受欢迎的、适合初学者使用的Python后端开发框架——FastAPI。

🧩 FastAPI 是什么？

简单来说，FastAPI 是一个用来快速搭建 Web API 接口服务的 Python 框架。它可以让你用最少的代码，就能写出高性能、自动文档化的 Web 接口（也就是我们常说的“前后端交互”的接口）。

比如：

• 用户注册功能
• 商品数据查询接口
• 聊天机器人回复接口
• 网络爬虫的数据输出接口

等等，都可以通过 FastAPI 来实现！

🚀 为什么选择 FastAPI？

• 上手快：语法简洁，适合新手
• 性能高：和 GoLang 相当，远超传统 Flask
• 自带文档：访问 /docs 自动生成美观的接口测试页面
• 类型提示支持强：写代码时能更好避免错误
• 社区活跃：资料丰富，问题容易解决

---

第一步：环境准备

在你开始写第一个 FastAPI 程序之前，需要准备好一些工具。别担心，这个过程不会太复杂，我们一步步来。

✅ 安装 Python

你需要安装 Python（推荐版本3.8或更高），可以在官网下载：
👉 https://www.python.org/downloads/

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

python --version

如果显示类似 Python 3.10.4，说明已经安装成功。

⛔️Windows用户可能需要使用 python -m pip 命令代替 pip。

---

✅ 安装 FastAPI 和 Uvicorn

FastAPI 本身只是一个库，我们需要配合运行服务器的组件。常用的是 uvicorn，它是一个异步 ASGI 服务器。

安装方法如下：

pip install fastapi uvicorn

✅ 安装成功后我们可以开始写第一个接口啦！

---

核心概念：最简单的 FastAPI 应用结构

让我们从一个最简单的例子开始，理解 FastAPI 的基本组成。

1️⃣ 创建你的第一个 FastAPI 文件

打开任意文本编辑器（如 VS Code、Sublime Text 或记事本），新建一个文件，命名为 main.py，然后输入以下内容：

from fastapi import FastAPI

app = FastAPI()

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

这段代码做了什么事呢？我们来分解一下：

代码	含义
from fastapi import FastAPI	导入 FastAPI 框架
app = FastAPI()	创建应用实例
@app.get("/")	定义 GET 请求，路径是根目录（"/"）
def read_root():	定义函数来处理请求
return {"message": "...}"	返回 JSON 数据作为响应

2️⃣ 启动服务器

在终端中进入文件所在目录，执行以下命令：

uvicorn main:app --reload

• main: 是你写的 Python 文件名（不带 .py）
• app: 是你在代码中定义的 FastAPI 实例的名字
• --reload: 表示开发模式，当你修改代码会自动重启服务器

启动成功后你会看到类似下面的提示：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

现在打开浏览器，访问：

👉 http://localhost:8000

你会看到：

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

🎉 恭喜！你已经成功创建了第一个 FastAPI 接口！

---

接口进阶：GET 请求与参数传递

接下来我们尝试构建更复杂的接口，例如一个可以接收参数的 GET 接口。

示例：根据用户名返回问候信息

继续修改 main.py 文件：

@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"你好，{name}！"}

➕ 解释

• @app.get("/hello/{name}")：表示这是一个 GET 请求接口，路径中带有参数 {name}
• def say_hello(name: str)：函数参数 name 类型为字符串，FastAPI 会自动转换

✅ 测试

运行服务器之后，访问：

👉 http://localhost:8000/hello/小明

你会看到结果：

{
  "message": "你好，小明！"
}

---

✅ 查询参数（Query Parameters）

除了路径参数，还可以使用查询参数。

举个例子：获取用户的年龄

@app.get("/user")
def get_user(name: str, age: int):
    return {"name": name, "age": age}

访问地址：

👉 http://localhost:8000/user?name=小花&age=20

结果：

{"name": "小花", "age": 20}

💡 注意：查询参数是可选的，也可以设置默认值：

@app.get("/items/")
async def read_items(q: str = None):
    return {"q": q}

---

实战项目：做一个图书管理接口

为了更好地掌握 FastAPI 的使用，我们一起来动手做一个简单的实战项目：图书管理系统接口

📚 功能目标

我们希望通过接口完成以下操作：

• 添加一本新书
• 查询所有书籍
• 根据 ID 查询一本书
• 删除一本书

🔧 1. 项目准备

新建一个文件夹（如叫 book_api），在里面新建两个文件：

• main.py：主程序
• books.py：模拟数据库逻辑

---

📄 books.py：模拟数据库存储

先编写一个简单的内存数据库（为了简化教学，我们暂时不用数据库）：

books_db = []

def add_book(title: str, author: str):
    book_id = len(books_db) + 1
    books_db.append({"id": book_id, "title": title, "author": author})
    return book_id

def get_all_books():
    return books_db

def get_book_by_id(book_id: int):
    for book in books_db:
        if book["id"] == book_id:
            return book
    return None

def delete_book(book_id: int):
    global books_db
    books_db = [book for book in books_db if book["id"] != book_id]

---

🧪 main.py：编写 API 接口

现在来编写实际的接口逻辑：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import books

app = FastAPI()

# 请求体模型
class BookCreate(BaseModel):
    title: str
    author: str

# 添加一本书
@app.post("/books/")
def create_book(book: BookCreate):
    book_id = books.add_book(book.title, book.author)
    return {"id": book_id, "message": "书籍添加成功"}

# 获取所有书籍
@app.get("/books/")
def list_books():
    return books.get_all_books()

# 获取某本书籍
@app.get("/books/{book_id}")
def get_book(book_id: int):
    book = books.get_book_by_id(book_id)
    if not book:
        raise HTTPException(status_code=404, detail="书籍未找到")
    return book

# 删除书籍
@app.delete("/books/{book_id}")
def delete_book(book_id: int):
    book = books.get_book_by_id(book_id)
    if not book:
        raise HTTPException(status_code=404, detail="书籍未找到")
    books.delete_book(book_id)
    return {"message": "书籍删除成功"}

---

🔍 测试接口

启动服务后，访问：

👉 http://localhost:8000/docs

你会看到 FastAPI 自动生成的接口文档页面。你可以在这里直接测试各个接口：

• POST /books → 添加一本书
• GET /books → 查看所有书
• GET /books/{id} → 查看指定 id 的书
• DELETE /books/{id} → 删除书

🎉 成功！你已经完成了自己的第一个完整的 FastAPI 项目！

---

新手常见问题解答（FAQ）

下面是学习过程中常遇到的一些问题和解答。

---

❓1. 我写了代码但报错 “ModuleNotFoundError: No module named 'fastapi'”

👉 那是因为没有正确安装 FastAPI，请确保执行了下面这行命令：

pip install fastapi uvicorn

---

❓2. 运行时报错 “error while loading shared libraries: libpython3.x.so.x.x: cannot open shared object file”

👉 这通常出现在 Linux 上，建议检查当前 Python 是否已正确安装，或考虑使用虚拟环境（后续学习建议）。

---

❓3. 我写的接口返回乱码或中文出现 Unicode 编码怎么办？

FastAPI 默认返回 UTF-8 编码，中文应该没问题。如果你看到 \uXXXX，那是正常行为，前端解析时会还原。

---

❓4. 可以不加 from fastapi import FastAPI 吗？

不可以，必须导入才能使用 FastAPI 提供的功能。

---

❓5. 如何让接口支持 POST 请求？

使用装饰器 @app.post("路径") 并配合 BaseModel 定义参数即可，就像上面我们做的那样。

---

❓6. 我可以同时有多个路径 /users/{id} 和 /users/me 吗？

可以，FastAPI 支持静态路径和动态路径共存，它会优先匹配静态路径。

---

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

恭喜你完成了 FastAPI 入门之旅！但这只是开始。如果你想继续深入学习，可以从以下几个方向入手：

📘 建议学习路径

1. 使用数据库
   • SQLite、PostgreSQL、MySQL
   • SQLAlchemy、Tortoise ORM（官方推荐）
2. 使用 Pydantic 增强数据验证
   • 更复杂的模型校验
3. 身份认证 & 权限控制
   • JWT Token、OAuth2
4. 部署上线
   • Nginx + Gunicorn/Uvicorn
   • Docker 部署
5. 结合前端开发
   • Vue.js、React.js、Flask+HTML 都可以结合使用
6. 自动化测试
   • 使用 pytest 写单元测试
7. 异步编程基础
   • async/await、事件循环原理
8. 日志与调试
   • logging、异常处理
9. 集成 Swagger/UI
   • 修改默认文档样式、增加接口分组等

---

总结：你已经掌握了 FastAPI 的哪些能力？

✅ 知道什么是 FastAPI，适合做什么样的项目
✅ 完成了开发环境的搭建
✅ 会编写最基本的 GET 和 POST 接口
✅ 理解路径参数和查询参数的使用
✅ 完成了一个小项目《图书管理系统》的接口实现
✅ 学会如何自动生成接口文档
✅ 解决了常见的安装与运行问题

只要坚持练习，你很快就能开发出属于自己的网站后台系统、聊天机器人、电商系统接口，甚至是 AI 服务接口！

---

🎯 下一步你可以：

• 把这本书接口加上作者简介字段
• 加一个搜索书籍的接口
• 尝试把它改成连接真实数据库
• 把接口部署到线上服务器试试看！

期待你在 Python 后端开发的路上越走越远！

📌 文章最后提供完整代码：

---

💾 books.py

books_db = []

def add_book(title: str, author: str):
    book_id = len(books_db) + 1
    books_db.append({"id": book_id, "title": title, "author": author})
    return book_id

def get_all_books():
    return books_db

def get_book_by_id(book_id: int):
    for book in books_db:
        if book["id"] == book_id:
            return book
    return None

def delete_book(book_id: int):
    global books_db
    books_db = [book for book in books_db if book["id"] != book_id]

---

💾 main.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import books

app = FastAPI()

class BookCreate(BaseModel):
    title: str
    author: str

@app.post("/books/")
def create_book(book: BookCreate):
    book_id = books.add_book(book.title, book.author)
    return {"id": book_id, "message": "书籍添加成功"}

@app.get("/books/")
def list_books():
    return books.get_all_books()

@app.get("/books/{book_id}")
def get_book(book_id: int):
    book = books.get_book_by_id(book_id)
    if not book:
        raise HTTPException(status_code=404, detail="书籍未找到")
    return book

@app.delete("/books/{book_id}")
def delete_book(book_id: int):
    book = books.get_book_by_id(book_id)
    if not book:
        raise HTTPException(status_code=404, detail="书籍未找到")
    books.delete_book(book_id)
    return {"message": "书籍删除成功"}

---

✨ 如果你喜欢这篇文章，欢迎分享给朋友；如果你有任何疑问，也欢迎留言提问，我们一起进步！

Happy Coding！👨‍💻👩‍💻