Strapi中如何在同一请求创建并关联Customer与Children实体？

问题背景 #

我在Strapi 5.9.0中搭建了包含Customer和Children的服务，二者是一对多关联（一个Customer对应多个Children，一个Children仅归属一个Customer）。尝试自定义Customer的创建API，实现在同一请求里同时创建Customer、Children并完成关联，但折腾一周都没解决。

已开放所有权限，执行关联操作时出现以下错误：

[2025-02-12 15:02:24.244] error: Document with id "b2vpvz81yx4v1ojlf0jxewib", locale "null" not found

报错代码行：

await strapi.documents("api::customer.customer").update({
  documentId: customer.documentId,
  data: {
    children: {
      connect: childrenToAdd.map((child) => child.documentId),
    },
  },
});

错误指向Children的documentId，但创建Children时没有报错且正常返回了该ID。当前使用的完整控制器代码如下：

"use strict";

import { factories } from "@strapi/strapi";
import { Core } from "@strapi/strapi";

export default factories.createCoreController(
  "api::customer.customer",
  ({ strapi }: { strapi: Core.Strapi }) => ({
    async create(ctx) {
      try {
        const requestBody = ctx.request.body;
        const { children, ...customerData } = requestBody.data;
        console.log({ customerData, children });

        // Create the customer first
        const customer = await strapi.service("api::customer.customer").create({
          data: customerData,
        });
        const publishedCustomer = await strapi
          .documents("api::customer.customer")
          .publish({
            documentId: customer.documentId,
          });
        console.log({ publishedCustomer });

        // If children exist, create them and associate them with the customer
        if (children && Array.isArray(children)) {
          const childrenToAddPromises = children.map(async (child) => {
            const childrenToPublish = await strapi.db
              .query("api::children.children")
              .create({
                data: child,
              });
            const publishedChildren = await strapi
              .documents("api::children.children")
              .publish({
                documentId: childrenToPublish.documentId,
              });
            return publishedChildren;
          });
          const childrenToAdd = await Promise.all(childrenToAddPromises);

          await strapi.documents("api::customer.customer").update({
            documentId: customer.documentId,
            data: {
              children: {
                connect: childrenToAdd.map((child) => child.documentId),
              },
            },
          });
        }

        return customer;
      } catch (error) {
        ctx.throw(400, error.message);
      }
    },
  })
);

使用的Strapi版本：

"@strapi/plugin-cloud": "5.9.0",
"@strapi/plugin-documentation": "^5.9.0",
"@strapi/plugin-users-permissions": "5.9.0",
"@strapi/strapi": "5.9.0",

测试方式：通过plugin-documentation生成的Swagger接口测试。

问题原因 #

1. 混合使用多类API导致状态不匹配：创建Customer用了strapi.service，创建Children用了strapi.db.query，关联时用了strapi.documents.update。Strapi 5中，数据库实体（Entities）和已发布文档（Documents）是两套逻辑，手动拆分操作容易导致数据状态不同步，出现找不到文档的错误。
2. 手动关联的时机错误：创建Children后立即发布并关联，可能文档系统还未完成数据同步，导致关联时无法识别刚创建的文档ID。

修复方案 #

直接使用Strapi服务层的关联创建语法，这是官方推荐的方式，可一次性完成父实体、子实体的创建及关联，无需手动处理后续关联操作。

修改后的控制器代码：

"use strict";

import { factories } from "@strapi/strapi";
import { Core } from "@strapi/strapi";

export default factories.createCoreController(
  "api::customer.customer",
  ({ strapi }: { strapi: Core.Strapi }) => ({
    async create(ctx) {
      try {
        const requestBody = ctx.request.body;
        let { children, ...customerData } = requestBody.data;

        // 直接在创建Customer时，通过关联语法创建并关联Children
        if (children && Array.isArray(children)) {
          customerData.children = {
            create: children.map(child => ({ data: child }))
          };
        }

        // 服务层会自动处理所有实体的创建、关联，添加publish参数可直接发布
        const customer = await strapi.service("api::customer.customer").create({
          data: customerData,
          publish: true
        });

        return customer;
      } catch (error) {
        ctx.throw(400, error.message);
      }
    },
  })
);

额外说明 #

1. Strapi 5关联语法规则：一对多关联场景下，父实体创建时可通过[关联字段名]: { create: [...] }的语法，直接嵌套创建子实体并完成关联，无需单独调用关联接口。
2. 自动发布控制：如果内容类型开启了draftAndPublish，添加publish: true参数可直接发布所有创建的实体，无需单独调用strapi.documents.publish。
3. 权限兼容：该代码继承了核心控制器的权限逻辑，无需额外修改权限配置（已开放所有权限的情况下可直接使用）。

内容的提问来源于stack exchange，提问作者Itay Tur