一、环境搭建

1. 创建虚拟环境

python -m venv venv

2. 激活虚拟环境

# Windows
venv\Scripts\activate
# Mac/Linux
source venv/bin/activate

3. 安装包

pip install fastapi uvicorn

二、第一个程序

4. 创建main.py

from fastapi import FastAPI

app = FastAPI()

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

5. 启动服务

uvicorn main:app --reload

6. 访问地址

• 接口地址：http://localhost:8000

• 自动文档：http://localhost:8000/docs

三、路径参数

7. 基本用法

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

访问 /user/123 → 返回 {"user_id": 123}

8. 多个路径参数

@app.get("/user/{user_id}/item/{item_id}")
def get_item(user_id: int, item_id: int):
    return {"user_id": user_id, "item_id": item_id}

四、查询参数

9. 基本用法

@app.get("/items")
def get_items(page: int = 1, size: int = 10):
    return {"page": page, "size": size}

访问 /items?page=3&size=20 → 返回 {"page": 3, "size": 20}

10. 必填查询参数

from fastapi import Query

@app.get("/search")
def search(q: str = Query(...), limit: int = 10):
    return {"q": q, "limit": limit}

Query(...) 中的 ... 表示必填

五、请求体（POST）

11. 定义数据模型

from pydantic import BaseModel

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

12. 接收请求体

@app.post("/users")
def create_user(user: User):
    return {"name": user.name, "age": user.age}

13. 可选字段

class User(BaseModel):
    name: str
    age: int = None  # 或者 Optional[int] = None

六、响应模型

14. 限制返回字段

@app.post("/users", response_model=User)
def create_user(user: User):
    return user

15. 返回列表

from typing import List

@app.get("/users", response_model=List[User])
def get_users():
    return [{"name": "张三", "age": 20}, {"name": "李四", "age": 22}]

七、HTTP状态码

16. 手动指定状态码

@app.post("/users", status_code=201)
def create_user(user: User):
    return user

17. 返回错误

from fastapi import HTTPException

@app.get("/user/{user_id}")
def get_user(user_id: int):
    if user_id <= 0:
        raise HTTPException(status_code=400, detail="user_id必须大于0")
    return {"user_id": user_id}

常用状态码：

• 200：成功

• 201：创建成功

• 400：请求参数错误

• 404：找不到资源

• 500：服务器错误

八、路径与查询参数混用

18. 同时使用

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str = None, page: int = 1):
    return {"item_id": item_id, "q": q, "page": page}

访问 /items/123?q=hello&page=2

九、请求头

19. 获取请求头

from fastapi import Header

@app.get("/headers")
def get_headers(user_agent: str = Header(None), token: str = Header(None)):
    return {"user_agent": user_agent, "token": token}

十、异步支持

20. 异步写法

import asyncio

@app.get("/async")
async def async_endpoint():
    await asyncio.sleep(1)
    return {"msg": "done"}

21. 什么时候用async

• 函数里有 await → 用 async def

• 只有计算和数据处理 → 用 def

十一、路径顺序

22. 固定路径写在动态路径前面

# 正确
@app.get("/users/me")
def get_current_user():
    return {"user": "me"}

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

# 错误：/users/me 会被 /users/{user_id} 匹配

十二、完整示例

23. 简易待办事项接口

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI()

class Todo(BaseModel):
    id: int
    title: str
    done: bool = False

todos = []

@app.post("/todos", status_code=201, response_model=Todo)
def create_todo(todo: Todo):
    for t in todos:
        if t.id == todo.id:
            raise HTTPException(status_code=400, detail="id已存在")
    todos.append(todo)
    return todo

@app.get("/todos", response_model=List[Todo])
def list_todos():
    return todos

@app.get("/todos/{todo_id}")
def get_todo(todo_id: int):
    for t in todos:
        if t.id == todo_id:
            return t
    raise HTTPException(status_code=404, detail="待办不存在")

@app.delete("/todos/{todo_id}")
def delete_todo(todo_id: int):
    for i, t in enumerate(todos):
        if t.id == todo_id:
            todos.pop(i)
            return {"msg": "删除成功"}
    raise HTTPException(status_code=404, detail="待办不存在")

十三、启动命令

24. 开发环境

uvicorn main:app --reload

25. 生产环境

uvicorn main:app --host 0.0.0.0 --port 8000

26. 生产环境（多进程）

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

十四、常见错误

27. 端口被占用

• 报错：Address already in use

• 解决：换端口 --port 8001 或关掉占用端口的程序

28. 422 Unprocessable Entity

• 原因：POST请求忘了加 Content-Type: application/json

• 解决：请求头加上这个

29. 路径顺序导致404

• 原因：固定路径写在动态路径下面

• 解决：把固定路径往上移

十五、常用命令速查

操作	命令
激活虚拟环境(Windows)	venv\Scripts\activate
激活虚拟环境(Mac/Linux)	source venv/bin/activate
安装包	pip install fastapi uvicorn
启动服务	uvicorn main:app --reload
查看已装包	pip list
退出虚拟环境	deactivate