DRF中外键模型国际化字段映射方案选型：注解vs自定义字段

我希望在Django Rest Framework中编写序列化器，当需要国际化（i18n）时返回Itemi18n模型的name字段，否则返回Item模型自身的name字段。目前想到两种解决方案：一是使用annotate覆盖字段，二是自定义字段，但不确定哪种是最佳实践以及二者的性能差异。

现有代码 #

models.py #

class Item(models.Model):
    name = models.CharField(max_length=100)
    # other_no_need_translate = models.CharField(max_length=100)

class Itemi18n(models.Model):
    origin = models.ForeignKey(Item, related_name='i18n')
    language = models.CharField(max_length=200, default="")
    name = models.CharField(max_length=100)

views.py #

class ItemViewSet(viewsets.GenericViewSet):
    
    def get_queryset(self):
        return Item.objects.annotate(name=F('i18n__name')) # something like this

serializers.py #

class I18nField(Field):

    def __init__(self, field_attr, **kwargs):
        self.field_attr = field_attr
        super().__init__(source='*', read_only=True, **kwargs)

    def to_representation(self, value) -> str:
        request = self.context['request']
        if request.query_params.get('lang') == 'es':
            value = ...
        else:
            value = ...
        return value

class ItemSerializer(serializers.ModelSerializer):
    name = I18nField(...)

1. 基于annotate的方案（数据库层处理） #

实现思路 #

在get_queryset中根据请求的lang参数，通过annotate将对应语言的国际化name字段注入到Item查询集，同时处理无翻译记录的情况：

def get_queryset(self):
    lang = self.request.query_params.get('lang')
    queryset = Item.objects.all()
    if lang:
        from django.db.models import Subquery, OuterRef, Case, When
        # 用子查询获取对应语言的翻译，避免多记录导致的结果重复
        i18n_subquery = Itemi18n.objects.filter(
            origin=OuterRef('pk'),
            language=lang
        ).values('name')[:1]
        queryset = queryset.annotate(
            translated_name=Subquery(i18n_subquery)
        ).annotate(
            name=Case(
                When(translated_name__isnull=False, then=F('translated_name')),
                default=F('name'),
                output_field=models.CharField()
            )
        )
    return queryset

性能特点 #

• 核心优势：所有逻辑在数据库层完成，仅需一次SQL查询，彻底避免序列化阶段的额外数据库请求（比如自定义字段易触发的N+1问题），数据量越大，性能优势越明显。
• 注意事项：必须处理Itemi18n无对应语言记录的场景，同时用[:1]限制子查询结果数量，防止一个Item对应多条同语言翻译时导致的查询结果重复。

2. 自定义字段方案（序列化层处理） #

实现思路 #

完善自定义字段逻辑，在序列化阶段根据请求参数获取对应翻译，无翻译则返回原字段：

class I18nField(serializers.Field):
    def __init__(self, field_attr, **kwargs):
        self.field_attr = field_attr
        super().__init__(source='*', read_only=True, **kwargs)

    def to_representation(self, item) -> str:
        request = self.context['request']
        lang = request.query_params.get('lang')
        if lang:
            # 优先取对应语言的翻译，无结果则返回原字段
            i18n_obj = item.i18n.filter(language=lang).first()
            if i18n_obj:
                return getattr(i18n_obj, self.field_attr)
        return getattr(item, self.field_attr)

class ItemSerializer(serializers.ModelSerializer):
    name = I18nField(field_attr='name')
    class Meta:
        model = Item
        fields = ['name']

性能特点 #

• 潜在风险：如果视图未提前用prefetch_related('i18n')预加载关联数据，会触发N+1查询问题——每序列化一条Item，就会发起一次查询获取翻译记录，数据量大时性能会急剧下降。
• 适用场景：小型项目或快速迭代场景，逻辑集中在序列化层，代码更直观；若提前预加载关联数据，性能也能满足需求。

最佳实践建议 #

• 优先选择annotate方案：尤其在数据量大、查询频率高的场景下，数据库层处理能保证性能稳定性，且序列化器可直接使用annotate生成的字段，无需额外修改。
• 自定义字段适合轻量场景：项目规模小、数据量不大，或需要对多字段做翻译逻辑时可选用，但必须在视图中添加prefetch_related('i18n')预加载关联数据，规避N+1问题。

额外优化点：可将语言参数的获取逻辑封装为视图Mixin，减少重复代码；同时给Itemi18n的origin和language字段添加联合唯一索引，避免重复翻译记录，提升查询效率。

内容的提问来源于stack exchange，提问作者Tony.Luo