Go语言的GraphQL实践总结
GraphQL背景
REST API的使用方式是，server定义一系列的接口，client调用自己需要的接口，获取目标数据进行整合。REST API开发中遇到的问题：
- 扩展性 ，随着API的不断发展，REST API的接口会变得越来臃肿。
- 无法按需获取 ，一个返回id, name, age, city, addr, email的接口，如果仅获取部分信息，如name, age，却必须返回接口的全部信息，然后从中提取自己需要的。坏处不仅会增加网络传输量，并且不便于client处理数据
- 一个请求无法获取所需全部资源 ，例如client需要显示一篇文章的内容，同时要显示评论，作者信息，那么就需要调用文章、评论、用户的接口。坏处造成服务的的维护困难，以及响应时间变长 。
- 原因： REST API通常由多个端点组成，每个端点代表一种资源。所以，当client需要多个资源是，它需要向REST API发起多个请求，才能获取到所需要的数据。
- REST API不好处理的问题 ， 比如确保client提供的参数是类型安全的，如何从代码生成API的文档等。
GraphQL解决的问题：
- 请求你的数据不多不少 ：GraphQL查询总是能准确获得你想要的数据，不多不少，所以返回的结果是可预测的。
- 获取多个资源只用一个请求 ：GraphQL查询不仅能够获得资源的属性，还能沿着资源间进一步查询，所以GraphQL可以通过一次请求就获取你应用所需的所有数据。
- 描述所有的可能类型系统： GraphQL API基于类型和字段的方式进行组成，使用类型来保证应用只请求可能的类型，同时提供了清晰的辅助性错误信息。
- 使用你现有的数据和代码： GraphQL让你的整个应用共享一套API，通过GraphQL API能够更好的利用你的现有数据和代码。GraphQL 引擎已经有多种语言实现，GraphQL不限于某一特定数据库，可以使用已经存在的数据、代码、甚至可以连接第三方的APIs。
- API 演进无需划分版本： 给GraphQL API添加字段和类型而无需影响现有查询。老旧字段可以废弃，从工具中隐藏。
什么是GraphQL
GraphQL官网给出定义：GraphQL既是一种用于API的查询语言 也是一个满足你数据查询的运行时 。GraphQL对你的API中的数据提供了一套易于理解的完整描述 ，使得客户端能够准确地获得它需要的数据 ，而且没有任何冗余，也让API更容易地随着时间推移而演进，还能用于构建强大的开发者工具。
- API不是用来调用的吗？是的，者正是GraphQL的强大之处，引用官方文档的一句话
ask exactly what you want - 本质上来说GraphQL是一种查询语言
- 上述的定义其实很难理解，只有真的使用过GraphQL才能够理解。
在GraphQL中，通过定义一张Schema和声明一些Type来达到上述描述的功能，需要学习：
- 对于数据模型的抽象是通过Type来描述的 ，如何定义Type？
- 对于接口获取数据的逻辑是通过schema来描述的 ，如何定义schema？
如何定义Type
对于数据模型的抽象是通过Type来描述的，每一个Type有若干Field组成，每个Field又分别指向某个Type。
GraphQL的Type简单可以分为两种，一种是scalar type（标量类型） ，另一种是object type（对象类型）。
scalar type
GraphQL中的内建的标量包含，String、Int、Float、Boolean、Enum，除此之外，GraphQL中可以通过scalar声明一个新的标量 ，比如：
- prisma ——一个使用GraphQL来抽象数据库操作的库中，还有DataTime（日期格式）和主键（ID）。
- 在使用GraphQL实现文件上传接口时，需要声明一个Upload标量来代表要上传的文件。
- 标量是GraphQL类型系统中最小的颗粒。
object type
仅有标量是不够抽象一些复杂的数据模型，这时需要使用对象类型。通过对象类型来构建GraphQL中关于一个数据模型的形状，同时还可以声明各个模型之间的内在关联（一对多，一对一或多对多）。
一对一模型
type Article {
id: ID
text: String
isPublished: Boolean
author: User
}上述代码，声明了一个Article类型，它有3个Field，分别是id（ID类型）、text（String类型）、isPublished（Boolean类型）以及author（新建的对象类型User），User类型的声明如下：
type User {
id: ID
name: String
}lType Modifier
类型修饰符，当前的类型修饰符有两种，分别是List和Required ，语法分别为[Type]和[Type!]，两者可以组合：
- [Type]! ：列表本身为必填项，但内部元素可以为空
- [Type!] ：列表本身可以为空，但是其内部元素为必填
- [Type!]! ：列表本身和内部元素均为必填
如何定义Schema
schema用来描述对于接口获取数据逻辑 ，GraphQL中使用Query来抽象数据的查询逻辑，分为三种，分别是query（查询）、mutation（更改）、subscription（订阅） 。API的接口概括起来有CRUD（创建、获取、更改、删除）四类，query可以覆盖R（获取）的功能，mutation可以覆盖（CUD创建、更改、删除）的功能。
注意： Query特指GraphQL中的查询（包含三种类型），query指GraphQL中的查询类型（仅指查询类型）。
Query
- query（查询）：当获取数据时，选择query类型
- mutation（更改）： 当尝试修改数据时，选择mutation类型
- subscription（订阅）：当希望数据更改时，可以进行消息推送，使用subscription类型（针对当前的日趋流行的real-time应用提出的）。
以Article为数据模型，分别以REST和GraphQL的角度，编写CURD的接口
Rest接口
- GET /api/v1/articles/
- GET /api/v1/article/:id/
- POST /api/v1/article/
- DELETE /api/v1/article/:id/
- PATCH /api/v1/article/:id/
GraphQL Query
- query类型
query {
articles():[Article!]!
article(id: Int!): Article!
} - mutation类型
mutation {
createArticle(): Article!
updateArticle(id: Int): Article!
deleteArticle(id: Int): Article!
}
注意：
GraphQL是按照类型来划分职能的query、mutation、ssubscription，同时必须明确声明返回的数据类型。
如果实际应用中对于评论列表有real-time 的需求，该如何处理？
在REST中，可以通过长连接，或者通过提供一些带验证的获取长连接URL的接口，比如
POST /api/v1/messages/之后长连接会将新的数据进行实时推送。在GraphQL中，会以更加声明式的方式进行声明，如下：
subscription { updatedArticle() { mutation node { comments: [Comment!]! } } }此处声明了一个subscription，这个subscription会在有新的Article被创建或者更新时，推送新的数据对象。实际上内部仍然是建立于长连接之上 。
Resolve
上述的描述并未说明如何返回相关操作（query、mutation、subscription）的数据逻辑。所有此处引入一个更核心的概念Resolve(解析函数)
GraphQL中，默认有这样的约定，Query（包括query、mutation、subscription）和与之对应的Resolve是同名的，比如关于
articles(): [Articles!]!这个query，它的Resolve的名字必然叫做articles以已经声明的articles的query为例，解释下GraphQL的内部工作机制：
Query { articles { id author { name } comments { id desc author } } }按照如下步骤进行解析：
- 首先进行第一次解析，当前的类型是query 类型，同时Resolver的名字为articles。
- 之后会尝试使用articles的Resolver获取解析数据，第一层解析完毕
- 之后对第一层解析的返回值，进行第二层解析，当前articles包含三个子query ，分别是id、author和comments
- id在Author类型中为标量类型，解析结束
- author在articles类型中为对象类型User，尝试使用User的Resolver获取数据，当前field解析完毕。
- 之后对第二层解析的返回值，进行第三层解析，当前author还包含一个query，name是标量类型，解析结束
- comments解析同上
- query类型
概括总结GraphQL大体解析流程就是遇见一个Query之后，尝试使用它的Resolver取值，之后再对返回值进行解析，这个过程是递归的，直到所有解析Field类型是Scalar Type（标量类型）为止。整个解析过程可以想象为一个很长的Resolver Chain（解析链）。
Resolver本身的声明在各个语言中是不同的，它代表数据获取的具体逻辑。它的函数签名（以golang为例）：
func(p graphql.ResolveParams) (interface{}, error) {}
// ResolveParams Params for FieldResolveFn()
type ResolveParams struct {
// Source is the source value
Source interface{}
// Args is a map of arguments for current GraphQL request
Args map[string]interface{}
// Info is a collection of information about the current execution state.
Info ResolveInfo
// Context argument is a context value that is provided to every resolve function within an execution.
// It is commonly
// used to represent an authenticated user, or request-specific caches.
Context context.Context
}值得注意的是，Resolver内部实现对于GraphQL完全是黑盒状态。这意味着Resolver如何返回数据、返回什么样的数据、从哪里返回数据，完全取决于Resolver本身。GraphQL在实际使用中常常作为中间层来使用，**数据的获取通过Resolver来封装，内部数据获取的实现可能基于RPC、REST、WS、SQL等多种不同的方式。
GraphQL例子
下面这部分将会展示一个用graphql-go实现的用户管理的例子，包括获取全部用户信息、获取指定用户信息、修改用户名称、删除用户的功能，以及如何创建枚举类型的功能，完整代码在这里。
生成后的schema文件内容如下：
type Mutation {
"""[用户管理] 修改用户名称"""
changeUserName(
"""用户ID"""
userId: Int!
"""用户名称"""
userName: String!
): Boolean
"""[用户管理] 创建用户"""
createUser(
"""用户名称"""
userName: String!
"""用户邮箱"""
email: String!
"""用户密码"""
pwd: String!
"""用户联系方式"""
phone: Int
): Boolean
"""[用户管理] 删除用户"""
deleteUser(
"""用户ID"""
userId: Int!
): Boolean
}
type Query {
"""[用户管理] 获取指定用户的信息"""
UserInfo(
"""用户ID"""
userId: Int!
): userInfo
"""[用户管理] 获取全部用户的信息"""
UserListInfo: [userInfo]!
}
"""用户信息描述"""
type userInfo {
"""用户email"""
email: String
"""用户名称"""
name: String
"""用户手机号"""
phone: Int
"""用户密码"""
pwd: String
"""用户状态"""
status: UserStatusEnum
"""用户ID"""
userID: Int
}
"""用户状态信息"""
enum UserStatusEnum {
"""用户可用"""
EnableUser
"""用户不可用"""
DisableUser
}
注意
- GraphQL基于golang实现的例子比较少
- GraphQL的schema可以自动生成，具体操作可查看graphq-cli文档，步骤大致包括npm包的安装、graphql-cli工具的安装，配置文件的更改（此处需要指定服务对外暴露的地址） ，执行
graphql get-schema命令。
GraphQL API以及Rsolve函数定义
type UserInfo struct {
UserID uint64 `json:"userID"`
Name string `json:"name"`
Email string `json:"email"`
Phone int64 `json:"phone"`
Pwd string `json:"pwd"`
Status model.UserStatusType `json:"status"`
}
//这段内容是如何使用GraphQL定义枚举类型
var UserStatusEnumType = graphql.NewEnum(graphql.EnumConfig{
Name: "UserStatusEnum",
Description: "用户状态信息",
Values: graphql.EnumValueConfigMap{
"EnableUser": &graphql.EnumValueConfig{
Value: model.EnableStatus,
Description: "用户可用",
},
"DisableUser": &graphql.EnumValueConfig{
Value: model.DisableStatus,
Description: "用户不可用",
},
},
})
var UserInfoType = graphql.NewObject(graphql.ObjectConfig{
Name: "userInfo",
Description: "用户信息描述",
Fields: graphql.Fields{
"userID": &graphql.Field{
Description: "用户ID",
Type: graphql.Int,
},
"name": &graphql.Field{
Description: "用户名称",
Type: graphql.String,
},
"email": &graphql.Field{
Description: "用户email",
Type: graphql.String,
},
"phone": &graphql.Field{
Description: "用户手机号",
Type: graphql.Int,
},
"pwd": &graphql.Field{
Description: "用户密码",
Type: graphql.String,
},
"status": &graphql.Field{
Description: "用户状态",
Type: UserStatusEnumType,
},
},
})query与mutation的定义
var MutationType = graphql.NewObject(graphql.ObjectConfig{
Name: "Mutation",
Fields: graphql.Fields{
"createUser": &graphql.Field{
Type: graphql.Boolean,
Description: "[用户管理] 创建用户",
Args: graphql.FieldConfigArgument{
"userName": &graphql.ArgumentConfig{
Description: "用户名称",
Type: graphql.NewNonNull(graphql.String),
},
"email": &graphql.ArgumentConfig{
Description: "用户邮箱",
Type: graphql.NewNonNull(graphql.String),
},
"pwd": &graphql.ArgumentConfig{
Description: "用户密码",
Type: graphql.NewNonNull(graphql.String),
},
"phone": &graphql.ArgumentConfig{
Description: "用户联系方式",
Type: graphql.Int,
},
},
Resolve: func(p graphql.ResolveParams) (interface{}, error) {
userId, _ := strconv.Atoi(GenerateID())
user := &model.User{
//展示如何解析传入的参数
Name: p.Args["userName"].(string),
Email: sql.NullString{
String: p.Args["email"].(string),
Valid: true,
},
Pwd: p.Args["pwd"].(string),
Phone: int64(p.Args["phone"].(int)),
UserID: uint64(userId),
Status: int64(model.EnableStatus),
}
if err := model.InsertUser(user); err != nil {
log.WithError(err).Error("[mutaition.createUser] invoke InserUser() failed")
return false, err
}
return true, nil
},
},
},
})
var QueryType = graphql.NewObject(graphql.ObjectConfig{
Name: "Query",
Fields: graphql.Fields{
"UserListInfo": &graphql.Field{
Description: "[用户管理] 获取指定用户的信息",
//定义了非空的list类型
Type: graphql.NewNonNull(graphql.NewList(UserInfoType)),
Resolve: func(p graphql.ResolveParams) (interface{}, error) {
users, err := model.GetUsers()
if err != nil {
log.WithError(err).Error("[query.UserInfo] invoke InserUser() failed")
return false, err
}
usersList := make([]*UserInfo, 0)
for _, v := range users {
userInfo := new(UserInfo)
userInfo.Name = v.Name
userInfo.Email = v.Email.String
userInfo.Phone = v.Phone
userInfo.Pwd = v.Pwd
userInfo.Status = model.UserStatusType(v.Status)
usersList = append(usersList, userInfo)
}
return usersList, nil
},
},
},
})
注意：
- 此处仅展示了部分例子
- 此处笔者仅列举了query、mutation类型的定义
如何定义服务main函数
type ServerCfg struct {
Addr string
MysqlAddr string
}
func main() {
//load config info
m := multiconfig.NewWithPath("config.toml")
svrCfg := new(ServerCfg)
m.MustLoad(svrCfg)
//new graphql schema
schema, err := graphql.NewSchema(
graphql.SchemaConfig{
Query: object.QueryType,
Mutation: object.MutationType,
},
)
if err != nil {
log.WithError(err).Error("[main] invoke graphql.NewSchema() failed")
return
}
model.InitSqlxClient(svrCfg.MysqlAddr)
h := handler.New(&handler.Config{
Schema: &schema,
Pretty: true,
GraphiQL: true,
})
http.HandleFunc("/graphql", func(w http.ResponseWriter, r *http.Request) {
ctx := context.Background()
//read user_id from gateway
userIDStr := r.Header.Get("user_id")
if len(userIDStr) > 0 {
userID, err := strconv.Atoi(userIDStr)
if err != nil {
w.WriteHeader(http.StatusBadRequest)
w.Write([]byte(err.Error()))
return
}
ctx = context.WithValue(ctx, "ContextUserIDKey", userID)
}
h.ContextHandler(ctx, w, r)
})
log.Fatal(http.ListenAndServe(svrCfg.Addr, nil))
}
展示下GraphQL自带的GraphiQL调试工具
笔者初次接触GraphQL，可能很多理解有误，欢迎指出。
参考资料
- GraphQL官网中文版
- 30分钟理解GraphQL核心概念
- GitHub为什么开放一套GraphQL版本的API？
- GraphQL入门
- 在GraphQL中建模一个博客索引