gqlgen README

The project's README from github.com/99designs/gqlgen. As one markdown file: README.md.

gqlgen

gqlgen Integration Coverage Status Go Report Card Go Reference Read the Docs

What is gqlgen?

gqlgen is a Go library for building GraphQL servers without any fuss.

Still not convinced enough to use gqlgen? Compare gqlgen with other Go graphql implementations

Quick start

  1. Initialise a new go module
mkdir example
cd example
go mod init example
  1. Add github.com/99designs/gqlgen to your project, as a tool dependency
go get -tool github.com/99designs/gqlgen
  1. Initialise gqlgen config and generate models
go tool gqlgen init
  1. Start the graphql server
go run server.go

More help to get started:

Reporting Issues

If you think you've found a bug, or something isn't behaving the way you think it should, please raise an issue on GitHub.

Contributing

We welcome contributions, Read our Contribution Guidelines to learn more about contributing to gqlgen

Frequently asked questions

How do I prevent fetching child objects that might not be used?

When you have nested or recursive schema like this:

type User {
	id: ID!
	name: String!
	friends: [User!]!
}

You need to tell gqlgen that it should only fetch friends if the user requested it. There are two ways to do this:

Using Custom Models

Write a custom model that omits the friends field:

type User struct {
  ID int
  Name string
}

And reference the model in gqlgen.yml:

# gqlgen.yml
models:
  User:
    model: github.com/you/pkg/model.User # go import path to the User struct above

Using Explicit Resolvers

If you want to keep using the generated model, mark the field as requiring a resolver explicitly in gqlgen.yml like this:

# gqlgen.yml
models:
  User:
    fields:
      friends:
        resolver: true # force a resolver to be generated

After doing either of the above and running generate we will need to provide a resolver for friends:

func (r *userResolver) Friends(ctx context.Context, obj *User) ([]*User, error) {
  // select * from user where friendid = obj.ID
  return friends,  nil
}

You can also use inline config with directives to achieve the same result

directive @goModel(
	model: String
	models: [String!]
) on OBJECT | INPUT_OBJECT | SCALAR | ENUM | INTERFACE | UNION

directive @goField(
	forceResolver: Boolean
	name: String
	omittable: Boolean
	type: String
  autoBindGetterHaser: Boolean
  forceGenerate: Boolean
	batch: Boolean
) on INPUT_FIELD_DEFINITION | FIELD_DEFINITION

type User @goModel(model: "github.com/you/pkg/model.User") {
	id: ID! @goField(name: "todoId")
	friends: [User!]! @goField(forceResolver: true)
	# When omit_resolver_fields is enabled, this field will still be generated in the struct
	data: String! @goField(forceResolver: true, forceGenerate: true)
}

The field resolvers will be executed concurrently in separate goroutines. The degree of concurrency can be customized with the worker_limit configuration attribute.

Can I change the type of the ID from type String to Type Int?

Yes! You can by remapping it in config as seen below:

models:
  ID: # The GraphQL type ID is backed by
    model:
      - github.com/99designs/gqlgen/graphql.IntID # a go integer
      - github.com/99designs/gqlgen/graphql.ID # or a go string
      - github.com/99designs/gqlgen/graphql.UintID # or a go uint

This means gqlgen will be able to automatically bind to strings or ints for models you have written yourself, but the first model in this list is used as the default type and it will always be used when:

There isn't any way around this, gqlgen has no way to know what you want in a given context.

Why do my interfaces have getters? Can I disable these?

These were added in v0.17.14 to allow accessing common interface fields without casting to a concrete type. However, certain fields, like Relay-style Connections, cannot be implemented with simple getters.

If you'd prefer to not have getters generated in your interfaces, you can add the following in your gqlgen.yml:

# gqlgen.yml
omit_getters: true

Other Resources

gqlgen (99designs/gqlgen)

Searching Database…

10.8K ·GitHub
Gqlgen
Что это такое?gqlgen — это библиотека Go для создания серверов GraphQL без большого количества шаблонного кода. Она использует подход «сначала схема» с генерацией кода.
Это фреймворк, который я запускаю, или библиотека, которую я подключаю?Это библиотека Go вместе с генератором кода на основе go generate: вы пишете схему GraphQL и небольшие функции-резолверы, а gqlgen сам генерирует шаблонные модели, интерфейсы резолверов и код выполнения запросов.
Как запустить сервер GraphQL с её помощью?Инициализируйте модуль Go, добавьте github.com/99designs/gqlgen в проект как инструментальную зависимость, выполните шаг gqlgen config/generate, чтобы создать каркас моделей, а затем запустите сгенерированный сервер.
Нужно ли что-то кроме Go, чтобы её использовать?Других зависимостей времени выполнения не указано: достаточно модуля Go и gqlgen, добавленного как инструментальная зависимость. Всё остальное (модели, резолверы) генерируется из вашей собственной схемы.
Есть ли подвох с типизированными ID или вложенными резолверами?Тип ID можно переназначить (например, с String на Int) в конфигурации. Однако первый перечисленный тип всегда используется по умолчанию для сгенерированных моделей и аргументов резолверов, и переопределить его для отдельного контекста нельзя. Вложенные поля загружаются заранее, если только вы не напишете собственную модель или не пометите поле для явного резолвера.
Кому это подойдёт и чем она отличается от других библиотек GraphQL для Go?Библиотека предназначена для разработчиков на Go, которые хотят создавать типобезопасные серверы GraphQL по подходу «сначала схема», а не писать шаблонный код вручную. В README есть ссылка на подробное сравнение с другими реализациями GraphQL для Go для тех, кто выбирает между вариантами.
Как подход «сначала схема» работает на практике, день за днём?Вы описываете API на языке определения схем GraphQL, а gqlgen по нему генерирует соответствующие модели Go и интерфейсы резолверов. Так схема остаётся единственным источником истины.
Можно ли сделать так, чтобы запрос не всегда загружал дочерние объекты?Да. Можно либо написать собственную модель, которая не включает это поле, либо пометить поле в gqlgen.yml как требующее явного резолвера. gqlgen будет вызывать его только тогда, когда поле действительно запрошено.
Резолверы полей выполняются последовательно или параллельно?По умолчанию они выполняются одновременно, в отдельных горутинах. Степень параллелизма можно настроить атрибутом конфигурации workerlimit.
Почему gqlgen избегает map[string]interface{}?Он ставит на первое место типобезопасность, поэтому сгенерированный код использует конкретные структуры и типы Go для вашей схемы вместо нетипизированных словарей. Несоответствия выявляются на этапе компиляции.
What are similar projects?graphql, graphql-code-generator, dataloader, wire, gin-vue-admin, moejs, forge, go-swagger
Which topics is it in?codegen, subscriptions, http-server, graphql, concurrency, code-generation, golang, sdk, backend, go, api, tool
Creator
99designs
Size
27.3 MB
Stars
10.8K
Updated
CommitOct 17Releasev0.17.95Sep 01
Age
8y
Commits · 90 Days