뮤테이션 페이로드 처리

뮤테이션 필드는 다음 두 가지 엔티티 타입 중 하나를 반환하도록 설정할 수 있습니다.

페이로드 객체 타입
뮤테이션된 엔티티를 직접 반환

페이로드 객체 타입

페이로드 객체 타입에는 뮤테이션에 관한 모든 데이터가 포함됩니다.

뮤테이션의 상태(성공 또는 실패)
에러(있는 경우)는 고유한 GraphQL 타입을 사용하여 표현
뮤테이션이 성공한 경우의 엔티티

예를 들어, 뮤테이션 updatePost는 PostUpdateMutationPayload 타입의 객체를 반환하며, 업데이트된 게시물 엔티티를 가져오려면 해당 필드 post를 추가로 쿼리해야 합니다.

mutation UpdatePost {
  updatePost(input: {
    id: 1724,
    title: "New title",
    status: publish
  }) {
    # This is the status of the mutation: SUCCESS or FAILURE
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
    }
    post {
      id
      title
      # This is the status of the post: publish, pending, trash, etc
      status
    }
  }
}

페이로드 객체를 사용하면 에러를 더욱 적절하게 표현할 수 있습니다. 에러 종류별로 고유한 GraphQL 타입을 가질 수도 있으며, 이를 통해 애플리케이션에서 에러 종류에 따라 다른 대응을 표시할 수 있어 사용자 경험이 향상됩니다.

위 예제에서 작업이 성공한 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "status": "SUCCESS",
      "errors": null,
      "post": {
        "id": 1724,
        "title": "Some title",
        "status": "publish"
      }
    }
  }
}

사용자가 로그인하지 않은 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "status": "FAILURE",
      "errors": [
        {
          "__typename": "UserIsNotLoggedInErrorPayload",
          "message": "You must be logged in to create or update custom posts"
        }
      ],
      "post": null
    }
  }
}

사용자가 게시물을 편집할 권한이 없는 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "status": "FAILURE",
      "errors": [
        {
          "__typename": "LoggedInUserHasNoEditingCustomPostCapabilityErrorPayload",
          "message": "Your user doesn't have permission for editing custom posts."
        }
      ],
      "post": null
    }
  }
}

이 모드에서는 GraphQL 스키마에 MutationPayload, MutationErrorPayloadUnion, ErrorPayload 등의 추가 타입이 많이 포함되므로 스키마 크기가 커집니다.

GraphQL schema with payload object types for mutations

뮤테이션 페이로드 객체 쿼리

스키마 내의 모든 뮤테이션에는 최근 생성된 페이로드 객체를 쿼리하기 위한 대응 필드가 있으며, 이름은 {mutationName}MutationPayloadObjects입니다.

이러한 필드에는 다음이 포함됩니다.

addCommentToCustomPostMutationPayloadObjects(addCommentToCustomPost 용)
createCustomPostMutationPayloadObjects(createCustomPost 용)
createMediaItemMutationPayloadObjects(createMediaItem 용)
createPageMutationPayloadObjects(createPage 용)
createPostMutationPayloadObjects(createPost 용)
removeFeaturedImageFromCustomPostMutationPayloadObjects(removeFeaturedImageFromCustomPost 용)
replyCommentMutationPayloadObjects(replyComment 용)
setCategoriesOnPostMutationPayloadObjects(setCategoriesOnPost 용)
setFeaturedImageOnCustomPostMutationPayloadObjects(setFeaturedImageOnCustomPost 용)
setTagsOnPostMutationPayloadObjects(setTagsOnPost 용)
updateCustomPostMutationPayloadObjects(updateCustomPost 용)
updatePageMutationPayloadObjects(updatePage 용)
updatePostMutationPayloadObjects(updatePost 용)

이러한 필드를 통해 배열의 항목을 순회하면서 @applyField를 사용하여 실행된 뮤테이션의 결과를 가져올 수 있습니다.

예를 들어, 다음 쿼리는 게시물을 일괄 복제합니다.

query GetPostsAndExportData
{
  postsToDuplicate: posts {
    title
    rawContent
    excerpt
 
    # Already create (and export) the inputs for the mutation
    postInput: _echo(value: {
      title: $__title
      contentAs: {
        html: $__rawContent
      },
      excerpt: $__excerpt
    })
      @export(as: "postInput", type: LIST)
      @remove
  }
}
 
mutation CreatePosts
  @depends(on: "GetPostsAndExportData")
{
  createdPostMutationPayloadObjectIDs: _echo(value: $postInput)
    @underEachArrayItem(
      passValueOnwardsAs: "input"
    )
      @applyField(
        name: "createPost"
        arguments: {
          input: $input
        },
        setResultInResponse: true
      )
    @export(as: "createdPostMutationPayloadObjectIDs")
}
 
query DuplicatePosts
  @depends(on: "CreatePosts")
{
  createdPostMutationObjectPayloads: createPostMutationPayloadObjects(input: {
    ids: $createdPostMutationPayloadObjectIDs
  }) {
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
    }
    post {
      id
      title
      rawContent
      excerpt
    }
  }
}

기본적으로 이러한 필드는 GraphQL 스키마에 추가되지 않습니다. 추가하려면 「Use payload types for mutations, and add fields to query those payload objects」 옵션을 선택해야 합니다.

뮤테이션된 엔티티

뮤테이션은 성공한 경우 뮤테이션된 엔티티를 직접 반환하고, 실패한 경우에는 null을 반환합니다. 에러 메시지는 JSON 응답의 최상위 errors 항목에 표시됩니다.

예를 들어, 뮤테이션 updatePost는 Post 타입의 객체를 반환합니다.

mutation UpdatePost {
  updatePost(input: {
    id: 1724,
    title: "New title",
    status: publish
  }) {
    id
    title
    status
  }
}

작업이 성공한 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "id": 1724,
      "title": "Some title",
      "status": "publish"
    }
  }
}

에러가 발생한 경우, 해당 에러는 응답의 errors 항목에 표시됩니다. 예를 들어, 사용자가 로그인하지 않은 경우 다음 응답을 받게 됩니다.

{
    "errors": [
      {
        "message": "You must be logged in to create or update custom posts'",
        "locations": [
          {
            "line": 2,
            "column": 3
          }
        ]
      }
  ],
  "data": {
    "updatePost": null
  }
}

주의할 점으로, 이 결과로 인해 최상위 errors 항목에는 구문 오류, 스키마 유효성 검사 오류, 로직 오류(예: 필드 인수 이름 미지정, 존재하지 않는 필드 요청, 네트워크 다운 시 _sendHTTPRequest 호출 등)뿐만 아니라 「콘텐츠 유효성 검사」 오류(예: 「이 게시물을 수정할 권한이 없습니다」)도 포함되게 됩니다.

추가 타입이 없으므로 GraphQL 스키마는 더욱 간결해집니다.

GraphQL schema without payload object types for mutations

뮤테이션의 페이로드 객체 타입 처리

첫 번째 옵션인 페이로드 객체 타입의 처리 방법을 살펴보겠습니다.

스키마 내의 뮤테이션은 어떤 페이로드 객체를 반환하며, 뮤테이션으로 인해 발생한 에러 또는 성공한 경우의 수정된 객체를 제공합니다(이 두 속성은 대부분 상호 배타적입니다. errors 또는 object 중 하나에 값이 있고 나머지 하나는 null이 됩니다).

에러는 해당 뮤테이션에서 발생 가능한 모든 에러를 포함하는 「ErrorPayloadUnion」 타입을 통해 제공됩니다. 각각의 에러는 인터페이스 ErrorPayload를 구현하는 어떤 「ErrorPayload」 타입입니다.

예를 들어, 작업 updatePost는 PostUpdateMutationPayload를 반환하며, 다음 필드가 포함됩니다.

status: 작업의 성공 여부를 나타내며, SUCCESS 또는 FAILURE 값을 가집니다
post 및 postID: 업데이트가 성공한 경우의 업데이트된 게시물 객체와 해당 ID
errors: 업데이트가 실패한 경우의 CustomPostUpdateMutationErrorPayloadUnion 목록

유니온 타입 CustomPostUpdateMutationErrorPayloadUnion에는 커스텀 게시물을 수정할 때 발생할 수 있는 모든 에러 목록이 포함됩니다.

CustomPostDoesNotExistErrorPayload
GenericErrorPayload
LoggedInUserHasNoEditingCustomPostCapabilityErrorPayload
LoggedInUserHasNoPermissionToEditCustomPostErrorPayload
LoggedInUserHasNoPublishingCustomPostCapabilityErrorPayload
UserIsNotLoggedInErrorPayload

에러 타입 GenericErrorPayload는 모든 「ErrorPayloadUnion」 타입에 포함됩니다. wp_update_post가 단순히 WP_Error를 생성하는 경우처럼 에러의 구체적인 원인을 특정할 수 없을 때 사용됩니다. 이 타입은 추가 필드로 code와 data를 제공합니다.

updatePost 뮤테이션을 실행하려면 다음과 같이 실행할 수 있습니다.

mutation UpdatePost(
  $postId: ID!
  $title: String!
) {
  updatePost(
    input: {
      id: $postId,
      title: $title,
    }
  ) {
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
      ...on GenericErrorPayload {
        code
      }
    }
    post {
      id
      title
    }
  }
}

작업이 성공한 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "status": "SUCCESS",
      "errors": null,
      "post": {
        "id": 1724,
        "title": "This incredible title"
      }
    }
  }
}

사용자가 로그인하지 않은 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "status": "FAILURE",
      "errors": [
        {
          "__typename": "UserIsNotLoggedInErrorPayload",
          "message": "You must be logged in to create or update custom posts"
        }
      ],
      "post": null
    }
  }
}

사용자가 게시물을 편집할 권한이 없는 경우, 다음 응답을 받게 됩니다.

{
  "data": {
    "updatePost": {
      "status": "FAILURE",
      "errors": [
        {
          "__typename": "LoggedInUserHasNoEditingCustomPostCapabilityErrorPayload",
          "message": "Your user doesn't have permission for editing custom posts."
        }
      ],
      "post": null
    }
  }
}

​페이로드 객체 타입

​뮤테이션 페이로드 객체 쿼리

​뮤테이션된 엔티티

​뮤테이션의 페이로드 객체 타입 처리

페이로드 객체 타입

뮤테이션 페이로드 객체 쿼리

뮤테이션된 엔티티

뮤테이션의 페이로드 객체 타입 처리