进阶：FastAPI 业务架构详解

# ❌ 反例：routes/trading.py —— 路由 + 业务逻辑 + 数据库操作混在一起
@router.post("/orders")
async def place_order(req: PlaceOrderRequest):
    # 校验逻辑（40 行）
    # 查询数据库余额（30 行）
    # 调用交易所 API（40 行）
    # 写入订单表（20 行）
    # 发送通知（15 行）
    return order

# app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.config import settings
from app.core.middleware import log_requests
from app.core.exceptions import register_exception_handlers
from app.routes import trading, agent, health

app = FastAPI(title="Electric Trading AI", version="0.1.0")

# 中间件
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])

# 全局异常处理器
register_exception_handlers(app)

# 注册路由
app.include_router(health.router)
app.include_router(trading.router)
app.include_router(agent.router)

# app/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    llm_api_key: str = ""
    llm_base_url: str = "https://api.siliconflow.cn/v1"
    llm_model: str = "Qwen/Qwen2.5-7B-Instruct"
    app_port: int = 8000
    debug: bool = True

    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}

settings = Settings()   # 全局单例

# app/models/schemas.py —— API 层的数据结构（对外的"合同"）
from pydantic import BaseModel, Field
from typing import Literal, Optional

class PlaceOrderRequest(BaseModel):
    """前端/调用方发给我们的数据格式"""
    symbol: str
    side: Literal["buy", "sell"]
    price: float = Field(gt=0)
    quantity: int = Field(gt=0)

class OrderResponse(BaseModel):
    """我们返回给调用方的数据格式"""
    order_id: str
    status: Literal["pending", "filled", "failed"]

# app/models/db.py —— 数据库表的结构（对内的"仓库货架"）
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase): pass

class OrderRecord(Base):
    """orders 表 —— 注意：和 OrderResponse 是两个东西！"""
    __tablename__ = "orders"
    id: Mapped[int] = mapped_column(primary_key=True)
    symbol: Mapped[str]
    side: Mapped[str]
    quantity: Mapped[int]
    created_at: Mapped[str]

# app/routes/trading.py
from fastapi import APIRouter, Depends
from app.models.schemas import PlaceOrderRequest, OrderResponse
from app.services.trading_service import TradingService
from app.routes.deps import get_trading_service

router = APIRouter(prefix="/api/trading", tags=["交易"])

@router.post("/orders", response_model=OrderResponse)
async def place_order(
    req: PlaceOrderRequest,
    service: TradingService = Depends(get_trading_service),  # 依赖注入
):
    return await service.place_order(req)   # 一行业务逻辑都不写

# app/routes/deps.py — 依赖注入（相当于 NestJS 的 Provider 注入）
from functools import lru_cache

@lru_cache
def get_trading_service() -> TradingService:
    return TradingService(order_dao=OrderDao(), market_service=MarketService())

# app/services/trading_service.py
from app.models.schemas import PlaceOrderRequest, OrderResponse
from app.dao.order_dao import OrderDao
from app.services.market_service import MarketService

class TradingService:
    def __init__(self, order_dao: OrderDao, market_service: MarketService):
        self.order_dao = order_dao              # 依赖通过构造函数传入
        self.market_service = market_service

    async def place_order(self, req: PlaceOrderRequest) -> OrderResponse:
        # 业务规则：查最新价、校验余额、风控……
        price = await self.market_service.get_price(req.symbol)
        if req.side == "buy" and req.price > price * 1.1:
            raise BusinessError("买单价格超出市价 10%，疑似误操作")

        record = await self.order_dao.create(req, price)
        return OrderResponse(order_id=record.id, status="pending")

# app/dao/order_dao.py
from app.models.db import OrderRecord

class OrderDao:
    async def create(self, req, price) -> OrderRecord:
        """插入一条订单记录 —— 没有规则判断，就是纯读写"""
        ...

    async def get_by_id(self, order_id: str) -> OrderRecord | None:
        ...

# app/core/exceptions.py — 自定义异常 + 全局处理
from fastapi import Request
from fastapi.responses import JSONResponse

class BusinessError(Exception):
    """业务规则不满足（如余额不足）"""
    def __init__(self, message: str, code: str = "BUSINESS_ERROR"):
        self.message, self.code = message, code

def register_exception_handlers(app):
    @app.exception_handler(BusinessError)
    async def business_error_handler(request: Request, exc: BusinessError):
        return JSONResponse(status_code=400, content={"code": exc.code, "message": exc.message})

# tests/test_trading_service.py — 单测业务层，不用启动 HTTP 服务！
async def test_place_order_price_too_high():
    service = TradingService(order_dao=MockDao(), market_service=MockMarket(price=100))
    with pytest.raises(BusinessError):
        await service.place_order(PlaceOrderRequest(symbol="BTC", side="buy", price=200, quantity=1))