大项目架构设计：从需求到代码结构

# 典型的分层结构
# ┌─────────────────────────────┐
# │  API/接口层 (routes/)        │  接收HTTP请求，参数校验
# ├─────────────────────────────┤
# │  业务逻辑层 (services/)      │  核心业务规则
# ├─────────────────────────────┤
# │  数据访问层 (repositories/)  │  数据库操作
# ├─────────────────────────────┤
# │  数据模型层 (models/)        │  数据结构定义
# └─────────────────────────────┘
#
# 依赖方向：API → Service → Repository → Model
# 内层不依赖外层：Service 不知道也不关心谁调用它（API或CLI）

# 反例：业务逻辑直接写在路由里（FastAPI/Flask新手常见）
@app.post("/orders")
def create_order(user_id: int, items: list):
    # 校验、计算、扣库存、写数据库、发通知全堆在一起
    # 问题：无法复用、无法测试、改一处影响全部
    ...

# 正例：分层
# routes/order.py
@router.post("/orders")
def create_order(req: OrderRequest):
    return order_service.create_order(req.user_id, req.items)

# services/order_service.py
def create_order(user_id, items):
    validate_items(items)
    total = pricing_service.calculate(items)
    order = order_repo.create(user_id, items, total)
    notification_service.send_confirmation(order)
    return order

# repositories/order_repo.py
def create(user_id, items, total):
    return db.execute(
        "INSERT INTO orders ...",
        {"user_id": user_id, "total": total}
    )

# 一个中型 FastAPI 项目的推荐结构
myapp/
├── pyproject.toml          # 项目配置和依赖
├── README.md
├── .env.example            # 环境变量模板
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── main.py         # 应用入口
│       ├── config.py       # 配置（从环境变量读取）
│       ├── api/            # 接口层
│       │   ├── routes/
│       │   └── deps.py     # 依赖注入
│       ├── core/           # 核心业务逻辑
│       │   ├── services/
│       │   └── exceptions.py
│       ├── db/             # 数据库
│       │   ├── models/
│       │   ├── repositories/
│       │   └── session.py
│       ├── schemas/        # Pydantic 模型（请求/响应）
│       └── utils/          # 工具函数
├── tests/
│   ├── unit/
│   ├── integration/
│   └── conftest.py
└── scripts/                # 运维脚本

# 关键原则：
# 1. src/ 布局：防止import混乱，打包更规范
# 2. 按功能分层，不按技术分层（api/core/db 而不是 models/views/controllers）
# 3. 每个模块有明确职责，一个文件不超过300行

# ❌ 硬编码配置（新手常见）
def connect_db():
    return psycopg2.connect(
        host="192.168.1.100",  # 生产IP写死在代码里！
        password="mypassword123",  # 密码提交到Git！
        dbname="myapp"
    )

# ✅ 配置从环境变量读取
import os
from dataclasses import dataclass

@dataclass(frozen=True)
class Config:
    db_host: str = os.getenv("DB_HOST", "localhost")
    db_port: int = int(os.getenv("DB_PORT", "5432"))
    db_name: str = os.getenv("DB_NAME", "myapp")
    db_user: str = os.getenv("DB_USER", "postgres")
    db_password: str = os.getenv("DB_PASSWORD", "")
    debug: bool = os.getenv("DEBUG", "false").lower() == "true"

config = Config()

# 更好：用 pydantic-settings 自动校验
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    db_host: str = "localhost"
    db_port: int = 5432
    db_password: str
    secret_key: str
    debug: bool = False

    model_config = {"env_file": ".env"}

settings = Settings()  # 自动从环境变量和.env文件读取，缺失必填项直接报错

# 不使用依赖注入：Service 内部直接创建 Repository（硬编码依赖）
class OrderService:
    def __init__(self):
        self.repo = PostgresOrderRepository()  # 写死了，测试时无法替换

# 使用依赖注入：依赖从外部传入
class OrderService:
    def __init__(self, order_repo, user_repo, notifier):
        self.order_repo = order_repo  # 任何实现了相同接口的对象都行
        self.user_repo = user_repo
        self.notifier = notifier

# 生产环境
service = OrderService(
    PostgresOrderRepository(),
    PostgresUserRepository(),
    EmailNotifier()
)

# 测试环境：用内存实现和Mock替换
service = OrderService(
    InMemoryOrderRepository(),
    InMemoryUserRepository(),
    MockNotifier()
)

# FastAPI 的 Depends 就是依赖注入容器
@router.post("/orders")
def create_order(
    req: OrderRequest,
    service: OrderService = Depends(get_order_service)  # 框架自动注入
):
    return service.create_order(req.user_id, req.items)