# Django Clean DRF 架构师 ## 概述此技能为遵循清洁架构原则创建 Django REST Framework 应用程序提供了专家指导。它强制执行严格的分层架构，分离关注点，最大化可测试性，并生成可维护的生产质量代码。 **架构层：** HTTP 层（视图/序列化器） ↓ 应用层（用例+DTO） ↓ 领域层（服务+模型） ↓ 基础设施层（ORM、外部 API、缓存） **关键能力：** * 具有严格依赖关系规则的分层架构（依赖关系仅向内流动） * 具有数据类输入/输出 DTO 的用例模式 * 领域逻辑的服务层（静态查询、实例突变） * 委托给用例的精简视图 * 单独的读取与创建/更新序列化器 * 明确的错误处理，业务逻辑无异常 * 现代 Python 3.12+ 和 Django 5+ 功能 * 完整的类型提示和可测试性设计 ## 何时使用当您遇到这些触发因素时，请调用此技能： **新应用程序设置：** *“为……创建一个新的 Django API” *“开始一个具有干净架构的新DRF项目” *“建立一个具有分层架构的新应用程序” *“初始化域驱动的 Django 应用程序” *“按照 SOLID 搭建 Django 应用程序” **用例实施：** *“创建一个用例......” *“实现业务逻辑......” *“添加新操作/动作......” *“以原子方式处理此事务” **服务层：** *“为……创建服务” * “这个业务逻辑应该去哪里？” *“为……实施域验证” *“遵循干净的架构查询数据” **架构问题：** * “我如何构建这个 Django 应用程序？” *“哪一层应该处理...” *“如何避免臃肿的视图/模型？” *“我如何使其可测试？” *“将 SOLID 原则应用于 Django” **API设计：** *“为...创建API端点” *“设计序列化器......” *“为此实体实施 CRUD” ## 说明处理 Django Clean DRF 请求时请遵循以下工作流程： ### 1\.分析需求并建立背景 **了解域：** * 涉及哪些实体/模型？ * 需要什么操作/行动？ * 必须执行哪些业务规则？ * 是否有外部依赖（API、队列）？ **检查现有项目结构：** * 审查现有应用程序及其组织 * 识别已经在使用的模式 * 检查 Django/Python 版本的功能可用性 **确定范围：** * 单一用例还是完整的 CRUD？ * 新应用程序或扩展现有应用程序？ * 仅限 API 还是包括管理？ ### 2\.加载相关参考文档根据任务，参考相应的捆绑文档： **架构：** * **新应用程序设置** → `references/project-struct.md` * **用例实现** → `references/use-cases-pattern.md` * **服务层** → `references/services-pattern.md` * **模型和领域逻辑** → `references/models-domain.md` * **视图和序列化器** → `references/views-serializers.md` * **测试** → `references/testing-clean-arch.md` * **完整示例** → `references/examples.md` **API开发：** * **查询优化/N+1** → `references/query-optimization.md` * **分页、过滤、搜索** → `references/api-patterns.md` * **身份验证/JWT/权限** → `references/authentication.md` * **生产部署** → `references/product-api.md` * **API 的 Django 管理** → `references/django-admin.md` **代码质量：** * **编码标准/Ruff/安全** → `references/coding-standards.md` ### 3\.实施遵循清洁架构原则 **关键：层依赖规则** 视图 → 用例 → 服务 → 模型 ↓ ↓ ↓ ↓ 序列化器 DTO（内部） ORM * 依赖关系仅向内流动（外层依赖于内层） * 切勿导入用例中的视图或服务中的用例 **用例模式：** 从数据类导入数据类从 uuid 导入 UUID 从 django.db 导入事务 @dataclass（冻结=真，槽=真）类创建订单输入：客户 ID：UUID 项目：列表['OrderItemInput'] 注释：str |无=无 @dataclass（冻结=真，槽=真）类创建订单输出：成功：布尔订单 ID：UUID |无=无错误：str |无=无类创建订单用例： def __init__( 自我, order_service：订单服务，库存服务：库存服务，）： self._order_service = order_service self._inventory_service = 库存服务 @transaction.atomic defexecute(self, input_dto: CreateOrderInput) -> CreateOrderOutput: # 验证 is_valid, error = self._inventory_service.validate_availability(input_dto.items) 如果不是 is_valid: 返回CreateOrderOutput（成功=假，错误=错误） # 执行订单 = self._order_service.create( customer_id=input_dto.customer_id, 项目=input_dto.items，）返回 CreateOrderOutput(成功=True, order_id=order.id) **服务模式：** 订单服务类： # QUERIES 的静态方法（无状态更改） @静态方法 def get_by_id(order_id: UUID) -> 订单 |无： return Order.objects.select_lated('customer').filter(id=order_id).first() # MUTATIONS 的实例方法（状态改变） def create(self, customer_id: UUID, items: list[OrderItemInput]) -> 订单: order = Order.objects.create(customer_id=customer_id) 对于项目中的项目： OrderItem.objects.create(order=order, **item.__dict__) 退货订单 # 验证返回元组[bool, str] def validate_can_cancel(self, order: Order) -> tuple[bool, str]: 如果 order.status == Order.Status.SHIPPED：返回 False，“无法取消已发货的订单” 返回真，“” **细视图模式：** 类 CreateOrderView(APIView): 权限类 = [已验证] def post(self, request: Request) -> 响应: 序列化器 = CreateOrderSerializer(data=request.data) 序列化器.is_valid(raise_exception=True) use_case = CreateOrderUseCase( order_service=OrderService(), inventory_service=InventoryService(), ） input_dto = CreateOrderInput(**serializer.validated_data) 输出 = use_case.execute(input_dto) 如果没有输出.成功：返回响应（{'错误'：输出.错误}，状态= 400）返回响应（{'order_id'：str（output.order_id）}，状态= 201） **序列化器分离：** # WRITE 序列化器（输入验证）类 CreateOrderSerializer(serializers.Serializer): items = OrderItemInputSerializer(许多=True, min_length=1) 注释=serializers.CharField(max_length=500，required=False) # READ 串行器（输出显示）类 OrderReadSerializer(serializers.ModelSerializer): customer_name = serializers.CharField(source='customer.name', read_only=True) 类元：型号=订单 fields = ['id', 'customer_name', 'status', 'created_at'] 只读字段 = 字段 **具有领域逻辑的模型：** 类订单（模型.模型）：类状态（models.TextChoices）： PENDING = '待定', '待定' CONFIRMED = '已确认', '已确认' 已发货 = '已发货', '已发货' id = models.UUIDField(primary_key=True, 默认=uuid.uuid4, editable=False) customer = models.ForeignKey('客户', on_delete=models.PROTECT, related_name='订单') 状态 = models.CharField(max_length=20, 选择=Status.choices, 默认=Status.PENDING) 创建的_at = models.DateTimeField(auto_now_add=True) 类元：排序 = ['-created_at'] 索引 = [models.Index(fields=['客户', '状态'])] @属性 def is_cancellable(self) -> bool: 返回 self.status in (self.Status.PENDING, self.Status.CONFIRMED) ### 4\.验证并最终确定 **架构清单：** * 视图很薄（< 20 行逻辑） * 用例处理单一操作 * 服务包含可重用的领域逻辑 * 依赖关系仅向内流动 * 层与层之间没有循环导入 **代码质量检查表：** * 所有公共接口上的类型提示 * 数据类 DTO 与槽一起冻结 * 业务逻辑错误无异常→返回Output * 验证返回 `tuple[bool, str]` * `@transaction.atomic` 包装状态更改 **性能检查表：** * 用于外键访问的“select_lated” * `prefetch_lated` 用于反向关系 * 经常查询的字段的索引 * 序列化器中没有 N+1 查询 ## 目录结构应用程序/<应用程序名称>/ ├── __init__.py ├── models.py # 带有@property逻辑的领域实体 ├──views.py # 瘦 HTTP 处理程序 ├── serializers.py # 读写序列化器 ├── urls.py # 路由定义 ├── admin.py # Django 管理 ├── 服务/ │ ├── __init__.py # 导出服务 │ └── <实体>_service.py ├── 用例/ │ ├── __init__.py # 导出用例 │ └── _.py # 每个用例一个文件 ├── 测试/ │ ├── __init__.py │ ├── test_models.py │ ├── test_services.py │ ├── test_use_cases.py │ ├── test_views.py │ └──factory.py # Factory Boy 工厂 └── 迁徙/ ## 捆绑资源 **参考文献/** \- 全面的干净架构和 API 文档 ### 架构模式 * **`references/project-struct.md`** 目录布局、文件命名、模块组织、依赖规则 * **`references/use-cases-pattern.md`** 输入/输出 DTO、构造函数注入、事务处理、错误处理 * **`references/services-pattern.md`** 静态方法与实例方法、验证模式、跨服务通信 * **`references/models-domain.md`** 模型中的域逻辑、TextChoices、UUID 键、索引 * **`references/views-serializers.md`** 精简视图、权限、读取与写入序列化器 * **`references/testing-clean-arch.md`** 单元测试用例、模拟服务、集成测试 * **`references/examples.md`** 完整的CRUD示例，复杂的工作流程，测试示例 ### API 最佳实践 * **`references/query-optimization.md`** N+1查询、select_lated/prefetch_lated、索引、批量操作、聚合 * **`references/api-patterns.md`** 分页、过滤、搜索、排序、API 版本控制、错误处理、限制 * **`references/authentication.md`** JWT 身份验证、权限、API 密钥、基于角色的访问、安全标头 * **`references/product-api.md`** 设置结构、数据库配置、缓存、日志记录、Sentry、健康检查、Docker * **`references/django-admin.md`** ModelAdmin 配置、内联、自定义操作、查询优化、权限、安全性 ### 代码质量 * **`references/coding-standards.md`** Ruff 配置、导入顺序、安全实践、YAGNI、日志记录、文档 ## 核心原则 ### 业务逻辑也不例外 # 不好 def create_order（自身，数据）：如果不是 self.can_create(): 引发 ValidationError("无法创建订单") 返回 Order.objects.create(**data) # 好 def create_order(self, data) -> CreateOrderOutput: 如果不是 self.can_create(): return CreateOrderOutput(success=False, error="无法创建订单") order = Order.objects.create(**data) 返回 CreateOrderOutput(成功=True, order_id=order.id) ### 验证返回元组 # 不好 def validate(self, order) -> bool：返回 order.status != '已发货' # 好 def validate(self, order) -> tuple[bool, str]：如果 order.status == '已发货': 返回 False，“无法修改已发货的订单” 返回真，“” ### 构造函数注入以实现可测试性 # 不好 - 难以测试类创建订单用例： def 执行(self, input_dto): service = OrderService() # 硬编码依赖返回 service.create(input_dto) # 好 - 容易嘲笑类创建订单用例： def __init__(self, order_service: OrderService): self._order_service = order_service def 执行(self, input_dto): 返回 self._order_service.create(input_dto) ## 附加说明 **Python 版本：** 需要 3.10+（对于 `X | None` 联合语法），推荐 3.12+ **Django 版本：** 最低 4.2 LTS，推荐 5.0+ **命名约定：** * 用例：`_.py`（例如，`create_order.py`） * 服务：`_service.py`（例如，`order_service.py`） * 序列化器：`ReadSerializer`、`CreateSerializer` **与其他技能的整合：** * 使用 `django-celery-expert` 进行后台任务 * 使用 `refactordjango` 将现有代码迁移到此架构

姜戈清洁博士

包含技能