Day 16 | Pydantic 数据验证

#!/usr/bin/env python3
"""
Day 16 - Pydantic Schema 定义
演示如何定义严格的数据验证模型
"""

from pydantic import BaseModel, EmailStr, Field
from typing import Optional

# ========== 1. 请求模型 (UserCreate) ==========
# 这是前端用来注册时发送的数据结构
# 注意：这个模型包含密码字段，用于接收数据
class UserCreate(BaseModel):
    """
    创建用户的请求模型
    用于验证前端发送的用户注册数据
    """
    # username: 必填，字符串，长度 3-20
    # Field(...) 中的 ... 表示必填字段（Ellipsis）
    # min_length=3: 最小长度 3 个字符
    # max_length=20: 最大长度 20 个字符
    # description: 字段描述（会显示在 Swagger 文档中）
    username: str = Field(
        ..., 
        min_length=3, 
        max_length=20, 
        description="用户名，3-20 个字符"
    )
    
    # password: 必填，最少 8 位
    # 注意：密码不应该在响应中返回，所以响应模型中不包含此字段
    password: str = Field(
        ..., 
        min_length=8, 
        description="密码，至少 8 个字符（不会在响应中返回）"
    )
    
    # email: 必填，必须符合邮箱格式
    # EmailStr 是 Pydantic 提供的特殊类型，自动验证邮箱格式
    # 需要安装 email-validator: pip install email-validator
    email: EmailStr = Field(..., description="邮箱地址")
    
    # age: 选填 (Optional)，默认 None
    # 但如果填了，必须在 0-120 之间
    # gt=0: 大于 0（greater than）
    # lt=120: 小于 120（less than）
    age: Optional[int] = Field(
        None, 
        gt=0, 
        lt=120, 
        description="年龄，0-120 之间（可选）"
    )

# ========== 2. 响应模型 (UserResponse) ==========
# 这是我们返回给前端的数据结构
# 注意：这里故意【不包含】password 字段，防止密码泄露！
class UserResponse(BaseModel):
    """
    用户响应模型
    用于返回用户信息，不包含敏感字段（如密码）
    """
    id: int = Field(..., description="用户 ID")
    username: str = Field(..., description="用户名")
    email: EmailStr = Field(..., description="邮箱地址")
    age: Optional[int] = Field(None, description="年龄")
    
    # Config 类的作用是让 Pydantic 支持读取 ORM 对象
    # from_attributes = True: 允许从对象属性创建模型（后面数据库部分会用到）
    class Config:
        from_attributes = True

#!/usr/bin/env python3
"""
Day 16 - Pydantic 数据验证实战
演示如何在 FastAPI 中使用 Pydantic 模型进行数据验证
"""

from fastapi import FastAPI, HTTPException
from schemas import UserCreate, UserResponse

# 初始化 FastAPI 应用
app = FastAPI(
    title="User Management API",
    description="演示 Pydantic 数据验证的 API",
    version="1.0.0"
)

# 模拟数据库（实际应该用真实数据库）
fake_users_db = []
next_user_id = 1

# ========== 关键点 1: user: UserCreate ==========
# 告诉 FastAPI，要用 UserCreate 这个模型去校验 request body
# 如果请求数据不符合 UserCreate 的定义，FastAPI 会自动返回 422 错误
#
# ========== 关键点 2: response_model=UserResponse ==========
# 告诉 FastAPI，返回数据时，请自动过滤掉不在 UserResponse 里的字段
# 比如即使数据库返回了 password，也会被自动过滤掉
@app.post("/users/", response_model=UserResponse, status_code=201)
def create_user(user: UserCreate):
    """
    创建用户接口
    
    功能：
    - **自动校验**: 长度、类型、邮箱格式
    - **自动脱敏**: 返回结果不含密码
    
    参数:
        user: 用户创建数据（自动验证）
    
    返回:
        UserResponse: 用户信息（不含密码）
    """
    # 如果代码能执行到这里，说明数据绝对是合法的！
    # 无需再做 if 判断，Pydantic 已经帮我们验证过了
    
    # 检查用户名是否已存在（业务逻辑验证）
    for existing_user in fake_users_db:
        if existing_user["username"] == user.username:
            raise HTTPException(
                status_code=400, 
                detail="Username already exists"
            )
    
    # 模拟保存到数据库
    global next_user_id
    new_user = {
        "id": next_user_id,
        "username": user.username,
        "email": user.email,
        "age": user.age,
        "password": user.password  # 这个字段会被 response_model 自动过滤
    }
    fake_users_db.append(new_user)
    next_user_id += 1
    
    print(f"✅ User created: {user.username} (password will not be returned)")
    
    # 返回用户信息
    # 注意：即使 new_user 包含 password，response_model 也会自动过滤掉
    return new_user

# ========== 查询用户列表 ==========
@app.get("/users/", response_model=list[UserResponse])
def list_users():
    """
    获取用户列表
    
    返回:
        用户列表（不含密码）
    """
    return fake_users_db

# ========== 查询单个用户 ==========
@app.get("/users/{user_id}", response_model=UserResponse)
def get_user(user_id: int):
    """
    获取单个用户信息
    
    参数:
        user_id: 用户 ID
    
    返回:
        UserResponse: 用户信息（不含密码）
    """
    for user in fake_users_db:
        if user["id"] == user_id:
            return user
    
    raise HTTPException(status_code=404, detail="User not found")