Mr.Nine 的技术笔记

Appearance

FastAPI ​

高性能、易学、快速的现代 Web 框架，基于 Python 类型提示构建。

相关链接:

安装 ​

powershell
uv add "fastapi[standard]"   # 项目级（推荐）
uv pip install --system "fastapi[standard]"  # 全局

[standard] 包含 uvicorn、pydantic、httpx、python-multipart、email-validator、jinja2、fastapi-cli 等常用依赖。如需精简安装：

powershell
uv add fastapi uvicorn  # 手动指定服务器

项目初始化 ​

powershell
uv init my-api && cd my-api
uv add "fastapi[standard]"

创建 main.py：

python
from fastapi import FastAPI

app = FastAPI()

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

运行 ​

fastapi[standard] 自带 FastAPI CLI，提供 fastapi dev 和 fastapi run 命令：

powershell
uv run fastapi dev main.py    # 开发模式（自动热重载）
uv run fastapi run main.py    # 生产模式

也可以直接使用 uvicorn：

powershell
uv run uvicorn main:app --reload                    # 开发模式
uv run uvicorn main:app --host 0.0.0.0 --port 8000  # 生产模式

Uvicorn 常用参数 ​

参数说明
--reload代码变更自动重载（仅开发）
--host监听地址，默认 127.0.0.1
--port监听端口，默认 8000
--workers工作进程数（生产建议 ≥ CPU 核数）

常用代码速查 ​

路径参数与查询参数 ​

python
from fastapi import FastAPI

app = FastAPI()

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

请求体 ​

python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None

@app.post("/items")
def create_item(item: Item):
    return item

响应模型 ​

python
@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int):
    ...

内置文档 ​

FastAPI 自动生成交互式 API 文档，启动服务后访问：

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

数据库集成 ​

推荐使用 SQLModel（同一作者，FastAPI + SQLAlchemy 融合）：

powershell
uv add sqlmodel

详见 SQLModel 官网

部署 ​

powershell
# fastapi run（推荐，自动检测 app）
uv run fastapi run main.py

# Gunicorn + Uvicorn（需要多 worker 时）
uv add gunicorn uvicorn
uv run gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Docker 部署

参考官方 Docker 模板：tiangolo/uvicorn-gunicorn-fastapi-docker