FastAPI 安装与使用指南

FastAPI 是一个基于 Python 类型提示的现代 Web 框架，特点是高性能、自动生成 API 文档、内置数据校验。它的核心优势：

• 快：基于 Starlette 和 Pydantic，性能与 Node.js、Go 接近
• 自动文档：自动生成 Swagger UI 和 ReDoc 交互式文档
• 类型安全：利用 Python 类型提示做参数校验和序列化
• 简洁：用少量代码就能写出完整的 REST API

适用环境

FastAPI 需要 Python 3.8 及以上版本。本文在 Linux 环境下示范，macOS 和 Windows 同样适用。

安装前确认 Python 版本：

1
python3 --version

建议先创建虚拟环境，避免依赖冲突。以下使用 Python 内置的 venv 模块：

安装 FastAPI

创建项目目录并初始化虚拟环境：

1
mkdir fastapi-demo && cd fastapi-demo
2
python3 -m venv .venv
3
source .venv/bin/activate

激活后终端提示符前会出现 (.venv) 标识。接下来安装 FastAPI 和 ASGI 服务器：

1
pip install fastapi uvicorn[standard]

• fastapi：框架本体
• uvicorn[standard]：ASGI 服务器，[standard] 额外安装 uvloop 和 httptools 以获得更好性能

安装完成后确认：

1
pip show fastapi

第一个应用

创建 main.py：

1
from fastapi import FastAPI
2

3
app = FastAPI()
4

5

6
@app.get("/")
7
def read_root():
8
    return {"message": "Hello, FastAPI!"}

启动服务：

1
uvicorn main:app --reload

• main:app：模块 main 里的 app 实例
• --reload：代码变更时自动重启，开发时使用

访问 http://127.0.0.1:8000 可以看到 JSON 响应。同时 FastAPI 自动生成了两份文档：

• Swagger UI：http://127.0.0.1:8000/docs
• ReDoc：http://127.0.0.1:8000/redoc

在 Swagger 页面可以直接测试接口，无需额外工具。

路径参数

路径参数用于从 URL 中提取动态值：

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

访问 /users/42 返回 {"user_id": 42}。FastAPI 会根据类型提示自动把字符串 "42" 转为整数 42。如果访问 /users/abc，FastAPI 会返回校验错误：

1
{
2
  "detail": [
3
    {
4
      "type": "int_parsing",
5
      "loc": ["path", "user_id"],
6
      "msg": "Input should be a valid integer, unable to parse string as an integer"
7
    }
8
  ]
9
}

查询参数

路径函数中不在路径里的参数会自动成为查询参数：

1
from typing import Optional
2

3

4
@app.get("/users")
5
def list_users(page: int = 1, size: int = 10, keyword: Optional[str] = None):
6
    return {"page": page, "size": size, "keyword": keyword}

请求 /users?page=2&size=20&keyword=zhang 即可获得对应参数。FastAPI 还支持用 Query 做更细致的校验：

1
from fastapi import Query
2

3

4
@app.get("/search")
5
def search(q: str = Query(..., min_length=2, max_length=50, description="搜索关键词")):
6
    return {"query": q}

Query(...) 表示 q 是必填参数，如果缺少会返回 422 错误。

请求体与数据模型

对于 POST、PUT 等请求，使用 Pydantic 模型定义请求体：

1
from pydantic import BaseModel
2

3

4
class Item(BaseModel):
5
    name: str
6
    price: float
7
    description: str = ""
8
    tax: float | None = None
9

10

11
@app.post("/items")
12
def create_item(item: Item):
13
    total = item.price + (item.tax or 0)
14
    return {"name": item.name, "total": total}

FastAPI 会自动：

• 从请求体解析 JSON 并转为 Item 对象
• 校验字段类型和必填项
• 在文档中展示模型结构

测试时可以用 curl：

1
curl -X POST http://127.0.0.1:8000/items \
2
  -H "Content-Type: application/json" \
3
  -d '{"name": "笔记本", "price": 15.5, "tax": 1.5}'

路由拆分

项目变大时，可以用 APIRouter 把路由拆到不同模块：

routers/users.py：

1
from fastapi import APIRouter
2

3
router = APIRouter(prefix="/users", tags=["用户"])
4

5

6
@router.get("/")
7
def list_users():
8
    return [{"id": 1, "name": "张三"}]
9

10

11
@router.post("/")
12
def create_user(name: str):
13
    return {"id": 2, "name": name}

main.py 中引入：

1
from fastapi import FastAPI
2
from routers import users
3

4
app = FastAPI()
5
app.include_router(users.router)

prefix 设置路径前缀，tags 在文档中分组显示。

CORS 配置

如果前端和后端不在同一域名，需要配置跨域：

1
from fastapi.middleware.cors import CORSMiddleware
2

3
app.add_middleware(
4
    CORSMiddleware,
5
    allow_origins=["http://localhost:3000"],
6
    allow_credentials=True,
7
    allow_methods=["*"],
8
    allow_headers=["*"],
9
)

开发阶段可以把 allow_origins 设为 ["*"]，但生产环境应指定具体域名。

常用启动参数

1
uvicorn main:app --reload --host 0.0.0.0 --port 8080

常见问题

pip 安装报找不到包

先确认虚拟环境已激活（终端提示符有 (.venv)），再升级 pip：

1
pip install --upgrade pip
2
pip install fastapi uvicorn[standard]

如果网络慢，可以换国内镜像源：

1
pip install fastapi uvicorn[standard] -i https://pypi.tuna.tsinghua.edu.cn/simple

端口已被占用

uvicorn 默认使用 8000 端口。如果端口被占用，指定其他端口：

1
uvicorn main:app --reload --port 8001

修改代码后不生效

检查是否带了 --reload 参数。另外 --reload 只监听 Python 文件的变更，修改静态文件不会触发重启。

生产环境部署

生产环境不要用 --reload，应该这样启动：

1
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

也可以搭配 Gunicorn 管理进程：

1
pip install gunicorn
2
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

总结

FastAPI 的核心优势是用 Python 类型提示同时实现数据校验、序列化和自动文档，省去了大量样板代码。这里介绍了安装、路由、参数校验、数据模型、路由拆分和 CORS 配置，足够搭建一个功能完整的后端服务。更多内容可以参考 FastAPI 官方文档。

如果你还在比较框架选择，可以先看 Python Web 框架有哪些，怎么选；项目开始变复杂后，再继续阅读 FastAPI 进阶使用指南。