第11章 · FastAPI 框架基础

# ============ FastAPI 最小程序 ============
from fastapi import FastAPI

# 1. 创建 FastAPI 实例（类似 Flask 的 app = Flask(__name__)）
app = FastAPI()


# 2. 用装饰器注册路由
# @app.get("/") 表示：GET 请求 / 时调用下面这个函数
@app.get("/")
def read_root():
    # 直接 return 字典，FastAPI 自动转成 JSON
    return {"message": "Hello, FastAPI!"}


# 3. 再来一个带参数的接口（路径里的 {item_id} 是占位符）
@app.get("/items/{item_id}")
def read_item(item_id: int):
    # 注意 item_id: int —— 这是 Python 类型提示
    # FastAPI 会自动把 URL 里的字符串转成 int
    # 如果转不成（比如访问 /items/abc）会自动返回 422 错误
    return {"item_id": item_id, "price": 9.99}

# ============ Path 参数：URL 路径里的一部分 ============
@app.get("/users/{user_id}")
def get_user(user_id: int):
    # user_id 是 Path 参数（因为名字在 URL 的 {} 里出现）
    # 类型 int —— 自动校验，传 abc 就会 422
    return {"user_id": user_id, "name": f"用户#{user_id}"}


# ============ Query 参数：URL 问号后面的 key=value ============
@app.get("/articles/")
def list_articles(skip: int = 0, limit: int = 10):
    # skip 和 limit 都是 Query 参数（名字没在 URL 里出现）
    # 都有默认值 → 可选；没传就是 0 和 10
    fake_db = [{"id": i, "title": f"文章{i}"} for i in range(100)]
    return fake_db[skip:skip+limit]


# ============ Path + Query 混着用 ============
@app.get("/users/{user_id}/articles")
def user_articles(user_id: int, q: str = None):
    # user_id 是 Path（在 {} 里），q 是 Query（不在）
    # q: str = None 表示是可选的字符串参数
    result = {"user_id": user_id}
    if q:
        result["search"] = q       # 有传 q 才加进结果
    return result

from pydantic import BaseModel


# ============ 1. 定义数据模型 ============
# 继承 BaseModel，每个属性都有类型注解
class Item(BaseModel):
    name: str                       # 必填字段：商品名
    price: float                    # 必填字段：单价
    description: str = None          # 可选字段（有默认值）
    in_stock: bool = True             # 可选字段，默认 True


# ============ 2. POST 接口：接收 JSON 请求体 ============
@app.post("/items/")
def create_item(item: Item):
    # item 是 Pydantic 模型实例，可以直接 .name / .price 访问
    # FastAPI 已经自动完成：JSON 解析 → 类型校验 → 缺字段报 422

    # 简单逻辑：算一个含税总价（演示用）
    total = item.price * 1.13
    return {
        "name": item.name,
        "price_with_tax": round(total, 2),
        "in_stock": item.in_stock,
    }


# ============ 3. Path + Body 同时用 ============
@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    # item_id 来自 URL（Path），item 来自请求体（Body）
    # FastAPI 自动分辨：基本类型 = Path/Query，Pydantic 模型 = Body
    return {"item_id": item_id, "updated": item.dict()}