yweb-ddd-architecture

name: yweb-ddd-architecture description: YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。

YWeb DDD 分层架构与 API 设计规范

核心架构要点

YWeb 采用 Active Record + DDD 分层思想，三层架构：

API 层 (路由) → Service 层 (业务编排) → Domain 层 (领域模型)

关键原则：

• 不引入 Repository 层，领域模型直接继承 ORM 基类
• API 层保持"瘦"，只做参数验证、DTO 转换、异常捕获、调用 Service
• 业务规则封装在领域模型的 validate_xxx() 方法中
• 跨聚合操作通过 Service 层协调
• 简单的纯查询（无业务逻辑）可由 API 层直接调用领域模型

各层职责速查

DTO 使用要点

• 响应模型：继承 DTO（来自 yweb），使用 from_entity() / from_page() 转换
• 请求模型：使用 Pydantic BaseModel
• DTO 继承自 Pydantic BaseModel，不要对 DTO 使用 @dataclass 装饰器
• 使用 _field_mapping 进行字段映射，使用 _value_processors 进行值处理（字段类型应与处理器转换后的类型一致）

响应格式要点

• 统一使用 Resp.OK() / Resp.Fail() / Resp.NotFound() 等
• 分页响应使用 PageResponse
• 异常统一捕获 ValueError，转为 Resp.Fail()

⚠️ API 路由 async 安全

ORM 是同步的，路由声明方式直接影响并发性能：

• 纯 DB 操作：路由用 def（推荐），FastAPI 自动放线程池
• 混合异步 + DB：路由用 async def，DB 调用用 await run_db(...) 包装
• 禁止：async def 中直接调用 Model.query / Model.get() 等同步 ORM，会触发 SynchronousOnlyOperation

# ✅ def 路由
@router.get("/users")
def get_users():
    return User.query.all()

# ✅ async def + 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}

详细规范文档

编码前必须阅读对应文档以获取完整规范和示例：

工作流程

1. 新建功能时，先阅读 ddd-layered-architecture-guide.md 确定分层
2. 编写 API 路由前，阅读 api_layer_design_guide.md
3. 编写 Model / Service 前，阅读 model_and_service_design_guide.md
4. 定义 DTO 和响应格式前，阅读 dto_response_guide.md
5. 综合参考 development_guide.md 中的完整示例