FastAPI 新手极速入门实战指南

FastAPI 新手极速入门实战指南

全文约5000字，阅读约15分钟，跟着操作约30分钟完成第一个可运行的API项目。

写在前面

WEB项目地址：演示地址 安卓APP下载地址：演示地址

FastAPI 是近几年 Python 生态中增长最快的 Web 框架，GitHub Star 数已超过 8 万。它基于 Python 类型提示，自动生成 API 文档、自动校验请求数据、原生支持异步，上手简单但上限很高。本文从零开始，手把手带你跑通第一个 FastAPI 项目。

前置要求：会写基础的 Python 代码（函数、类、字典这些），懂一点点命令行操作就行。

一、开发环境搭建与依赖安装

1.1 确认 Python 版本

FastAPI 要求 Python 3.7+，建议用 3.9 或更高版本。在终端输入：

python –version
# 或者
python3 –version

如果版本低于 3.7，先去 python.org 下载安装。

1.2 创建虚拟环境（重要！）

不要直接在全局环境装包，用虚拟环境隔离项目依赖。

# 创建虚拟环境
python -m venv fastapi_env

# 激活（Mac/Linux）
source fastapi_env/bin/activate

# 激活（Windows）
fastapi_env\\Scripts\\activate

激活后，命令行前面会显示 (fastapi_env)，说明成功了。

1.3 安装 FastAPI 和 Uvicorn

pip install fastapi uvicorn[standard]

uvicorn[standard] 是 ASGI 服务器，用来运行 FastAPI 应用。加 [standard] 会多装一些推荐依赖，省得后面缺包。

想一步到位装全套的，也可以运行：

pip install "fastapi[all]"

这会连带装上 uvicorn 和一些常用工具。

验证安装：

pip list | grep fastapi
pip list | grep uvicorn

能看到版本号就说明装好了。

二、第一个 Hello World 接口

2.1 创建项目文件

新建一个文件夹，在里面创建 main.py：

from fastapi import FastAPI

app = FastAPI()

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

逐行解释：

• from fastapi import FastAPI —— 导入框架
• app = FastAPI() —— 创建应用实例，这是整个项目的入口
• @app.get("/") —— 装饰器，告诉 FastAPI 这是一个 GET 请求的路由，路径是根路径 /
• async def hello(): —— 异步函数，处理请求
• return {"message": "Hello World"} —— 返回 JSON 响应

2.2 启动服务

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

uvicorn main:app –reload

• main:app —— main 是文件名，app 是应用实例名
• –reload —— 开启热重载，改代码后服务自动重启，开发时必加

看到类似这样的输出就成功了：

INFO: Uvicorn running on http://127.0.0.1:8000
INFO: Application startup complete.

2.3 测试接口

打开浏览器访问 http://127.0.0.1:8000，应该能看到：

{"message": "Hello World"}

也可以用 curl 测试：

curl http://127.0.0.1:8000

第一个接口就跑通了。

三、路径参数与查询参数

3.1 路径参数（Path Parameters）

路径参数是写在 URL 路径里的变量，比如 /users/123 里的 123。

@app.get("/users/{user_id}")
async def get_user(user_id: int):
return {"user_id": user_id, "name": f"用户{user_id}"}

访问 http://127.0.0.1:8000/users/42，返回：

{"user_id": 42, "name": "用户42"}

关键点：user_id: int 这个类型注解不是摆设——FastAPI 会自动把 URL 里的字符串转成整数，如果传 abc 会直接报 422 错误。

3.2 查询参数（Query Parameters）

查询参数是 URL 问号后面的键值对，比如 /items?page=2&size=10。

@app.get("/items")
async def list_items(page: int = 1, size: int = 10, keyword: str = None):
return {
"page": page,
"size": size,
"keyword": keyword,
"data": [f"item_{i}" for i in range(page, page + size)]
}

访问 http://127.0.0.1:8000/items?page=3&size=5&keyword=test，返回：

{"page": 3, "size": 5, "keyword": "test", "data": ["item_3", "item_4", …]}

没传的参数会用默认值。

3.3 路径参数 + 查询参数混用

@app.get("/users/{user_id}/orders")
async def get_user_orders(user_id: int, status: str = None, limit: int = 10):
return {"user_id": user_id, "status": status, "limit": limit}

FastAPI 能自动区分：user_id 匹配路径，status 和 limit 是查询参数。

四、请求体数据模型定义与验证

POST、PUT 请求通常要传 JSON 数据，用 Pydantic 模型来定义和验证。

4.1 定义数据模型

from pydantic import BaseModel

class CreateUserRequest(BaseModel):
username: str
email: str
age: int = 0 # 默认值
bio: str | None = None # 可选字段

4.2 在接口中使用

@app.post("/users")
async def create_user(user: CreateUserRequest):
return {
"message": f"用户 {user.username} 创建成功",
"data": user.model_dump()
}

4.3 测试 POST 请求

用 curl 测试：

curl -X POST http://127.0.0.1:8000/users \\
-H "Content-Type: application/json" \\
-d '{"username": "张三", "email": "zhangsan@test.com", "age": 25}'

返回：

{"message": "用户 张三 创建成功", "data": {"username": "张三", "email": "zhangsan@test.com", "age": 25, "bio": null}}

自动验证：如果传 {"username": "张三", "email": "不是邮箱"}，FastAPI 会返回详细的校验错误。

4.4 请求体 + 路径 + 查询参数同时使用

@app.put("/users/{user_id}")
async def update_user(
user_id: int, # 路径参数
user: CreateUserRequest, # 请求体
dry_run: bool = False # 查询参数
):
if dry_run:
return {"dry_run": True, "data": user.model_dump()}
return {"user_id": user_id, "updated": user.model_dump()}

FastAPI 会根据参数类型自动分配到正确的位置。

五、异步函数与并发性能优势

5.1 什么时候用 async def

FastAPI 支持两种写法：

# 同步写法
@app.get("/sync")
def sync_endpoint():
return {"type": "sync"}

# 异步写法
@app.get("/async")
async def async_endpoint():
return {"type": "async"}

怎么选：如果接口内部需要等待外部资源（数据库查询、HTTP 请求、文件读写），用 async def 配合 await，这样等待时不会阻塞其他请求。

5.2 异步示例

import httpx

@app.get("/proxy/{url:path}")
async def proxy_request(url: str):
async with httpx.AsyncClient() as client:
response = await client.get(f"https://{url}")
return {"status": response.status_code, "data": response.text[:200]}

await client.get(…) 发起 HTTP 请求时，FastAPI 可以去处理其他请求，不会干等着。

5.3 性能优势

FastAPI 基于 ASGI 异步模型，处理 I/O 密集型任务时，吞吐量比传统 WSGI 框架（如 Flask）高出数倍。如果你的接口只是简单的计算（不涉及 IO），用普通 def 就行，FastAPI 会自动放到线程池执行，不影响主事件循环。

六、自动生成交互式 API 文档

这是 FastAPI 最省心的功能——零配置，自动生成。

启动服务后访问：

• Swagger UI：http://127.0.0.1:8000/docs —— 交互式界面，可以直接在网页上点按钮测试接口
• ReDoc：http://127.0.0.1:8000/redoc —— 另一种风格的文档，更适合阅读

打开 /docs 你会看到所有接口自动列出来了，每个接口的路径参数、查询参数、请求体格式都一目了然。点击 “Try it out” 可以直接发送请求测试。

给文档加点信息

app = FastAPI(
title="我的第一个 API",
description="这是一个新手入门项目",
version="1.0.0"
)

@app.get("/hello", summary="打招呼接口", description="返回一句问候语")
async def hello(name: str = "World"):
return {"message": f"Hello {name}"}

这些信息会自动显示在文档里。

七、常见启动报错与排查方法

7.1 ModuleNotFoundError: No module named 'fastapi'

原因：没装 FastAPI，或者装在了别的环境里。

解决：确认虚拟环境已激活，重新安装：

pip install fastapi uvicorn[standard]

7.2 ImportError: cannot import name 'FastAPI'

原因：文件名不小心叫 fastapi.py，和框架包重名了。

解决：把文件名改成别的，比如 main.py。

7.3 端口 8000 被占用

报错：OSError: [Errno 48] Address already in use（Mac）或类似。

解决：换一个端口：

uvicorn main:app –reload –port 8001

或者找到占用 8000 的进程杀掉。

7.4 uvicorn 命令找不到

原因：虚拟环境没激活，或者 uvicorn 没装。

解决：激活虚拟环境后重装：

source fastapi_env/bin/activate # Mac/Linux
pip install uvicorn[standard]

7.5 代码改了但服务没变化

原因：启动时忘了加 –reload。

解决：加上 –reload 重启：

uvicorn main:app –reload

7.6 请求返回 422 Unprocessable Entity

原因：请求数据不符合模型定义（类型不对、缺少必填字段等）。

解决：检查请求体格式，FastAPI 会在响应里告诉你具体哪个字段有问题。

八、项目结构优化与模块拆分

一个文件写完所有接口只适合极小的项目。项目稍微大一点，就该拆分模块了。

8.1 推荐的项目结构

my_project/
├── main.py # 应用入口
├── app/
│ ├── __init__.py
│ ├── api/ # 路由层
│ │ ├── __init__.py
│ │ ├── v1/ # API 版本
│ │ │ ├── __init__.py
│ │ │ ├── users.py
│ │ │ └── orders.py
│ ├── models/ # Pydantic 数据模型
│ │ ├── __init__.py
│ │ └── user.py
│ └── core/ # 核心配置
│ ├── __init__.py
│ └── config.py
├── requirements.txt
└── .env

8.2 使用 APIRouter 拆分路由

app/api/v1/users.py：

from fastapi import APIRouter

router = APIRouter(prefix="/users", tags=["用户管理"])

@router.get("/")
async def list_users():
return [{"id": 1, "name": "张三"}, {"id": 2, "name": "李四"}]

@router.get("/{user_id}")
async def get_user(user_id: int):
return {"id": user_id, "name": f"用户{user_id}"}

app/api/v1/orders.py：

from fastapi import APIRouter

router = APIRouter(prefix="/orders", tags=["订单管理"])

@router.get("/")
async def list_orders():
return [{"id": 1, "total": 100}, {"id": 2, "total": 200}]

8.3 在 main.py 中注册路由

from fastapi import FastAPI
from app.api.v1 import users, orders

app = FastAPI(title="我的项目")

app.include_router(users.router)
app.include_router(orders.router)

这样 /docs 里接口会自动按 tags 分组，清晰很多。

九、实用调试技巧与日志配置

9.1 开发阶段调试

打印日志：直接用 print() 最简单，但正式项目建议用 logging。

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.get("/debug")
async def debug_endpoint():
logger.info("有人访问了调试接口")
return {"status": "ok"}

查看请求详情：Uvicorn 默认会打印每个请求的日志，包括方法、路径、状态码和耗时。

9.2 配置更详细的日志

import logging

logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s – %(name)s – %(levelname)s – %(message)s'
)
logger = logging.getLogger(__name__)

这样会显示时间、模块名、日志级别等详细信息。

9.3 调试技巧

十、从本地运行到部署准备

10.1 开发模式和生成模式的区别

生产环境不要用 –reload，会消耗额外资源。

10.2 生成依赖文件

pip freeze > requirements.txt

这样部署时只需 pip install -r requirements.txt 就能装上所有依赖。

10.3 生产部署方案

方案一：直接用 Uvicorn（适合小型项目）

uvicorn main:app –host 0.0.0.0 –port 8000

方案二：Gunicorn + Uvicorn Worker（推荐）

Gunicorn 做进程管理，Uvicorn 做实际处理，适合多核 CPU。

gunicorn -k uvicorn.workers.UvicornWorker -w 4 main:app

-w 4 表示启动 4 个 worker 进程。

方案三：Docker 容器化

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "–host", "0.0.0.0", "–port", "8000"]

构建并运行：

docker build -t my-fastapi-app .
docker run -p 8000:8000 my-fastapi-app

10.4 部署前检查清单

• 确认 requirements.txt 已生成且包含所有依赖
• 确认没有硬编码的敏感信息（密钥、密码等），改用环境变量
• 确认关闭了 –reload
• 确认日志级别设为 INFO 或 WARNING
• 确认服务监听的地址是 0.0.0.0（而不是 127.0.0.1），否则外部访问不到

下一步学什么

到这里你已经跑通了一个完整的 FastAPI 项目，掌握了最核心的概念。接下来可以继续学：

• 依赖注入（Depends）—— 复用数据库连接、权限校验等逻辑
• 中间件（Middleware）—— 统一处理跨域、日志、鉴权
• 数据库集成—— SQLAlchemy + FastAPI 的异步支持
• 异常处理—— 全局捕获异常，统一返回格式

这些够你玩一阵子了。遇到问题先去 /docs 看看，很多答案文档里都有。