Menu
YWeb 框架编码总规范。基于 FastAPI + SQLAlchemy 的 Web 框架，采用 Active Record + DDD 分层架构。在编写任何基于 yweb 框架的代码时使用此技能，包括 API 开发、ORM 操作、认证授权、缓存、异常处理等场景。
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
YWeb 基础设施模块规范。在使用缓存（@cached）、异常处理（Err/register_exception_handlers）、日志（get_logger）、配置（AppSettings/YAML）、文件存储（本地/OSS/S3）、定时任务（Scheduler）、限流（setup_ratelimit）时使用。
YWeb DDD 分层架构与 API 设计规范。在创建或修改 API 路由、Service 层、领域模型、DTO 时使用。涵盖瘦 API 原则、服务层拆分、Model 设计、DTO 转换、响应格式等。
YWeb ORM 使用规范。在编写数据库模型定义、CRUD 操作、查询过滤、分页、软删除、事务管理、批量操作、关系定义等数据层代码时使用。基于 SQLAlchemy 的 Active Record 模式。
YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。
审查和改进 pytest 测试的真实性，防止 Happy Path、浅层、实现驱动、同义反复等虚假测试；在测试失败时执行先诊断后改码流程。用于测试评审、测试重构、失败排查场景。
YWeb 框架 Pytest 单元测试编写规范。适用于 yweb-core 底层框架本身，以及通过 pip install yweb 安装后基于该框架开发的任何上层应用。涵盖测试目录结构、conftest 编写、fixture 模式、ORM 测试、API 测试、Service 测试、Domain 测试、Mock 策略、异步测试等场景。
| name | yweb-framework |
| description | YWeb 框架编码总规范。基于 FastAPI + SQLAlchemy 的 Web 框架，采用 Active Record + DDD 分层架构。在编写任何基于 yweb 框架的代码时使用此技能，包括 API 开发、ORM 操作、认证授权、缓存、异常处理等场景。 |
本技能是 YWeb 框架所有编码规范的总入口。具体规范细节请查阅对应文档，不要凭猜测编码。
重要原则：所有编码规范的详细要求均以
yweb-core/docs/下的文档为准。遇到不确定的用法时，必须先阅读对应文档再编码。
YWeb 是基于 FastAPI + SQLAlchemy 的 Python Web 框架，核心特点：
ValueError 表达业务规则违反，不定义自定义异常类comment 参数Resp.OK() / Resp.NotFound() 等统一响应；响应模型使用 DTO 类BaseModel（不是 DTO）@cached 装饰器，注意 TTL 设置和失效策略@transactional 装饰器| 主题 | 文档路径 | 说明 |
|---|---|---|
| DDD 分层架构 | yweb-core/docs/webapi_development_standards/ddd-layered-architecture-guide.md | 分层架构、各层职责、服务层拆分原则 |
| API 层设计 | yweb-core/docs/webapi_development_standards/api_layer_design_guide.md | 瘦 API 原则、Schema 设计、响应返回规范 |
| Model 与 Service 设计 | yweb-core/docs/webapi_development_standards/model_and_service_design_guide.md | Model 字段规范、Service 层设计规范 |
| DTO 与响应处理 | yweb-core/docs/webapi_development_standards/dto_response_guide.md | DTO 基础、字段映射、响应格式规范 |
| API 与 Service 开发规范 | yweb-core/docs/webapi_development_standards/development_guide.md | 项目结构、导入规范、完整开发示例 |
| 主题 | 文档路径 | 说明 |
|---|---|---|
| ORM 基础指南 | yweb-core/docs/03_orm_guide.md | 数据库初始化、模型定义、CRUD、分页、软删除 |
| ORM 详细功能文档 | yweb-core/docs/orm_docs/README.md | 完整 ORM 功能索引（20+ 篇详细文档） |
| ORM 事务提交行为 | yweb-core/docs/orm_commit_behavior_outside_transaction.md | 事务外提交行为说明 |
| ORM 提交抑制机制 | yweb-core/docs/orm_commit_suppression_mechanism.md | 提交抑制机制说明 |
| 主题 | 文档路径 | 说明 |
|---|---|---|
| 认证模块指南 | yweb-core/docs/06_auth_guide.md | JWT、Session、OAuth、API Key 等认证方式 |
| 认证流程详解 | yweb-core/docs/webapi_development_standards/auth_flow_guide.md | JWT 认证流程、缓存优化、自动失效 |
| JWT Token 规范 | yweb-core/docs/webapi_development_standards/jwt_auth_guide.md | 双 Token 机制、前后端规范 |
| 权限管理 | yweb-core/docs/08_permission_guide.md | RBAC 框架、角色/权限管理 |
| 组织管理 | yweb-core/docs/07_organization_guide.md | 组织架构管理模块 |
| 主题 | 文档路径 | 说明 |
|---|---|---|
| 缓存 | yweb-core/docs/11_cache_guide.md | @cached 装饰器、缓存后端、失效策略 |
| 异常处理 | yweb-core/docs/05_exception_handling.md | 全局异常处理器、Err 快捷类、验证约束 |
| 配置管理 | yweb-core/docs/02_config_guide.md | YAML + 环境变量配置、AppSettings |
| 日志 | yweb-core/docs/04_log_guide.md | get_logger、日志轮转、敏感数据过滤 |
| 文件存储 | yweb-core/docs/10_storage_guide.md | 本地/OSS/S3 存储、文件验证 |
| 定时任务 | yweb-core/docs/09_scheduler_guide.md | APScheduler 封装、Builder 模式、持久化 |
| 快速开始 | yweb-core/docs/01_quickstart.md | 框架安装与基础示例 |
当需要编写或修改 yweb 相关代码时：
yweb-core/docs/orm_docs/ 下的专题文档