Объединённый источник в Django: почему ForeignKey конфликтует и что делать

Почему Django ORM конфликтует с origin_id при попытке свести несколько ForeignKey к одному источнику, и как обойти это безопасно с @property и аксессорами.

Когда вы пытаетесь объединить несколько внешних ключей в единый логический «источник» и представить его как стандартную связь Django, вы быстро упираетесь в ограничение ORM. Цель понятна: читать из единого представления и по‑прежнему получать доступ к связанным записям так, как если бы это был обычный ForeignKey с обратной связью. На практике же внутренности ForeignKey резервируют имена столбцов так, что этот подход блокируется. Ниже — как проявляется конфликт, почему он возникает и что сегодня можно с этим сделать безопасно.

Постановка задачи

Представим модель записи, которая может указывать на одну из двух исходных сущностей. Каждый тип источника — отдельный, но в базе данных есть представление, которое объединяет их в единую выборку строк. Нужно уметь переходить от объединённого источника к его элементам и от элемента назад к источнику стандартными средствами Django.

class EntryRecord(models.Model):
    uid = models.UUIDField(default=uuid4, editable=False, unique=True, primary_key=True)
    manuscript_id: UUID | None
    manuscript = models.ForeignKey[
        "Manuscript"
    ](
        "Manuscript",
        on_delete=models.CASCADE,
        related_name="entries",
        null=True,
        blank=True,
    )
    hub_id: UUID | None
    hub = models.ForeignKey[
        "Hub"
    ](
        "Hub",
        on_delete=models.CASCADE,
        related_name="entries",
        null=True,
        blank=True,
    )

Далее представление склеивает исходные источники в одну «табличную» модель. Мы хотим считать её единым происхождением для всех записей.

class Origin(pg.View):
    sql = """
        SELECT ...
        FROM manuscripts
        UNION ALL
        SELECT ...
        FROM hubs
        ;
    """
    key = models.UUIDField(unique=True, primary_key=True)
    # ...

Чтобы привязать запись к объединённому источнику, очевидная попытка — сгенерировать единый origin_id на основе двух возможных внешних ключей и объявить ForeignKey на представление, используя этот столбец.

class EntryRecord(models.Model):
    # ... fields above ...
    origin_id = models.GeneratedField(
        expression=Coalesce(F("manuscript_id"), F("hub_id")),
        output_field=models.UUIDField(),
        db_persist=False,
    )
    origin = models.ForeignKey[
        "Origin"
    ](
        "Origin",
        on_delete=models.DO_NOTHING,
        related_name="entries",
        db_column="origin_id",
        to_field="key",
        null=True,
        editable=False,
    )

При выполнении миграций Django выдаёт ошибку:

(models.E006) The field 'origin' clashes with the field 'origin_id' from model 'EntryRecord'.

Почему так происходит

В Django каждый ForeignKey автоматически создаёт и ведёт соответствующий атрибут и столбец в базе вида «<name>_id». Если объявить явное поле модели с тем же именем, возникает конфликт имён. Иными словами, ForeignKey с именем origin неявно ожидает столбец origin_id; когда вы добавляете собственное поле origin_id, это ломает внутренний контракт, и Django отказывается продолжать.

Это и есть ключевое ограничение: нельзя иметь пользовательское поле, чьё имя пересекается с неявным «<fk_field>_id», которым управляет ForeignKey.

Практичное решение

Если требуется сохранить объединённый доступ и при этом избежать конфликта, используйте аксессоры на уровне Python. Свойства — не полноценные ORM‑связи, но они позволяют выразить задумку, не нарушая правил именования. Это компромисс: запросы остаются удобными там, где это важнее всего, а код — читаемым.

Сначала добавьте read‑only origin_id и origin в модель элемента. Затем в модели объединённого представления определите свойство, которое возвращает QuerySet элементов, связанных через любой из ключей. Для чтения это почти та же эргономика, включая привычное сцепление фильтров.

class EntryRecord(models.Model):
    uid = models.UUIDField(default=uuid4, editable=False, unique=True, primary_key=True)
    manuscript_id: UUID | None
    manuscript = models.ForeignKey[
        "Manuscript"
    ](
        "Manuscript",
        on_delete=models.CASCADE,
        related_name="entries",
        null=True,
        blank=True,
    )
    hub_id: UUID | None
    hub = models.ForeignKey[
        "Hub"
    ](
        "Hub",
        on_delete=models.CASCADE,
        related_name="entries",
        null=True,
        blank=True,
    )
    @property
    def origin_id(self) -> UUID | None:
        return self.manuscript_id or self.hub_id
    @property
    def origin(self):
        oid = self.origin_id
        if not oid:
            return None
        try:
            return Origin.objects.get(pk=oid)
        except Origin.DoesNotExist:
            return None

class Origin(pg.View):
    sql = """
        SELECT ...
        FROM manuscripts
        UNION ALL
        SELECT ...
        FROM hubs
        ;
    """
    key = models.UUIDField(unique=True, primary_key=True)
    @property
    def entries(self):
        return EntryRecord.objects.filter(
            Q(manuscript_id=self.key) | Q(hub_id=self.key)
        )

С такой структурой вызов origin.entries.all() работает, потому что entries возвращает QuerySet. Со стороны записи origin и origin_id остаются доступными атрибутами, хотя это уже не ORM‑связи. Так вы полностью обходите внутренний конфликт имён ForeignKey.

Почему это важно понимать

Ограничение проистекает из того, как Django сопоставляет поля связей с неявными столбцами «<fk>_id» и связанными дескрипторами. Про это легко забыть, особенно когда вы конструируете виртуальные столбцы вроде GeneratedField. Понимание этой особенности помогает избежать длительных миграций, которые всё равно не пройдут проверку, и держать модель данных предсказуемой.

Есть и другие пути в экосистеме. GenericForeignKey может решить полиморфную ссылку ценой части автодополнения в ORM. Альтернатива — django-polymorphic, которая может дать более изящное поведение, если подключение сторонней зависимости вам подходит. Взвесьте эти компромиссы относительно вашей среды и ожидаемых инструментов.

Итог

Если попытаться свести несколько ветвей FK в один ForeignKey, подкреплённый сгенерированным столбцом «_id», Django остановит вас из‑за зарезервированных имён для хранения связей. Когда нужна лишь навигация на чтение и аккуратный API, опирайтесь на аксессоры @property, чтобы предоставить единый источник и связанные записи. Не допускайте конфликтов имён: не добавляйте свои «<name>_id» к полям ForeignKey, и оставляйте ORM‑связи для случаев, где можно однозначно привязаться к одному столбцу.