EasyGQL Documentation

# 一、Introduction

本章主要对GraphQL的一些概念和EasyGQL的特点进行介绍

# 1.1 GraphQL

GraphQL是一个用于API的查询语言，也是一个满足你数据查询的运行时。GraphQL 对你的 API 中的数据提供了一套易于理解的完整描述，使得客户端能够准确地获得它需要的数据，而且没有任何冗余，也让 API 更容易地随着时间推移而演进，还能用于构建强大的开发者工具[1，https://graphql.cn/]。它是2012年由Facebook创造的一种用于描述CS架构应用中数据模型的能力和要求的语言，它从产生之初就一直在进行演化，目前已经被各种体量的开发团队使用，比如Facebook、Twitter、github、pinterrest等。

GraphQL具有如下设计原则：

  • 层次分明：今时今日的大部分产品开发都涉及到创建和操作视图层次。为了满足应用结构的层次性，每个GraphQL查询也是层次构建的，每个查询和其数据共用了相同的形状，这样的方式在描述数据需求上更为直观。
  • 以产品为中心：不可置辩的说，GraphQL是一种视图需求驱动的语言，因为主要是前端工程师书写它。GraphQL从前端工程师的思想和需求出发，再开发了语言和运行时库以满足这些需求。
  • 强类型：每个GraphQL服务器都会构建一个针对应用的类型系统，查询语句就在这个类型系统上下文中执行。对于一个查询语句，GraphQL工具可以在执行以前通过类型系统检查这个查询语句的语法正确性和查询有效性，譬如在开发期，服务器就能保证返回值的形状和特性。
  • 客户端定制：通过类型系统，GraphQL向客户端通告了自己那些可以被消费的能力。而客户端则专注于如何消费这些能力，其查询语句的粒度是字段级的。在大多数没有GraphQL的CS模型应用中，不同的服务端用不同的脚本和入口决定了返回的数据。而GraphQL查询则会返回客户端要求的数据，不多不少。
  • 内省：GraphQL是内省的，一个GraphQL服务器的类型系统必须能用GraphQL语言自身来查询，本规范将后文描述此特性。GraphQL的内省特性使之能成为建造通用工具和客户端库的强大平台。

基于这些原则，GraphQL在建造客户端应用的时候就成了强大的生产环境。产品开发者和设计师在高质量工具的支撑下，无需阅读大量文档，只需一点或者无需正式训练就能根据GraphQL服务器建造客户端。当然为了完成这个目的，这些服务器和工具的建造者也必不可少。（注：具体GraphQL介绍参见GraphQL规范）

相比于传统的Restful接口，GraphQL的意义主要体现在以下几个方面。

  • 接口的可重用性。在使用Restful API时，针对不同的查询场景，比如查询一个用户的信息、一个用户的所有博客、一个用户的所有订阅信息时需要使用不同的接口。使用Restful API，可以用一个数据接口方便的满足所有这些查询需求。
  • 数据获取的准确性。在使用Restful API时，我们只能掉固定的接口获取固定格式的数据，这样总是容易获取更多（比实际需要）或少获取数据，很难针对某一次查询设计一个API返回刚刚好的数据。
  • 满足前端快速迭代的需求。在使用Restful API时，前端的快速迭代会给后端开发带来很大的压力。
  • 更方便的后台数据统计，因为GraphQL的使用者，总是请求他们需要的数据，所以后端可以通过分析GraphQL的请求情况，准确的分析各种业务数据的实际价值。
  • 类型系统和格式定义的好处。GraphQL使用强类型系统去定义一个API所提供的服务，所有的类型都事先在GraphQL格式定义中事先约定好了。

# 1.2 EasyGQL

EasyGQL（Easy GraphQL）[github网址：https://easygql.github.io/doc/]是由[Zukdoor][https://zukdoor.cloud]于2020年2月份推出的一款多数据库支持的实时GraphQL 引擎。能够让开发者非常方便的进行GraphQL类型定义，并能够为开发者灵活的提供各种类型的graphql接口。 如图所示：EasyGQL架构 EasyGQL已经集成了信息系统最基本、核心的功能模块：权限管理和数据的CRUD，开发者可以无需开发一行后台代码搭建自己的Web应用。

# 1.2.1 EasyGQL的基本概念

为了方便读者尽快的理解EasyGQL的架构思路和设计理念，现在对文档中涉及的一些名词加以解释

# 1.2.1.1 Schema

在EasyGQL中，一个Schema是一个含对象类型、数据源定义、权限定义、角色定义的集合，不同schema之间是完全独立的，用户通过定义一个完整的Schema,可以完成一个信息系统所有需要持久化的数据对象格式定义，细分系统中不同角色和权限，并且获得一批交互良好的GraphQL接口。

# 1.2.2.2 Object

在EasyGQL中，Object（对象类型）是Schema设计的核心，用户根据自己的业务需要和数据模型，定义一系列Object类型，以及object之间的关系，来完成一个Schema中的Object定义。在理解上，Object可以一定程度上理解为关系型数据库的表，object中的各个字段可以理解为关系型数据库中的各个字段。

# 1.2.2.3 Scalar和ScalarField

在EasyGQL中，标量类型(Scalar)是基础类型，通过定义标量类型字段（ScalarField）来定义对象类型。Object和标量的关系可以理解为java的POJO对象和Java 8种基本类型的关系，一个对象类型的定义需要定义一些标量类型的具体属性和字段。但在EasyGQL种，支持的标量类型不止8种，而且可以持续扩展。

# 1.2.2.4 EnumType、EnumElement和EnumField

在实际的业务场景种，有许多类型的字段值是固定的几个值，例如币种、性别、省份等，针对这些类型的字段，EasyGQL为开发者提供了定义EnumType（枚举类型）的功能，一个枚举类型由多个EnumElement(枚举元素)组成，例如币种类型由美元、人民币、日元等多个元素组成，EnumField是用来在Object对象种定义一个EnumType的字段，例如很多信息系统保存用户信息的时候，都会保存用户的性别类型信息，需要定义一个性别字段。

# 1.2.2.5 RelationType和RelationField

在EasyGQL中，针对对象之间的关联关系，设计了4种关联类型（RelationType）:一对一、一对多、多对一、多对多，在定义Object时，可以定义RelationField字段，这样就可以在不同Object对象之间相互引用。

# 1.2.2.6 User和Role

在使用EasyGQL控制台进行Schema定义时，默认会给定义的Schema增加一个User对象类型和Role枚举类型，User的字段有ID、useranme、password和role，Role这个枚举类型默认的元素有Admin和Guest。

# 1.2.2.7 权限控制

EasyGQL提供基于用户角色的行级和列级的数据权限控制，用户需要分别定义行和列级的权限，默认为所有角色均有权限。

# 1.2.2.8 Trigger

EasyGQL为对象设计了触发器机制，如果用户需要随时知道对象类型的实际数据变化，可以使用Trigger。

# 1.2.2.9 ThirdAPI

ThirdAPI是EasyGQL提供的和纯粹的Object对象增删改查不太一样的接口，比如用户Token校验。开发人员可以通过采用ThirdAPI,快速开发并集成类似邮件发送、短信通知、文件上传等多种丰富功能。

# 1.2.2 EasyGQL的特点

作为一个GraphQL引擎，它具备以下特点：

# 1.2.2.1 多种数据库支持

目前EasyGQL能够支持的数据库类型已经提供支持的数据库类型有RethinkDB、MongoDB、PostgreSQL数据库，未来还将支持MySQL、Cassandra等数据库类型，此外开发者还可以根据自己喜好非常方便地进行开发并支持新的数据库类型。具体见xxx

# 1.2.2.2 全方位API支持

通过EasyGQL框架，开发者可以非常方便地针对各种自定义对象快速生成增删改查接口，并能够为盖对象定义变更订阅接口，当订阅中的结果集中有对象发生变化时。具体见xxx

# 1.2.2.3 方便的关系维护

EasyGQL支持对象间4种关系的定义（1对1、1对多、多对1、多对多），并且针对1对多和1对1的关系类型，可以支持数据对象间的级联删除。具体见xxx

# 1.2.2.4 灵活扩展新功能

通过EasyGQL,开发者可以非常方便的开发新的接口并集成到框架中去，从而丰富EasyGQL的功能。具体见xxx

# 1.2.2.5 快速集成外部接口

在EasyGQL中，开发者可以很方便的定义Trigger的功能，当自定义对象种类出现新增、删除货修改时，Trigger会调用开发者事先定义好的外部接口（Restful API）,从而实现和第三方API的集成。

# 1.2.2.6 外部Schema的整合

在EasyGQL中，开发者可以添加外部Graphql的端点，EasyGQL会自动识别对应graphl端点的所支持的所有数据类型、API，并且自动整合到现有Schema中去。

# 1.2.2.7 灵活的数据访问权限控制

EasyGQL允许开发者在Schema中定义用户的角色，并且针对所有API提供基于角色的访问权限控制，针对自定义对象类型的数据访问API还能够提供基于行级、列级的精确数据访问控制，能够满足一般开发者的大多数使用场景需求。

# 1.2.2.8 便捷的部署方式

ZukDoor团队已经将EasyGQL的运行环境以docker镜像的形式发布在了docker-hub中，您可以非常方便的进行使用。可以通过以下docker compose文件快速试用。

二、查询 →