从API同步数据到Wagtail更新页面报树节点已存在错误如何解决

Wagtail页面模型基于django-treebeard实现层级树结构，add_child方法仅支持对从未入库的全新页面实例调用，触发Attempted to add a tree node that is already in the database报错的核心原因是对已存在于数据库的页面重复调用了树节点新增方法。
另外Wagtail默认的Page模型主键id由框架托管为自增字段，同时关联树结构的路径、深度、左右定位值等核心元数据，直接将外部API返回的ID赋值给该字段会彻底破坏页面树结构，必然触发主键约束或树结构异常。

1. 新增独立字段存储外部API唯一标识 #

不要修改默认主键，在自定义的Product页面模型中新增独立字段存储API返回的商品ID，加唯一索引提升查询效率、避免重复创建：

# 你的Product模型定义文件（通常是models.py）
from django.db import models
from wagtail.models import Page

class Product(Page):
    # 存储外部API返回的唯一商品ID，和框架默认主键隔离
    api_product_id = models.CharField(max_length=100, unique=True, db_index=True)
    # 保留你原有定义的其他字段：language、code等
    language = models.ForeignKey(Language, on_delete=models.SET_NULL, null=True)
    code = models.CharField(max_length=100, blank=True)
    # 其他业务字段...

2. 调整同步逻辑，区分创建/更新分支 #

同步时先查询本地已存在的对应页面，已存在则直接更新字段后保存，不存在才调用add_child新建，绝对不要对已存在页面调用树新增方法：

def get_some_data():
    products = some_api_endpoint()
    product_page_content_type = ContentType.objects.get_for_model(Product)
    language_en = Language.objects.get(code="en")
    home_page_en = HomePage.objects.get(language=1)
    product_index_page_en = ProductsPage.objects.descendant_of(
        home_page_en
    ).first()

    # 一次性取出当前商品索引页下所有英文商品，构建外部ID到实例的映射，减少循环内数据库查询
    existing_products = {
        str(p.api_product_id): p
        for p in Product.objects.child_of(product_index_page_en).filter(language=language_en)
    }

    for level_1 in products:
        for level_2 in level_1["general"]:
            external_id = str(level_2["id"]) # 统一转字符串，避免类型不匹配导致查询失效
            # 匹配到已有页面，走更新逻辑
            if external_id in existing_products:
                product_en = existing_products[external_id]
                # 赋值需要同步更新的字段
                product_en.title = level_2["name"]
                product_en.draft_title = level_2["name"]
                product_en.code = level_2["id"]
                # 父节点没有变化的情况下，绝对不要调用add_child，直接保存即可
                product_en.save()
                # 若需要同步后直接发布，替换为 product_en.save_revision().publish()
            # 未匹配到，走新建逻辑
            else:
                product_en = Product(
                    language=language_en,
                    title=level_2["name"],
                    draft_title=level_2["name"],
                    code=level_2["id"],
                    api_product_id=external_id,
                    content_type=product_page_content_type,
                )
                # 只有全新未入库的页面实例，才能通过父节点调用add_child完成树挂载
                product_index_page_en.add_child(instance=product_en)
                product_en.save()
                # 若需要新建后直接发布，替换为 product_en.save_revision().publish()

• 禁止直接修改Wagtail Page默认的id主键值，该字段由treebeard框架自动维护，手动赋值会导致页面路由、层级查询全量异常
• 禁止直接用Product.objects.create()或基于默认主键的update_or_create()新建页面，这类方法不会写入树结构必需的路径、定位元数据，会生成损坏的无效节点
• 已存在页面如果父节点没有变化，更新字段时不需要调用任何树操作方法（add_child/move等），直接调用实例save()方法即可
• 若同步时存在页面层级调整需求，对需要变更位置的已存在页面调用move()方法，不要重复调用add_child

内容的提问来源于stack exchange，提问作者John Charger