src/
├── api/                    # API 路由
│   ├── __init__.py
│   ├── deps.py            # 依赖注入
│   ├── middleware/       # 中间件
│   └── v1/
│       ├── endpoints/    # 端点
│       │   ├── users.py
│       │   └── items.py
│       └── router.py
├── core/                   # 核心配置
│   ├── config.py         # 配置管理
│   ├── security.py       # 安全相关
│   └── database.py       # 数据库连接
├── models/                # 数据模型
│   ├── user.py
│   └── item.py
├── schemas/               # Pydantic schemas
│   ├── user.py
│   └── item.py
├── services/              # 业务逻辑
│   ├── user_service.py
│   └── item_service.py
├── utils/                 # 工具函数
├── constants/             # 常量
├── tests/                 # 测试
└── main.py               # 应用入口

API 层 (endpoints/)     → 处理请求/响应，调用 Service
    ↓
Service 层 (services/)  → 业务逻辑，事务管理
    ↓
Repository 层          → 数据访问抽象
    ↓
Model 层 (models/)     → 数据库模型

def get_user_by_id(user_id: int) -> User | None:
    """
    根据用户ID获取用户信息

    Args:
        user_id: 用户ID

    Returns:
        User: 用户信息，如果不存在返回 None

    Raises:
        ValueError: user_id 无效时
    """

class UserRepository:
    def __init__(self, db: Session):
        self.db = db

    def get_by_id(self, user_id: int) -> User | None:
        return self.db.query(User).filter(User.id == user_id).first()

    def create(self, user: User) -> User:
        self.db.add(user)
        self.db.commit()
        self.db.refresh(user)
        return user

class UserService:
    def __init__(self, user_repository: UserRepository):
        self.user_repo = user_repository

    def get_user(self, user_id: int) -> User:
        user = self.user_repo.get_by_id(user_id)
        if not user:
            raise UserNotFoundError(f"User {user_id} not found")
        return user

router = APIRouter(prefix="/users", tags=["用户管理"])

@router.get("", response_model=List[UserSchema])
def list_users(
    skip: int = 0,
    limit: int = 100,
    user_service: UserService = Depends(get_user_service)
):
    """获取用户列表"""
    return user_service.list_users(skip=skip, limit=limit)

def get_user_service(
    user_repo: UserRepository = Depends(get_user_repository)
) -> UserService:
    return UserService(user_repo)