FastAPI 入门到进阶

一句话：FastAPI 就是一个用 Python 写“后端接口”的工具，让别人可以通过网址来问你的程序要数据、交数据、改数据。

目录

1. FastAPI 是什么
2. 它解决什么问题
3. 最小例子
4. 核心概念
5. 做一个简单接口
6. 进阶但常用的东西
7. 常见错误
8. 学习顺序

1. FastAPI 是什么

你可以把 FastAPI 想成一个“餐厅前台”。

用户、网页、小程序、App 来点餐：

我要看商品列表
我要登录
我要提交订单
我要查这个用户的信息

FastAPI 就像前台一样负责接待：

你要什么？
参数给我。
我检查一下。
我去后厨处理。
处理完把结果还给你。

这里的“前台”就是接口服务。

2. 它解决什么问题

假设你有一个前端页面，它不能直接去数据库里乱翻东西。它需要问后端：

GET /users/1

意思是：我要查 id 为 1 的用户。

后端收到后，去数据库查，然后返回：

{
  "id": 1,
  "name": "小明"
}

FastAPI 就是帮你快速写这种后端接口的框架。

它的优点很实在：

3. 第一个最小例子

先安装：

pip install "fastapi[standard]"

新建 main.py：

from fastapi import FastAPI

app = FastAPI()

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

运行：

fastapi dev main.py

打开：

http://127.0.0.1:8000

你会看到：

{
  "message": "Hello FastAPI"
}

再打开：

http://127.0.0.1:8000/docs

这就是 FastAPI 自动生成的接口测试页面。你不用自己写 Swagger 文档，它会自动帮你生成。

4. 核心概念

app

app = FastAPI()

这就像开了一家餐厅。后面所有接口都挂在这个 app 上。

路径 path

@app.get("/users")

/users 就是路径。别人访问这个地址，就会来到这个接口。

请求方法 method

常见有 4 个：

比如：

@app.get("/users")
def get_users():
    return ["小明", "小红"]

@app.post("/users")
def create_user():
    return {"message": "创建成功"}

函数

def get_users():
    return ["小明", "小红"]

当有人访问 /users，FastAPI 就会调用这个函数。

返回值

你可以直接返回字典、列表、字符串、数字。FastAPI 会帮你变成 JSON。

return {"name": "小明", "age": 10}

5. 做一个简单用户接口

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int

users = []

@app.get("/users")
def list_users():
    return users

@app.post("/users")
def create_user(user: User):
    users.append(user)
    return {
        "message": "创建成功",
        "user": user
    }

@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id < 0 or user_id >= len(users):
        return {"error": "用户不存在"}
    return users[user_id]

这里为了让你先看懂流程，暂时用了内存里的 users = []，也暂时用了 return {"error": ...}。正式项目里，数据应该放数据库，错误应该用后面会讲的 HTTPException。

这里重点看这个：

class User(BaseModel):
    name: str
    age: int

这叫数据模型。大白话就是：你告诉 FastAPI，“新增用户必须长这样”。

如果前端传：

{
  "name": "小明",
  "age": 10
}

可以。

如果传：

{
  "name": "小明",
  "age": "十岁"
}

FastAPI 会发现 age 应该是数字，不应该是文字，然后自动报错。

这就是 FastAPI 很爽的地方：它帮你守门。

6. 参数怎么传

路径参数

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

访问：

/users/3

user_id 就是 3。

查询参数

@app.get("/search")
def search(keyword: str, page: int = 1):
    return {
        "keyword": keyword,
        "page": page
    }

访问：

/search?keyword=apple&page=2

就能拿到：

{
  "keyword": "apple",
  "page": 2
}

请求体 body

一般 POST 用 body：

class Product(BaseModel):
    name: str
    price: float

@app.post("/products")
def create_product(product: Product):
    return product

前端传 JSON：

{
  "name": "苹果",
  "price": 9.9
}

7. async 是什么

你会看到有些例子这样写：

@app.get("/")
async def hello():
    return {"message": "hi"}

async 可以理解成：这个函数可能会等别人，比如等数据库、等网络请求。等的时候，它不会傻站着，可以先去处理别的请求。

大白话：

普通 def：我在窗口等你办完，别人先排队。
async def：你去拿材料时，我先服务下一个人。

刚入门时记住：

不用一开始就纠结。先会写接口更重要。

8. 常用进阶功能

HTTPException：认真地报错

不要这样：

return {"error": "用户不存在"}

更推荐：

from fastapi import HTTPException

@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id < 0 or user_id >= len(users):
        raise HTTPException(status_code=404, detail="用户不存在")
    return users[user_id]

这样前端能明确知道：这是 404 错误。

Depends：公共逻辑复用

比如很多接口都要检查 token：

from fastapi import Depends

def check_token(token: str):
    if token != "123":
        raise HTTPException(status_code=401, detail="未登录")
    return token

@app.get("/profile")
def profile(token: str = Depends(check_token)):
    return {"message": "这是个人资料"}

这个例子为了讲清楚 Depends，先用普通参数模拟 token。正式项目通常会从请求头里的 Authorization: Bearer <token> 读取 token。

Depends 大白话就是：进这个接口之前，先做一件公共检查。

APIRouter：接口太多时分文件

项目小的时候，全部写 main.py 可以。

项目大了以后，应该拆：

app/
  main.py
  routers/
    users.py
    products.py

users.py 专门放用户接口，products.py 专门放商品接口。

9. 常见错误

10. 你应该怎么学

按这个顺序就行：

1. 先会启动服务：main.py + fastapi dev main.py
2. 学会写 GET
3. 学会写 POST
4. 学会路径参数：/users/{id}
5. 学会查询参数：?page=1
6. 学会 Pydantic 模型
7. 学会用 /docs 测接口
8. 学会 HTTPException
9. 学会拆分 APIRouter
10. 再学数据库、登录、部署

11. 小抄

最后一句话总结

FastAPI 的核心就是：用 Python 函数接住 HTTP 请求，把参数检查好，处理业务，再把 JSON 返回给前端。先别急着学数据库、权限、部署，先把“路径、方法、参数、返回值、模型、文档”这 6 件事吃透，FastAPI 就算入门了。

参考资料

• FastAPI 官方首页
• FastAPI Tutorial - User Guide
• FastAPI First Steps
• FastAPI CLI