Example of separating schema and resolvers for a large project structure with for multi-team setup #3631

afreeland · 2025-04-01T20:19:23Z

This MR includes an additional example of how it is possible to separate schema and resolvers into separate packages, even external packages, allowing support for larger projects. Hoping this kind of dovetails in the this MR: #3595

The project has the following layout:

tree 
.
├── integration
│   ├── go.mod
│   ├── go.sum
│   ├── integration.go
│   └── schema.graphqls
├── main
│   ├── go.mod
│   ├── go.sum
│   ├── gqlgen.yml
│   ├── graph
│   │   ├── generated.go
│   │   ├── model
│   │   │   └── models_gen.go
│   │   ├── resolver.go
│   │   ├── schema.graphqls
│   │   └── schema.resolvers.go
│   ├── server.go
│   └── tools.go
└── shared
    ├── go.mod
    ├── go.sum
    ├── schema.graphqls
    └── shared.go

6 directories, 18 files

The main package is the centralized graph and will consume the schema files from both the shared and the integration packages.

The main package, after initial generate command, has commented out the resolver: section in the gqlgen.yml file. This prevents the main package from generating all resolvers, which we would like other teams to be able to manage. When generate is ran, it will still generate all model information in the main package, which the external packages can manage.

Additionally, the main package in the resolver.go file tries to lift the generated interface for external resolvers into its own interface called ExternalQueryResolver. This interface is then embedded in in the Resolver like so:

type Resolver struct {
	ExternalQueryResolver
}

This allows the RootResolver to still function as it should but lifts some of the MutationResolver and QueryResolver interfaces that were generated up in a way that other teams can implement the resolver.

Then upon initialization, you can define the ExternalQueryResolver from another package like so:

// Create a new executable schema with the composed resolver
	srv := handler.NewDefaultServer(graph.NewExecutableSchema(graph.Config{
		Resolvers: &graph.Resolver{
			ExternalQueryResolver: &integration.Resolver{},
			// Add other team resolvers here
		},
	}))

It was challenging to find a good way to provide a balance of gqlgen built-in functionality in a way that allowed for ease of use, while also allowing still providing some autonomy to other teams.

There are very few discussions on how this is doable and I couldn't really find any examples of doing this in practice. I wanted to put this up in hopes it would help others...or at the very least call out any major flaws that may exist with this.

Describe your PR and link to any relevant issues.

I have:

Added tests covering the bug / feature (see testing)
Updated any relevant documentation (see docs)

…ure with for multi-team setup

coveralls · 2025-04-01T20:35:39Z

coverage: 73.374% (+0.03%) from 73.349%
when pulling 02a4d4b on afreeland:large-project-structure
into 492bf92 on 99designs:master.

StevenACoffman · 2025-04-01T22:39:29Z

_examples/large-project-structure/integration/go.mod

@@ -0,0 +1,17 @@
+module github.com/corelight/integration


Do you mind if we rename this something that matches the directory like:

Suggested change

module github.com/corelight/integration

module github.com/99designs/gqlgen/_examples/large-project-structure/integration

Some of the people who are new to Go have their minds blown when the directory and module names don't match.

StevenACoffman · 2025-04-02T00:13:39Z

Thanks! Also, some larger installations combine other options like use_function_syntax_for_execution_context, omit_root_models and a few other config options to further customize gqlgen behavior and scale even further.

afreeland · 2025-04-02T12:59:41Z

Thanks! Also, some larger installations combine other options like use_function_syntax_for_execution_context, omit_root_models and a few other config options to further customize gqlgen behavior and scale even further.

Just reading some of the comment descriptions on both use_function_syntax_for_execution_context and omit_root_models, they both seem useful! I guess I kind of skipped both of them somehow when working through things. Appreciate the heads up on those two and I plan on experimenting with those here in just a little bit! 🙏

Hopefully, one of us will get some free time available soon to writeup some more detailed documentation on configs like that and just structuring a project for scale. I definitely think theres a need and the community will benefit from it 😉

Edit: It looks like use_function_syntax_for_execution_context: true is actually missing from the gqlgen.yml that the project gets initialized with. It is in the docs > content > config.md though.

StevenACoffman · 2025-04-02T15:33:48Z

I wonder if some members of the community who have experience using gqlgen in larger orgs or teams might offer guidance here?
@a8m @giautm @kanodia-parag @duckbrain

For a single gqlgen project, what gqlgen config works best really changes at a few key points during the course of that project's normal growth and evolution. For instance:

quick proof of concept - single file layout
medium-sized team(s) - follow schema layout
many teams - separate schema and resolvers into separate packages as in this example
very large type systems (more than 65,000 methods) - use_function_syntax_for_execution_context

However, some will instead choose to adopt GraphQL Federation and split into multiple gqlgen instances before one of these growth points is even reached.

StevenACoffman · 2025-04-24T18:59:40Z

Oh, hey, I forgot to mention another large scale config option is to limit the concurrency for resolvers:

# Optional: Maximum number of goroutines in concurrency to use per child resolvers(default: unlimited)
# worker_limit: 1000

Example of separating schema and resolvers for a large project struct…

c3bfa83

…ure with for multi-team setup

StevenACoffman reviewed Apr 1, 2025

View reviewed changes

PR Feedback: rename modules for clarity

02a4d4b

StevenACoffman merged commit 33f0390 into 99designs:master Apr 4, 2025
17 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Example of separating schema and resolvers for a large project structure with for multi-team setup #3631

Example of separating schema and resolvers for a large project structure with for multi-team setup #3631

Uh oh!

afreeland commented Apr 1, 2025

Uh oh!

coveralls commented Apr 1, 2025 •

edited

Loading

Uh oh!

StevenACoffman Apr 1, 2025 •

edited

Loading

Uh oh!

StevenACoffman commented Apr 2, 2025 •

edited

Loading

Uh oh!

afreeland commented Apr 2, 2025 •

edited

Loading

Uh oh!

StevenACoffman commented Apr 2, 2025

Uh oh!

Uh oh!

StevenACoffman commented Apr 24, 2025 •

edited

Loading

Uh oh!

Uh oh!

	module github.com/corelight/integration
	module github.com/99designs/gqlgen/_examples/large-project-structure/integration

Example of separating schema and resolvers for a large project structure with for multi-team setup #3631

Example of separating schema and resolvers for a large project structure with for multi-team setup #3631

Uh oh!

Conversation

afreeland commented Apr 1, 2025

Uh oh!

coveralls commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StevenACoffman Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StevenACoffman commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

afreeland commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StevenACoffman commented Apr 2, 2025

Uh oh!

Uh oh!

StevenACoffman commented Apr 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

coveralls commented Apr 1, 2025 •

edited

Loading

StevenACoffman Apr 1, 2025 •

edited

Loading

StevenACoffman commented Apr 2, 2025 •

edited

Loading

afreeland commented Apr 2, 2025 •

edited

Loading

StevenACoffman commented Apr 24, 2025 •

edited

Loading