07 FastAPI - 技术栈

FastAPI 入门

FastAPI 是什么？

FastAPI 是 Python 里写 Web API 的框架，特点：

特点	说明
快	性能接近 Node.js、Go
简单	几行代码就能起一个 API
自动文档	启动后访问 /docs 有交互式文档
类型注解	和第 19 课的类型注解无缝配合

它和 Flask、Django 的区别：

Flask → 轻量，灵活，老项目多
Django → 全栈，带 ORM/模板，适合完整网站
FastAPI → 专注 API，现代、异步友好，Agent/LLM 项目首选

最小示例与路由

一个路径 + 一种方法 = 一个端点；处理函数名随意，不影响 URL；返回 dict / list 自动变 JSON。

py 复制代码

from fastapi import FastAPI

app = FastAPI()

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

app = FastAPI() --- 创建应用
@app.get("/") --- 注册 GET 路由
uvicorn ... :app --reload --- 启动服务，改代码自动重启
http://127.0.0.1:8000/ → 看到 JSON
http://127.0.0.1:8000/docs → Swagger 自动文档（非常重要）

uvicorn 启动方式

bash 复制代码

cd D:\yunyanshijie\skill_test\python_study
.venv\Scripts\activate
pip install fastapi uvicorn
uvicorn lessons.stage3.28_fastapi_intro:app --reload

方式 1：命令行（更接近实际部署习惯）。

bash 复制代码

uvicorn lessons.stage3.28_fastapi_intro:app --reload

默认地址：http://127.0.0.1:8000

方式 2：文件内启动

py 复制代码

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("code.stage3.28_fastapi_intro:app", reload=True)

参数类别

路径参数（Path Parameter）

URL 路径里的动态部分，用 {变量名} 声明：

py 复制代码

@app.get("/users/{user_id}/posts/{post_id}")
def get_post(user_id: int, post_id: int):
    return {"user_id": user_id, "post_id": post_id}

/users/3/posts/7 → user_id=3, post_id=7（FastAPI 自动把字符串转成 int）。

查询参数（Query Parameter）

URL 里 ? 后面的部分：/items?skip=0&limit=10

py 复制代码

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit, "items": []}

路径参数 vs 查询参数

	路径参数	查询参数
写法	/hello/{name}	函数普通参数 + 默认值
位置	URL 路径里	?key=value
典型用途	定位某个资源	筛选、分页、可选配置
例子	/users/1	/items?skip=0&limit=10

请求体与数据校验

Pydantic BaseModel 是什么？

FastAPI 内置 Pydantic，用来定义「请求/响应数据的形状」，并自动校验。

py 复制代码

from pydantic import BaseModel

class MessageCreate(BaseModel):
    name: str
    message: str
    priority: int = 1


class MessageCreateResponse(BaseModel):
    status: str
    echo: str

含义：

调用方必须传 JSON，且包含 name 和 message
两个字段都必须是字符串
缺字段或类型不对 → FastAPI 自动返回 422 Unprocessable Entity，并说明哪里错了

FastAPI 怎么接收请求体？

py 复制代码

@app.post("/messages")
def create_message(data: MessageCreate)->MessageCreateResponse:
   return {"status": "ok", "echo": f"{data.name} 说：{data.message}"}

FastAPI 会自动：

读 Body 里的 JSON
转成 MessageCreate 实例
校验失败就返回 422，不会进你的函数
访问字段用 data.name、data.message（像对象属性，不是 data $"name"$ ）。

HTTPException 是什么？

在 FastAPI 里，当业务逻辑走不通（找不到资源、参数非法、权限不足等），用 raise HTTPException 主动中断请求，返回对应的 HTTP 状态码和错误信息。

py 复制代码

from fastapi import HTTPException

raise HTTPException(status_code=404, detail="找不到城市：Beijing")

环境变量（.env、python-dotenv、API Key 安全）

环境变量是什么？

操作系统和进程里的一组「键值对」，程序启动时可以读取。

env 复制代码

# 注释以 # 开头
API_KEY=sk-your-real-key-here
APP_NAME=Python Study
DEBUG=true

规则：

一行一个变量：KEY=value
不要加引号（除非值本身需要引号）
等号两边不要空格（KEY=value，不是 KEY = value）
值里有特殊字符时再用引号

py 复制代码

from dotenv import load_dotenv # dot==.
import os # Operating System

load_dotenv()  # 默认读取项目根目录的 .env

value = os.getenv("API_KEY")        # 没有则返回 None
value = os.getenv("API_KEY", "")    # 没有则返回默认值 ""

load_dotenv() 做的事：

读取 .env 文件
把里面的键值写进 os.environ
之后 os.getenv() 就能读到

用时机：在读取任何配置之前调用一次，通常放在文件最顶部。

Windows PowerShell 里也可以临时设置：

powershell 复制代码

$env:API_KEY = "sk-test"
python lessons/stage3/30_env_config.py

关掉终端就没了。开发时更常用 .env 文件持久保存。

.env.example --- 给队友的模板

真实 Key 不能分享，但要告诉别人需要哪些变量：

env 复制代码

# .env.example --- 可以提交到 Git
API_KEY=your-api-key-here
APP_NAME=Python Study
DEBUG=false