"""
FastAPI 核心处理流水线 - 完整代码示例
对应流程图的每个环节都有注释说明
"""

from fastapi import FastAPI, HTTPException, Depends, Query, Path
from pydantic import BaseModel, Field, EmailStr
from typing import Optional

app = FastAPI()

# ============================================================================
# 📦 1. 定义 Pydantic 模型（用于请求体验证）
# ============================================================================

class ItemCreate(BaseModel):
    """请求体模型 - 对应流程图的【请求体解析与验证】"""
    name: str = Field(..., min_length=1, max_length=50, description="物品名称")
    price: float = Field(..., gt=0, description="价格必须大于 0")
    quantity: int = Field(default=1, ge=0, description="数量不能为负")
    owner_email: Optional[EmailStr] = None  # 自动验证邮箱格式

class ItemResponse(BaseModel):
    """响应模型 - 对应流程图的【响应模型与序列化】"""
    item_id: int
    name: str
    price: float
    quantity: int
    status: str = "active"

# ============================================================================
# 🔗 2. 定义依赖项（对应流程图的【依赖注入系统】）
# ============================================================================

async def verify_token(x_token: str = Header(...)) -> str:
    """依赖函数 1 - 验证 Token"""
    if x_token != "secret-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return x_token

async def get_db_session():
    """依赖函数 2 - 模拟数据库连接"""
    db = {"connection": "opened"}
    yield db  # 可以使用 yield，在请求结束后执行清理
    db["connection"] = "closed"

async def check_item_exists(item_id: int, db = Depends(get_db_session)):
    """依赖函数 3 - 检查物品是否存在"""
    if item_id > 100:  # 模拟不存在
        raise HTTPException(status_code=404, detail="Item not found")
    return {"id": item_id, "db": db}

# ============================================================================
# 🚀 3. 路径操作（完整展示处理流水线）
# ============================================================================

@app.post("/items/{item_id}", response_model=ItemResponse)
async def create_item(
    # --- 🔑 路径参数（自动验证）---
    item_id: int = Path(..., gt=0, description="物品 ID 必须大于 0"),
  
    # --- 🔍 查询参数（自动验证）---
    skip: int = Query(default=0, ge=0, description="跳过数量"),
    limit: int = Query(default=10, ge=1, le=100, description="限制数量"),
  
    # --- 📦 请求体（Pydantic 验证）---
    item: ItemCreate,
  
    # --- 🔗 依赖注入（按顺序执行）---
    token: str = Depends(verify_token),
    db: dict = Depends(get_db_session),
    item_exists: dict = Depends(check_item_exists),
):
    """
    路径操作函数 - 对应流程图的【用户自定义路径操作函数】
  
    此时所有参数已经过验证和转换：
    - item_id 已确认为 int 且 > 0
    - item 已确认为有效的 ItemCreate 对象
    - 依赖项已全部执行完成
    """
  
    # 模拟业务逻辑
    if item.price > 1000:
        raise HTTPException(status_code=400, detail="Price too high")
  
    # 返回数据（会自动被 Pydantic 序列化）
    return ItemResponse(
        item_id=item_id,
        name=item.name,
        price=item.price,
        quantity=item.quantity,
        status="active"
    )

# ============================================================================
# 🧪 4. 测试示例
# ============================================================================

"""
# 启动服务器
uvicorn main:app --reload

# 测试 1 - 成功请求 ✅
curl -X POST "http://localhost:8000/items/1?skip=0&limit=10" \
  -H "x-token: secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apple", "price": 5.5, "quantity": 10}'

# 响应 200:
{
  "item_id": 1,
  "name": "Apple",
  "price": 5.5,
  "quantity": 10,
  "status": "active"
}

# 测试 2 - 验证失败 ❌ (price <= 0)
curl -X POST "http://localhost:8000/items/1" \
  -H "x-token: secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apple", "price": -5, "quantity": 10}'

# 响应 422:
{
  "detail": [
    {
      "loc": ["body", "price"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

# 测试 3 - 类型转换失败 ❌ (item_id 不是 int)
curl -X POST "http://localhost:8000/items/abc" \
  -H "x-token: secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apple", "price": 5.5}'

# 响应 422:
{
  "detail": [
    {
      "loc": ["path", "item_id"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

# 测试 4 - 依赖项失败 ❌ (Token 无效)
curl -X POST "http://localhost:8000/items/1" \
  -H "x-token: wrong-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apple", "price": 5.5}'

# 响应 401:
{
  "detail": "Invalid token"
}

# 测试 5 - 依赖项失败 ❌ (物品不存在)
curl -X POST "http://localhost:8000/items/999" \
  -H "x-token: secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apple", "price": 5.5}'

# 响应 404:
{
  "detail": "Item not found"
}
"""

@app.post("/items/{item_id}", response_model=ItemResponse)
async def create_item(
    item_id: int,      # ✓ 已验证：int, >0
    skip: int,         # ✓ 已验证：int, >=0
    limit: int,        # ✓ 已验证：int, 1-100
    item: ItemCreate,  # ✓ 已验证：Pydantic 模型
    token: str,        # ✓ 依赖注入：已验证的 token
    db: dict,          # ✓ 依赖注入：DB 连接
    item_exists: dict, # ✓ 依赖注入：物品存在确认
):
    # 此时所有参数都是安全的 Python 对象！
    if item.price > 1000:
        raise HTTPException(status_code=400, detail="Price too high")
  
    return ItemResponse(
        item_id=item_id,
        name=item.name,
        price=item.price,
        quantity=item.quantity,
        status="active"
    )

project_root/
├── src/
│   └── app/                # 应用主目录
│       ├── core/           # 全局核心代码（配置、数据库、依赖等）
│       ├── modules/        # 业务模块目录，每个模块自成体系
│       ├── main.py         # FastAPI 应用入口
│       └── __init__.py
├── tests/                  # 测试代码
├── docs/                   # 项目文档
├── worker.py               # RQ (Redis Queue) worker 入口
├── Dockerfile              # Docker 镜像构建文件
├── docker-compose.yml      # Docker Compose 配置
├── pyproject.toml          # uv/Poetry 依赖管理文件
├── uv.lock                 # uv lock文件，锁定依赖版本
├── alembic.ini             # Alembic 配置（如用数据库迁移）
├── migrations/             # Alembic 迁移脚本目录
├── Makefile                # 常用命令脚本
├── .env.example            # 环境变量示例文件
├── .gitignore
└── README.md

src/app/
├── core/
│   ├── config.py           # 配置加载与管理
│   ├── database.py         # 数据库连接与会话
│   ├── redis.py            # Redis 连接与 RQ 队列
│   ├── dependencies.py     # 全局依赖（如认证、权限）
│   ├── exceptions.py       # 自定义异常定义
│   ├── handlers.py         # 全局异常处理器
│   ├── security.py         # 安全相关工具（如密码哈希、JWT 编码解码）
│   ├── logging.py          # 日志配置与管理
│   └── __init__.py
│
├── modules/
│   ├── users/              # 用户模块
│   │   ├── router.py       # 路由定义（APIRouter）
│   │   ├── service.py      # 业务逻辑
│   │   ├── schemas.py      # Pydantic 数据模型 (请求/响应/校验)
│   │   ├── models.py       # SQLAlchemy ORM 数据模型 (数据库表结构)
│   │   ├── crud.py         # 数据库 CRUD 操作
│   │   ├── tasks.py        # 异步任务定义
│   │   └── __init__.py
│   │
│   ├── products/           # 产品模块
│   │   ├── router.py
│   │   ├── service.py
│   │   ├── schemas.py
│   │   ├── models.py
│   │   ├── crud.py
│   │   ├── tasks.py
│   │   └── __init__.py
│   │
│   └── ...                 # 其他业务模块
│
├── main.py                 # FastAPI 应用实例与路由注册
└── __init__.py

# FastAPI 连接数据库的URL
# docker使用
#DATABASE_URL=mysql+pymysql://root:xxx@host.docker.internal:3306/cognitive_disorder?charset=utf8mb4
# 本地使用
DATABASE_URL=mysql+pymysql://root:xxx@localhost:3306/cognitive_disorder?charset=utf8mb4

# minio配置（若需要使用minio对象存储）
MINIO_ENDPOINT=xxx
MINIO_ACCESS_KEY=xxx
MINIO_SECRET_KEY=xxx
MINIO_SECURE=false 
MINIO_BUCKET_NAME=xxx

# 若需要使用JWT验证，JWT配置
SECRET_KEY="miyue"
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=240

pip install pydantic-settings

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    # MySQL 数据库连接 URL
    DATABASE_URL: str
    # 告诉pydantic从.env读取
    model_config = {"env_file": ".env", "case_sensitive": False, "extra": "ignore"}


# 创建配置实例，供其他地方引用
settings = Settings()

fastapi-demo/
   ├── pyproject.toml
   ├── .env                    # 环境变量配置
   ├── .env.example            # 配置模板（提交到 Git）
   ├── src/
   │   └── fastapi_demo/
   │       ├── __init__.py
   │       ├── main.py         # 应用入口
   │       ├── config.py       # Pydantic 配置类 ⭐
   │       └── routes/
   │           └── __init__.py
   └── venv/

# .env
APP_NAME="My FastAPI App"
APP_VERSION="1.0.0"
DEBUG=true

# 服务器配置
HOST=0.0.0.0
PORT=8000

# API 配置
API_PREFIX=/api/v1
BASE_URL=http://localhost:8000

# 数据库配置（示例）
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# 其他配置
MAX_ITEMS=100
ALLOWED_HOSTS=["localhost", "127.0.0.1"]

# .env.example
APP_NAME="My FastAPI App"
APP_VERSION="1.0.0"
DEBUG=false

# 服务器配置
HOST=0.0.0.0
PORT=8000

# API 配置
API_PREFIX=/api/v1
BASE_URL=http://localhost:8000

# 数据库配置
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# 其他配置
MAX_ITEMS=100
ALLOWED_HOSTS=["localhost", "127.0.0.1"]

# .gitignore
.env
venv/
__pycache__/
*.pyc
.pytest_cache/

# src/fastapi_demo/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field, HttpUrl, field_validator
from typing import List
from functools import lru_cache


class Settings(BaseSettings):
    """
    应用配置类 - 使用 Pydantic Settings 管理环境变量
    自动从 .env 文件读取配置，并进行类型验证
    """

    # ============ 应用基础配置 ============
    app_name: str = Field(default="FastAPI Demo", description="应用名称")
    app_version: str = Field(default="1.0.0", description="应用版本")
    debug: bool = Field(default=False, description="调试模式")
  
    # ============ 服务器配置 ============
    host: str = Field(default="0.0.0.0", description="服务器 host")
    port: int = Field(default=8000, ge=1, le=65535, description="服务器端口")
  
    # ============ API 配置 ============
    api_prefix: str = Field(default="/api/v1", description="API 前缀")
    base_url: HttpUrl = Field(default="http://localhost:8000", description="基础 URL")
  
    # ============ 数据库配置 ============
    database_url: str = Field(default="sqlite:///./test.db", description="数据库连接 URL")
  
    # ============ 其他配置 ============
    max_items: int = Field(default=100, ge=1, le=1000, description="最大物品数量")
    allowed_hosts: List[str] = Field(default=["localhost"], description="允许的主机列表")
  
    # ============ Pydantic Settings 配置 ============
    model_config = SettingsConfigDict(
        env_file=".env",           # .env 文件路径
        env_file_encoding="utf-8",  # 文件编码
        case_sensitive=False,       # 环境变量名不区分大小写
        extra="ignore",             # 忽略 .env 中未定义的字段
    )
  
    # ============ 自定义验证器 ============
    @field_validator("api_prefix")
    @classmethod
    def validate_api_prefix(cls, v: str) -> str:
        """确保 API 前缀以 / 开头"""
        if not v.startswith("/"):
            return f"/{v}"
        return v
  
    @property
    def docs_url(self) -> str:
        """文档 URL 属性"""
        return f"{self.base_url}/docs"
  
    @property
    def is_production(self) -> bool:
        """是否生产环境"""
        return not self.debug


@lru_cache()
def get_settings() -> Settings:
    """
    获取配置单例（使用 lru_cache 缓存，避免重复读取 .env）
    在 FastAPI 中作为依赖注入使用
    """
    return Settings()

# src/fastapi_demo/main.py
from fastapi import FastAPI, Depends, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from .config import Settings, get_settings


def create_app(settings: Settings) -> FastAPI:
    """
    应用工厂函数 - 使用配置创建 FastAPI 应用
    """
    # 创建 FastAPI 实例，使用配置中的信息
    app = FastAPI(
        title=settings.app_name,
        version=settings.app_version,
        debug=settings.debug,
        description=f"""
        ## {settings.app_name}
    
        **版本**: {settings.app_version}
    
        **基础 URL**: {settings.base_url}
    
        ### 特性
        - 自动配置加载
        - Pydantic 类型验证
        - 环境变量管理
        """,
    )
  
    # ============ 添加中间件 ============
    app.add_middleware(
        CORSMiddleware,
        allow_origins=settings.allowed_hosts,
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
  
    # ============ 注册路由 ============
    @app.get("/")
    async def root(config: Settings = Depends(get_settings)):
        """根路径 - 显示应用信息"""
        return {
            "app_name": config.app_name,
            "version": config.app_version,
            "debug": config.debug,
            "docs_url": config.docs_url,
        }
  
    @app.get("/health")
    async def health_check(config: Settings = Depends(get_settings)):
        """健康检查"""
        return {
            "status": "healthy",
            "environment": "production" if config.is_production else "development",
        }
  
    @app.get(f"{settings.api_prefix}/items/{{item_id}}")
    async def get_item(
        item_id: int,
        limit: int = 10,
        config: Settings = Depends(get_settings)
    ):
        """获取物品 - 使用 API 前缀"""
        if limit > config.max_items:
            raise HTTPException(
                status_code=400,
                detail=f"Limit cannot exceed {config.max_items}"
            )
        return {
            "item_id": item_id,
            "limit": limit,
            "max_allowed": config.max_items,
            "base_url": str(config.base_url),
        }
  
    @app.get("/config")
    async def get_config(config: Settings = Depends(get_settings)):
        """
        查看当前配置（生产环境建议禁用）
        """
        if config.is_production:
            raise HTTPException(
                status_code=403,
                detail="Config endpoint disabled in production"
            )
        # 不返回敏感信息
        return {
            "app_name": config.app_name,
            "app_version": config.app_version,
            "debug": config.debug,
            "host": config.host,
            "port": config.port,
            "api_prefix": config.api_prefix,
            "max_items": config.max_items,
        }
  
    return app


# 创建应用实例
settings = get_settings()
app = create_app(settings)


if __name__ == "__main__":
    import uvicorn
    # 从配置读取 host 和 port
    settings = get_settings()
    print("==========================================")
    print(settings)
    uvicorn.run(
        "src.fastapi_demo.main:app",
        host=settings.host,
        port=settings.port,
        reload=settings.debug
    )

# 开发模式（自动重载）
uv run uvicorn src.fastapi_demo.main:app --reload
# 或者使用 main.py 中的配置启动
uv run python -m src.fastapi_demo.main

# 指定 host 和 port（会覆盖 .env 中的配置）
uv run uvicorn src.fastapi_demo.main:app --reload --host 0.0.0.0 --port 8000

{"app_name":"My FastAPI App","version":"1.0.0","debug":true,"docs_url":"http://localhost:8000//docs"}