清洁拱门
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# django_clean_arch
Standard Django encourages "fat models" and business logic in views or model methods. Clean Architecture inverts this: Django becomes a delivery mechanism, and the core domain is framework-independent. This skill covers the patterns, file structure, and conventions for Clean Architecture in Django.
## The Layered Structure
```
myproject/
├── domain/ # Pure Python — no Django, no DB
│ ├── models/ # Domain entities and value objects
│ │ ├── order.py
│ │ └── user.py
│ ├── repositories/ # Abstract interfaces (Protocol/ABC)
│ │ ├── order_repository.py
│ │ └── user_repository.py
│ └── exceptions.py # Domain-specific exceptions
│
├── application/ # Use cases — orchestrates domain
│ ├── use_cases/
│ │ ├── create_order.py
│ │ ├── cancel_order.py
│ │ └── get_order_summary.py
│ └── services/ # Application services (not domain services)
│ └── email_service.py # Abstract interface for sending emails
│
├── infrastructure/ # Concrete implementations of interfaces
│ ├── repositories/
│ │ ├── django_order_repository.py # Uses Django ORM
│ │ └── django_user_repository.py
│ └── services/
│ └── sendgrid_email_service.py
│
├── interfaces/ # Delivery layer — Django views, DRF serializers
│ ├── api/
│ │ ├── views.py # Thin views: parse → use case → serialize
│ │ ├── serializers.py
│ │ └── urls.py
│ └── admin/
│ └── admin.py
│
└── config/ # Django settings, dependency injection
├── settings.py
├── urls.py
└── container.py # Dependency injection wiring
```
## Domain Models (Pure Python)
Domain models are plain Python dataclasses or classes — no Django inheritance, no ORM fields:
```python
# domain/models/order.py
from __future__ import annotations
from dataclasses import dataclass, field
from decimal import Decimal
from datetime import datetime
from typing import Optional
from enum import Enum
class OrderStatus(str, Enum):
PENDING = "pending"
CONFIRMED = "confirmed"
SHIPPED = "shipped"
CANCELLED = "cancelled"
@dataclass
class OrderItem:
product_id: int
name: str
price: Decimal
quantity: int
@property
def subtotal(self) -> Decimal:
return self.price * self.quantity
@dataclass
class Order:
user_id: int
items: list[OrderItem]
status: OrderStatus = OrderStatus.PENDING
id: Optional[int] = None
created_at: Optional[datetime] = None
@property
def total(self) -> Decimal:
return sum(item.subtotal for item in self.items)
def cancel(self, reason: str) -> None:
if self.status == OrderStatus.SHIPPED:
raise ValueError("Cannot cancel a shipped order")
self.status = OrderStatus.CANCELLED
self._cancellation_reason = reason
```
## Repository Interfaces (Abstract)
```python
# domain/repositories/order_repository.py
from typing import Protocol, Optional
from myproject.domain.models.order import Order
class OrderRepository(Protocol):
def save(self, order: Order) -> Order: ...
def find_by_id(self, order_id: int) -> Optional[Order]: ...
def find_by_user(self, user_id: int) -> list[Order]: ...
def delete(self, order_id: int) -> None: ...
```
## Use Cases
Each use case handles exactly one business operation. It receives dependencies via constructor, and exposes a single `execute()` method:
```python
# application/use_cases/create_order.py
from dataclasses import dataclass
from decimal import Decimal
from typing import Optional
from myproject.domain.models.order import Order, OrderItem
from myproject.domain.repositories.order_repository import OrderRepository
from myproject.domain.repositories.product_repository import ProductRepository
from myproject.domain.exceptions import ProductNotFoundError
@dataclass
class CreateOrderInput:
user_id: int
product_ids: list[int]
coupon_code: Optional[str] = None
@dataclass
class CreateOrderOutput:
order_id: int
total: Decimal
status: str
class CreateOrderUseCase:
def __init__(
self,
order_repo: OrderRepository,
product_repo: ProductRepository,
) -> None:
self._orders = order_repo
self._products = product_repo
def execute(self, input: CreateOrderInput) -> CreateOrderOutput:
products = self._products.find_by_ids(input.product_ids)
if len(products) != len(input.product_ids):
raise ProductNotFoundError("One or more products not found")
items = [
OrderItem(
product_id=p.id,
name=p.name,
price=p.price,
quantity=1, # simplification
)
for p in products
]
order = Order(user_id=input.user_id, items=items)
saved = self._orders.save(order)
return CreateOrderOutput(
order_id=saved.id,
total=saved.total,
status=saved.status.value,
)
```
## Django ORM Repository (Infrastructure)
```python
# infrastructure/repositories/django_order_repository.py
from typing import Optional
from myproject.domain.models.order import Order, OrderItem, OrderStatus
from myproject.domain.repositories.order_repository import OrderRepository
from myproject.infrastructure.orm_models import OrderORM, OrderItemORM
class DjangoOrderRepository:
"""Translates between domain Order and Django ORM OrderORM."""
def save(self, order: Order) -> Order:
if order.id is None:
orm_obj = OrderORM.objects.create(
user_id=order.user_id,
status=order.status.value,
)
for item in order.items:
OrderItemORM.objects.create(
order=orm_obj,
product_id=item.product_id,
name=item.name,
price=item.price,
quantity=item.quantity,
)
else:
orm_obj = OrderORM.objects.get(id=order.id)
orm_obj.status = order.status.value
orm_obj.save()
return self._to_domain(orm_obj)
def find_by_id(self, order_id: int) -> Optional[Order]:
try:
orm_obj = OrderORM.objects.prefetch_related('items').get(id=order_id)
return self._to_domain(orm_obj)
except OrderORM.DoesNotExist:
return None
def _to_domain(self, orm_obj: OrderORM) -> Order:
return Order(
id=orm_obj.id,
user_id=orm_obj.user_id,
status=OrderStatus(orm_obj.status),
items=[
OrderItem(
product_id=item.product_id,
name=item.name,
price=item.price,
quantity=item.quantity,
)
for item in orm_obj.items.all()
],
)
```
## Thin Views (Delivery Layer)
```python
# interfaces/api/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from myproject.application.use_cases.create_order import CreateOrderUseCase, CreateOrderInput
from myproject.config.container import get_container
from .serializers import CreateOrderSerializer
class OrderCreateView(APIView):
def post(self, request):
# 1. Parse and validate input
serializer = CreateOrderSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
# 2. Call use case
use_case: CreateOrderUseCase = get_container().create_order_use_case
output = use_case.execute(
CreateOrderInput(
user_id=request.user.id,
product_ids=serializer.validated_data['product_ids'],
coupon_code=serializer.validated_data.get('coupon_code'),
)
)
# 3. Serialize output
return Response(
{"order_id": output.order_id, "total": str(output.total)},
status=status.HTTP_201_CREATED,
)
```
## Dependency Injection / Container
Wire up concrete implementations to interfaces in one place:
```python
# config/container.py
from functools import lru_cache
from myproject.infrastructure.repositories.django_order_repository import DjangoOrderRepository
from myproject.infrastructure.repositories.django_product_repository import DjangoProductRepository
from myproject.application.use_cases.create_order import CreateOrderUseCase
class Container:
@property
def order_repository(self):
return DjangoOrderRepository()
@property
def product_repository(self):
return DjangoProductRepository()
@property
def create_order_use_case(self) -> CreateOrderUseCase:
return CreateOrderUseCase(
order_repo=self.order_repository,
product_repo=self.product_repository,
)
@lru_cache(maxsize=1)
def get_container() -> Container:
return Container()
```
## Testing Strategy
The biggest win of Clean Architecture is testability. Use cases can be tested with in-memory repositories — no DB, no Django test client, no fixtures:
```python
def test_create_order_calculates_correct_total():
order_repo = InMemoryOrderRepository()
product_repo = InMemoryProductRepository([
Product(id=1, name="Book", price=Decimal("29.99")),
Product(id=2, name="Pen", price=Decimal("4.99")),
])
use_case = CreateOrderUseCase(order_repo, product_repo)
output = use_case.execute(CreateOrderInput(user_id=1, product_ids=[1, 2]))
assert output.total == Decimal("34.98")
assert len(order_repo.find_by_user(user_id=1)) == 1
```
## Key Rules
- Domain models never import from Django.
- Use cases never import from Django.
- Repositories in the domain layer are abstract (Protocol); concrete ones live in infrastructure.
- Views are thin: parse → use case → serialize. No business logic in views.
- Django ORM models (for migrations and DB access) live in `infrastructure/` and are separate from domain models.
---
> Source: [bloom-tool/bloom](https://github.com/bloom-tool/bloom) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
领域模型(纯Python)
使用案例
依赖注入/容器
测试策略
关键规则
文件/命令 -> execute() · infrastructure/ · order.py · user.py · Protocol/ABC · order_repository.py · user_repository.py · exceptions.py
内容校验值 -> 0803586deb81
当前原文的自动摘译,尚未人工审校。
领域模型(纯Python)
领域模型是普通的 Python 数据类或类——没有 Django 继承,没有 ORM 字段:
使用案例
每个用例只处理一个业务操作。它通过构造函数接收依赖项,并公开一个
execute()方法:依赖注入/容器
将具体实现连接到一处的接口:
测试策略
清洁架构的最大胜利是可测试性。用例可以使用内存存储库进行测试 - 没有数据库,没有 Django 测试客户端,没有固定装置:
关键规则
领域模型永远不会从 Django 导入。用例永远不会从 Django 导入。领域层的存储库是抽象的(协议);具体的生活在基础设施中。视图很薄:解析→用例→序列化。视图中没有业务逻辑。 Django ORM 模型(用于迁移和数据库访问)位于
infrastructure/中,并且与域模型分离。