SQLModel 教程：代码结构与多文件组织最佳实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00508/article/details/148375972

SQLModel 教程：代码结构与多文件组织最佳实践

sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel

前言

在开发数据库应用时，合理的代码组织结构对于项目的可维护性和扩展性至关重要。本文将深入探讨 SQLModel 项目中的代码组织策略，特别关注模型间存在循环引用时的解决方案。

循环引用问题解析

在数据模型中，我们经常会遇到实体间的双向关联关系。例如：

英雄(Hero)属于某个团队(Team)
团队(Team)包含多个英雄(Hero)

这种双向关联在代码层面表现为循环导入问题。如果我们将 Hero 和 Team 类放在不同文件中并相互导入，Python 解释器会抛出循环导入错误。

单文件模型方案（推荐）

对于大多数项目，最简单的解决方案是将所有模型集中在一个文件中。

项目结构

.
├── project
    ├── __init__.py
    ├── app.py
    ├── database.py
    └── models.py

模型文件(models.py)

将所有模型定义放在一个文件中可以避免循环导入问题：

from typing import List, Optional
from sqlmodel import Field, Relationship, SQLModel

class Team(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    headquarters: str
    heroes: List["Hero"] = Relationship(back_populates="team")

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    secret_name: str
    age: Optional[int] = Field(default=None, index=True)
    team_id: Optional[int] = Field(default=None, foreign_key="team.id")
    team: Optional[Team] = Relationship(back_populates="heroes")

数据库配置(database.py)

from sqlmodel import SQLModel, create_engine

sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"
engine = create_engine(sqlite_url, echo=True)

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

应用入口(app.py)

from .models import Hero, Team
from .database import engine, create_db_and_tables

def main():
    create_db_and_tables()
    # 应用逻辑...

if __name__ == "__main__":
    main()

运行方式

由于项目已组织为包结构，需要使用模块方式运行：

python -m project.app

多文件模型方案（高级）

对于确实需要将模型拆分到不同文件的情况，可以使用 Python 的类型检查机制解决循环导入问题。

项目结构

.
├── project
    ├── __init__.py
    ├── app.py
    ├── database.py
    ├── hero_model.py
    └── team_model.py

类型检查技巧

利用 typing.TYPE_CHECKING 变量，它只在类型检查时为 True，运行时为 False。

英雄模型(hero_model.py)

from typing import TYPE_CHECKING, Optional
from sqlmodel import Field, Relationship, SQLModel

if TYPE_CHECKING:
    from .team_model import Team

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    secret_name: str
    age: Optional[int] = Field(default=None, index=True)
    team_id: Optional[int] = Field(default=None, foreign_key="team.id")
    team: Optional["Team"] = Relationship(back_populates="heroes")

团队模型(team_model.py)

from typing import TYPE_CHECKING, List, Optional
from sqlmodel import Field, Relationship, SQLModel

if TYPE_CHECKING:
    from .hero_model import Hero

class Team(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    headquarters: str
    heroes: List["Hero"] = Relationship(back_populates="team")