FastAPI零基础入门（纯知识点版）（附完整代码）

一、环境搭建

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

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

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

十五、常用命令速查