Go语言的GraphQL实践总结

小咪咪 2022-05-27 07:19 375阅读 0赞

## 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解析同上

概括总结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][]实现的用户管理的例子，包括获取全部用户信息、获取指定用户信息、修改用户名称、删除用户的功能，以及如何创建枚举类型的功能，[完整代码在这里][Link 1]。

#### 生成后的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调试工具 ####

![这里写图片描述][70]

笔者初次接触GraphQL，可能很多理解有误，欢迎指出。

## 参考资料 ##

*  [GraphQL官网中文版][GraphQL]
 *  [30分钟理解GraphQL核心概念][30_GraphQL]
 *  [GitHub为什么开放一套GraphQL版本的API？][GitHub_GraphQL_API]
 *  [GraphQL入门][GraphQL 1]
 *  [在GraphQL中建模一个博客索引][GraphQL 2]

[prisma]: https://www.prisma.io/docs/
[graphql-go]: https://github.com/graphql-go/graphql
[Link 1]: https://github.com/darker11/graphql
[graphq-cli]: https://github.com/graphql-cli/graphql-cli
[70]: /images/20220527/ef9180dedaba41ccb13c12767bffc3f6.png
[GraphQL]: http://graphql.cn/
[30_GraphQL]: https://juejin.im/post/5ac1b03bf265da237b223e82
[GitHub_GraphQL_API]: https://laravel-china.org/topics/3112/why-did-github-open-a-graphql-version-of-api
[GraphQL 1]: http://www.cnblogs.com/sunshine-anycall/p/6357577.html
[GraphQL 2]: https://linux.cn/article-8524-1.html