Skip to content

feat: structured GraphQL exception handling#2268

Open
zhaomoran wants to merge 1 commit into
hub4j:mainfrom
zhaomoran:feat/graphql-exception-handling
Open

feat: structured GraphQL exception handling#2268
zhaomoran wants to merge 1 commit into
hub4j:mainfrom
zhaomoran:feat/graphql-exception-handling

Conversation

@zhaomoran
Copy link
Copy Markdown

Description

Add structured GraphQL error handling by introducing GHGraphQLException and GHGraphQLError, enabling callers to programmatically inspect GraphQL error responses instead of parsing exception messages.

Key changes:

  • New GHGraphQLError class exposing all GraphQL spec fields: message, type, path, locations, extensions
  • New GHGraphQLException (extends GHIOException) thrown by Requester.fetchGraphQL on GraphQL errors, carrying the full error list, partial response data, and original query
  • Improved error message format: "Request failed due to following response errors:\n - <msg1>\n - <msg2>"
  • GHGraphQLResponse.getDataUnchecked() for accessing partial data in partial-success scenarios
  • Forward-compatible with @JsonIgnoreProperties(ignoreUnknown = true)

Modeled after octokit/graphql.js's GraphqlResponseError pattern.

Relevant GraphQL spec reference: https://spec.graphql.org/October2021/#sec-Errors

This change is fully backward compatible — GHGraphQLException extends GHIOException which extends IOException, so existing catch (IOException) blocks continue to work. Callers can optionally catch GHGraphQLException for structured access.

Before submitting a PR:

  • Changes must not break binary backwards compatibility. If you are unclear on how to make the change you think is needed while maintaining backward compatibility, CONTRIBUTING.md for details.
  • Add JavaDocs and other comments explaining the behavior.
  • When adding or updating methods that fetch entities, add @link JavaDoc entries to the relevant documentation on https://docs.github.com/en/rest .
  • Add tests that cover any added or changed code. This generally requires capturing snapshot test data. See CONTRIBUTING.md for details.
  • Run mvn -D enable-ci clean install site "-Dsurefire.argLine=--add-opens java.base/java.net=ALL-UNNAMED" locally. If this command doesn't succeed, your change will not pass CI.
  • Push your changes to a branch other than main. You will create your PR from that branch.

When creating a PR:

  • Fill in the "Description" above with clear summary of the changes. This includes:
    • No specific issue tracks this improvement. Related: GitHub v4 GraphQL API support #521 (GraphQL API support)
    • Relevant spec link provided above. No REST API docs applicable (this is GraphQL-only).
  • All lines of new code should be covered by tests as reported by code coverage. Any lines that are not covered must have PR comments explaining why they cannot be covered. For example, "Reaching this particular exception is hard and is not a particular common scenario."
  • Enable "Allow edits from maintainers".

@zhaomoran zhaomoran force-pushed the feat/graphql-exception-handling branch 2 times, most recently from 21bc97f to f72b2d3 Compare May 26, 2026 10:46
Introduce GHGraphQLException and GHGraphQLError to provide structured
access to GraphQL error responses, including type, path, locations, and
extensions fields per the GraphQL spec. This enables callers to
programmatically inspect errors rather than parsing exception messages.

Modeled after octokit/graphql.js's GraphqlResponseError pattern.
@zhaomoran zhaomoran force-pushed the feat/graphql-exception-handling branch from 88a6810 to 343ec1a Compare May 26, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant