Какие поля могут быть в сериализаторах?

Поля в сериализаторах (на примере Django REST Framework)

Сериализаторы — это ключевой компонент REST API. Они преобразуют между Python объектами и JSON (или другими форматами). Вот полный обзор возможных полей на основе моего опыта с DRF.

1. Базовые скалярные поля

from rest_framework import serializers
from django.db import models

class UserSerializer(serializers.Serializer):
    # ✅ Базовые типы
    id = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=100)
    email = serializers.EmailField()
    age = serializers.IntegerField(min_value=0, max_value=150)
    salary = serializers.DecimalField(max_digits=10, decimal_places=2)
    is_active = serializers.BooleanField()
    birth_date = serializers.DateField()
    created_at = serializers.DateTimeField()
    duration = serializers.TimeField()
    
    # ✅ URL поле
    profile_url = serializers.URLField()
    
    # ✅ UUID
    uuid = serializers.UUIDField()
    
    # ✅ JSON поле
    metadata = serializers.JSONField()
    
    # ✅ Файл
    avatar = serializers.FileField()
    
    # ✅ Изображение
    photo = serializers.ImageField()

# Использование
data = {
    'id': 1,
    'name': 'John',
    'email': 'john@example.com',
    'age': 30,
    'salary': '50000.00',
    'is_active': True,
    'birth_date': '1994-03-22',
    'created_at': '2024-03-22T10:30:00Z',
    'duration': '14:30:00',
    'profile_url': 'https://example.com/users/1',
    'uuid': '123e4567-e89b-12d3-a456-426614174000',
    'metadata': {'key': 'value'},
    'avatar': '<file object>',
    'photo': '<image object>'
}

serializer = UserSerializer(data=data)
if serializer.is_valid():
    print(serializer.validated_data)
else:
    print(serializer.errors)

2. Поля для выбора

from django.db import models

class Article(models.Model):
    STATUS_CHOICES = [
        ('draft', 'Draft'),
        ('published', 'Published'),
        ('archived', 'Archived'),
    ]
    title = models.CharField(max_length=200)
    status = models.CharField(max_length=20, choices=STATUS_CHOICES)

class ArticleSerializer(serializers.ModelSerializer):
    # ✅ Поле выбора из констант
    status = serializers.ChoiceField(choices=Article.STATUS_CHOICES)
    
    class Meta:
        model = Article
        fields = ['id', 'title', 'status']

# Использование
data = {'title': 'My Article', 'status': 'published'}
serializer = ArticleSerializer(data=data)
if serializer.is_valid():
    article = serializer.save()
    # {'id': 1, 'title': 'My Article', 'status': 'published'}

3. Вложенные сериализаторы (Nested)

class Author(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField()

class Post(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    content = models.TextField()

class AuthorSerializer(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = ['id', 'name', 'email']

class PostSerializer(serializers.ModelSerializer):
    # ✅ Вложенный сериализатор для чтения
    author = AuthorSerializer(read_only=True)
    # ✅ ID для записи
    author_id = serializers.IntegerField(write_only=True)
    
    class Meta:
        model = Post
        fields = ['id', 'title', 'author', 'author_id', 'content']
    
    def create(self, validated_data):
        author_id = validated_data.pop('author_id')
        return Post.objects.create(author_id=author_id, **validated_data)

# При GET — автор вложен
# {'id': 1, 'title': 'Post', 'author': {'id': 1, 'name': 'John', 'email': 'john@example.com'}, 'content': '...'}

# При POST — используем author_id
# {'title': 'New Post', 'author_id': 1, 'content': '...'}

4. Поля связей (Relations)

class Comment(models.Model):
    post = models.ForeignKey(Post, on_delete=models.CASCADE, related_name='comments')
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    text = models.TextField()

class CommentSerializer(serializers.ModelSerializer):
    # ✅ PrimaryKeyRelatedField — используется ID
    post = serializers.PrimaryKeyRelatedField(queryset=Post.objects.all())
    author = serializers.PrimaryKeyRelatedField(queryset=Author.objects.all())
    
    class Meta:
        model = Comment
        fields = ['id', 'post', 'author', 'text']

class PostDetailSerializer(serializers.ModelSerializer):
    # ✅ StringRelatedField — использует __str__
    author = serializers.StringRelatedField(read_only=True)
    
    # ✅ SlugRelatedField — использует slug
    category = serializers.SlugRelatedField(
        read_only=True,
        slug_field='slug'
    )
    
    # ✅ Вложенные объекты
    comments = CommentSerializer(many=True, read_only=True)
    
    class Meta:
        model = Post
        fields = ['id', 'title', 'author', 'category', 'comments']

# Результат:
# {
#   'id': 1,
#   'title': 'Post',
#   'author': 'John Doe',
#   'category': 'tech',
#   'comments': [
#     {'id': 1, 'post': 1, 'author': 1, 'text': 'Great!'},
#     {'id': 2, 'post': 1, 'author': 2, 'text': 'Thanks!'}
#   ]
# }

5. Many=True для списков

class PostListSerializer(serializers.ModelSerializer):
    author = AuthorSerializer(read_only=True)
    
    class Meta:
        model = Post
        fields = ['id', 'title', 'author']

# Сериализация списка
posts = Post.objects.all()
serializer = PostListSerializer(posts, many=True)
print(serializer.data)
# [
#   {'id': 1, 'title': 'Post 1', 'author': {'id': 1, 'name': 'John', 'email': 'john@example.com'}},
#   {'id': 2, 'title': 'Post 2', 'author': {'id': 2, 'name': 'Jane', 'email': 'jane@example.com'}}
# ]

6. Вычисляемые поля (SerializerMethodField)

from django.utils import timezone

class UserDetailSerializer(serializers.ModelSerializer):
    # ✅ Вычисляемое поле
    full_name = serializers.SerializerMethodField()
    is_verified = serializers.SerializerMethodField()
    days_active = serializers.SerializerMethodField()
    
    class Meta:
        model = Author
        fields = ['id', 'name', 'email', 'full_name', 'is_verified', 'days_active']
    
    def get_full_name(self, obj):
        # obj — это экземпляр Author
        return f"{obj.name} <{obj.email}>"
    
    def get_is_verified(self, obj):
        # Проверка сложной логики
        return obj.email and '@' in obj.email
    
    def get_days_active(self, obj):
        # Вычисление на основе времени
        if hasattr(obj, 'created_at'):
            delta = timezone.now() - obj.created_at
            return delta.days
        return None

# Результат:
# {
#   'id': 1,
#   'name': 'John',
#   'email': 'john@example.com',
#   'full_name': 'John <john@example.com>',
#   'is_verified': True,
#   'days_active': 365
# }

7. Поля с параметрами валидации

class ProductSerializer(serializers.Serializer):
    # ✅ Параметры валидации
    name = serializers.CharField(max_length=200, min_length=3)
    price = serializers.DecimalField(max_digits=10, decimal_places=2, min_value=0)
    stock = serializers.IntegerField(min_value=0, max_value=10000)
    description = serializers.CharField(allow_blank=True, required=False)
    tags = serializers.ListField(child=serializers.CharField(max_length=50))
    
    # ✅ Значение по умолчанию
    is_active = serializers.BooleanField(default=True)
    
    # ✅ Поле только для чтения (не принимается при создании)
    id = serializers.IntegerField(read_only=True)
    created_at = serializers.DateTimeField(read_only=True)
    
    # ✅ Поле только для записи (не выводится при чтении)
    password = serializers.CharField(write_only=True)

# Использование
data = {
    'name': 'Laptop',
    'price': '999.99',
    'stock': 50,
    'description': 'High-end laptop',
    'tags': ['electronics', 'computers'],
    'is_active': True,
    'password': 'secret123'
}

serializer = ProductSerializer(data=data)
if serializer.is_valid():
    print(serializer.validated_data)
    # 'password' будет в validated_data, но не в .data
else:
    print(serializer.errors)

8. Поля с кастомной валидацией

class UserRegistrationSerializer(serializers.Serializer):
    username = serializers.CharField(max_length=100)
    email = serializers.EmailField()
    password = serializers.CharField(write_only=True, min_length=8)
    password_confirm = serializers.CharField(write_only=True)
    
    # ✅ Валидация отдельного поля
    def validate_username(self, value):
        if len(value) < 3:
            raise serializers.ValidationError("Username must be at least 3 characters")
        if User.objects.filter(username=value).exists():
            raise serializers.ValidationError("Username already exists")
        return value
    
    # ✅ Валидация нескольких полей
    def validate(self, data):
        if data['password'] != data['password_confirm']:
            raise serializers.ValidationError({"password": "Passwords don't match"})
        return data

# Использование
data = {
    'username': 'john_doe',
    'email': 'john@example.com',
    'password': 'secure_password_123',
    'password_confirm': 'secure_password_123'
}

serializer = UserRegistrationSerializer(data=data)
if serializer.is_valid():
    print(serializer.validated_data)
else:
    print(serializer.errors)

9. Динамические поля

class DynamicFieldsSerializer(serializers.ModelSerializer):
    """Позволяет клиенту выбрать какие поля получить"""
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        
        request = self.context.get('request')
        if request:
            # ?fields=id,name,email
            fields = request.query_params.get('fields')
            if fields:
                allowed = set(fields.split(','))
                existing = set(self.fields.keys())
                for field_name in existing - allowed:
                    self.fields.pop(field_name)

class PostDynamicSerializer(DynamicFieldsSerializer):
    author = AuthorSerializer(read_only=True)
    
    class Meta:
        model = Post
        fields = ['id', 'title', 'author', 'content', 'created_at']

# Использование в view
# GET /api/posts/?fields=id,title,author
# {
#   'id': 1,
#   'title': 'Post',
#   'author': {'id': 1, 'name': 'John', 'email': 'john@example.com'}
# }

10. Дополнительные поля

class BookSerializer(serializers.ModelSerializer):
    # ✅ Ссылка на объект
    url = serializers.HyperlinkedIdentityField(
        view_name='book-detail',
        lookup_field='pk'
    )
    
    # ✅ Относительная ссылка на связанный объект
    author_url = serializers.HyperlinkedRelatedField(
        view_name='author-detail',
        read_only=True,
        source='author'
    )
    
    # ✅ Список ID (для многие-ко-многим)
    tags = serializers.PrimaryKeyRelatedField(
        many=True,
        queryset=Tag.objects.all()
    )
    
    # ✅ Логический флаг — есть ли отзывы
    has_reviews = serializers.SerializerMethodField()
    
    class Meta:
        model = Book
        fields = ['id', 'url', 'title', 'author_url', 'tags', 'has_reviews']
    
    def get_has_reviews(self, obj):
        return obj.reviews.exists()

# Результат:
# {
#   'id': 1,
#   'url': 'http://api.example.com/books/1/',
#   'title': 'Python Guide',
#   'author_url': 'http://api.example.com/authors/1/',
#   'tags': [1, 2, 3],
#   'has_reviews': True
# }

Рекомендации

1. Используйте read_only=True — для полей, которые только выводятся
2. Используйте write_only=True — для полей вроде пароля
3. Вложенные сериализаторы — для сложных структур данных
4. SerializerMethodField — для вычисляемых полей
5. Валидация на уровне поля — проверяйте формат (email, URL)
6. Валидация на уровне сериализатора — проверяйте связь между полями
7. Many=True — для массивов объектов
8. Динамические поля — позволяйте клиентам выбирать поля
9. Гиперссылки — для удобства клиентов
10. Тестируйте валидацию — неправильная валидация опаснее, чем её отсутствие

Сериализаторы — это граница между вашей логикой и внешним миром. Сделайте их надежными и предсказуемыми.