yweb-orm

name: yweb-orm description: YWeb ORM 使用规范。在编写数据库模型定义、CRUD 操作、查询过滤、分页、软删除、事务管理、批量操作、关系定义等数据层代码时使用。基于 SQLAlchemy 的 Active Record 模式。

YWeb ORM 使用规范

核心要点

YWeb ORM 基于 SQLAlchemy，采用 Active Record 模式：

• 模型继承 BaseModel（自动获得 id/name/code/时间戳/软删除等字段）
• 或继承 CoreModel（仅 id + 时间戳，更轻量）
• 使用 init_database() 一行初始化
• 通过 Model.query 进行链式查询

关键编码规范

1. 所有字段必须有 comment：mapped_column(String(255), comment="字段说明")
2. 使用 SQLAlchemy 2.0 风格：Mapped[str] 类型注解 + mapped_column()
3. 表名自动生成：类名驼峰转下划线，也可手动指定 __tablename__
4. 软删除：BaseModel 自带软删除支持，查询自动过滤已删除记录
5. 事务管理：Service 层使用 @transactional 装饰器管理事务边界
6. ORM 事务外行为：注意理解提交抑制机制，避免意外的自动提交

ORM 功能文档索引

编码时根据需要阅读对应文档：

基础指南

核心功能

高级功能

辅助功能

高级混入（Mixin）

事务行为专题

⚠️ async 安全（必读）

ORM 基于同步 SQLAlchemy Session，在 async def 中直接调用会阻塞事件循环，框架会抛出 SynchronousOnlyOperation。

# ✅ 推荐：纯 DB 路由用 def
@router.get("/users")
def get_users():
    return User.query.all()

# ✅ 混合场景用 run_db
from yweb.orm import run_db

@router.get("/users")
async def get_users():
    users = await run_db(User.get_all)
    extra = await some_async_call()
    return {"users": users, "extra": extra}

# ❌ 禁止：async def 直接调 ORM
@router.get("/users")
async def get_users():
    return User.query.all()  # → SynchronousOnlyOperation!

详见 yweb-core/docs/orm_docs/15_fastapi_integration.md 和 yweb-core/yweb/orm/async_safety.py。

工作流程

1. 定义新模型前，阅读 02_model_definition.md
2. 编写 CRUD 操作前，阅读 03_crud_operations.md
3. 涉及事务管理时，阅读 11_transaction.md 和 16_transaction_manager.md
4. 使用高级混入（树形/排序/状态机/标签）前，阅读对应文档
5. 不确定时，先从 03_orm_guide.md 基础指南开始