99designs/gqlgen
GitHub: 99designs/gqlgen
一个基于 Go 代码生成的 GraphQL 服务端库，通过 Schema 优先的方式帮助开发者快速构建类型安全的 GraphQL API。
Stars: 10738 | Forks: 1250
# gqlgen [](https://github.com/99designs/gqlgen/actions) [](https://coveralls.io/github/99designs/gqlgen?branch=master) [](https://goreportcard.com/report/github.com/99designs/gqlgen) [](https://pkg.go.dev/github.com/99designs/gqlgen) [](http://gqlgen.com/)
## 什么是 gqlgen？
[gqlgen](https://github.com/99designs/gqlgen) 是一个用于轻松构建 GraphQL 服务器的 Go 库。
- **gqlgen 基于Schema 优先的方法** — 你可以使用 GraphQL [Schema Definition Language](http://graphql.org/learn/schema/) 来定义你的 API。 - **gqlgen 优先考虑类型安全** — 在这里你永远不会看到 `map[string]interface{}`。 - **gqlgen 实现了代码生成** — 我们会生成那些枯燥的代码，这样你就可以专注于快速构建你的应用。 仍然不太确信是否要使用 **gqlgen**？可以将 **gqlgen** 与其他 Go graphql [实现](https://gqlgen.com/feature-comparison/)进行比较。 ## 快速开始 1. [初始化一个新的 go module](https://golang.org/doc/tutorial/create-module) ``` mkdir example cd example go mod init example ``` 2. 将 `github.com/99designs/gqlgen` 作为[工具依赖](https://go.dev/doc/modules/managing-dependencies#tools)添加到你的项目中 ``` go get -tool github.com/99designs/gqlgen ``` 3. 初始化 gqlgen 配置并生成模型 ``` go tool gqlgen init ``` 4. 启动 graphql 服务器 ``` go run server.go ``` 更多入门帮助： - [入门教程](https://gqlgen.com/getting-started/) - 帮助你入门的全面指南 - [真实案例](https://github.com/99designs/gqlgen/tree/master/_examples) 展示了如何创建 GraphQL 应用 - API 的[参考文档](https://pkg.go.dev/github.com/99designs/gqlgen) ## 报告问题 如果你认为自己发现了一个 bug，或者某些功能的运行方式与你的预期不符，请在 GitHub 上提出一个 [issue](https://github.com/99designs/gqlgen/issues)。 ## 常见问题 ### 如何防止获取可能不会被使用的子对象？ 当你遇到像这样的嵌套或递归 schema 时： ``` type User { id: ID! name: String! friends: [User!]! } ``` 你需要告诉 gqlgen 只有在用户请求时才获取 friends。有两种方法可以做到这一点： ### 使用自定义模型 编写一个省略了 friends 字段的自定义模型： ``` type User struct { ID int Name string } ``` 并在 `gqlgen.yml` 中引用该模型： ``` # gqlgen.yml models: User: model: github.com/you/pkg/model.User # go import path to the User struct above ``` ### 使用显式 Resolvers 如果你想继续使用生成的模型，可以在 `gqlgen.yml` 中将该字段显式标记为需要 resolver，如下所示： ``` # gqlgen.yml models: User: fields: friends: resolver: true # force a resolver to be generated ``` 在完成上述任一操作并运行生成后，我们需要为 friends 提供一个 resolver： ``` func (r *userResolver) Friends(ctx context.Context, obj *User) ([]*User, error) { // select * from user where friendid = obj.ID return friends, nil } ``` 你还可以使用带有指令的内联配置来实现相同的结果 ``` 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) } ``` 字段 resolver 将在不同的 goroutine 中并发执行。可以通过 [`worker_limit` 配置属性](https://gqlgen.com/config/)来自定义并发度。 ### 我可以将 ID 的类型从 String 类型更改为 Int 类型吗？ 可以！你可以通过在配置中重新映射它来实现，如下所示： ``` 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 ``` 这意味着 gqlgen 能够自动为你自己编写的模型绑定到字符串或整数，但是 此列表中的第一个模型会被用作默认类型，并且在以下情况总是会使用它： - 基于 schema 生成模型时 - 作为 resolver 中的参数时 这没有任何变通的方法，gqlgen 无法知道你在特定上下文中想要什么。 ### 为什么我的接口有 getter？我可以禁用它们吗？ 这些是在 v0.17.14 版本中添加的，允许在不强制转换为具体类型的情况下访问公共接口字段。 然而，某些字段（例如 Relay 风格的 Connections）无法通过简单的 getter 来实现。 如果你不希望生成的接口中包含 getter，可以在你的 `gqlgen.yml` 中添加以下内容： ``` # gqlgen.yml omit_getters: true ``` ## 其他资源 - [Christopher Biscardi @ Gophercon UK 2018](https://youtu.be/FdURVezcdcw) - [介绍 gqlgen：一个用于 Go 的 GraphQL 服务器生成器](https://99designs.com.au/blog/engineering/gqlgen-a-graphql-server-generator-for-go/) - [由 Iván Corrales Solera 编写的 Dive into GraphQL](https://medium.com/@ivan.corrales.solera/dive-into-graphql-9bfedf22e1a) - [由 Oleg Shalygin 编写的基于 gqlgen 和 Postgres 的示例项目](https://github.com/oshalygin/gqlgen-pg-todo-example) - [由 Shayegan Hooshyari 编写的带有 gqlgen 的 Hackernews GraphQL 服务器](https://www.howtographql.com/graphql-go/0-introduction/)
- **gqlgen 基于Schema 优先的方法** — 你可以使用 GraphQL [Schema Definition Language](http://graphql.org/learn/schema/) 来定义你的 API。 - **gqlgen 优先考虑类型安全** — 在这里你永远不会看到 `map[string]interface{}`。 - **gqlgen 实现了代码生成** — 我们会生成那些枯燥的代码，这样你就可以专注于快速构建你的应用。 仍然不太确信是否要使用 **gqlgen**？可以将 **gqlgen** 与其他 Go graphql [实现](https://gqlgen.com/feature-comparison/)进行比较。 ## 快速开始 1. [初始化一个新的 go module](https://golang.org/doc/tutorial/create-module) ``` mkdir example cd example go mod init example ``` 2. 将 `github.com/99designs/gqlgen` 作为[工具依赖](https://go.dev/doc/modules/managing-dependencies#tools)添加到你的项目中 ``` go get -tool github.com/99designs/gqlgen ``` 3. 初始化 gqlgen 配置并生成模型 ``` go tool gqlgen init ``` 4. 启动 graphql 服务器 ``` go run server.go ``` 更多入门帮助： - [入门教程](https://gqlgen.com/getting-started/) - 帮助你入门的全面指南 - [真实案例](https://github.com/99designs/gqlgen/tree/master/_examples) 展示了如何创建 GraphQL 应用 - API 的[参考文档](https://pkg.go.dev/github.com/99designs/gqlgen) ## 报告问题 如果你认为自己发现了一个 bug，或者某些功能的运行方式与你的预期不符，请在 GitHub 上提出一个 [issue](https://github.com/99designs/gqlgen/issues)。 ## 常见问题 ### 如何防止获取可能不会被使用的子对象？ 当你遇到像这样的嵌套或递归 schema 时： ``` type User { id: ID! name: String! friends: [User!]! } ``` 你需要告诉 gqlgen 只有在用户请求时才获取 friends。有两种方法可以做到这一点： ### 使用自定义模型 编写一个省略了 friends 字段的自定义模型： ``` type User struct { ID int Name string } ``` 并在 `gqlgen.yml` 中引用该模型： ``` # gqlgen.yml models: User: model: github.com/you/pkg/model.User # go import path to the User struct above ``` ### 使用显式 Resolvers 如果你想继续使用生成的模型，可以在 `gqlgen.yml` 中将该字段显式标记为需要 resolver，如下所示： ``` # gqlgen.yml models: User: fields: friends: resolver: true # force a resolver to be generated ``` 在完成上述任一操作并运行生成后，我们需要为 friends 提供一个 resolver： ``` func (r *userResolver) Friends(ctx context.Context, obj *User) ([]*User, error) { // select * from user where friendid = obj.ID return friends, nil } ``` 你还可以使用带有指令的内联配置来实现相同的结果 ``` 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) } ``` 字段 resolver 将在不同的 goroutine 中并发执行。可以通过 [`worker_limit` 配置属性](https://gqlgen.com/config/)来自定义并发度。 ### 我可以将 ID 的类型从 String 类型更改为 Int 类型吗？ 可以！你可以通过在配置中重新映射它来实现，如下所示： ``` 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 ``` 这意味着 gqlgen 能够自动为你自己编写的模型绑定到字符串或整数，但是 此列表中的第一个模型会被用作默认类型，并且在以下情况总是会使用它： - 基于 schema 生成模型时 - 作为 resolver 中的参数时 这没有任何变通的方法，gqlgen 无法知道你在特定上下文中想要什么。 ### 为什么我的接口有 getter？我可以禁用它们吗？ 这些是在 v0.17.14 版本中添加的，允许在不强制转换为具体类型的情况下访问公共接口字段。 然而，某些字段（例如 Relay 风格的 Connections）无法通过简单的 getter 来实现。 如果你不希望生成的接口中包含 getter，可以在你的 `gqlgen.yml` 中添加以下内容： ``` # gqlgen.yml omit_getters: true ``` ## 其他资源 - [Christopher Biscardi @ Gophercon UK 2018](https://youtu.be/FdURVezcdcw) - [介绍 gqlgen：一个用于 Go 的 GraphQL 服务器生成器](https://99designs.com.au/blog/engineering/gqlgen-a-graphql-server-generator-for-go/) - [由 Iván Corrales Solera 编写的 Dive into GraphQL](https://medium.com/@ivan.corrales.solera/dive-into-graphql-9bfedf22e1a) - [由 Oleg Shalygin 编写的基于 gqlgen 和 Postgres 的示例项目](https://github.com/oshalygin/gqlgen-pg-todo-example) - [由 Shayegan Hooshyari 编写的带有 gqlgen 的 Hackernews GraphQL 服务器](https://www.howtographql.com/graphql-go/0-introduction/)
标签：EVTX分析, 日志审计