Menu
YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | yweb-ddd-architecture |
| description | YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。 |
YWeb 采用 Active Record + DDD 分层思想，三层架构：
API 层 (路由) → Service 层 (业务编排) → Domain 层 (领域模型)
关键原则：
validate_xxx() 方法中| 层 | 职责 | 禁止 |
|---|---|---|
| API 层 | 参数验证、DTO 转换、异常→HTTP 响应、调用 Service | 业务逻辑、事务管理、数据库操作 |
| Service 层 | 跨聚合协调、事务管理、权限检查 | HTTP 感知、直接返回 Response |
| Domain 层 | 单聚合业务规则、数据验证、状态变更 | 调用其他聚合、HTTP 感知 |
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 子对象有独立生命周期、需独立增删改查 | OneToOne / ManyToOne | 两张表，外键关联 |
| 子对象是聚合内部状态、无独立主键 | OwnsOne | 单表展开，值对象语义 |
典型 OwnsOne 场景：地址、金额区间、联系方式、审计信息、时间窗口等。
详见 yweb-core/docs/orm_docs/21_owns_one.md。
DTO（来自 yweb），使用 from_entity() / from_page() 转换BaseModel@dataclass 装饰器_field_mapping 进行字段映射，使用 _value_processors 进行值处理（字段类型应与处理器转换后的类型一致）Resp.OK() / Resp.Fail() / Resp.NotFound() 等PageResponseValueError，转为 Resp.Fail()编码前必须阅读对应文档以获取完整规范和示例：
| 主题 | 文档路径 |
|---|---|
| DDD 分层架构全貌 | yweb-core/docs/webapi_development_standards/ddd-layered-architecture-guide.md |
| API 层设计规范（瘦 API 原则） | yweb-core/docs/webapi_development_standards/api_layer_design_guide.md |
| Model 与 Service 层设计规范 | yweb-core/docs/webapi_development_standards/model_and_service_design_guide.md |
| DTO 与响应处理规范 | yweb-core/docs/webapi_development_standards/dto_response_guide.md |
| API 与 Service 开发综合规范 | yweb-core/docs/webapi_development_standards/development_guide.md |
ddd-layered-architecture-guide.md 确定分层api_layer_design_guide.mdmodel_and_service_design_guide.mddto_response_guide.mddevelopment_guide.md 中的完整示例YWeb 基础设施模块规范。在使用缓存（@cached）、异常处理（Err/register_exception_handlers）、日志（get_logger）、配置（AppSettings/YAML）、文件存储（本地/OSS/S3）、定时任务（Scheduler）、限流（setup_ratelimit）时使用。
YWeb ORM 使用规范。在编写数据库模型定义、CRUD 操作、查询过滤、分页、软删除、事务管理、批量操作、关系定义等数据层代码时使用。基于 SQLAlchemy 的 Active Record 模式。
YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。
YWeb 框架编码总规范。基于 FastAPI + SQLAlchemy 的 Web 框架，采用 Active Record + DDD 分层架构。在编写任何基于 yweb 框架的代码时使用此技能，包括 API 开发、ORM 操作、认证授权、缓存、异常处理等场景。
审查和改进 pytest 测试的真实性，防止 Happy Path、浅层、实现驱动、同义反复等虚假测试；在测试失败时执行先诊断后改码流程。用于测试评审、测试重构、失败排查场景。
YWeb 框架 Pytest 单元测试编写规范。适用于 yweb-core 底层框架本身，以及通过 pip install yweb 安装后基于该框架开发的任何上层应用。涵盖测试目录结构、conftest 编写、fixture 模式、ORM 测试、API 测试、Service 测试、Domain 测试、Mock 策略、异步测试等场景。