101 lines
3.5 KiB
Markdown
101 lines
3.5 KiB
Markdown
# graphql-go [](https://sourcegraph.com/github.com/graph-gophers/graphql-go?badge) [](https://semaphoreci.com/graph-gophers/graphql-go) [](https://godoc.org/github.com/graph-gophers/graphql-go)
|
|
|
|
<p align="center"><img src="docs/img/logo.png" width="300"></p>
|
|
|
|
The goal of this project is to provide full support of the [GraphQL draft specification](https://facebook.github.io/graphql/draft) with a set of idiomatic, easy to use Go packages.
|
|
|
|
While still under heavy development (`internal` APIs are almost certainly subject to change), this library is
|
|
safe for production use.
|
|
|
|
## Features
|
|
|
|
- minimal API
|
|
- support for `context.Context`
|
|
- support for the `OpenTracing` standard
|
|
- schema type-checking against resolvers
|
|
- resolvers are matched to the schema based on method sets (can resolve a GraphQL schema with a Go interface or Go struct).
|
|
- handles panics in resolvers
|
|
- parallel execution of resolvers
|
|
|
|
## Roadmap
|
|
|
|
We're trying out the GitHub Project feature to manage `graphql-go`'s [development roadmap](https://github.com/graph-gophers/graphql-go/projects/1).
|
|
Feedback is welcome and appreciated.
|
|
|
|
## (Some) Documentation
|
|
|
|
### Basic Sample
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"log"
|
|
"net/http"
|
|
|
|
graphql "github.com/graph-gophers/graphql-go"
|
|
"github.com/graph-gophers/graphql-go/relay"
|
|
)
|
|
|
|
type query struct{}
|
|
|
|
func (_ *query) Hello() string { return "Hello, world!" }
|
|
|
|
func main() {
|
|
s := `
|
|
schema {
|
|
query: Query
|
|
}
|
|
type Query {
|
|
hello: String!
|
|
}
|
|
`
|
|
schema := graphql.MustParseSchema(s, &query{})
|
|
http.Handle("/query", &relay.Handler{Schema: schema})
|
|
log.Fatal(http.ListenAndServe(":8080", nil))
|
|
}
|
|
```
|
|
|
|
To test:
|
|
```sh
|
|
$ curl -XPOST -d '{"query": "{ hello }"}' localhost:8080/query
|
|
```
|
|
|
|
### Resolvers
|
|
|
|
A resolver must have one method for each field of the GraphQL type it resolves. The method name has to be [exported](https://golang.org/ref/spec#Exported_identifiers) and match the field's name in a non-case-sensitive way.
|
|
|
|
The method has up to two arguments:
|
|
|
|
- Optional `context.Context` argument.
|
|
- Mandatory `*struct { ... }` argument if the corresponding GraphQL field has arguments. The names of the struct fields have to be [exported](https://golang.org/ref/spec#Exported_identifiers) and have to match the names of the GraphQL arguments in a non-case-sensitive way.
|
|
|
|
The method has up to two results:
|
|
|
|
- The GraphQL field's value as determined by the resolver.
|
|
- Optional `error` result.
|
|
|
|
Example for a simple resolver method:
|
|
|
|
```go
|
|
func (r *helloWorldResolver) Hello() string {
|
|
return "Hello world!"
|
|
}
|
|
```
|
|
|
|
The following signature is also allowed:
|
|
|
|
```go
|
|
func (r *helloWorldResolver) Hello(ctx context.Context) (string, error) {
|
|
return "Hello world!", nil
|
|
}
|
|
```
|
|
|
|
### Community Examples
|
|
|
|
[tonyghita/graphql-go-example](https://github.com/tonyghita/graphql-go-example) - A more "productionized" version of the Star Wars API example given in this repository.
|
|
|
|
[deltaskelta/graphql-go-pets-example](https://github.com/deltaskelta/graphql-go-pets-example) - graphql-go resolving against a sqlite database
|
|
|
|
[OscarYuen/go-graphql-starter](https://github.com/OscarYuen/go-graphql-starter) - a starter application integrated with dataloader, psql and basic authentication
|