戰(zhàn)開發(fā)規(guī)范：模型、會(huì)話、關(guān)系與 CRUD 編碼模式指南)
ORM數(shù)據(jù)庫后端【免費(fèi)下載鏈接】sqlmodelSQL databases in Python, designed for simplicity, compatibility, and robustness.項(xiàng)目地址https://gitcode.com/gh_mirrors/sq/sqlmodel點(diǎn)擊查看免費(fèi)下載本篇指南以 SQLModel 官方 AI 編碼規(guī)范文檔倉庫內(nèi)sqlmodel/.agents/skills/sqlmodel/SKILL.md為骨架系統(tǒng)講解在 Python 項(xiàng)目中用 SQLModel 編寫模型、執(zhí)行查詢、建模關(guān)系、完成增刪改操作的推薦模式并結(jié)合倉庫源碼sqlmodel/main.py、sqlmodel/orm/session.py驗(yàn)證底層原理。讀完本篇你將掌握一套可復(fù)制的 SQLModel 標(biāo)準(zhǔn)寫法正確的導(dǎo)入方式、表模型與請求/響應(yīng)模型的拆分、session.exec()查詢范式、一對(duì)多/多對(duì)多關(guān)系建模、部分更新與級(jí)聯(lián)刪除以及何時(shí)該使用 SQLAlchemy 逃生艙。核心原則優(yōu)先使用 SQLModel 的 API編寫或評(píng)審 SQLModel 代碼時(shí)的第一原則是優(yōu)先使用 SQLModel 自己的 API不要默認(rèn)回退到原生 SQLAlchemy 模式除非任務(wù)明確需要 SQLAlchemy 獨(dú)有的特性。這一點(diǎn)在倉庫的公開導(dǎo)出中體現(xiàn)得非常徹底。查看 sqlmodel/init.py 可以看到SQLModel 從 SQLAlchemy 直接 re-export 了create_engine、inspect、Column、ForeignKey、MetaData、全部常用 SQL 類型Integer、String、Text、DateTime、UUID等以及select、and_、or_、func等表達(dá)式工具同時(shí)還 re-export 了 Pydantic 的Discriminator、Tag。也就是說絕大多數(shù)場景下你只需要一條from sqlmodel import ...就能拿到完整工具集無需分別導(dǎo)入 SQLAlchemy 與 Pydantic。相應(yīng)地不要為普通 SQLModel 代碼使用 SQLAlchemy 聲明式默認(rèn)寫法例如declarative_base()—— SQLModel 的SQLModel基類已內(nèi)置聲明式能力Mapped[...]/mapped_column()—— 直接使用Field()更簡潔且類型注解更友好裸relationship()—— 使用Relationship()并配合back_populatessessionmaker()—— 直接Session(engine)打開會(huì)話即可詳見下文會(huì)話小節(jié)。這條原則的目的在于SQLModel 的封裝層提供了更強(qiáng)的類型提示與更少樣板代碼混用兩套風(fēng)格會(huì)讓代碼庫失去一致性。導(dǎo)入規(guī)范從sqlmodel單一入口導(dǎo)入規(guī)范推薦在代碼中統(tǒng)一從sqlmodel導(dǎo)入常用符號(hào)from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select從源碼看這條導(dǎo)入路徑完全成立Field、Relationship、SQLModel定義于 sqlmodel/main.pyField在約 L246 起有完整重載簽名SQLModel是核心元類驅(qū)動(dòng)基類Session來自 sqlmodel/orm/session.py它直接繼承 SQLAlchemy 的Sessionselect來自 sqlmodel/sql/expression.py 的Select/SelectOfScalar封裝create_engine則直接 re-export 自 SQLAlchemy。模型定義表模型與數(shù)據(jù)模型表模型SQLModel, tableTrueField()定義數(shù)據(jù)庫表模型時(shí)繼承SQLModel并傳入tableTrue字段用Field()聲明class Hero(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) name: str Field(indexTrue) team_id: int | None Field(defaultNone, foreign_keyteam.id)要點(diǎn)說明tableTrue表示這是一個(gè)映射到真實(shí)數(shù)據(jù)庫表的模型不加tableTrue的SQLModel子類只是普通數(shù)據(jù)模型Pydantic 模型不建表主鍵通常寫成id: int | None Field(defaultNone, primary_keyTrue)讓數(shù)據(jù)庫在插入時(shí)生成自增 IDField(indexTrue)為該列創(chuàng)建數(shù)據(jù)庫索引Field(foreign_keyteam.id)聲明外鍵約束對(duì)由數(shù)據(jù)庫生成的默認(rèn)值或 ID使用Field(default_factory...)import uuid id: uuid.UUID Field(default_factoryuuid.uuid4, primary_keyTrue)從FieldInfo的構(gòu)造函數(shù)sqlmodel/main.py 約 L112 起可以看到Field()除了繼承 Pydantic 的全部校驗(yàn)參數(shù)gt、ge、min_length、max_length、description、alias等還額外支持primary_key、nullable、foreign_key、ondelete、unique、index、sa_type、sa_column、sa_column_args、sa_column_kwargs等數(shù)據(jù)庫專用參數(shù)這正是“一個(gè)Field()同時(shí)搞定 Pydantic 校驗(yàn)與 SQLAlchemy 列定義”的實(shí)現(xiàn)基礎(chǔ)。數(shù)據(jù)模型非表SQLModel類對(duì)于創(chuàng)建/更新/對(duì)外 API 的輸入輸出結(jié)構(gòu)不要把僅用于請求或響應(yīng)的字段混進(jìn)表模型而應(yīng)使用非表的SQLModel子類。這是后續(xù) FastAPI 分體模型split model模式的基礎(chǔ)詳見下文。會(huì)話與查詢session.exec()范式直接用Session(engine)打開會(huì)話典型的 SQLModel 示例不需要sessionmaker()直接以引擎打開會(huì)話with Session(engine) as session: heroes session.exec(select(Hero)).all()Session類是 SQLAlchemySession的子類見 sqlmodel/orm/session.py L25因此所有原生能力依然可用同時(shí)獲得了 SQLModel 的便捷方法。用session.exec()而不是session.execute()/session.query()規(guī)范明確查詢請使用session.exec(select(...))不要用session.execute(...)也不要用session.query(...)并且在exec()之后不要再手動(dòng)加.scalars()。原因在源碼中一目了然Session.exec()的實(shí)現(xiàn)sqlmodel/orm/session.py L62-L85內(nèi)部調(diào)用super().execute(...)然后判斷語句類型——當(dāng)語句是SelectOfScalar即select(Hero)這種單實(shí)體標(biāo)量選擇時(shí)自動(dòng)執(zhí)行results.scalars()并返回ScalarResult。也就是說exec()已經(jīng)把“取標(biāo)量結(jié)果”這步替你做了# SQLModel 推薦無需 .scalars() heroes session.exec(select(Hero)).all() # 與之等價(jià)的 SQLAlchemy 寫法冗長且返回 Row # heroes session.execute(select(Hero)).scalars().all()而execute()與query()在源碼中都被顯式標(biāo)記為deprecatedsqlmodel/orm/session.py L87-L168其文檔字符串直接提示“你很可能應(yīng)該用session.exec()”。結(jié)果方法選擇在session.exec(...)之后按語義選擇結(jié)果方法.all()—— 返回全部結(jié)果的列表.first()—— 返回第一行可能為None.one()—— 恰好存在一行否則拋異常多行或零行都會(huì)報(bào)錯(cuò).one_or_none()—— 零行或一行時(shí)合法返回None或該行。主鍵查詢則直接使用session.get(Model, id)返回None表示不存在hero session.get(Hero, hero_id) if not hero: raise HTTPException(status_code404, detailHero not found)該用法在 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py 的read_hero接口中就有完整示范。提交與刷新創(chuàng)建或修改對(duì)象后如果需要數(shù)據(jù)庫默認(rèn)值或生成的主鍵回填到內(nèi)存對(duì)象必須依次執(zhí)行commit與refreshsession.add(hero) session.commit() session.refresh(hero)commit()將事務(wù)寫入數(shù)據(jù)庫refresh()重新從數(shù)據(jù)庫加載該對(duì)象從而拿到自增 ID、數(shù)據(jù)庫默認(rèn)值等。關(guān)系建模一對(duì)多與多對(duì)多一對(duì)多Relationship(back_populates...)使用 SQLModel 的關(guān)系屬性而不是臨時(shí)拼 SQLAlchemy 表或用secondaryclass Team(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) heroes: list[Hero] Relationship(back_populatesteam) class Hero(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) team_id: int | None Field(defaultNone, foreign_keyteam.id) team: Team | None Relationship(back_populatesheroes)back_populates建立雙向關(guān)系訪問team.heroes得到該隊(duì)伍的成員列表訪問hero.team得到所屬隊(duì)伍。外鍵team_id與Relationship配合形成標(biāo)準(zhǔn)的“外鍵在多的一方”的一對(duì)多映射。多對(duì)多l(xiāng)ink_model...多對(duì)多需要一張鏈接表。當(dāng)鏈接表只有兩側(cè)外鍵時(shí)用link_model參數(shù)聲明class HeroTeamLink(SQLModel, tableTrue): team_id: int | None Field(defaultNone, foreign_keyteam.id, primary_keyTrue) hero_id: int | None Field(defaultNone, foreign_keyhero.id, primary_keyTrue) class Team(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) heroes: list[Hero] Relationship(back_populatesteams, link_modelHeroTeamLink) class Hero(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) teams: list[Team] Relationship(back_populatesheroes, link_modelHeroTeamLink)如果鏈接表需要攜帶額外字段如角色、加入時(shí)間就把它建模為帶兩側(cè)關(guān)系的完整 SQLModel 表并直接與鏈接對(duì)象交互即顯式讀取/創(chuàng)建/刪除HeroTeamLink記錄而不是依賴隱式secondary行為。從RelationshipInfo的簽名sqlmodel/main.py L180-L209可以看到Relationship()除了back_populates與link_model還支持cascade_delete、passive_deletes、sa_relationship、sa_relationship_args、sa_relationship_kwargs這為下文刪除級(jí)聯(lián)與 SQLAlchemy 逃生艙提供了第一等入口?？缥募Ｅc類型注解字符串新項(xiàng)目起步時(shí)盡量把彼此關(guān)聯(lián)的表模型放在同一個(gè)文件可以簡化關(guān)系注解與元數(shù)據(jù)metadata的注冊順序問題。若必須拆分文件使用TYPE_CHECKING導(dǎo)入 字符串注解from typing import TYPE_CHECKING, Optional if TYPE_CHECKING: from .team_model import Team team: Optional[Team] Relationship(back_populatesheroes)TYPE_CHECKING只在類型檢查階段導(dǎo)入避免運(yùn)行時(shí)循環(huán)導(dǎo)入字符串注解讓 SQLModel/SQLAlchemy 在運(yùn)行時(shí)按名稱解析關(guān)系目標(biāo)。創(chuàng)建與更新直接構(gòu)造、模型校驗(yàn)與部分更新可信內(nèi)部值直接構(gòu)造對(duì)可信的內(nèi)部數(shù)據(jù)直接構(gòu)造表對(duì)象hero Hero(nameDeadpond, secret_nameDive Wilson)從數(shù)據(jù)模型構(gòu)建表對(duì)象model_validate()當(dāng)從輸入數(shù)據(jù)模型如HeroCreate構(gòu)建表對(duì)象時(shí)使用 Pydantic 的model_validate()db_hero Hero.model_validate(hero_create)model_validate在 sqlmodel/main.py L913 附近有 SQLModel 自己的重載實(shí)現(xiàn)負(fù)責(zé)將驗(yàn)證后的數(shù)據(jù)填充進(jìn)表模型實(shí)例。FastAPI 分體模型模式在 FastAPI 場景下規(guī)范推薦按職責(zé)拆分模型HeroBase—— 共享字段名字、秘名、年齡等Hero(HeroBase, tableTrue)—— 數(shù)據(jù)庫表模型HeroCreate—— 創(chuàng)建接口的輸入HeroUpdate—— PATCH 接口的輸入所有字段可選HeroPublic—— 輸出模型含id僅在需要時(shí)定義關(guān)系相關(guān)輸出模型如HeroPublicWithTeam。這正是 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py 展示的經(jīng)典寫法HeroBase聲明name、secret_name、ageHero(HeroBase, tableTrue)追加主鍵idHeroUpdate中三個(gè)字段全部為None可選HeroPublic追加非空id。部分更新model_dump(exclude_unsetTrue)sqlmodel_update()對(duì)于 PATCH 這類部分更新只導(dǎo)出客戶端實(shí)際提供的字段再原位更新hero_data hero_update.model_dump(exclude_unsetTrue) db_hero.sqlmodel_update(hero_data) session.add(db_hero) session.commit() session.refresh(db_hero)關(guān)鍵點(diǎn)exclude_unsetTrue保證未提供的字段不會(huì)出現(xiàn)在字典中避免把None覆蓋到已有值上隨后sqlmodel_update()實(shí)現(xiàn)見 sqlmodel/main.py L1026-L1052只對(duì)模型字段做setattr原位更新。該方法接受dict或 Pydantic/SQLModel對(duì)象并支持可選的update追加覆蓋字段。元數(shù)據(jù)與應(yīng)用初始化建表時(shí)機(jī)先導(dǎo)入所有模型再create_all調(diào)用SQLModel.metadata.create_all(engine)之前必須確保所有表模型類已被導(dǎo)入。因?yàn)榻ū硪蕾嘢QLModel.metadata上已注冊的表定義漏導(dǎo)入某個(gè)模型會(huì)導(dǎo)致其對(duì)應(yīng)的表不被創(chuàng)建。FastAPI 中的會(huì)話依賴在 FastAPI 示例中用依賴dependency產(chǎn)出Session(engine)實(shí)例def get_session(): with Session(engine) as session: yield session然后在路由中通過session: Session Depends(get_session)注入見 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py L40-L42 與各路由函數(shù)。with塊保證請求結(jié)束后會(huì)話正確關(guān)閉。SQLite 使用要點(diǎn)測試與小型示例常選用 SQLite。內(nèi)存庫的經(jīng)典用法是顯式建元數(shù)據(jù) 直接會(huì)話engine create_engine(sqlite:///:memory:) SQLModel.metadata.create_all(engine) with Session(engine) as session: ...當(dāng) SQLite 與 FastAPI 搭配時(shí)多線程訪問同一連接必須加上check_same_threadFalseconnect_args {check_same_thread: False} engine create_engine(sqlite_url, connect_argsconnect_args)原因FastAPI 的請求處理線程與創(chuàng)建連接的線程可能不同SQLite 默認(rèn)拒絕跨線程使用連接check_same_threadFalse關(guān)閉該校驗(yàn)。真實(shí)示例見 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py L32-L33。刪除應(yīng)用級(jí)級(jí)聯(lián)與數(shù)據(jù)庫級(jí)行為應(yīng)用級(jí)級(jí)聯(lián)刪除cascade_deleteTrue用 SQLModel 的關(guān)系輔助參數(shù)實(shí)現(xiàn)級(jí)聯(lián)刪除heroes: list[Hero] Relationship(back_populatesteam, cascade_deleteTrue) team_id: int | None Field(defaultNone, foreign_keyteam.id, ondeleteCASCADE)cascade_deleteTrue讓 ORM 在刪除Team時(shí)于應(yīng)用層先刪除其Hero子記錄ondeleteCASCADE則在數(shù)據(jù)庫層聲明外鍵級(jí)聯(lián)。兩者配合可在不同層次保證引用完整性。數(shù)據(jù)庫級(jí)行為SET NULL與passive_deletes若希望刪除父記錄后子記錄的外鍵被置空而不是刪除子記錄把ondelete與可空外鍵配對(duì)使用并在關(guān)系上按需設(shè)置passive_deletesteam_id: int | None Field(defaultNone, foreign_keyteam.id, ondeleteSET NULL)注意ondeleteSET NULL要求外鍵列可空即int | None/ 顯式nullableTrue否則數(shù)據(jù)庫會(huì)因違反非空約束而報(bào)錯(cuò)。passive_deletes用于告訴 ORM 把刪除行為交給數(shù)據(jù)庫處理避免不必要的 SELECT 預(yù)加載。底層約束在FieldInfo.__init__中也有體現(xiàn)ondelete只能在同時(shí)給出foreign_key時(shí)使用否則直接拋RuntimeError見 sqlmodel/main.py L164-L166。SQLAlchemy 逃生艙何時(shí)以及如何使用當(dāng)普通Field()/Relationship()參數(shù)無法覆蓋某個(gè)列或關(guān)系的需求時(shí)優(yōu)先使用 SQLModel 提供的逃生艙參數(shù)而不是把整個(gè)模型切換回 SQLAlchemy 聲明式風(fēng)格列級(jí)Field(sa_type...)、Field(sa_column...)、Field(sa_column_args...)、Field(sa_column_kwargs...)關(guān)系級(jí)Relationship(sa_relationship_kwargs{...})、Relationship(sa_relationship_args[...])終極手段Relationship(sa_relationshiprelationship(...))僅在 SQLModel 關(guān)系包裝器確實(shí)無法表達(dá)該映射時(shí)使用。源碼層面FieldInfosqlmodel/main.py L112-L177對(duì)這四個(gè)sa_*參數(shù)做了嚴(yán)格的互斥校驗(yàn)一旦傳了sa_column再傳sa_column_args、sa_column_kwargs、primary_key、nullable、foreign_key、ondelete、unique、index、sa_type都會(huì)觸發(fā)RuntimeError。這保證了配置來源唯一、行為可預(yù)期。RelationshipInfosqlmodel/main.py L180-L209對(duì)sa_relationship與sa_relationship_args/sa_relationship_kwargs也有同樣的互斥校驗(yàn)。換句話說為了一個(gè)自定義列或自定義關(guān)系不要放棄 SQLModel 的聲明式風(fēng)格——先用 SQLModel 提供的逃生艙參數(shù)實(shí)在不行再考慮底層 SQLAlchemy 對(duì)象。小結(jié)遵循這套模式可以得到風(fēng)格統(tǒng)一、類型安全、易維護(hù)的 SQLModel 代碼統(tǒng)一從sqlmodel導(dǎo)入用SQLModel, tableTrueField()定義表模型用非表模型承載請求/響應(yīng)數(shù)據(jù)會(huì)話直接Session(engine)查詢一律session.exec(select(...))并按需搭配.all()/.first()/.one()/.one_or_none()主鍵查找用session.get()關(guān)系用Relationship(back_populates...)表達(dá)一對(duì)多、link_model表達(dá)多對(duì)多更新用model_dump(exclude_unsetTrue)sqlmodel_update()實(shí)現(xiàn)精準(zhǔn)的部分更新刪除用cascade_delete/ondelete控制級(jí)聯(lián)行為遇到 SQLModel 表達(dá)不了的極端需求才逐列使用sa_*逃生艙參數(shù)。這些約定在倉庫中均有對(duì)應(yīng)實(shí)現(xiàn)與可運(yùn)行示例可查證核心參考文件包括sqlmodel/main.pyField/Relationship/SQLModel/sqlmodel_update、sqlmodel/orm/session.pySession.exec與棄用提示、sqlmodel/init.py統(tǒng)一導(dǎo)出、docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.pyFastAPI 分體模型 會(huì)話依賴的完整示例。贊分享ORM數(shù)據(jù)庫后端【免費(fèi)下載鏈接】sqlmodelSQL databases in Python, designed for simplicity, compatibility, and robustness.項(xiàng)目地址https://gitcode.com/gh_mirrors/sq/sqlmodel點(diǎn)擊查看免費(fèi)下載相關(guān)推薦FastAPI 集成 SQL 數(shù)據(jù)庫實(shí)戰(zhàn)基于 SQLModel 的單模型與多模型 CRUD 開發(fā)指南FastAPI 集成 SQL 數(shù)據(jù)庫實(shí)戰(zhàn)基于 SQLModel 的單模型與多模型 CRUD 開發(fā)指南 本文以 FastAPI 官方教程中「SQL關(guān)系型數(shù)據(jù)后端Web框架API設(shè)計(jì)RuoYi-Vue-Plus 后端編碼約定與 CRUD 開發(fā)規(guī)范實(shí)戰(zhàn)指南RuoYi Vue Plus 后端編碼約定與 CRUD 開發(fā)規(guī)范實(shí)戰(zhàn)指南 本篇技術(shù)指南以 .codex/skills/ruoyi plus ai coding/后端企業(yè)應(yīng)用認(rèn)證鑒權(quán)使用 FastAPI SQLModel 開發(fā) SQL 關(guān)系型數(shù)據(jù)庫應(yīng)用從單模型 CRUD 到多模型安全重構(gòu)使用 FastAPI SQLModel 開發(fā) SQL 關(guān)系型數(shù)據(jù)庫應(yīng)用從單模型 CRUD 到多模型安全重構(gòu) SQL 關(guān)系型數(shù)據(jù)庫是絕大多數(shù)后端應(yīng)用的存儲(chǔ)底后端Web框架API設(shè)計(jì)上一篇SwipeBackLayout滑動(dòng)狀態(tài)持久化保存用戶偏好設(shè)置的終極指南下一篇OpenOCD Flash編程完全手冊支持CFI、NAND、SPI等30芯片驅(qū)動(dòng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 SQLModel 實(shí)戰(zhàn)開發(fā)規(guī)范：模型、會(huì)話、關(guān)系與 CRUD 編碼模式指南
ORM數(shù)據(jù)庫后端【免費(fèi)下載鏈接】sqlmodelSQL databases in Python, designed for simplicity, compatibility, and robustness.項(xiàng)目地址https://gitcode.com/gh_mirrors/sq/sqlmodel點(diǎn)擊查看免費(fèi)下載本篇指南以 SQLModel 官方 AI 編碼規(guī)范文檔倉庫內(nèi)sqlmodel/.agents/skills/sqlmodel/SKILL.md為骨架系統(tǒng)講解在 Python 項(xiàng)目中用 SQLModel 編寫模型、執(zhí)行查詢、建模關(guān)系、完成增刪改操作的推薦模式并結(jié)合倉庫源碼sqlmodel/main.py、sqlmodel/orm/session.py驗(yàn)證底層原理。讀完本篇你將掌握一套可復(fù)制的 SQLModel 標(biāo)準(zhǔn)寫法正確的導(dǎo)入方式、表模型與請求/響應(yīng)模型的拆分、session.exec()查詢范式、一對(duì)多/多對(duì)多關(guān)系建模、部分更新與級(jí)聯(lián)刪除以及何時(shí)該使用 SQLAlchemy 逃生艙。核心原則優(yōu)先使用 SQLModel 的 API編寫或評(píng)審 SQLModel 代碼時(shí)的第一原則是優(yōu)先使用 SQLModel 自己的 API不要默認(rèn)回退到原生 SQLAlchemy 模式除非任務(wù)明確需要 SQLAlchemy 獨(dú)有的特性。這一點(diǎn)在倉庫的公開導(dǎo)出中體現(xiàn)得非常徹底。查看 sqlmodel/init.py 可以看到SQLModel 從 SQLAlchemy 直接 re-export 了create_engine、inspect、Column、ForeignKey、MetaData、全部常用 SQL 類型Integer、String、Text、DateTime、UUID等以及select、and_、or_、func等表達(dá)式工具同時(shí)還 re-export 了 Pydantic 的Discriminator、Tag。也就是說絕大多數(shù)場景下你只需要一條from sqlmodel import ...就能拿到完整工具集無需分別導(dǎo)入 SQLAlchemy 與 Pydantic。相應(yīng)地不要為普通 SQLModel 代碼使用 SQLAlchemy 聲明式默認(rèn)寫法例如declarative_base()—— SQLModel 的SQLModel基類已內(nèi)置聲明式能力Mapped[...]/mapped_column()—— 直接使用Field()更簡潔且類型注解更友好裸relationship()—— 使用Relationship()并配合back_populatessessionmaker()—— 直接Session(engine)打開會(huì)話即可詳見下文會(huì)話小節(jié)。這條原則的目的在于SQLModel 的封裝層提供了更強(qiáng)的類型提示與更少樣板代碼混用兩套風(fēng)格會(huì)讓代碼庫失去一致性。導(dǎo)入規(guī)范從sqlmodel單一入口導(dǎo)入規(guī)范推薦在代碼中統(tǒng)一從sqlmodel導(dǎo)入常用符號(hào)from sqlmodel import Field, Relationship, Session, SQLModel, create_engine, select從源碼看這條導(dǎo)入路徑完全成立Field、Relationship、SQLModel定義于 sqlmodel/main.pyField在約 L246 起有完整重載簽名SQLModel是核心元類驅(qū)動(dòng)基類Session來自 sqlmodel/orm/session.py它直接繼承 SQLAlchemy 的Sessionselect來自 sqlmodel/sql/expression.py 的Select/SelectOfScalar封裝create_engine則直接 re-export 自 SQLAlchemy。模型定義表模型與數(shù)據(jù)模型表模型SQLModel, tableTrueField()定義數(shù)據(jù)庫表模型時(shí)繼承SQLModel并傳入tableTrue字段用Field()聲明class Hero(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) name: str Field(indexTrue) team_id: int | None Field(defaultNone, foreign_keyteam.id)要點(diǎn)說明tableTrue表示這是一個(gè)映射到真實(shí)數(shù)據(jù)庫表的模型不加tableTrue的SQLModel子類只是普通數(shù)據(jù)模型Pydantic 模型不建表主鍵通常寫成id: int | None Field(defaultNone, primary_keyTrue)讓數(shù)據(jù)庫在插入時(shí)生成自增 IDField(indexTrue)為該列創(chuàng)建數(shù)據(jù)庫索引Field(foreign_keyteam.id)聲明外鍵約束對(duì)由數(shù)據(jù)庫生成的默認(rèn)值或 ID使用Field(default_factory...)import uuid id: uuid.UUID Field(default_factoryuuid.uuid4, primary_keyTrue)從FieldInfo的構(gòu)造函數(shù)sqlmodel/main.py 約 L112 起可以看到Field()除了繼承 Pydantic 的全部校驗(yàn)參數(shù)gt、ge、min_length、max_length、description、alias等還額外支持primary_key、nullable、foreign_key、ondelete、unique、index、sa_type、sa_column、sa_column_args、sa_column_kwargs等數(shù)據(jù)庫專用參數(shù)這正是“一個(gè)Field()同時(shí)搞定 Pydantic 校驗(yàn)與 SQLAlchemy 列定義”的實(shí)現(xiàn)基礎(chǔ)。數(shù)據(jù)模型非表SQLModel類對(duì)于創(chuàng)建/更新/對(duì)外 API 的輸入輸出結(jié)構(gòu)不要把僅用于請求或響應(yīng)的字段混進(jìn)表模型而應(yīng)使用非表的SQLModel子類。這是后續(xù) FastAPI 分體模型split model模式的基礎(chǔ)詳見下文。會(huì)話與查詢session.exec()范式直接用Session(engine)打開會(huì)話典型的 SQLModel 示例不需要sessionmaker()直接以引擎打開會(huì)話with Session(engine) as session: heroes session.exec(select(Hero)).all()Session類是 SQLAlchemySession的子類見 sqlmodel/orm/session.py L25因此所有原生能力依然可用同時(shí)獲得了 SQLModel 的便捷方法。用session.exec()而不是session.execute()/session.query()規(guī)范明確查詢請使用session.exec(select(...))不要用session.execute(...)也不要用session.query(...)并且在exec()之后不要再手動(dòng)加.scalars()。原因在源碼中一目了然Session.exec()的實(shí)現(xiàn)sqlmodel/orm/session.py L62-L85內(nèi)部調(diào)用super().execute(...)然后判斷語句類型——當(dāng)語句是SelectOfScalar即select(Hero)這種單實(shí)體標(biāo)量選擇時(shí)自動(dòng)執(zhí)行results.scalars()并返回ScalarResult。也就是說exec()已經(jīng)把“取標(biāo)量結(jié)果”這步替你做了# SQLModel 推薦無需 .scalars() heroes session.exec(select(Hero)).all() # 與之等價(jià)的 SQLAlchemy 寫法冗長且返回 Row # heroes session.execute(select(Hero)).scalars().all()而execute()與query()在源碼中都被顯式標(biāo)記為deprecatedsqlmodel/orm/session.py L87-L168其文檔字符串直接提示“你很可能應(yīng)該用session.exec()”。結(jié)果方法選擇在session.exec(...)之后按語義選擇結(jié)果方法.all()—— 返回全部結(jié)果的列表.first()—— 返回第一行可能為None.one()—— 恰好存在一行否則拋異常多行或零行都會(huì)報(bào)錯(cuò).one_or_none()—— 零行或一行時(shí)合法返回None或該行。主鍵查詢則直接使用session.get(Model, id)返回None表示不存在hero session.get(Hero, hero_id) if not hero: raise HTTPException(status_code404, detailHero not found)該用法在 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py 的read_hero接口中就有完整示范。提交與刷新創(chuàng)建或修改對(duì)象后如果需要數(shù)據(jù)庫默認(rèn)值或生成的主鍵回填到內(nèi)存對(duì)象必須依次執(zhí)行commit與refreshsession.add(hero) session.commit() session.refresh(hero)commit()將事務(wù)寫入數(shù)據(jù)庫refresh()重新從數(shù)據(jù)庫加載該對(duì)象從而拿到自增 ID、數(shù)據(jù)庫默認(rèn)值等。關(guān)系建模一對(duì)多與多對(duì)多一對(duì)多Relationship(back_populates...)使用 SQLModel 的關(guān)系屬性而不是臨時(shí)拼 SQLAlchemy 表或用secondaryclass Team(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) heroes: list[Hero] Relationship(back_populatesteam) class Hero(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) team_id: int | None Field(defaultNone, foreign_keyteam.id) team: Team | None Relationship(back_populatesheroes)back_populates建立雙向關(guān)系訪問team.heroes得到該隊(duì)伍的成員列表訪問hero.team得到所屬隊(duì)伍。外鍵team_id與Relationship配合形成標(biāo)準(zhǔn)的“外鍵在多的一方”的一對(duì)多映射。多對(duì)多l(xiāng)ink_model...多對(duì)多需要一張鏈接表。當(dāng)鏈接表只有兩側(cè)外鍵時(shí)用link_model參數(shù)聲明class HeroTeamLink(SQLModel, tableTrue): team_id: int | None Field(defaultNone, foreign_keyteam.id, primary_keyTrue) hero_id: int | None Field(defaultNone, foreign_keyhero.id, primary_keyTrue) class Team(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) heroes: list[Hero] Relationship(back_populatesteams, link_modelHeroTeamLink) class Hero(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) teams: list[Team] Relationship(back_populatesheroes, link_modelHeroTeamLink)如果鏈接表需要攜帶額外字段如角色、加入時(shí)間就把它建模為帶兩側(cè)關(guān)系的完整 SQLModel 表并直接與鏈接對(duì)象交互即顯式讀取/創(chuàng)建/刪除HeroTeamLink記錄而不是依賴隱式secondary行為。從RelationshipInfo的簽名sqlmodel/main.py L180-L209可以看到Relationship()除了back_populates與link_model還支持cascade_delete、passive_deletes、sa_relationship、sa_relationship_args、sa_relationship_kwargs這為下文刪除級(jí)聯(lián)與 SQLAlchemy 逃生艙提供了第一等入口?？缥募Ｅc類型注解字符串新項(xiàng)目起步時(shí)盡量把彼此關(guān)聯(lián)的表模型放在同一個(gè)文件可以簡化關(guān)系注解與元數(shù)據(jù)metadata的注冊順序問題。若必須拆分文件使用TYPE_CHECKING導(dǎo)入 字符串注解from typing import TYPE_CHECKING, Optional if TYPE_CHECKING: from .team_model import Team team: Optional[Team] Relationship(back_populatesheroes)TYPE_CHECKING只在類型檢查階段導(dǎo)入避免運(yùn)行時(shí)循環(huán)導(dǎo)入字符串注解讓 SQLModel/SQLAlchemy 在運(yùn)行時(shí)按名稱解析關(guān)系目標(biāo)。創(chuàng)建與更新直接構(gòu)造、模型校驗(yàn)與部分更新可信內(nèi)部值直接構(gòu)造對(duì)可信的內(nèi)部數(shù)據(jù)直接構(gòu)造表對(duì)象hero Hero(nameDeadpond, secret_nameDive Wilson)從數(shù)據(jù)模型構(gòu)建表對(duì)象model_validate()當(dāng)從輸入數(shù)據(jù)模型如HeroCreate構(gòu)建表對(duì)象時(shí)使用 Pydantic 的model_validate()db_hero Hero.model_validate(hero_create)model_validate在 sqlmodel/main.py L913 附近有 SQLModel 自己的重載實(shí)現(xiàn)負(fù)責(zé)將驗(yàn)證后的數(shù)據(jù)填充進(jìn)表模型實(shí)例。FastAPI 分體模型模式在 FastAPI 場景下規(guī)范推薦按職責(zé)拆分模型HeroBase—— 共享字段名字、秘名、年齡等Hero(HeroBase, tableTrue)—— 數(shù)據(jù)庫表模型HeroCreate—— 創(chuàng)建接口的輸入HeroUpdate—— PATCH 接口的輸入所有字段可選HeroPublic—— 輸出模型含id僅在需要時(shí)定義關(guān)系相關(guān)輸出模型如HeroPublicWithTeam。這正是 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py 展示的經(jīng)典寫法HeroBase聲明name、secret_name、ageHero(HeroBase, tableTrue)追加主鍵idHeroUpdate中三個(gè)字段全部為None可選HeroPublic追加非空id。部分更新model_dump(exclude_unsetTrue)sqlmodel_update()對(duì)于 PATCH 這類部分更新只導(dǎo)出客戶端實(shí)際提供的字段再原位更新hero_data hero_update.model_dump(exclude_unsetTrue) db_hero.sqlmodel_update(hero_data) session.add(db_hero) session.commit() session.refresh(db_hero)關(guān)鍵點(diǎn)exclude_unsetTrue保證未提供的字段不會(huì)出現(xiàn)在字典中避免把None覆蓋到已有值上隨后sqlmodel_update()實(shí)現(xiàn)見 sqlmodel/main.py L1026-L1052只對(duì)模型字段做setattr原位更新。該方法接受dict或 Pydantic/SQLModel對(duì)象并支持可選的update追加覆蓋字段。元數(shù)據(jù)與應(yīng)用初始化建表時(shí)機(jī)先導(dǎo)入所有模型再create_all調(diào)用SQLModel.metadata.create_all(engine)之前必須確保所有表模型類已被導(dǎo)入。因?yàn)榻ū硪蕾嘢QLModel.metadata上已注冊的表定義漏導(dǎo)入某個(gè)模型會(huì)導(dǎo)致其對(duì)應(yīng)的表不被創(chuàng)建。FastAPI 中的會(huì)話依賴在 FastAPI 示例中用依賴dependency產(chǎn)出Session(engine)實(shí)例def get_session(): with Session(engine) as session: yield session然后在路由中通過session: Session Depends(get_session)注入見 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py L40-L42 與各路由函數(shù)。with塊保證請求結(jié)束后會(huì)話正確關(guān)閉。SQLite 使用要點(diǎn)測試與小型示例常選用 SQLite。內(nèi)存庫的經(jīng)典用法是顯式建元數(shù)據(jù) 直接會(huì)話engine create_engine(sqlite:///:memory:) SQLModel.metadata.create_all(engine) with Session(engine) as session: ...當(dāng) SQLite 與 FastAPI 搭配時(shí)多線程訪問同一連接必須加上check_same_threadFalseconnect_args {check_same_thread: False} engine create_engine(sqlite_url, connect_argsconnect_args)原因FastAPI 的請求處理線程與創(chuàng)建連接的線程可能不同SQLite 默認(rèn)拒絕跨線程使用連接check_same_threadFalse關(guān)閉該校驗(yàn)。真實(shí)示例見 docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.py L32-L33。刪除應(yīng)用級(jí)級(jí)聯(lián)與數(shù)據(jù)庫級(jí)行為應(yīng)用級(jí)級(jí)聯(lián)刪除cascade_deleteTrue用 SQLModel 的關(guān)系輔助參數(shù)實(shí)現(xiàn)級(jí)聯(lián)刪除heroes: list[Hero] Relationship(back_populatesteam, cascade_deleteTrue) team_id: int | None Field(defaultNone, foreign_keyteam.id, ondeleteCASCADE)cascade_deleteTrue讓 ORM 在刪除Team時(shí)于應(yīng)用層先刪除其Hero子記錄ondeleteCASCADE則在數(shù)據(jù)庫層聲明外鍵級(jí)聯(lián)。兩者配合可在不同層次保證引用完整性。數(shù)據(jù)庫級(jí)行為SET NULL與passive_deletes若希望刪除父記錄后子記錄的外鍵被置空而不是刪除子記錄把ondelete與可空外鍵配對(duì)使用并在關(guān)系上按需設(shè)置passive_deletesteam_id: int | None Field(defaultNone, foreign_keyteam.id, ondeleteSET NULL)注意ondeleteSET NULL要求外鍵列可空即int | None/ 顯式nullableTrue否則數(shù)據(jù)庫會(huì)因違反非空約束而報(bào)錯(cuò)。passive_deletes用于告訴 ORM 把刪除行為交給數(shù)據(jù)庫處理避免不必要的 SELECT 預(yù)加載。底層約束在FieldInfo.__init__中也有體現(xiàn)ondelete只能在同時(shí)給出foreign_key時(shí)使用否則直接拋RuntimeError見 sqlmodel/main.py L164-L166。SQLAlchemy 逃生艙何時(shí)以及如何使用當(dāng)普通Field()/Relationship()參數(shù)無法覆蓋某個(gè)列或關(guān)系的需求時(shí)優(yōu)先使用 SQLModel 提供的逃生艙參數(shù)而不是把整個(gè)模型切換回 SQLAlchemy 聲明式風(fēng)格列級(jí)Field(sa_type...)、Field(sa_column...)、Field(sa_column_args...)、Field(sa_column_kwargs...)關(guān)系級(jí)Relationship(sa_relationship_kwargs{...})、Relationship(sa_relationship_args[...])終極手段Relationship(sa_relationshiprelationship(...))僅在 SQLModel 關(guān)系包裝器確實(shí)無法表達(dá)該映射時(shí)使用。源碼層面FieldInfosqlmodel/main.py L112-L177對(duì)這四個(gè)sa_*參數(shù)做了嚴(yán)格的互斥校驗(yàn)一旦傳了sa_column再傳sa_column_args、sa_column_kwargs、primary_key、nullable、foreign_key、ondelete、unique、index、sa_type都會(huì)觸發(fā)RuntimeError。這保證了配置來源唯一、行為可預(yù)期。RelationshipInfosqlmodel/main.py L180-L209對(duì)sa_relationship與sa_relationship_args/sa_relationship_kwargs也有同樣的互斥校驗(yàn)。換句話說為了一個(gè)自定義列或自定義關(guān)系不要放棄 SQLModel 的聲明式風(fēng)格——先用 SQLModel 提供的逃生艙參數(shù)實(shí)在不行再考慮底層 SQLAlchemy 對(duì)象。小結(jié)遵循這套模式可以得到風(fēng)格統(tǒng)一、類型安全、易維護(hù)的 SQLModel 代碼統(tǒng)一從sqlmodel導(dǎo)入用SQLModel, tableTrueField()定義表模型用非表模型承載請求/響應(yīng)數(shù)據(jù)會(huì)話直接Session(engine)查詢一律session.exec(select(...))并按需搭配.all()/.first()/.one()/.one_or_none()主鍵查找用session.get()關(guān)系用Relationship(back_populates...)表達(dá)一對(duì)多、link_model表達(dá)多對(duì)多更新用model_dump(exclude_unsetTrue)sqlmodel_update()實(shí)現(xiàn)精準(zhǔn)的部分更新刪除用cascade_delete/ondelete控制級(jí)聯(lián)行為遇到 SQLModel 表達(dá)不了的極端需求才逐列使用sa_*逃生艙參數(shù)。這些約定在倉庫中均有對(duì)應(yīng)實(shí)現(xiàn)與可運(yùn)行示例可查證核心參考文件包括sqlmodel/main.pyField/Relationship/SQLModel/sqlmodel_update、sqlmodel/orm/session.pySession.exec與棄用提示、sqlmodel/init.py統(tǒng)一導(dǎo)出、docs_src/tutorial/fastapi/session_with_dependency/tutorial001_py310.pyFastAPI 分體模型 會(huì)話依賴的完整示例。贊分享ORM數(shù)據(jù)庫后端【免費(fèi)下載鏈接】sqlmodelSQL databases in Python, designed for simplicity, compatibility, and robustness.項(xiàng)目地址https://gitcode.com/gh_mirrors/sq/sqlmodel點(diǎn)擊查看免費(fèi)下載相關(guān)推薦FastAPI 集成 SQL 數(shù)據(jù)庫實(shí)戰(zhàn)基于 SQLModel 的單模型與多模型 CRUD 開發(fā)指南FastAPI 集成 SQL 數(shù)據(jù)庫實(shí)戰(zhàn)基于 SQLModel 的單模型與多模型 CRUD 開發(fā)指南 本文以 FastAPI 官方教程中「SQL關(guān)系型數(shù)據(jù)后端Web框架API設(shè)計(jì)RuoYi-Vue-Plus 后端編碼約定與 CRUD 開發(fā)規(guī)范實(shí)戰(zhàn)指南RuoYi Vue Plus 后端編碼約定與 CRUD 開發(fā)規(guī)范實(shí)戰(zhàn)指南 本篇技術(shù)指南以 .codex/skills/ruoyi plus ai coding/后端企業(yè)應(yīng)用認(rèn)證鑒權(quán)使用 FastAPI SQLModel 開發(fā) SQL 關(guān)系型數(shù)據(jù)庫應(yīng)用從單模型 CRUD 到多模型安全重構(gòu)使用 FastAPI SQLModel 開發(fā) SQL 關(guān)系型數(shù)據(jù)庫應(yīng)用從單模型 CRUD 到多模型安全重構(gòu) SQL 關(guān)系型數(shù)據(jù)庫是絕大多數(shù)后端應(yīng)用的存儲(chǔ)底后端Web框架API設(shè)計(jì)上一篇SwipeBackLayout滑動(dòng)狀態(tài)持久化保存用戶偏好設(shè)置的終極指南下一篇OpenOCD Flash編程完全手冊支持CFI、NAND、SPI等30芯片驅(qū)動(dòng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考