Separating Business Logic from Data Access in Django: A Practical Guide to Domain and Data Models

In Django development, many developers encounter a common problem: as projects grow, the models.py file becomes excessively bloated, containing not only data model definitions but also business logic, external API calls, email sending, and other non-database operations. This design violates the single responsibility principle, making code difficult to understand and maintain. Based on Domain-Driven Design principles, this article systematically explains how to achieve clear separation between business logic and data access.

Core Distinctions Between Domain Models and Data Models

First, it's essential to understand two key concepts: data models and domain models. Data models focus on how data is stored and related in the database, answering "what data does the application store?" Domain models focus on business logic and user-perceived entities, answering "what does the application do?" In Django, models.py is often misused to handle both, leading to code confusion.

The core of domain modeling lies in commands and queries. Commands represent operations that change system state, such as "activate user"; queries represent operations that retrieve information, such as "get user name." This separation helps build task-oriented applications, improving both user experience and code testability.

Separating and Implementing Commands

When model methods begin to involve non-database operations, they should be extracted as independent commands. Django offers two primary implementation approaches:

Service Layer Pattern

Create a dedicated services.py module, encapsulating each command as a function. For example, a user activation command:

def activate_user(user_id):
    user = User.objects.get(pk=user_id)
    
    # Database operation
    user.active = True
    user.save()
    
    # Business logic: send email
    send_mail('Your account is activated!', '...', [user.email])
    
    # Other side effects: system logging, etc.
    log_activation(user)

This approach centralizes command execution logic, facilitating testing and reuse.

Form Encapsulation Pattern

Use Django forms to encapsulate commands, combining validation, execution, and presentation:

class ActivateUserForm(forms.Form):
    user_id = IntegerField(widget=UsernameSelectWidget)
    
    def clean_user_id(self):
        user_id = self.cleaned_data['user_id']
        if User.objects.get(pk=user_id).active:
            raise ValidationError("This user cannot be activated")
        return user_id
    
    def execute(self):
        user_id = self.cleaned_data['user_id']
        user = User.objects.get(pk=user_id)
        user.active = True
        user.save()
        send_mail('Your account is activated!', '...', [user.email])

The form pattern is particularly suitable for web interface interactions, tightly integrating parameter validation with command execution.

Separating and Optimizing Queries

Query separation is equally important, especially when queries involve complex logic or external data sources. Distinguish between query types: presentational queries (for template rendering), business logic queries (affecting command execution), and reporting queries (for analytical purposes).

Custom Template Tags and Filters

For purely presentational queries, use custom template tags:

@register.filter
def friendly_name(user):
    return remote_api.get_cached_name(user.id) or 'Anonymous'

Use in templates: <h1>Welcome, {{ user|friendly_name }}</h1>

Query Modules

Create a queries.py module to encapsulate complex queries:

def inactive_users():
    return User.objects.filter(active=False)

def users_called_publysher():
    for user in User.objects.all():
        if remote_api.get_cached_name(user.id) == "publysher":
            yield user

Proxy Models

For scenarios requiring specific query sets, use proxy models:

class InactiveUserManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(active=False)

class InactiveUser(User):
    objects = InactiveUserManager()
    class Meta:
        proxy = True

This allows direct retrieval of inactive users via InactiveUser.objects.all().

Query Models and Signal Mechanisms

For frequently executed complex queries, create dedicated query models and maintain data synchronization through signals:

class InactiveUserDistribution(models.Model):
    country = CharField(max_length=200)
    inactive_user_count = IntegerField(default=0)

user_activated = Signal(providing_args=['user'])

@receiver(user_activated)
def on_user_activated(sender, **kwargs):
    user = kwargs['user']
    query_model = InactiveUserDistribution.objects.get_or_create(country=user.country)
    query_model.inactive_user_count -= 1
    query_model.save()

Trigger signals during command execution: user_activated.send_robust(sender=self, user=user)

Guidelines for Keeping Code Clean

Follow these principles to maintain a clear architecture:

• Do model methods involve non-database operations? → Extract as commands
• Do model properties map to non-database fields? → Extract as queries
• Does the model reference infrastructure like email services? → Extract as commands
• Do views directly manipulate database models? → Call commands through the service layer

Through this separation, the original User model can be simplified to a pure data model:

class User(models.Model):
    uid = models.CharField(max_length=100)
    email = models.EmailField()
    status = models.CharField(max_length=20)
    active = models.BooleanField(default=False)
    
    # Keep only basic database operations
    def save(self, *args, **kwargs):
        super().save(*args, **kwargs)

Business logic migrates to service layers, forms, or query modules.

This architecture not only improves code readability and maintainability but also enhances testability. Each command can be tested independently, and query logic can be optimized for different scenarios. It also provides clear boundaries for team collaboration, allowing different developers to focus on data layers, business layers, or presentation layers.

In practice, these patterns can be flexibly combined based on project scale. Small projects may only need simple service layer separation, while large, complex systems might require full domain models, query models, and event-driven architectures. The key is to consistently adhere to separation of concerns, preventing the model layer from becoming a "dumping ground" for code.