TangoGraphQL参考手册

2024/8/20

一、概述

TangoGQL的实现主要基于GraphQL这种新兴的api规范，相比于传统B/S架构中使用的REST-api，GraphQL的最大特点在于可以更灵活而精准的获取数据，而REST-api的往返数据皆为服务端固定格式的数据。GraphQL更像一种查询语言，同时支持嵌套和关联查询，可以有效的降低网络负载和带宽，但系统开发也更为复杂。

TangoGQL 的基本工作流程如下图所示：
GQL

首先，web client 向 webserver 发起请求，其HTTP报文中携带的JSON串需要符合GraphQL规范。websever 会将HTTP报文中的JSON串提交给GQLEngine，GQLEngine 对json串进行解析并调用一系列的execute()函数，最后会调用tango中相应操作对应函数来更改数据库中数据以完成操作。

二、安装与示例

2.1 安装

从gitlab拉取源码后，更改CmakeLists的MAKE_ENV，将ClassFactory.cpp等文件中的

1
#include <tango.h> -> #include <tango/tango.h>

随后执行命令

1
cmake -B build -S .

在build目录下执行

1
2
cmake --build .
cmake --install .

build过程中可能会有很多错误，原因都是命名空间的原因，加上 std:: 即可

随后我们进入grapghiql目录，grapghiql是源代码作者给我们提供的测试和开发工具，作为一个 web client 使用 ， 依照其所给README.md 构建即可

2.2 示例

TangoGQL 提供给了我们三种操作，分别是 query、mutation 和 subscription ,对应功能分别为 查询、更改和对事件event的订阅，主要操作对象为device和database，对于tango中绝大部分的内容都支持查询和更改。
以TangoTest设备实例中的ampli为例，进行相应的mutation、query、subscription操作，如下图所示：
GQL
GQL
GQL

三、GraphQL规范以及Tango GraphQL schema简述

GraphQL的通用语法可参考此链接中的内容，以一个简单的Query代码为例做一个简述:

1
2
3
4
5
6
7
8
9
query {
    device(name:"sys/tg_test/1") {
        read_attributes(names:["ampli"]) {
            name
            value
            data_format
        }
    }
}

query即我们的操作名称，每一个GraphQL请求都需要有相应的操作名称；device就是我们的操作对象，()中的内容就是他的属性，其后{}中的read_attributes等是他的次级选择或者说子字段，我们需要查找到最后的value、data_format等叶子字段(即其不含任何其他子字段)才行。更详细的语法请参考上面的链接。

那么GraphQL或者说GQLEngine是如何知道我们有哪些字段或者查询哪些东西才是合法的呢？每一个 GraphQL 服务都会定义一套类型(schema)，用以描述客户可能从那个服务查询到的数据。每当查询到来，服务器就会根据 schema 验证并执行查询。TangoGraphGQL也定义了一套自己的schema，在我们利用graphiql调试时，其侧边栏就有系统中schema的信息，或者可以参考下面这个链接

下面我将利用上面示例代码讲解怎么查看Tango GraphQL schema的内容来写我们想要的代码:

首先我们找到type Query ， 这是我们查询操作的入口，mutation、subscription类似。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Query类型，也是我们查询操作的入口
type Query {

  # __schema 与 __type是每个GraphQL都必须定义的内省类型，不用管
  __schema: __Schema
  __type(name: String!): __Type
   # 实测没有该类型，不用管
  __devnames: [String!]!

  # 设备的相应字段，如果根据name:tango://host:port/domain/family/member找不到相应设备，DeviceRead字段中的error字段会报错
  device(name:String!): DeviceRead!

  # 数据库的字段，默认利用TANGO_HOST进行连接
  database(tangoHost:String = "default"): DatabaseRead!
}

因为我们想要查询的是sys/tg_test/1这个设备下的ampli属性，因此我们选择device字段，然后我们去找到其次级选择字段类型DeviceRead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 对设备进行查询的对象
type DeviceRead {

  # Device name
  name: String!

  # 读取attributes，name属性填写想要查询的attributes名字，!代表非空，[]代表数组，即可以同时查询多个。失败会返回null
  read_attributes(names:[String!]!) : [DeviceAttribute!]

  # 读取attribute polling的历史记录，失败会返回null
  read_attribute_hist(name:String!,depth:Int!) : [DeviceAttribute!]

  # 读取 attribute list. 失败会返回null
  attribute_list: [String!]

  # 读取 attribute properties. 失败会返回null ，可以使用names:["*"]来获取所有attributes的attribute properties
  attribute_info(names:[String!] = ["*"]) : [AttributeInfo!]

  # Get command list. Returns null when fails. 与上面的类似
  command_list: [String!]
  command_info(names:[String!] = ["*"]) : [CommandInfo!]

  # 成功返回null，否则为error string，默认只返回顶级堆栈中的错误信息
  error(getStack:Boolean = false): [String]
}

DeviceRead类型中我们可以看到read_attributes这个字段，其注释也告诉我们是用于读取attributes的，由于其还不是叶子字段，我们还需要查找DeviceAttribute这个字段

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 设备Attribute的一些叶子字段
type DeviceAttribute {
  # Attribute name
  name: String!
  # Attribute quality factor (ATTR_ERROR when reading fails)
  quality: String!
  # 读value，失败返回null，默认 DevEnum and DevState 以整数形式返回，使用 resolveEnum:true返回string
  value(resolveEnum:Boolean = false): ScalarTypes
  # 写入值，如果不可写则为空
  write_value(resolveEnum:Boolean = false): ScalarTypes
  timestamp(formatAsDate:Boolean = false): ScalarTypes!
  dim_x: Int
  dim_y: Int
  w_dim_x: Int
  w_dim_y: Int
  # Data type (DevBoolean,DevShort, ...)
  data_type: String
  # Data format (SCALAR, SPECTRUM, IMAGE)
  data_format: String
  encoded_format: String
  error(getStack:Boolean = false): [String]
}

DeviceAttribute中这些叶子字段就是我们可以查询的一些信息，例如ampli的value值等

上面的三个type就覆盖了我们示例代码中所需要的全部类型，根据不同的组合就可以产生许多不同的我们需要的代码，mutation和subscribe操作类似，从根类型即type Mutation或者Type Subscription出发找即可。在这个过程中，使用graphiql会更加方便快捷，它支持type类型的快速跳转查阅。