如何 build NebulaGraph？如何为 NebulaGraph 内核做贡献？从本章作为切入点就够了。

新手也能分分钟搞定：NebulaGraph 内核贡献开发指南


![GitHub 自动合并 pr 的机器人——auto-merge-bot](https://www-cdn.nebula-graph.com.cn/nebula-blog/auto-merge-bot.jpg)

# 背景

作为一款开源的分布式图数据库产品，Nebula 所有的研发流程都在 GitHub 上运作。基于 GitHub 生态 Nebula 技术团队有一套 pr 的自动化流程：每次 pr 提上来的时候， pull request bot 跑一遍测试，看看这个 pr merge 到主分支以后是否可以保证当前的一些功能还可以继续正常运行。

这时候，问题出现了：每个 pr 上来一次都要跑一遍测试，这样的操作既费时又对测试机造成不必要的消耗。于是，Nebula 研发团队打算演变现有的 pr 合并机器人。

本文主要讲述如何在原先的设定下，优化设计，从而节省测试资源。

# 设计思路

基于现有 bot 的实现思路，来开发一款新的 bot 优化 pr 合并。新的 bot 主要特点是，利用 github action 提供的 on schedule 功能，在每隔一段时间后可以自动执行所有 pull request 合并后的测试，这样一来就不需要每个 pull request 都跑一次 CI，节省了时间和性能消耗。若测试失败，则用随机剔除的方案剔除其中某个 pull request 然后继续执行测试，直到测试通过或者没用可用的 pull request 为止。随后将此次测试通过中的包含的 pull request merge 到主分支中，并且提供发送此次 merge 信息到钉钉群里的功能。

假设用户有一个新的 pull request 提上来，它的一生需要经历：

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/auto-merge-workflow.png) 

1. pull request 被 reviewers approve
2. Repository maintainer 评论/merge，表明同意 merge
3. 完成 1，2 后， pull request 就会被 bot 识别为可 merge 的 pull request
4. bot 将所有标为可 merge 的 pull request 预加载到 runner 的本地基于 master 的分支中进行 ci 测试
5. 测试通过，pull request 被 merge 到主分支；测试失败，bot 会随机剔除现有包含的 pull request，再进行测试，直到测试通过或者没有可用的分支为止。
6. （可选）bot 将本次 merge 的结果发送到钉钉群中

需要注意：

* 使用 auto-merge-bot 时，repository 需要在 GitHub orgnization 中配置一个 team，这个 team 里的部分 member 的 role 需被标识为 maintainer，对应上述步骤2。

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/auto-merge-team.png) 

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/auto-merge-maintainer.png) 

* maintainer 可以通过评论 / merge 表示同意 merge 该 pull request，也可以通过评论 / wait a minute 或者删除评论取消 merge，但是目前如果 bot 已经在运行中，只能通过手动停止此次 bot 的 workflow 来取消 merge，在未来版本中会加入该功能。
* 关于钉钉群发送功能，需在钉钉群中配置机器人，详见 [https://developers.dingtalk.com/document/robots/custom-robot-access](https://developers.dingtalk.com/document/robots/custom-robot-access) 和 [https://developers.dingtalk.com/document/robots/customize-robot-security-settings](https://developers.dingtalk.com/document/robots/customize-robot-security-settings)，目前仅支持加签的安全设置方式。
* ci 测试的代码需要用户在入参中传入。
* Github Action 的 schedule 有延迟，并不会按照指定的时间如期运行，通常延迟 15 - 30 分钟。

# 测试用例

```
 ...

 on:
  schedule:
    - cron: '* */1 * * *'  --- 每小时跑一次
  workflow_dispatch:

 ...

    - name: Run merge script
      uses: klay-ke/auto-merge-pr@master  --- 该地址以后可能会改
      id: merge-pr
      with:
        send-to-dingtalk-group: true
        dingtalk-access-token: ${{ secrets.DINGTALK_ACCESS_TOKEN }}
        dingtalk-secret: ${{ secrets.DINGTALK_SECRET }}
        maintainer-team-name: ${{ secrets.MAINTAINER_TEAM_NAME }}
        gh-token: ${{ secrets.GH_TOKEN }}
        ci-command: 'bash ./build.sh'
```



## 输入

| 参数                   | 类型    | required                              | 默认值   | 描述                                                         |
| ---------------------- | ------- | ------------------------------------- | -------- | ------------------------------------------------------------ |
| send-to-dingtalk-group | boolean | 否                                    | false    | 若为 true，则表明需要发送 merge 信息到钉钉群中，同时 dingtalk-access-token 和 dingtalk-access-token 字段需要提供 |
| dingtalk-access-token  | string  | 当 send-to-dingtalk-group 为 true     | 空字符串 | 钉钉群机器人的 access token                                   |
| dingtalk-secret        | string  | 当 send-to-dingtalk-group 为 true     | 空字符串 | 钉钉群机器人的 secret.                                        |
| maintainer-team-name   | string  | 是                                    | None     | maintainer team 的名字                                        |
| gh-token               | string  | 是                                    | None     | Github Token                                                 |
| ci-command             | string  | 否                                    | None     | ci 测试代码                                                   |

# 输出

可通过 `${{ steps.{action设置的id - 对应用例中的merge-pr}.outputs.{参数名} }}` 在后续 step 中读取输出；

| 参数       | 类型    | 描述                        |
| ---------- | ------- | --------------------------- |
| merge-info | string  | 本次 merge 信息               |
| error-log  | string  | 错误日志                    |
| pass-log   | string  | 日志信息                    |
| merged     | boolean | 是否有 pull request 成功 merge |

以上。

---

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

【活动】Nebula Hackathon 2021 进行中，一起来探索未知，领取 ¥ 150,000 奖金 →→ [https://nebula-graph.com.cn/hackathon/](https://nebula-graph.com.cn/hackathon/)

作为一款开源的分布式图数据库产品，NebulaGraph 所有的研发流程都在 GitHub 上运作。基于 GitHub 生态 Nebula 技术团队有一套 pr 的自动化流程，本文主要讲解这套流程的演进…

GitHub 自动合并 pr 的机器人——auto-merge-bot


![K6 在 NebulaGraph 上的压测实践](https://www-cdn.nebula-graph.com.cn/nebula-blog/k6.jpg)

## 背景

对于数据库来说，性能测试是一个非常频繁的事情。优化查询引擎的规则，调整存储引擎的参数等，都需要通过性能测试，查看系统在不同场景下的影响。

即便是同样的代码，同样的参数配置，在不同的机器资源配置，不同的业务场景下也有较大的区别，记录一下内部的压测实践过程，有一个参考。

*本文中操作系统为 x86 架构 CentOS 7.8*。

*部署 nebula 的机器配置为 4C 16G 内存，SSD 磁盘，万兆网络*。

## 工具

* [nebula-ansible](https://github.com/vesoft-inc/nebula-ansible) 用于部署 nebula 服务
* [nebula-importer](https://github.com/vesoft-inc/nebula-importer) 用于导入数据到 nebula 集群中
* [k6-plugin](https://github.com/vesoft-inc/k6-plugin) k6 压测工具，里面使用 go 客户端向 nebula 集群发起请求
* [nebula-bench](https://github.com/vesoft-inc/nebula-bench) 整合了生成 LDBC 数据集，数据导入和压测。
* [ldbc_snb_datagen_hadoop](https://github.com/ldbc/ldbc_snb_datagen_hadoop) LDBC 数据生成工具

## 概述

数据使用 [ldbc_snb_datagen](https://github.com/ldbc/ldbc_snb_datagen_hadoop) 自动生成的 LDBC 数据集，整体流程如下图。

![图片](https://www-cdn.nebula-graph.com.cn/nebula-blog/bench-practice-workflow.png)

部署拓扑，使用 1 台机器作为压测负载机，3 台机器组成一个 nebula 集群

![图片](https://www-cdn.nebula-graph.com.cn/nebula-blog/bench-practice-cluster.png)

为了方便监控，压测负载机还部署了：

* Prometheus
* Influxdb
* Grafana
* node-exporter

nebula 机器上还部署了：

* node-exporter
* process-exporter

## 具体步骤

### 使用 nebula-ansible 部署 nebula

1. 先初始化用户，打通 ssh 
    1. 分别登录 192.168.8.60，192.168.8.61，192.168.8.62，192.168.8.63，创建 vesoft 用户，加入 sudoer 中，并设置 NOPASSWD。
    2. 登录 192.168.8.60，打通 ssh
```bash
ssh-keygen

ssh-copy-id vesoft@192.168.8.61
ssh-copy-id vesoft@192.168.8.62
ssh-copy-id vesoft@192.168.8.63
```

2. 下载 nebula-ansible，安装 ansible，修改 ansible 配置
```bash
sudo yum install ansible -y
git clone https://github.com/vesoft-inc/nebula-ansible
cd nebula-ansible/

# 因为默认是国际 cdn，改为国内的 cdn
sed -i 's/oss-cdn.nebula-graph.io/oss-cdn.nebula-graph.com.cn/g' group_vars/all.yml
```

inventory.ini 示例

```yaml
[all:vars]
# GA or nightly
install_source_type = GA
nebula_version = 2.0.1
os_version = el7
arc = x86_64
pkg = rpm

packages_dir = {{ playbook_dir }}/packages
deploy_dir = /home/vesoft/nebula
data_dir = {{ deploy_dir }}/data

# ssh user
ansible_ssh_user = vesoft

force_download = False

[metad]
192.168.8.[61:63]

[graphd]
192.168.8.[61:63]

[storaged]
192.168.8.[61:63]
```

3. 安装并启动 nebula
```bash
ansible-playbook install.yml
ansible-playbook start.yml
```

### 部署监控

为了方便部署，使用 Docker-Compose 运行，需要先在机器上安装 Docker 和 Docker-Compose。

登录 192.168.8.60 压测机

```bash
git clone https://github.com/vesoft-inc/nebula-bench.git

cd nebula-bench
cp -r third/promethues ~/.
cp -r third/exporter ~/.



cd ~/exporter/ && docker-compose up -d

cd ~/promethues
# 修改监控节点的 exporter 的地址
# vi prometheus.yml
docker-compose up -d

# 复制 exporter 到 192.168.8.61，192.168.8.62，192.168.8.63，然后启动 docker-compose 
```
配置 grafana 的数据源和 dashboard，具体见 [https://github.com/vesoft-inc/nebula-bench/tree/master/third](https://github.com/vesoft-inc/nebula-bench/tree/master/third) 。
### 生成 LDBC 数据集

```bash
cd nebula-bench

sudo yum install -y git \
                    make \
                    file \
                    libev \
                    libev-devel \
                    gcc \
                    wget \
                    python3 \
                    python3-devel \
                    java-1.8.0-openjdk \
                    maven

pip3 install --user -r requirements.txt

# 默认生成 sf1, 1G的数据，300w+点，1700w+边
python3 run.py data

# mv 生成好的数据
mv target/data/test_data/ ./sf1
```

### 导入数据

```bash
cd nebula-bench
# 修改 .evn
cp env .env
vi .env
```

以下是 .env 示例

```bash
DATA_FOLDER=sf1
NEBULA_SPACE=sf1
NEBULA_USER=root
NEBULA_PASSWORD=nebula
NEBULA_ADDRESS=192.168.8.61:9669,192.168.8.62:9669,192.168.8.63:9669
#NEBULA_MAX_CONNECTION=100
INFLUXDB_URL=http://192.168.8.60:8086/k6
```

```bash
# 编译 nebula-importer 和 k6
./scripts/setup.sh

# 导入数据
python3 run.py nebula importer
```
导入过程中，可以重点关注以下网络带宽和磁盘 io 写。

![图片](https://www-cdn.nebula-graph.com.cn/nebula-blog/bench-practice-network-traffic-basic.png)

![图片](https://www-cdn.nebula-graph.com.cn/nebula-blog/bench-practice-write-bytes.png)


### 执行压测

```bash
python3 run.py stress run
```

会根据 scenarios 里的代码，自动渲染出 js 文件，然后使用 k6 压测所有场景。

执行后，js 文件和压测结果都在 output 文件夹中。

其中  `latency` 是服务端返回的 latency 时间， `responseTime` 是客户端从发起 execute 到接收的时间，单位 us。

```bash
[vesoft@qa-60 nebula-bench]$ more output/result_Go1Step.json
{
    "metrics": {
        "data_sent": {
            "count": 0,
            "rate": 0
        },
        "checks": {
            "passes": 1667632,
            "fails": 0,
            "value": 1
        },
        "data_received": {
            "count": 0,
            "rate": 0
        },
        "iteration_duration": {
            "min": 0.610039,
            "avg": 3.589942336582023,
            "med": 2.9560145,
            "max": 1004.232905,
            "p(90)": 6.351617299999998,
            "p(95)": 7.997563949999995,
            "p(99)": 12.121579809999997
        },
        "latency": {
            "min": 308,
            "avg": 2266.528722763775,
            "med": 1867,
            "p(90)": 3980,
            "p(95)": 5060,
            "p(99)": 7999
        },
        "responseTime": {
            "max": 94030,
            "p(90)": 6177,
            "p(95)": 7778,
            "p(99)": 11616,
            "min": 502,
            "avg": 3437.376111156418,
            "med": 2831
        },
        "iterations": {
            "count": 1667632,
            "rate": 27331.94978169588
        },
        "vus": {
            "max": 100,
            "value": 100,
            "min": 0
```

```bash
[vesoft@qa-60 nebula-bench]$ head -300 output/output_Go1Step.csv | grep -v USE
timestamp,nGQL,latency,responseTime,isSucceed,rows,errorMsg
1628147822,GO 1 STEP FROM 4398046516514 OVER KNOWS,1217,1536,true,1,
1628147822,GO 1 STEP FROM 2199023262994 OVER KNOWS,1388,1829,true,94,
1628147822,GO 1 STEP FROM 1129 OVER KNOWS,1488,2875,true,14,
1628147822,GO 1 STEP FROM 6597069771578 OVER KNOWS,1139,1647,true,30,
1628147822,GO 1 STEP FROM 2199023261211 OVER KNOWS,1399,2096,true,6,
1628147822,GO 1 STEP FROM 2199023256684 OVER KNOWS,1377,2202,true,4,
1628147822,GO 1 STEP FROM 4398046515995 OVER KNOWS,1487,2017,true,39,
1628147822,GO 1 STEP FROM 10995116278700 OVER KNOWS,837,1381,true,3,
1628147822,GO 1 STEP FROM 933 OVER KNOWS,1130,3422,true,5,
1628147822,GO 1 STEP FROM 6597069771971 OVER KNOWS,1022,2292,true,60,
1628147822,GO 1 STEP FROM 10995116279952 OVER KNOWS,1221,1758,true,3,
1628147822,GO 1 STEP FROM 8796093031179 OVER KNOWS,1252,1811,true,13,
1628147822,GO 1 STEP FROM 10995116279792 OVER KNOWS,1115,1858,true,6,
1628147822,GO 1 STEP FROM 6597069777326 OVER KNOWS,1223,2016,true,4,
1628147822,GO 1 STEP FROM 8796093028089 OVER KNOWS,1361,2054,true,13,
1628147822,GO 1 STEP FROM 6597069777454 OVER KNOWS,1219,2116,true,2,
1628147822,GO 1 STEP FROM 13194139536109 OVER KNOWS,1027,1604,true,2,
1628147822,GO 1 STEP FROM 10027 OVER KNOWS,2212,3016,true,83,
1628147822,GO 1 STEP FROM 13194139544176 OVER KNOWS,855,1478,true,29,
1628147822,GO 1 STEP FROM 10995116280047 OVER KNOWS,1874,2211,true,12,
1628147822,GO 1 STEP FROM 15393162797860 OVER KNOWS,714,1684,true,5,
1628147822,GO 1 STEP FROM 6597069770517 OVER KNOWS,2295,3056,true,7,
1628147822,GO 1 STEP FROM 17592186050570 OVER KNOWS,768,1630,true,26,
1628147822,GO 1 STEP FROM 8853 OVER KNOWS,2773,3509,true,14,
1628147822,GO 1 STEP FROM 19791209307908 OVER KNOWS,1022,1556,true,6,
1628147822,GO 1 STEP FROM 13194139544258 OVER KNOWS,1542,2309,true,91,
1628147822,GO 1 STEP FROM 10995116285325 OVER KNOWS,1901,2556,true,0,
1628147822,GO 1 STEP FROM 6597069774931 OVER KNOWS,2040,3291,true,152,
1628147822,GO 1 STEP FROM 8796093025056 OVER KNOWS,2007,2728,true,29,
1628147822,GO 1 STEP FROM 21990232560726 OVER KNOWS,1639,2364,true,9,
1628147822,GO 1 STEP FROM 8796093030318 OVER KNOWS,2145,2851,true,6,
1628147822,GO 1 STEP FROM 21990232556027 OVER KNOWS,1784,2554,true,5,
1628147822,GO 1 STEP FROM 15393162796879 OVER KNOWS,2621,3184,true,71,
1628147822,GO 1 STEP FROM 17592186051113 OVER KNOWS,2052,2990,true,5,
```

也可以对单个场景压测，不断调整配置参数，来进行对比。

#### 并发读

```bash
# 执行 go 2 跳，50 并发，持续 300 秒
python3 run.py stress run -scenario go.Go2Step -vu 50 -d 300
```

```shell

INFO[0302] 2021/08/06 03:55:27 [INFO] finish init the pool

     ✓ IsSucceed

     █ setup

     █ teardown

     checks...............: 100.00% ✓ 1559930     ✗ 0
     data_received........: 0 B     0 B/s
     data_sent............: 0 B     0 B/s
     iteration_duration...: min=687.47µs avg=9.6ms       med=8.04ms max=1.03s  p(90)=18.41ms p(95)=22.58ms p(99)=31.87ms
     iterations...........: 1559930 5181.432199/s
     latency..............: min=398      avg=6847.850345 med=5736   max=222542 p(90)=13046   p(95)=16217   p(99)=23448
     responseTime.........: min=603      avg=9460.857877 med=7904   max=226992 p(90)=18262   p(95)=22429   p(99)=31726.71
     vus..................: 50      min=0         max=50
     vus_max..............: 50      min=50        max=50

```
同时可以观察监控的各个指标。

![图片](https://www-cdn.nebula-graph.com.cn/nebula-blog/bench-practice-network-traffic-basic-01.png)


checks 是校验请求是否执行成功，如果执行失败，会在 csv 中保存失败的错误消息。

```bash
awk -F ',' '{print $NF}' output/output_Go2Step.csv|sort |uniq -c
```

```bash
# 执行 go 2 跳，200 并发，持续 300 秒
python3 run.py stress run -scenario go.Go2Step -vu 200 -d 300
```

```shell

INFO[0302] 2021/08/06 04:02:34 [INFO] finish init the pool

     ✓ IsSucceed

     █ setup

     █ teardown

     checks...............: 100.00% ✓ 1866850    ✗ 0
     data_received........: 0 B     0 B/s
     data_sent............: 0 B     0 B/s
     iteration_duration...: min=724.77µs avg=32.12ms      med=25.56ms max=1.03s  p(90)=63.07ms p(95)=84.52ms  p(99)=123.92ms
     iterations...........: 1866850 6200.23481/s
     latency..............: min=395      avg=25280.893558 med=20411   max=312781 p(90)=48673   p(95)=64758    p(99)=97993.53
     responseTime.........: min=627      avg=31970.234329 med=25400   max=340299 p(90)=62907   p(95)=84361.55 p(99)=123750
     vus..................: 200     min=0        max=200
     vus_max..............: 200     min=200      max=200

```

grafana 上 k6 的监控数据

![图片](https://www-cdn.nebula-graph.com.cn/nebula-blog/bench-practice-K6-load-testing-result.png)


#### 并发写

```bash
# 执行 insert，200 并发，持续 300 秒，默认 batchSize 100
python3 run.py stress run -scenario go.Go2Step -vu 200 -d 300
```

可以手动修改一下 js 文件，调整 batchSize

```bash
sed -i 's/batchSize = 100/batchSize = 300/g' output/InsertPersonScenario.js

# 手动运行 k6
scripts/k6 run output/InsertPersonScenario.js -u 400 -d 30s --summary-trend-stats "min,avg,med,max,p(90),p(95),p(99)" --summary-export output/result_InsertPersonScenario.json --out influxdb=http://192.168.8.60:8086/k6
```

当 batchSize 为 300，并发为 400 的时候，就会错误产生。

```shell
INFO[0032] 2021/08/06 04:03:49 [INFO] finish init the pool

     ✗ IsSucceed
      ↳  96% — ✓ 31257 / ✗ 1103

     █ setup

     █ teardown

     checks...............: 96.59% ✓ 31257       ✗ 1103
     data_received........: 0 B    0 B/s
     data_sent............: 0 B    0 B/s
     iteration_duration...: min=12.56ms avg=360.11ms      med=319.12ms max=2.07s   p(90)=590.31ms p(95)=696.69ms p(99)=958.32ms
     iterations...........: 32360  1028.339207/s
     latency..............: min=4642    avg=206931.543016 med=206162   max=915671  p(90)=320397.4 p(95)=355798.7 p(99)=459521.39
     responseTime.........: min=6272    avg=250383.122188 med=239297.5 max=1497159 p(90)=384190.5 p(95)=443439.6 p(99)=631460.92
     vus..................: 400    min=0         max=400
     vus_max..............: 400    min=400       max=400

```
```bash

awk -F ',' '{print $NF}' output/output_InsertPersonScenario.csv|sort |uniq -c

```

```shell

  31660
   1103  error: E_CONSENSUS_ERROR(-16)."
      1 errorMsg 
```

发现是  `E_CONSENSUS_ERROR`，应该是并发大的时候，raft 的 appendlog buffer overflow 了，可以调整相关的参数。

## 总结

* 使用 LDBC 作为标准数据集，数据特征会标准一些，可以生成更多的数据比如 10 亿点，而数据结构是一样的。
* 使用 k6 作为压测负载工具，二进制相比 Jmeter 更方便，而且因为 k6 底层使用 Golang 的 goroutine，相比 Jmeter 使用更少的资源。
* 通过工具，模拟各种场景或者调整 nebula 的参数，可以更好的使用到服务器资源。

《开源分布式图数据库NebulaGraph完全指南》，又名：Nebula 小书，里面详细记录了图数据库以及图数据库 NebulaGraph 的知识点以及具体的用法，阅读传送门：[https://docs.nebula-graph.com.cn/site/pdf/NebulaGraph-book.pdf](https://docs.nebula-graph.com.cn/site/pdf/NebulaGraph-book.pdf)

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~


对于数据库来说，性能测试是一个非常频繁的事情。优化查询引擎的规则、调整存储引擎的参数等等，都需要通过性能测试…本文主要记录一下内部的压测实践过程，让大家有一个参考。

K6 在 NebulaGraph 上的压测实践


![基于 BDD 理论的 Nebula 集成测试框架重构（下篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/bdd.png)

# 引子

由于 NebulaGraph 在持续研发过程中会频繁地更改返回数据的格式，这样就会造成了上层应用程序无法正确解析数据。

比如在 v2.0.0 发布的时候，改变了 SHOW JOBS 的格式，造成了 Studio 解析的时候页面崩溃。

为了避免再次发生这样的悲剧问题，可以使用 NebulaGraph 提供的测试框架，方便地增加测试用例。

# 环境准备   

按照文档[《源码编译安装》](https://docs.nebula-graph.com.cn/2.0.1/4.deployment-and-installation/2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code/) 中所示，我们可以参考以下步骤进行操作：

a. 准备一台开发机，这里给出了开发环境的配置要求。

- Python3 要求的最低版本为 Python 3.7.

```
python3 --version
``` 

b. 按照文档中步骤编译源代码。选择 master 版本,并拉一个分支

```
git checkout -b  dev tck
```

具体步骤可以见 Nebula 文档站中如何贡献中的 GitHub [使用步骤部分](https://docs.nebula-graph.com.cn/2.0.1/15.contribution/how-to-contribute/) 。

c. 安装 case 运行环境

```
$ cd nebula-graph/tests/
$ make init-all
```

如果遇到模块版本过低，可以根据提示升级版本，比如：命令 `pip3 install --upgrade keyrings.alt` 。

d. 运行已有case 

```
make test
```

# 开发 case

## 研究一下已有 case

大多数已有 case 都在 https://github.com/vesoft-inc/nebula-graph/tree/master/tests/tck/features 目录下，根据主要功能放在不同目录下。

例如，以最常用的 MATCH 功能举例。打开 GitHub 目录下的 [match/MatchById.feature](https://github.com/vesoft-inc/nebula-graph/blob/master/tests/tck/features/match/MatchById.feature) 文件

```
Feature: Match By Id

  Background:
    Given a graph with space named "basketballplayer"     # 选择一个已有的单元测试数据集 basketballplayer

  Scenario: single node                                   # 给这个 case 取个名字
    When executing query:                              # 以下三引号之间的部分，为发送给 NebulaGraph 的文本。
      """                                                            # 这句话的目的，是获vid为James Harden的点
      MATCH (n) WHERE id(n) == 'James Harden' RETURN n
      """                                                            # Then 表示测试结果匹配                
    Then the result should be, in any order, with relax comparison:
      | n                |                                           # 期望获取的文本结果，应该是这样一个格式。列名为 n
      | ("James Harden") |                                # 内容为 "James Harden", 圆括号表示这是一个点
    When executing query:                             # 开始下一个命令。
      """
      MATCH (n) WHERE id(n) == 'not_exist_vertex' RETURN n
      """
    Then the result should be, in any order, with relax comparison:
      | n |
```

nebula-test 是基于 BDD 思想撰写的，这些 feature 文件基本是自然语言（gherkin文本），BDD 介绍文章可参考：[《基于 BDD 理论的 Nebula 集成测试框架重构（上篇）》](https://mp.weixin.qq.com/s/gw1hJetflofQc2aiiZ6frA)。

这里简单地解释一下 case 用例模版主要的格式：

- Feature：介绍整个文本是做什么的；
- Background：设置一下公共的运行环境，例子中，选用了一个已经存在的数据集 basketballplayer（建立了schema，index，写入了数据）；
- Scenario：一组 `When-Then` 的组合，是一个最小的并发执行单位；
- When executing query：向 NebulaGraph 发送一组命令；
- Then the result should be：从 NebulaGraph 获取结果，和下面的期望结果对比；


这个对比方式可以有以下几种：

- the result should be：需完全一样 （行、列、单元格内容都必须一模一样）；
- the result should contain：只包含以下内容即可；
- the result should be, in any order：返回结果的行顺序无关（对于行 1 和行 2 的顺序没有要求）；
- the result should be, in any order, with relax comparison：结果集需要是以下形式，行顺序无关，并且至少包括以下内容（例如，每个单元格至少包括"Tiago Splitter"，但可以比这个多）；
- the execution should be successful：返回码为成功；
- an ExecutionError should be raised at runtime: not existed! 执行失败，抛出异常ExecutionError，且返回错误码为 not existed!；

## 尝试自己撰写一个 case

假设现在我们的目的是检查一下`SHOW JOBS` 的返回格式，可以这么操作：在 nebula-graph/tests/tck/features/job/(https://github.com/vesoft-inc/nebula-graph/tree/master/tests/tck/features/job) 下增加一个 JobCommands.feature 的文件

```
@mintest                                                          #用于调试

Feature: Job compact, flush, rebuild_index

  Background:                                     # 选择数据集
    Given a graph with space named "basketballplayer"

  Scenario: submit job
    When executing query:
      """
      SUBMIT JOB COMPACT;
      """
    Then the result should contain:
      | New Job Id |
      | /\d+/          |              # 用正则表达式检查为正数
    When executing query:
      """
      SUBMIT JOB FLUSH;
      """
     When executing query:
      """
      SUBMIT JOB STATS;

      SHOW JOBS;
      """
    Then the result should contain:   # 检查返回形式
      | Job Id | Command | Status  | Start Time                               | Stop Time                 |
      | /\d+/  | "STATS"      | /\w+/  | /\d+-\d+-\d+T\d+:\d+:\d+/ | /\d+-\d+-\d+T\d+:\d+:\d+/ |
```

## 调试 case

```
nebula-graph/tests> make fmt
```

检查格式错误，并格式化文件。

```
nebula-graph/tests>  pytest -m "mintest"
```

运行刚撰写的 case，通常要来回更改多次。用`#`号注释。也可以用 `@skip` 标注跳过整个 Scenario。

```
nebula-graph/tests>  pytest -n4
```

如果内存有限，-n4 控制并发度。

更多说明可以参见这里：https://github.com/vesoft-inc/nebula-graph/tree/master/tests#nebula-graph-test-manual 。

## 通过 git 向 NebulaGraph repo 增加该 case

如果所有的测试都已经通过，将调试标记 `@mintest` 去掉，通过 git 指令向 NebulaGraph 仓库提交一个 pull request，参考 [如何贡献](https://docs.nebula-graph.com.cn/2.0.1/15.contribution/how-to-contribute/) 。

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~


这回，我们来给 NebulaGraph 添加一个测试用例，步骤很简单，首先：打开文章，然后准备好环境，开发 case，提交上线…

如何向 NebulaGraph 增加一个测试用例


![基于 BDD 理论的 Nebula 集成测试框架重构（下篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/bdd.png)

在[上篇文章](https://mp.weixin.qq.com/s/gw1hJetflofQc2aiiZ6frA)中，我们介绍了 NebulaGraph 的集成测试的演进过程。本篇就介绍一下向测试集合中添加一个用例，并成功运行所有的测试用例的过程。

## 环境准备

在构建 2.0 测试框架之初，我们定制了部分工具类来帮助测试框架快速地启停一个单节点的 nebula 服务，其中有检查端口冲突、修改部分配置选项等功能。原来的执行流程如下:

1. 通过 python 脚本启动 nebula 的服务；
2. 调用`pytest.main`并发执行所有的测试用例；
3. 停止 nebula 的服务。

其中的不便之处在于，当需要给 pytest 指定某些参数选项时，需要将该参数透传给`pytest.main`函数，并且每次运行单个测试用例需要通过`cmake`生成的脚本来操作，不是很方便。我们希望“测试用例在哪儿，就在哪儿执行测试”。

### 服务启动

在本次测试框架的改造过程中，我们除了改变了程序入口之外，大部分复用了原来封装好的逻辑。由于 nebula 目前积累了很多的用例，单进程运行已经不能满足快速迭代的需求，在尝试了其他并行插件之后，考虑到兼容性，我们最终选择了 pytest-xdist 插件来加速整个测试流程。

但是 pytest 只提供了四种 scope 的 fixture：session，module，class 和 function。而我们希望能用一种 global 级别的 fixture 来完成 nebula 服务的启动和初始化。目前最高层次的 session 级别还是每个 runner 都要执行一次，如此如果有 8 个 runner 的话，就要启动 8 个 nebula 服务，这不是我们期望的。

参考 pytest-xdist 的[文档](https://github.com/pytest-dev/pytest-xdist#making-session-scoped-fixtures-execute-only-once)，需要通过文件锁来进行不同 runner 之间的并行控制。为了让控制逻辑足够的简单，我们把程序启停和预备的逻辑同执行测试的过程分开，使用单独的步骤控制 nebula 的启动，当某些测试有问题时，还可以通过 nebula-console 单独连接测试的服务，进行进一步的验证调试。

### 数据导入

在此之前，Nebula 的数据导入过程是直接执行一条拼接好的 nGQL INSERT 语句。这样做，存在如下问题：

1. 测试数据集大的情况，INSERT 语句会变得冗长，client 执行超时；
2. 不易拓展新的测试数据集，需要将现成的 csv 数据文件构造成对应的 nGQL 语句文件；
3. 不能复用相同的数据集，比如希望同一份 csv 导入到不同 VID 类型的 space 中测试，需要构造不同的 INSERT 语句。

针对以上的问题，参考[nebula-importer](https://github.com/vesoft-inc/nebula-importer)的实现，我们将导入的逻辑和数据集完全分离，重新实现了 python 版的导入模块。不过，目前只支持导入 csv 类型的数据文件，且每个 csv 文件中只能存储一个`tag/edge`类型。

重构导入的逻辑之后，目前 nebula 的测试数据集变得清晰明了：

```tree
nebula-graph/tests/data
├── basketballplayer
│   ├── bachelor.csv
│   ├── config.yaml
│   ├── like.csv
│   ├── player.csv
│   ├── serve.csv
│   ├── team.csv
│   └── teammate.csv
├── basketballplayer_int_vid
│   └── config.yaml
└── student
    ├── config.yaml
    ├── is_colleagues.csv
    ├── is_friend.csv
    ├── is_schoolmate.csv
    ├── is_teacher.csv
    ├── person.csv
    ├── student.csv
    └── teacher.csv
 
3 directories, 16 files
```

每个目录包含一个 space 中所有的 csv 数据文件，通过该目录下的`config.yaml`来配置每个文件的描述以及 space 的详细信息。通过这份配置信息，我们也实现了 basketballplayer 和 basketballplayer`_int_vid`两个 space 共享同一份数据。以后如果想添加新的测试数据集，只要增加一个类似 basketballplayer 的数据目录即可。`config.yaml`的具体内容见[repo](https://github.com/vesoft-inc/nebula-graph/blob/master/tests/data/nba/config.yaml)。

### 安装依赖

除却常用的 pytest 和 nebula-python 库之外，目前的测试框架还用到了 pytest-bdd 和 pytest-xdist 等插件。此外，为了更好地统一添加测试用例 feature 文件的格式，我们引入了社区的[reformat-gherkin](https://github.com/ducminh-phan/reformat-gherkin)工具，并基于此做了[部分格式的调整](https://github.com/OneContainer/reformat-gherkin)，来保持与 openCypher TCK feature 文件的格式统一。

目前 nebula-python 和 reformat-gherkin 两款插件都是通过源码直接安装，我们在`nebula-graph/tests`下提供了`Makefile`来简化用户的操作流程。执行测试的所有环境准备只需要执行命令：

```plain
$ cd nebula-graph/tests && make init-all
```
我们也将上述格式检查集成到了 GitHub Action 的 CI 流程中，如果用户修改的测试文件格式不合预期，可通过`make fmt`命令做本地的格式化处理。
## 编写用例

由上篇所述，现在 nebula 的集成测试变为“黑盒”测试，用户不再需要关心自己编写的语句怎么调用，调用什么函数比较符合预期结果。只要按照约定的规范，使用近似“自然语言”的方式在 feature 文件中描述自己的用例即可。以下是一个测试用例的示例：

```
Feature: Variable length pattern match (m to n)
  Scenario: both direction expand with properties
    Given a graph with space named "basketballplayer"
    When executing query:
      """
      MATCH (:player{name:"Tim Duncan"})-[e:like*2..3{likeness: 90}]-(v)
      RETURN e, v
      """
    Then the result should be, in any order, with relax comparison:
      | e                                                                                  | v                  |
      | [[:like "Tim Duncan"<-"Manu Ginobili"], [:like "Manu Ginobili"<-"Tiago Splitter"]] | ("Tiago Splitter") |
```

`Given`提供测试的初始条件，这里初始化一个名为 "basketballplayer" 的 space。`When`描述测试的输入，即 nGQL 语句。`Then`给出期望结果和期望比较的方式，这里表示无序宽松比较表格中的结果。

#### Feature 文件结构

Feature 文件是 Gherkin 语言描述的一种文件格式，主要由如下几个部分构成：

* Feature：可以添加当前文件的“Title”，也可以详细描述文件内容；
* Background：后续 Scenario 共同使用的步骤；
* Scenario：由一个个步骤描述每个测试用例的场景；
* Examples：可以进一步将测试场景和测试数据进行分离，简化当前 Feature 文件中 Scenarios 的书写；

每个 Scenario 又分为了不同的 step，每个 step 都有特殊的意义：

* Given: 设置当前测试场景的初始条件，上述 Background 中只能含有 Given 类型的 step；
* When: 给定当前测试场景的输入；
* Then: 描述做完 When 的 step 后期望得到的结果；
* And: 可以紧跟上述 Given/When/Then 中任何一种类型的 step，进一步补充上述的 step 的动作；
* Examples: 类似上述 Examples 描述，不过作用的范围限定在单个 Scenario 中，不影响同 Feature 文件中的其他 Scenario 测试。
#### Steps

由上面描述可知，Scenario 就是有一个个的 step 组成，nebula 在兼容 openCypher TCK 的 step 基础上又定制了一些特有的步骤来方便测试用例的书写：

1. `Given a graph with space named "basketballplayer"`：使用预先导入 “basketballplayer” 数据的 space；
2. `creating a new space with following options`：创建一个含有如下参数的新的 space，可以指定 name、partition_num、replica_factor、vid_type、charset 和 collate 等参数；
3. `load "basketballplayer" csv data to a new space`：向新 space 导入 “basketballplayer” 数据集；
4. `profiling query`：对 query 语句执行`PROFILE`，返回结果中会含有 execution plan；
5. `wait 3 seconds`：等待 3 秒钟，在 schema 相关的操作时往往需要一定的数据同步时间，这时就可以用到该步骤；
6. `define some list variables`：定义一些变量表示元素很多的 List 类型，方便在期望结果中书写对应的 List；
7. `the result should be, in any order, with relax comparison`：执行结果进行无序宽松比较，意味着期望结果中用户写了什么就比较什么，没写的部分即使返回结果中有也不作比较；
8. `the result should contain`：返回结果必须包含期望结果；
9. `the execution plan should be`：比较返回结果中的执行计划。

除却以上的这些步骤，还可根据需要定义更多的 steps 来加速测试用例的开发。

#### Parser

根据[TCK 的描述](https://github.com/opencypher/openCypher/tree/master/tck#format-of-the-expected-results)可知，openCypher 定义了一组图语义的表示方式来表达期望的返回结果。这些点边的格式借鉴了`MATCH`查询中的 pattern，所以如果熟悉 openCypher 的查询，基本可以很容易理解 TCK 测试场景中的结果。比如部分图语义的格式如下所示：

1. 点的描述:`(:L {p:1, q:"string"})`;
2. 边的描述:`[:T {p:0, q:"string"}]`;
3. 路径的描述：`<(:L)-[:T]->(:L2)>`。

但是 NebulaGraph 同 Neo4J 的在图模型上还是有一些不同，比如在 NebulaGraph 中每个 Tag 均可以有自己的属性，那么按照现有的表述方式是不能描述含有多个带属性 Tag 的 vertex 的。在边的表示上也有差异，NebulaGraph 的 Edge Key 是由四元组组成`<src, type, rank, dst>`，而现有的表示也不能描述边的 src、dst 和 rank 的值。故而在考虑了这些差异之后，我们扩充了现有 TCK 的 expected results 表达：

1. 点的描述支持带属性的多个 Tag：`("VID" :T1{p:0} :T2{q: "string"})`；
2. 边的描述支持 src、dst 和 rank 的表示：`[:type "src"->"dst"@rank {p:0, q:"string"}]`；
3. 路径就是循环上述点边的表示即可，同 TCK 。

通过上述的点边描述方式上的扩充，即兼容 TCK 现有用例，又契合了 NebulaGraph 的设计。在解决了表达方式上的问题后，面临的下一个问题是如何高效无误地转化上述的表示到具体的数据结构，以便能够跟真正的查询结果做比较。在考虑了正则匹配、parser 解析等方案后，我们选择构造一个解析器的方式来处理这些具有特定语法规则的字符串，这样做的好处有如下的几点：

1. 可以根据具体的语法规则让解析出来的 AST 符合查询返回结果的数据结构，两者再进行比较时，便是具体结构中的具体字段的校验了；
2. 避免处理复杂的正则匹配字符串，减少解析的错误；
3. 可以支持其他字符串解析的需求，比如正则表达式、列表、集合等

借助ply.yacc 和 ply.lex 两个 library，我们可以用少量的代码实现上述复杂的需求，具体实现见[nbv.py 文件](https://github.com/vesoft-inc/nebula-graph/blob/master/tests/tck/utils/nbv.py)。

## 测试流程

目前的测试流程变为：

#### 1) 编写 Feature 文件

目前 NebulaGraph 所有的 feature 用例均位于 github.com/vesoft-inc/nebula-graph repo 中的[tests/tck/features](https://github.com/vesoft-inc/nebula-graph/tree/master/tests/tck/features)目录中。

#### 2) 启动 nebula graph 服务

```
$ cd /path/to/nebula-graph/tests
$ make up # 启动 nebula graph 服务
```

#### 3) 本地执行测试

```
$ make fmt # 格式化
$ make tck # 执行 TCK 测试
```

#### 4)停止 nebula graph 服务

```
$ mak
e down
```
### 调试

当编写的用例需要调试时，便可以使用 pytest 支持的方式来进一步的调试，比如重新运行上次过程中失败的用例：

```
$ pytest --last-failed tck/ # 运行 tck 目录中上次执行失败的用例
$ pytest -k "match" tck/    # 执行含有 match 字段的用例
```

也可以在 feature 文件中对特定的一个 scenario 打上一个 mark，只运行该被 mark 的用例，比如：

```
# in feature file
  @testmark
  Scenario: both direction expand with properties
    Given a graph with space named "basketballplayer"
    ...
 
# in nebula-graph/tests directory
$ pytest -m "testmark" tck/ # 运行带有 testmark 标记的测试用例
```

## 总结

站在前人的肩膀之上才让我们找到更适合 NebulaGraph 的测试方案，在此也一并感谢文中提到的所有开源工具和项目。

在实践 pytest-bdd 的过程中，也发现其中一些不完美的地方，比如其跟 pytest-xdist 等插件兼容性的问题(gherkin-reporter)，还有 pytest 没有原生提供 global scope 级别的 fixture 等。但终究其带给 NebulaGraph 的收益要远大于这些困难。

上篇中有提到不需要用户进行编程，并非凭空想象，当我们把上述的模式固定后，可以开发一套添加测试用例的脚手架，让用户在页面上进行数据“填空”，自动生成对应的 feature 测试文件，如此便可进一步地方便用户，此处可以留给感兴趣的社区用户来做些尝试了。

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~


本篇侧重介绍一下如何向 Nebula 测试集合中添加一个用例，并成功运行所有的测试用例的过程。

基于 BDD 理论的 Nebula 集成测试框架重构（下篇）


![基于 BDD 理论的 Nebula 集成测试框架重构（上篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/bdd.png)

# 测试框架的演进

截止目前为止，在 NebulaGraph 的开发过程中，测试框架一共发生三次较大的改动，如下图所示。在不断的演进中，团队还是积累了一些经验和教训，希望借由此文做个简单的介绍和梳理。

![基于 BDD 理论的 Nebula 集成测试框架重构（上篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/bdd01.png)

对于一个数据库产品而言，测试的重要性不言而喻，如何强调都不为过。所以测试框架无论切换到谁，出发点始终只有一个：方便快速的积累测试用例来保障 NebulaGraph 功能的稳定。这里提到的“方便快速”，不是局限于“开发者”这个群体，而是需要面向 NebulaGraph 的所有用户，可能是运维、文档甚至是非技术相关人员。为了实现这点目标，最好是能够让用户进行“无码编程”甚至不需要编程。

纵观大多数的数据库产品，往往是定制一套自己的文本规则，开发者基于这套规则来提交测试，前期我们也有过[这方面的尝试](https://github.com/yixinglu/nebula-test)，后续考虑到要从头实现定制功能太多，再加上用户又需要学习一套新的规则，最终没有真正的切换过去。直到我们开始做兼容 openCypher 的 MATCH 功能时，注意到 [TCK 这个 repo](https://github.com/opencypher/openCypher/tree/master/tck)，这虽然是一个兼容性的测试套件，但给我们实现 NebulaGraph 的集成测试提供了新的思路。前述尝试不好落地的一个原因是 NebulaGraph 返回的结果集中是一个可能含有点、边和路径的复合数据结构，采用类似 JSON 的方式不是不可，只是不够优雅简洁。结果集多了之后，便有“形式”大于“内容”之嫌，结构上的描述远超真正关心的数据，啰嗦冗长，不胜其烦。而 TCK 中制定的这套描述点、边和路径的描述规则足够简单直观，又契合 MATCH 中的 Pattern 语句，前后呼应，只要用过 openCypher 的用户，很容易接受和理解。只是针对 NebulaGraph 的强 schema 要求，需要对其规则做些拓展，但无伤大雅，鉴于上述的优点，让我们坚定的走向 BDD 的测试框架。

NebulaGraph 端到端的功能测试其实是个“黑盒”测试，主要完成的事情抽象出来就是：执行一条 nGQL 语句，比较返回的结果集。

首先通过下述测试用例的复杂度比较，我们可以直观的感受到每一次的进步，从上至下依次为：1. 基于 GTest 的测试；2. 基于 pytest 的测试；3. 基于 BDD 的测试。

![基于 BDD 理论的 Nebula 集成测试框架重构（上篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/gtest-test.png)
[基于 GTest 的测试]
![基于 BDD 理论的 Nebula 集成测试框架重构（上篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/pytest-test.png)
[基于 pytest 的测试]
![基于 BDD 理论的 Nebula 集成测试框架重构（上篇）](https://www-cdn.nebula-graph.com.cn/nebula-blog/bdd-test.png)
[基于 BDD 的测试]

从上述对比可以看出，我们越来越靠近“测试”本真，只要关心输入和输出，无需再编码组装测试数据，再辅以一些小的自动化工具，便极大的降低了添加用例的门槛。

# 期望和实现

在拓展基于 TCK 的测试框架之前，我们给本次的升级定了如下几个期望达成的目标：
1. 添加用例简单，构造期望数据方便；
2. 支持导入其他的测试数据集；
3. 复用 pytest 框架的灵活性，尤其是 plugins 和 fixture 等机制；
4. 兼容 Match TCK 用例；

为了达成上述目标，我们开始了新的技术选型和模块设计。在构建 NebulaGraph 自己的 TCK 测试框架之前，首选要选择一个“合适的”测试框架，针对该框架的基本要求有如下的几点：
1. 对基于 BDD 的测试有完善的支持；
2. 方便灵活可拓展；
3. 最好能与已有的 pytest 的用例兼容并存。

实现 BDD 的测试框架有很多，即便在 python 语言环境下也是一道[多选题](https://automationpanda.com/2019/04/02/python-bdd-framework-comparison/)，比如 [pytest-bdd](https://pytest-bdd.readthedocs.io/en/latest/)， [behave](https://behave.readthedocs.io/en/stable/) 等。鉴于上述目标中的第三点，我们选择了基于 pytest-bdd 来构建 NebulaGraph 的整个测试流程。 pytest-bdd 是 pytest 的一个插件，可以很好的支持 BDD 的特性同时又可以直接利用 pytest 的功能，比较契合我们的预期。

在选定测试框架之后，便开始设计整个测试流程的各个模块，大体结构可以划分为五个部分：**ConnectionManager**、**DataLoader**、**Parser**、**Comparator**、**Reporter**。

## ConnectionManager

管理同 nebula graph 之间的连接，包括出错重试、错误过滤等功能。

## DataLoader

读取 CSV 数据文件，解析配置中的数据类型，拼接插入数据的 INSERT 语句等。

## Parser

解析 TCK 中描述的点、边和路径的字符串，转成 Nebula 定义的 Value 结构，方便比较。

## Comparator

负责不同的 Value 结构的值比较，包括基础数据类型和复合数据类型，复合数据类型有：List、Map、Set、Vertex、Edge 和 Path 等。

## Reporter

更好的输出出错的 nGQL 语句在 feature 文件中的位置和行号等定制功能。

模块之间相互独立又相互联系，再配合着 pytest 中 fixture 不同的 scope 可以很好的完成不同场景的隔离和测试。

# 何为 BDD

前文提到了很多次的 BDD，我们了解 TDD 和 DDD 比较多，可能对[何为 BDD 还持有疑问](https://cucumber.io/docs/bdd/)。所谓 BDD 其实是由 TDD 演进而来的一种测试方法，即行为驱动测试（behavior-driven development）。通过用自然语言书写测试用例的方式完成测试，对开发人员之外的参与者更加的友好，从而拉近了开发者和用户之间的距离。在我们实践过程中发现，其实 BDD 的这套方式方法不止对管理软件质量有效，对繁杂的需求管理也是一个很好的补充手段。用户的需求描述不再局限于复杂的场景描述，可以通过期望的查询语句、过程和结论来跟开发者对齐功能需求，这些需求文件在功能开发完毕之后反过来又变成了测试场景用例，可谓一举两得。

说到 BDD，是离不开 Gherkin 语言的。它定义了一组基本的语法规则用来有效的组织普通文本的结构，以便于 BDD 测试工具可以理解文本中描述的内容。存放 Gherkin 语言文本的文件以 .feature 作为拓展名，其中可以描述很多的场景（Scenario）以及每个场景中的步骤是什么（Given/When/Then）。这些语法的规则非常简单易懂，而且关键词数量也少，所以阅读 Gherkin 的测试文本就像“一问一答”的对话，很容易上手。

NebulaGraph 的测试框架期望借助 BDD 的方法打造一个纯“黑盒”的测试流程，无论用户是否是开发者都只需要关注两点，输入的 nGQL 是什么和期望返回的结果数据是什么？如此才能减轻用户添加用例的心智负担，方便其为 NebulaGraph 添砖加瓦。在我们完成框架改造半年之内，内部便已经积累了大约 2500 个测试用例，为 2.0 项目的重构提供了有力的质量保证。所有的用例都分门别类的置于 repo 中的 [tests/tck/features](https://github.com/vesoft-inc/nebula-graph/tree/master/tests/tck/features) 目录中，这些用例本质上也是一部 nGQL 的使用指南，下次用户再碰到棘手的问题不知如何用 nGQL 描述时，也可以先参考这里的用例。

# 总结

本篇简单回顾了 NebulaGraph 的测试框架的演变历程，后续会向大家展示目前测试框架已经完成的功能以及如何使用它来测试对 NebulaGraph 源码的改动。

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~


在 NebulaGraph 的开发过程中，测试框架一共发生三次较大的改动。在不断的演进的过程中，Nebula 研发团队还是积累了一些经验和教训，希望借由此文做个简单的介绍和梳理。

基于 BDD 理论的 Nebula 集成测试框架重构（上篇）


![troubleshooting-crash-clang-compiler-optimization](https://www-cdn.nebula-graph.com.cn/nebula-blog/troubleshooting-crash-clang-compiler-optimization.png)

如果有人告诉你，下面的 C++ 函数会导致程序 crash，你会想到哪些原因呢？

```cpp
std::string b2s(bool b) {
    return b ? "true" : "false";
}
```

如果再多给一些描述，比如：

- Crash 以一定的概率复现
- Crash 原因是段错误（SIGSEGV）
- 现场的 Backtrace 经常是不完整甚至完全丢失的。
- 只有优化级别在 -O2 以上才会（更容易）复现
- 仅在 Clang 下复现，GCC 复现不了

好了，一些老鸟可能已经有线索了，下面给出一个最小化的复现程序和步骤：

```cpp
// file crash.cpp
#include <iostream>
#include <string>

std::string __attribute__((noinline)) b2s(bool b) {
    return b ? "true" : "false";
}

union {
    unsigned char c;
    bool b;
} volatile u;

int main() {
    u.c = 0x80;
    std::cout << b2s(u.b) << std::endl;
    return 0;
}
```

```
$ clang++ -O2 crash.cpp
$ ./a.out
truefalse,d$x4DdzRx

Segmentation fault (core dumped)

$ gdb ./a.out core.3699
Core was generated by `./a.out'.
Program terminated with signal SIGSEGV, Segmentation fault.
#0  0x0000012cfffff0d4 in ?? ()
(gdb) bt
#0  0x0000012cfffff0d4 in ?? ()
#1  0x00000064fffff0f4 in ?? ()
#2  0x00000078fffff124 in ?? ()
#3  0x000000b4fffff1e4 in ?? ()
#4  0x000000fcfffff234 in ?? ()
#5  0x00000144fffff2f4 in ?? ()
#6  0x0000018cfffff364 in ?? ()
#7  0x0000000000000014 in ?? ()
#8  0x0110780100527a01 in ?? ()
#9  0x0000019008070c1b in ?? ()
#10 0x0000001c00000010 in ?? ()
#11 0x0000002ffffff088 in ?? ()
#12 0xe2ab001010074400 in ?? ()
#13 0x0000000000000000 in ?? ()
```

因为 backtrace 信息不完整，说明程序并不是在第一时间 crash 的。面对这种情况，为了快速找出第一现场，我们可以试试 AddressSanitizer（ASan）：

```
$ clang++ -g -O2 -fno-omit-frame-pointer -fsanitize=address crash.cpp
$ ./a.out
=================================================================
==3699==ERROR: AddressSanitizer: global-buffer-overflow on address 0x000000552805 at pc 0x0000004ff83a bp 0x7ffd7610d240 sp 0x7ffd7610c9f0
READ of size 133 at 0x000000552805 thread T0
    #0 0x4ff839 in __asan_memcpy (a.out+0x4ff839)
    #1 0x5390a7 in b2s[abi:cxx11](bool) crash.cpp:6
    #2 0x5391be in main crash.cpp:16:18
    #3 0x7faed604df42 in __libc_start_main (/usr/lib64/libc.so.6+0x23f42)
    #4 0x41c43d in _start (a.out+0x41c43d)

0x000000552805 is located 59 bytes to the left of global variable '<string literal>' defined in 'crash.cpp:6:25' (0x552840) of size 6
  '<string literal>' is ascii string 'false'
0x000000552805 is located 0 bytes to the right of global variable '<string literal>' defined in 'crash.cpp:6:16' (0x552800) of size 5
  '<string literal>' is ascii string 'true'
SUMMARY: AddressSanitizer: global-buffer-overflow (/home/dutor.hou/Wdir/nebula-graph/build/bug/a.out+0x4ff839) in __asan_memcpy
Shadow bytes around the buggy address:
…
...
```

从 ASan 给出的信息，我们可以定位到是函数 `b2s(bool)` 在读取字符串常量 `"true"` 的时候，发生了“全局缓冲区溢出”。好了，我们再次以上帝视角审视一下问题函数和复现程序，“似乎”可以得出结论：因为 `b2s` 的布尔类型参数 `b` 没有初始化，所以 `b` 中存储的是一个 `0` 和 `1` 之外的值[1]。那么问题来了，为什么 `b` 的这种取值会导致“缓冲区溢出”呢？感兴趣的可以将 `b` 的类型由 `bool` 改成 `char` 或者 `int`，问题就可以得到修复。

想要解答这个问题，我们不得不看下 clang++ 为 `b2s` 生成了怎样的指令（之前我们提到 GCC 下没有出现 crash，所以问题可能和代码生成有关）。在此之前，我们应该了解：

- 样例程序中，`b2s` 的返回值是一个临时的 `std::string` 对象，是保存在栈上的
- C++ 11 之后，GCC 的 `std::string` 默认实现使用了 SBO（Small Buffer Optimization），其定义大致为 `std::string{ char *ptr; size_t size; union{ char buf[16]; size_t capacity}; }`。对于长度小于 `16` 的字符串，不需要额外申请内存。

OK，那我们现在来看一下 `b2s` 的反汇编并给出关键注解：

```
(gdb) disas b2s
Dump of assembler code for function b2s[abi:cxx11](bool):
   0x00401200 <+0>:     push   %r14
   0x00401202 <+2>:     push   %rbx
   0x00401203 <+3>:     push   %rax
   0x00401204 <+4>:     mov    %rdi,%r14         # 将返回值(string)的起始地址保存到 r14
   0x00401207 <+7>:     mov    $0x402010,%ecx    # 将 "true" 的起始地址保存至 ecx
   0x0040120c <+12>:    mov    $0x402015,%eax    # 将 "false" 的起始地址保存至 eax
   0x00401211 <+17>:    test   %esi,%esi         # “测试” 参数 b 是否非零
   0x00401213 <+19>:    cmovne %rcx,%rax         # 如果 b 非零，则将 "true" 地址保存至 rax
   0x00401217 <+23>:    lea    0x10(%rdi),%rdi   # 将 string 中的 buf 起始地址保存至 rdi
                                                 # （同时也是后面 memcpy 的第一个参数）
   0x0040121b <+27>:    mov    %rdi,(%r14)       # 将 rdi 保存至 string 的 ptr 字段，即 SBO
   0x0040121e <+30>:    mov    %esi,%ebx         # 将 b 的值保存至 ebx
   0x00401220 <+32>:    xor    $0x5,%rbx         # 将 0x5 异或到 rbx（也即 ebx）
                                                 # 注意，如果 rbx 非 0 即 1，那么 rbx 保存的就是 4 或 5，
                                                 # 即 "true" 或 "false" 的长度 
   0x00401224 <+36>:    mov    %rax,%rsi         # 将字符串起始地址保存至 rsi，即 memcpy 的第二个参数
   0x00401227 <+39>:    mov    %rbx,%rdx         # 将字符串的长度保存至 rdx，即 memcpy 的第三个参数
   0x0040122a <+42>:    callq  <memcpy@plt>      # 调用 memcpy
   0x0040122f <+47>:    mov    %rbx,0x8(%r14)    # 将字符串长度保存到 string::size
   0x00401233 <+51>:    movb   $0x0,0x10(%r14,%rbx,1)  # 将 string 以 '\0' 结尾
   0x00401239 <+57>:    mov    %r14,%rax         # 将 string 地址保存至 rax，即返回值
   0x0040123c <+60>:    add    $0x8,%rsp
   0x00401240 <+64>:    pop    %rbx
   0x00401241 <+65>:    pop    %r14
   0x00401243 <+67>:    retq
End of assembler dump.
```

到这里，问题就无比清晰了：

1. clang++ 假设了 `bool` 类型的值非 `0` 即 `1`
1. 在编译期，`”true”` 和 `”false”` 长度已知
1. 使用异或指令（ `0x5 ^ false == 5`, `0x5 ^ true == 4`）计算要拷贝的字符串的长度
1. 当 `bool` 类型不符合假设时，长度计算错误
1. 因为 `memcpy` 目标地址在栈上（仅对本例而言），因此栈上的缓冲区也可能溢出，从而导致程序跑飞，backtrace 缺失。

注：

1. C++ 标准要求 `bool` 类型至少**能够**表示两个状态： `true` 和 `false` ，但并没有规定 `sizeof(bool)` 的大小。但在几乎所有的编译器实现上， `bool` 都占用一个寻址单位，即字节。因此，从存储角度，取值范围为  `0x00-0xFF`，即 `256` 个状态。

喜欢这篇文章？来来来，给我们的 [GitHub](https://github.com/vesoft-inc/nebula-graph) 点个 star 表鼓励啦~~ 🙇‍♂️🙇‍♀️ [手动跪谢]

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

# 推荐阅读

- [一次 Segmentation Fault 和 GCC Illegal Instruction 编译问题排查](https://nebula-graph.com.cn/posts/segmentation-fault-gcc-illegal-instruction-trouble-shooting/)



一个有意思的 Crash 探究过程，Clang 有 GCC 没有

记一起由 Clang 编译器优化触发的 Crash


​![Docker 调试进程](https://www-cdn.nebula-graph.com.cn/nebula-blog/debug-docker-processes.png)

## 需求

在开发或者测试过程中，我们经常会用到 [vesoft-inc/nebula-docker-compose](https://github.com/vesoft-inc/nebula-docker-compose) 这个 repo 下的部署方式，因为当初为了尽可能的压缩每个 [NebulaGraph](https://github.com/vesoft-inc/nebula) 服务的 docker 镜像的体积，所以开发过程中常用的一切工具都没有安装，甚至连编辑器 VIM 都没有。

这给我们在容器内部定位问题带来一定的难度，因为每次只能去 install 一些工具包，才能开展接下来的工作，甚是费事。其实调试容器内部的进程还有另外一种方式，不需要破坏原有容器的内容，也不用在其中安装任何的工具包就能像在本地一样来调试。

这种技术在 k8s 环境下其实已经挺常用，就是 sidecar 模式。原理也比较朴素就是再起一个容器然后让这个容器跟你要调试的容器共享相同的 pid/network 的 namespace。这样原容器中的进程和网络空间在调试容器中就能“一览无余”，而在调试容器中安装了你想要的一切顺手工具，接下来的舞台就是留于你发挥了。

## 演示

接下来我就演示一下如何操作：

我们先用上述的 docker-compose 方式在本地部署一套 NebulaGraph 集群，教程见 repo 中的 README。部署好后的结果如下：

```bash
$ docker-compose up -d
Creating network "nebula-docker-compose_nebula-net" with the default driver
Creating nebula-docker-compose_metad1_1 ... done
Creating nebula-docker-compose_metad2_1 ... done
Creating nebula-docker-compose_metad0_1 ... done
Creating nebula-docker-compose_storaged2_1 ... done
Creating nebula-docker-compose_storaged1_1 ... done
Creating nebula-docker-compose_storaged0_1 ... done
Creating nebula-docker-compose_graphd_1    ... done
$ docker-compose ps
              Name                             Command                       State                                             Ports
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
nebula-docker-compose_graphd_1      ./bin/nebula-graphd --flag ...   Up (health: starting)   0.0.0.0:32907->13000/tcp, 0.0.0.0:32906->13002/tcp, 0.0.0.0:3699->3699/tcp
nebula-docker-compose_metad0_1      ./bin/nebula-metad --flagf ...   Up (health: starting)   0.0.0.0:32898->11000/tcp, 0.0.0.0:32896->11002/tcp, 45500/tcp, 45501/tcp
nebula-docker-compose_metad1_1      ./bin/nebula-metad --flagf ...   Up (health: starting)   0.0.0.0:32895->11000/tcp, 0.0.0.0:32894->11002/tcp, 45500/tcp, 45501/tcp
nebula-docker-compose_metad2_1      ./bin/nebula-metad --flagf ...   Up (health: starting)   0.0.0.0:32899->11000/tcp, 0.0.0.0:32897->11002/tcp, 45500/tcp, 45501/tcp
nebula-docker-compose_storaged0_1   ./bin/nebula-storaged --fl ...   Up (health: starting)   0.0.0.0:32901->12000/tcp, 0.0.0.0:32900->12002/tcp, 44500/tcp, 44501/tcp
nebula-docker-compose_storaged1_1   ./bin/nebula-storaged --fl ...   Up (health: starting)   0.0.0.0:32903->12000/tcp, 0.0.0.0:32902->12002/tcp, 44500/tcp, 44501/tcp
nebula-docker-compose_storaged2_1   ./bin/nebula-storaged --fl ...   Up (health: starting)   0.0.0.0:32905->12000/tcp, 0.0.0.0:32904->12002/tcp, 44500/tcp, 44501/tcp
```

这时我们分两个场景来演示，一个是进程空间，一个是网络空间。首先我们要先有一个顺手的调试镜像，我们就不自己构建了，从 docker hub 中找个已经打包好的用作演示，后期觉得不够用，我们可以维护一份 nebula-debug 的镜像，安装我们想要的所有调试工具，此处先借用社区内的方案 [nicolaka/netshoot](https://hub.docker.com/r/nicolaka/netshoot)。我们先把镜像拉取到本地：

```shell
$ docker pull nicolaka/netshoot
$ docker images
REPOSITORY               TAG                 IMAGE ID            CREATED             SIZE
vesoft/nebula-graphd     nightly             c67fe54665b7        36 hours ago        282MB
vesoft/nebula-storaged   nightly             5c77dbcdc507        36 hours ago        288MB
vesoft/nebula-console    nightly             f3256c99eda1        36 hours ago        249MB
vesoft/nebula-metad      nightly             5a78d3e3008f        36 hours ago        288MB
nicolaka/netshoot        latest              6d7e8891c980        2 months ago        352MB
```

我们先看看直接执行这个镜像会是什么样：

```bash
$ docker run --rm -ti nicolaka/netshoot bash
bash-5.0# ps
PID   USER     TIME  COMMAND
    1 root      0:00 bash
    8 root      0:00 ps
bash-5.0#
```

上面显示这个容器看不到任何 NebulaGraph 服务进程的内容，那么我们给其加点参数再看看：

```bash
$ docker run --rm -ti --pid container:nebula-docker-compose_metad0_1 --cap-add sys_admin nicolaka/netshoot bash
bash-5.0# ps
PID   USER     TIME  COMMAND
    1 root      0:03 ./bin/nebula-metad --flagfile=./etc/nebula-metad.conf --daemonize=false --meta_server_addrs=172.28.1.1:45500,172.28.1.2:45500,172.28.1.3:45500 --local_ip=172.28.1.1 --ws_ip=172.28.1.1 --port=45500 --data_path=/data/meta --log_dir=/logs --v=15 --minloglevel=0
  452 root      0:00 bash
  459 root      0:00 ps
bash-5.0# ls -al /proc/1/net/
total 0
dr-xr-xr-x    6 root     root             0 Sep 18 07:17 .
dr-xr-xr-x    9 root     root             0 Sep 18 06:55 ..
-r--r--r--    1 root     root             0 Sep 18 07:18 anycast6
-r--r--r--    1 root     root             0 Sep 18 07:18 arp
dr-xr-xr-x    2 root     root             0 Sep 18 07:18 bonding
-r--r--r--    1 root     root             0 Sep 18 07:18 dev
...
-r--r--r--    1 root     root             0 Sep 18 07:18 sockstat
-r--r--r--    1 root     root             0 Sep 18 07:18 sockstat6
-r--r--r--    1 root     root             0 Sep 18 07:18 softnet_stat
dr-xr-xr-x    2 root     root             0 Sep 18 07:18 stat
-r--r--r--    1 root     root             0 Sep 18 07:18 tcp
-r--r--r--    1 root     root             0 Sep 18 07:18 tcp6
-r--r--r--    1 root     root             0 Sep 18 07:18 udp
-r--r--r--    1 root     root             0 Sep 18 07:18 udp6
-r--r--r--    1 root     root             0 Sep 18 07:18 udplite
-r--r--r--    1 root     root             0 Sep 18 07:18 udplite6
-r--r--r--    1 root     root             0 Sep 18 07:18 unix
-r--r--r--    1 root     root             0 Sep 18 07:18 xfrm_stat
```
这次有点不一样了，我们看到 metad0 的进程了，并且其 pid 还是 1。看到这个进程再想对其做点啥就好办了，比如能不能直接在 gdb 中 attach 它，由于手边没有带 nebula binary 的对应 image，就留给大家私下探索吧。

我们已经看到 pid 空间通过指定 `--pid container:<container_name|id>` 可以共享了，那么我们接下来看看网络的情况，毕竟有时候需要抓个包，执行如下的命令：

```bash
bash-5.0# netstat -tulpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
```
啥也没有，跟预想的有点不一样，我们有 metad0 这个进程不可能一个连接都没有。要想看到这个容器内的网络空间还要再加点参数，像如下方式再启动调试容器：
```bash
$ docker run --rm -ti --pid container:nebula-docker-compose_metad0_1 --network container:nebula-docker-compose_metad0_1 --cap-add sys_admin nicolaka/netshoot bash
bash-5.0# netstat -tulpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 172.28.1.1:11000        0.0.0.0:*               LISTEN      -
tcp        0      0 172.28.1.1:11002        0.0.0.0:*               LISTEN      -
tcp        0      0 0.0.0.0:45500           0.0.0.0:*               LISTEN      -
tcp        0      0 0.0.0.0:45501           0.0.0.0:*               LISTEN      -
tcp        0      0 127.0.0.11:33249        0.0.0.0:*               LISTEN      -
udp        0      0 127.0.0.11:51929        0.0.0.0:*                           -
```

这回就跟上面的输出不一样了，加了 `--network container:nebula-docker-compose_metad0_1` 运行参数后，metad0 容器内的连接情况也能看到了，那么想抓包调试就都可以了。

# 总结

通过运行另外一个容器，并让其跟想要调试的容器共享 pid/network namespace 是我们能像本地调试的关键。社区里甚至还有人基于上述想法开发了一些小工具进一步方便使用：

- [Docker-debug](https://github.com/zeromake/docker-debug)

## 推荐阅读

- [使用 Docker 构建 NebulaGraph 源码](https://nebula-graph.com.cn/posts/build-nebula-graph-source-code-with-docker/)




本文主要介绍如何不破坏原有容器的内容，也不用在其中安装任何的工具包前提下，像在本地一样来调试 NebulaGraph 进程

调试 Docker 容器内部的 NebulaGraph 进程


![sql-vs-ngql](https://www-cdn.nebula-graph.com.cn/nebula-blog/sql-vs-ngql.png)

这篇文章将介绍图数据库 **NebulaGraph** 的查询语言 [nGQL](https://docs.nebula-graph.com.cn/manual-CN/1.overview/1.concepts/2.nGQL-overview/) 和 [SQL](https://baike.baidu.com/item/%E7%BB%93%E6%9E%84%E5%8C%96%E6%9F%A5%E8%AF%A2%E8%AF%AD%E8%A8%80/10450182) 的区别。不过我们不会深入探讨这两种语言，而是将这两种语言做对比，以帮助您从 SQL 过渡到 nGQL。

SQL (Structured Query Language) 是具有数据操纵和数据定义等多种功能的数据库语言，这种语言是一种[特定目的编程语言](https://zh.wikipedia.org/wiki/%E7%89%B9%E5%AE%9A%E7%9B%AE%E7%9A%84%E7%A8%8B%E5%BC%8F%E8%AF%AD%E8%A8%80)，用于管理[关系数据库管理系统](https://zh.wikipedia.org/wiki/%E5%85%B3%E7%B3%BB%E6%95%B0%E6%8D%AE%E5%BA%93%E7%AE%A1%E7%90%86%E7%B3%BB%E7%BB%9F)（RDBMS），或在[关系流数据管理系统](https://zh.wikipedia.org/wiki/%E5%85%B3%E7%B3%BB%E6%B5%81%E6%95%B0%E6%8D%AE%E7%AE%A1%E7%90%86%E7%B3%BB%E7%BB%9F)（RDSMS）中进行流处理。

[nGQL](https://docs.nebula-graph.com.cn/master/3.ngql-guide/1.nGQL-overview/1.overview/) 是一种类 SQL 的声明型的文本查询语言，相比于 SQL， nGQL 为可扩展、支持图遍历、模式匹配、分布式事务（开发中）的图数据库查询语言。

# 概念对比
| 对比项 | SQL | nGQL |
| --- | --- | --- |
| 点 | \\ | 点 |
| 边 | \\ | 边 |
| 点类型 | \\ | tag |
| 边类型 | \\ | edge type |
| 点 ID | 主键 | vid |
| 边 ID | 复合主键 | 起点、终点、rank |
| 列 | 列 | 点或边的属性 |
| 行 | 行 | 点或边 |

# 语法对比

## 数据定义语言 (DDL)

数据定义语言（DDL）用于创建或修改数据库的结构，也就是 schema。

| 对比项 | SQL | nGQL |
| --- | --- | --- |
| 创建图空间（数据库） | CREATE DATABASE `<database_name>` | CREATE SPACE `<space_name>` |
| 列出图空间（数据库） | SHOW DATABASES | SHOW SPACES |
| 使用图空间（数据库） | USE `<database_name>` | USE `<space_name>` |
| 删除图空间（数据库） | DROP DATABASE `<database_name>` | DROP SPACE `<space_name>` |
| 修改图空间（数据库） | ALTER DATABASE `<database_name>` alter_option | \\ |
| 创建 tags/edges | \\ | CREATE TAG &#124; EDGE `<tag_name>` |
| 创建表 | CREATE TABLE `<tbl_name>` (create_definition,...) | \\ |
| 列出表列名 | SHOW COLUMNS FROM `<tbl_name>` | \\ |
| 列出 tags/edges | \\ | SHOW TAGS &#124; EDGES |
| Describe tags/edge | \\ | DESCRIBE TAG &#124; EDGE `<tag_name | edge_name>` |
| 修改 tags/edge | \\ | ALTER TAG &#124; EDGE `<tag_name | edge_name>` |
| 修改表 | ALTER TABLE `<tbl_name>` | \\ |

### 索引

| 对比项 | SQL | nGQL |
| --- | --- | --- |
| 创建索引 | CREATE INDEX | CREATE {TAG &#124; EDGE} INDEX |
| 删除索引 | DROP INDEX | DROP {TAG &#124; EDGE} INDEX |
| 列出索引 | SHOW INDEX FROM | SHOW {TAG &#124; EDGE} INDEXES |
| 重构索引 | ANALYZE TABLE | REBUILD {TAG &#124; EDGE} INDEX `<index_name>` [OFFLINE] |

## 数据操作语言（DML）

数据操作语言（DML）用于操作数据库中的数据。

| 对比项   | SQL                                                          | nGQL                                                         |
| :------- | :----------------------------------------------------------- | ------------------------------------------------------------ |
| 插入数据| INSERT IGNORE INTO `<tbl_name>` [(col_name [, col_name] ...)] {VALUES &#124; VALUE} [(value_list) [, (value_list)] | INSERT VERTEX `<tag_name>` (prop_name_list[, prop_name_list]) {VALUES &#124; VALUE} vid: (prop_value_list[, prop_value_list])   INSERT EDGE `<edge_name>` ( `<prop_name_list>` ) VALUES &#124; VALUE `<src_vid>` -> `<dst_vid>`[`@<rank>`] : ( `<prop_value_list>` ) |
| 查询数据 | SELECT                                                       | GO, FETCH                                                    |
| 更新数据 | UPDATE `<tbl_name>` SET field1=new-value1, field2=new-value2 [WHERE Clause] | UPDATE VERTEX `<vid>` SET `<update_columns>` [WHEN `<condition>`]    UPDATE EDGE `<edge>` SET `<update_columns>` [WHEN `<condition>`] |
| 删除数据 | DELETE FROM `<tbl_name>` [WHERE Clause]                      | DELETE EDGE `<edge_type>` `<vid>` -> `<vid>`[`@<rank>`] [, `<vid>` -> `<vid>` ...]    DELETE VERTEX `<vid_list>` |
| 拼接数据 | JOIN                                                         | `|`                                                          |

## 数据查询语言（DQL）

数据查询语言（DQL）语句用于执行数据查询。本节说明如何使用 SQL 语句和 nGQL 语句查询数据。

```sql
SELECT
 [DISTINCT]
 select_expr [, select_expr] ...
 [FROM table_references]
 [WHERE where_condition]
 [GROUP BY {col_name | expr | position}]
 [HAVING  where_condition]
 [ORDER BY {col_name | expr | position} [ASC | DESC]]
```

```sql
GO [[<M> TO] <N> STEPS ] FROM <node_list>
 OVER <edge_type_list> [REVERSELY] [BIDIRECT]
 [WHERE where_condition]
 [YIELD [DISTINCT] <return_list>]
 [| ORDER BY <expression> [ASC | DESC]]
 [| LIMIT [<offset_value>,] <number_rows>]
 [| GROUP BY {col_name | expr | position} YIELD <col_name>]

<node_list>
   | <vid> [, <vid> ...]
   | $-.id

<edge_type_list>
   edge_type [, edge_type ...]

<return_list>
    <col_name> [AS <col_alias>] [, <col_name> [AS <col_alias>] ...]
```

## 数据控制语言（DCL）

数据控制语言（DCL）包含诸如 `GRANT` 和 `REVOKE` 之类的命令，这些命令主要用来处理数据库系统的权限、其他控件。


| 对比项 | SQL | nGQL |
| --- | --- | --- |
| 创建用户 | CREATE USER | CREATE USER |
| 删除用户 | DROP USER | DROP USER |
| 更改密码 | SET PASSWORD | CHANGE PASSWORD |
| 授予权限 | GRANT `<priv_type>` ON [object_type] TO `<user>` | GRANT ROLE `<role_type>` ON `<space>` TO `<user>` |
| 删除权限 | REVOKE `<priv_type>` ON [object_type] TO `<user>` | REVOKE ROLE `<role_type>` ON `<space>` FROM `<user>` |

# 数据模型

查询语句基于以下数据模型：

## RDBMS 关系结构图

![RDBMS](https://www-cdn.nebula-graph.com.cn/nebula-blog/RDBMS.png)

## NebulaGraph 最小模型图

![Studio](https://www-cdn.nebula-graph.com.cn/nebula-blog/Studio.png)

本文将使用 NBA 数据集。该数据集包含两种类型的点，也就是两个标签，即 `player` 和 `team` ；两种类型的边，分别是 `serve` 和 `follow`。

在关系型数据管理系统中（RDBMS）中，我们用表来表示点以及与点相关的边（连接表）。因此，我们创建了以下表格：`player`、`team`、`serve` 和 `follow`。在 **NebulaGraph** 中，基本数据单位是顶点和边。两者都可以拥有属性，相当于 RDBMS 中的属性。

在 **NebulaGraph** 中，点之间的关系由边表示。每条边都有一种类型，在 NBA 数据集中，我们使用边类型 `serve` 和 `follow` 来区分两种类型的边。

# 示例数据

## 在 RDBMS 插入数据

首先，让我们看看如何在 RDBMS 中插入数据。我们先创建一些表，然后为这些表插入数据。

```sql
CREATE TABLE player (id INT, name VARCHAR(100), age INT);
CREATE TABLE team (id INT, name VARCHAR(100));
CREATE TABLE serve (player_id INT, team_id INT, start_year INT, end_year INT);
CREATE TABLE follow (player_id1 INT, player_id2 INT, degree INT);
```

然后插入数据。

```sql
INSERT INTO player
VALUES
   (100, 'Tim Duncan', 42),
   (101, 'Tony Parker', 36),
   (102, 'LaMarcus Aldridge', 33),
   (103, 'Rudy Gay',32),
   (104, 'Marco Belinelli', 32),
   (105, 'Danny Green', 31),
   (106, 'Kyle Anderson', 25),
   (107, 'Aron Baynes', 32),
   (108, 'Boris Diaw', 36),
   (109, 'Tiago Splitter', 34),
   (110, 'Cory Joseph', 27);

INSERT INTO team
VALUES
   (200, 'Warriors'),
   (201, 'Nuggets'),
   (202, 'Rockets'),
   (203, 'Trail'),
   (204, 'Spurs'),
   (205, 'Thunders'),
   (206, 'Jazz'),
   (207, 'Clippers'),
   (208, 'Kings');

INSERT INTO serve
VALUES
   (100,200,1997,2016),
   (101,200,1999,2010),
   (102,200,2001,2005),
   (106,200,2000,2011),
   (107,200,2001,2009),
   (103,201,1999,2018),
   (104,201,2006,2015),
   (107,201,2007,2010),
   (108,201,2010,2016),
   (109,201,2011,2015),
   (105,202,2015,2019),
   (109,202,2017,2019),
   (110,202,2007,2009);

INSERT INTO follow
VALUES
   (100,101,95),
   (100,102,91),
   (100,106,90),
   (101,100,95),
   (101,102,91),
   (102,101,75),
   (103,102,70),
   (104,103,50),
   (104,105,60),
   (105,104,83),
   (105,110,87),
   (106,100,88),
   (106,107,81),
   (107,106,92),
   (107,108,97),
   (108,109,95),
   (109,110,78),
   (110,109,72),
   (110,105,85);
```

## 在 NebulaGraph 插入数据

在 **NebulaGraph** 中插入数据与上述类似。首先，我们需要定义好数据结构，也就是创建好 schema。然后可以选择手动或使用 NebulaGraph Studio（NebulaGraph 的可视化工具）导入数据。这里我们手动添加数据。

在下方的 `INSERT` 插入语句中，我们向图空间 NBA 插入了球员数据（这和在 MySQL 中插入数据类似）。

```cpp
INSERT VERTEX player(name, age) VALUES
100: ('Tim Duncan', 42),
101: ('Tony Parker', 36),
102: ('LaMarcus Aldridge', 33),
103: ('Rudy Gay', 32),
104: ('Marco Belinelli', 32),
105: ('Danny Green', 31),
106: ('Kyle Anderson', 25),
107: ('Aron Baynes', 32),
108: ('Boris Diaw', 36),
109: ('Tiago Splitter', 34),
110: ('Cory Joseph', 27);
```

考虑到篇幅限制，此处我们将跳过插入球队和边的重复步骤。你可以点击[此处](https://oss-cdn.nebula-graph.io/doc/example_data.zip)下载示例数据亲自尝试。

![Nebula-Graph-Studio](https://www-cdn.nebula-graph.com.cn/nebula-blog/Nebula-Graph-Studio.png)

# 增删改查（CRUD）

本节介绍如何使用 SQL 和 nGQL 语句创建（C）、读取（R）、更新（U）和删除（D）数据。

## 插入数据

```sql
mysql> INSERT INTO player VALUES (100, 'Tim Duncan', 42);

nebula> INSERT VERTEX player(name, age) VALUES 100: ('Tim Duncan', 42);
```

## 查询数据

查找 ID 为 100 的球员并返回其 `name` 属性：

```sql
mysql> SELECT player.name FROM player WHERE player.id = 100;

nebula> FETCH PROP ON player 100 YIELD player.name;
```

## 更新数据

```sql
mysql> UPDATE player SET name = 'Tim';

nebula> UPDATE VERTEX 100 SET player.name = "Tim";
```

## 删除数据

```sql
mysql> DELETE FROM player WHERE name = 'Tim';

nebula> DELETE VERTEX 121;
nebula> DELETE EDGE follow 100 -> 200;
```

# 建立索引

返回年龄超过 36 岁的球员。

```sql
SELECT player.name
FROM player
WHERE player.age < 36;
```

使用 nGQL 查询有些不同，因为您必须在过滤属性之前创建索引。更多信息请参见 [索引文档](https://www.yuque.com/nebulagraph/2.query-language/4.statement-syntax/1.data-definition-statements/index.md)。

```cpp
CREATE TAG INDEX player_age ON player(age);
REBUILD TAG INDEX player_age OFFLINE;
LOOKUP ON player WHERE player.age < 36;
```

# 示例查询

本节提供一些示例查询供您参考。

## 示例 1

在表 `player` 中查询 ID 为 100 的球员并返回其 `name` 属性。

```sql
SELECT player.name
FROM player
WHERE player.id = 100;
```

接下来使用 **NebulaGraph** 查找 ID 为 100 的球员并返回其 `name` 属性。

```cpp
FETCH PROP ON player 100 YIELD player.name;
```

**NebulaGraph** 使用 `FETCH` 关键字获取特定点或边的属性。本例中，属性即为点 100 的名称。nGQL 中的 `YIELD` 关键字相当于 SQL 中的 `SELECT`。

## 示例 2

查找球员 Tim Duncan 并返回他效力的所有球队。

```sql
SELECT a.id, a.name, c.name
FROM player a
JOIN serve b ON a.id=b.player_id
JOIN team c ON c.id=b.team_id
WHERE a.name = 'Tim Duncan'
```

使用如下 nGQL 语句完成相同操作：

```cpp
CREATE TAG INDEX player_name ON player(name);
REBUILD TAG INDEX player_name OFFLINE;
LOOKUP ON player WHERE player.name == 'Tim Duncan' YIELD player.name AS name | GO FROM $-.VertexID OVER serve YIELD $-.name, $$.team.name;
```

这里需要注意一下，在 nGQL 中的等于操作采用的是 C 语言风格的 `==`，而不是SQL风格的 `=`。

## 示例 3

以下查询略复杂，现在我们来查询球员 Tim Duncan 的队友。

```sql
SELECT a.id, a.name, c.name
FROM player a
JOIN serve b ON a.id=b.player_id
JOIN team c ON c.id=b.team_id
WHERE c.name IN (SELECT c.name
FROM player a
JOIN serve b ON a.id=b.player_id
JOIN team c ON c.id=b.team_id
WHERE a.name = 'Tim Duncan')
```

nGQL 则使用管道将前一个子句的结果作为下一个子句的输入。

```cpp
GO FROM 100 OVER serve YIELD serve._dst AS Team | GO FROM $-.Team OVER serve REVERSELY YIELD $$.player.name;
```

您可能已经注意到了，我们仅在 SQL 中使用了 `JOIN`。这是因为 **NebulaGraph** 只是使用类似 Shell 的管道对子查询进行嵌套，这样更符合我们的阅读习惯也更简洁。

# 参考资料

我们建议您亲自尝试上述查询语句，这将帮您更好地理解 SQL 和 nGQL，并节省您上手 nGQL 的学习时间。以下是一些参考资料：

- [NebulaGraph Studio 用户指南](https://github.com/vesoft-inc/nebula-studio)
- [NebulaGraph GitHub 仓库](https://github.com/vesoft-inc/nebula)
- [NebulaGraph 快速入门文档](https://docs.nebula-graph.com.cn/)

> 作者有话说：Hi，Hi ，大家好，我是 Amber，NebulaGraph 的文档工程师，希望上述内容可以给大家带来些许启发。限于水平，如有不当之处还请斧正，在此感谢^^

喜欢这篇文章？来来来，给我们的 [GitHub](https://github.com/vesoft-inc/nebula-graph) 点个 star 表鼓励啦~~ 🙇‍♂️🙇‍♀️ [手动跪谢]

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~



这篇文章将介绍图数据库 NebulaGraph 的查询语言 nGQL 和 SQL 的区别。

文档解读 ｜ SQL vs. nGQL


![D3显示优化](https://www-cdn.nebula-graph.com.cn/nebula-blog/D3显示优化.png)

# 前言
在上篇文章中（[D3.js 力导向图的显示优化](https://nebula-graph.com.cn/posts/d3-force-layout-optimization/)），我们说过 [D3.js](https://d3js.org/) 在自定义图形上相较于其他开源可视化库的优势，以及如何对文档对象模型（DOM）进行灵活操作。既然 D3.js 辣么灵活，那是不是实现很多我们想做的事情呢？在本文中，我们将借助 [D3.js](https://d3js.org/) 的灵活性这一优势，去新增一些 D3.js 本身并不支持但我们想要的一些常见的功能。

# 构建 D3.js 力导向图

在这里我们就不再细说 d3-force 粒子物理运动模块原理，感兴趣同学可以看看我们的[上篇](https://nebula-graph.com.cn/posts/d3-force-layout-optimization/#d3-force%E5%8A%9B%E5%AF%BC%E5%90%91%E5%9B%BE)的简单描述, 本次实践我们侧重于可视化操作的功能实现。

好的，进入我们的实践时间，我们还是以 D3.js 力导向图对图数据库的数据关系进行分析为目的，增加一些我们想要功能。

首先，我们用 [d3-force](https://d3js.org.cn/document/d3-force/#installing) 力导向图来构建一个简单的关联网

```javascript
this.force = d3
        .forceSimulation()
        // 为节点分配坐标
        .nodes(data.vertexes)
        // 连接线
        .force('link', linkForce)
        // 整个实例中心
        .force('center', d3.forceCenter(width / 2, height / 2))
        // 引力
        .force('charge', d3.forceManyBody().strength(-20))
        // 碰撞力 防止节点重叠
        .force('collide',d3.forceCollide().radius(60).iterations(2));
```

通过上述代码，我们可以得到下面这样一个可视化的节点和关系图。

![NebulaGraph Studio](https://www-cdn.nebula-graph.com.cn/nebula-blog/Nebula-Graph-Studio.png)

这里我们简单介绍下上图，上图为图数据库 NebulaGraph 可视化工具 Studio 的图探索功能截图，在业务上，图探索支持用户任意选中某个点进行拓展，找寻、显示同它存在某种关系的点，例如上图点 100 和 点 200 存在单向 follow 关系。

上图数据量并不大，如果我们在拓展时返回的数据量较大或多步拓展出来的数据逐步累加显示，则会导致当前视图页节点和边极多，页面需呈现的数据信息量大，且也不好找到想要的某个节点。好的，一个新场景上线了：用户只想分析图中的部分节点数据，不想看到全部的节点信息。删除任意选中这个新功能就可以很好地应对上面场景，删除不需要的节点信息，只留下想探索的部分节点数据。

# 支持删除任意选中功能

在实现这个功能之前，我先开始介绍下 D3.js 自带 API。没错，还是[上篇](https://nebula-graph.com.cn/posts/d3-force-layout-optimization/#%E5%AE%9E%E7%8E%B0%E6%8B%93%E5%B1%95%E6%9F%A5%E8%AF%A2%E6%98%BE%E7%A4%BA%E4%BC%98%E5%8C%96)提及的 D3.js 的 [enter()](https://www.d3js.org.cn/#enter%E5%92%8Cexit%E6%93%8D%E4%BD%9C) 及没提到的 [exit()](https://www.d3js.org.cn/#enter%E5%92%8Cexit%E6%93%8D%E4%BD%9C)

摘自文档的描述：

> 数据绑定的时候可能出现 `DOM` 元素与数据元素个数不匹配的问题， `enter` 和 `exit` 就是用来处理这个问题的。`enter` 操作用来添加新的 `DOM` 元素，`exit` 操作用来移除多余的 `DOM` 元素。
> 如果数据元素多于 `DOM` 个数时用 `enter`，如果数据元素少于 `DOM`元素，则用 `exit`。
> 在数据绑定时候存在三种情形：
> - 数据元素个数多于 `DOM` 元素个数
> - 数据元素与 `DOM` 元素个数一样
> - 数据元素个数少于 `DOM` 元素个数


根据文档描述，想实现删除任意选中功能还是很简单的，乐观的笔者想当然地认为直接在数据层面进行操作就行。于是笔者直接在 nodes 数据里删除选中的节点数据 node，然后根据官方用法 `d3.select(this.nodeRef).exit().remove()` 移除多余的元素，好的，我们现在来看看这样做会带来了什么？

![D3移除元素](https://www-cdn.nebula-graph.com.cn/nebula-blog/D3移除元素.png)

不想选中的节点是删除了，但其他节点的显示也乱了，节点颜色和属性同当前 DOM 节点对不上，为什么会这样呢？笔者又仔仔细细地看了一遍上面的文档描述，灵光一闪，来，先打印下 exit().remove() 的节点，看看到底它 remove 哪些节点？

果然是它，D3.js enter().exit() 的触发其实是在监听元素的个数的变化，也就是说，如果总个数缺少了两个，它确实会触发 exit() 方法，但是它处理的数据不是真正需删除的数据，而是当前 nodes 数据最后两个节点。说白了 enter()、exit() 的触发原理，是 D3.js 监听当前数据的长度变化来触发的。然而 D3.js 在获取数据长度变化之后，以 exit() 为例，对单个数据的处理方法是根据长度的减量 N 截取数据数组位置中最后 N 位到最后一位区间的所有元素，enter() 则相反，会在数组位置中最后一个元素后面增加 N 个数据。

所以，如果选中删除的是之前拓展探索出来的节点（它不是当前数据数组位置的最后一个元素），进行删除操作时，虽然从我们的 nodes 数据里面删除了这个数据，但是在已经存在的视图中，d3.select(this.nodeRef).exit() 方法定位到的操作元素却是最后一个，这样显示就乱套了，那么，我们该如何处理这个问题呢？

这里就直接分享下我的方法，简单粗暴但有效——显然这个 exit() 并不能满足删除选中节点的业务需求，那我们单独地处理需删除的节点。我们定位到真实删除的节点 DOM 进行操作，为此我们需要在渲染时给每个节点绑定一个 ID，然后再进行遍历，根据已删除的节点数据找到这些需要删除的节点对应的 DOM，以下为我们的处理代码：

```javascript
  componentDidUpdate(prevProps) {
    const { nodes } = this.props;
    if (nodes.length < prevProps.nodes.length) {
      const removeNodes = _.differenceBy(
        prevProps.nodes,
        nodes,
        (v: any) => v.name,
      );
      removeNodes.forEach(removeNode => {
        d3.select('#name_' + removeNode.name).remove();
      });
    } else {
      this.labelRender(this.props.nodes);
    }
  }
```

其实在这里需要处理的不仅仅定位到当前真实删除节点的 DOM，还需要将它所关联的边、显示文案一并删除。因为没有起点/终点的边，是没有任何意义的，边、文案的处理方法同点删除的逻辑类似，这里不做赘述。

# 支持按钮缩放功能

说完删除选中点，在可视化视图中缩放操作也是比较常见的功能，D3.js 中的 [d3.zoom()](https://www.d3js.org.cn/document/d3-zoom/#api-reference) 就是用来实现缩放功能的，且该方法经过其他厂的业务考验相对来说成熟稳定，那我们还有什么理由要自己做呢？（要啥自行车 😂）。

其实缩放功能纯粹是交互改动层面上的一个功能。采用滚轮控制缩放的方案的话，不了解 NebulaGraph Studio 的用户很难发现这种隐藏操作，而且滚动控制缩放无法控制缩放的明确比例，举个例子，用户想缩放 30% / 50%，对于这种限定的比例，滚动控制缩放就无能为力了。除此之外，笔者在实施滚轮缩放的过程中发现滚动缩放会影响节点和边的位置偏移，这又是什么原因造成的呢？

通过查看 d3.zoom() 代码，我们发现 D3.js 本质是获取事件中 d3.event 的缩放值再针对整个画布修改 transform 属性值，但这样处理 svg 中的节点和边元素 x、y 坐标不发生变化，所以导致 d3.zoom() 实现缩放功能时，放大画布，视图会往坐左上方偏移（因为对画布来说，相较视图中的边元素 x、y 坐标，自己变小了），缩小画布，视图会往右下方偏移。

发现问题形成的原因是解决问题的第一步，下面来解决下问题，在进行缩放时添加一个节点和边相对画布大小偏移量的变化处理逻辑，好的，那开始操作吧。

我们先弄一个滑动条控件提供给用户进行手动控制缩放画布的比例，直接用 antd 的[滑动条](https://ant.design/components/slider-cn/)，根据它滑动的的值来控制整个画布缩放比例，下面直接贴代码了

```javascript
 <svg
  width={width}
  viewBox={`0 0 ${width * (1 + scale)}  ${height * (1 + scale)}`}
  height={height}
  >
 {/*****/}
</svg>
```

上面代码中的 scale 参数是我们根据控件滚动条中缩放值来生成的，我们需要记录这个值来放大画布（svg 元素)，从来造成视图缩小的效果的。

此外，我们处理下上面提到的节点和边偏移问题时也需要 scale 值，因为我们需要给节点和边设置一个反偏移量。简单的说，画布放大 scale 倍，节点和边的 x、y 位置也要相对画布偏移当前的 scale 倍，这样就能保持在缩放过程中，节点和边位置相对画布大小变化而保持不变。下面就是处理节点缩放过程中偏移的关键代码

```javascript
 const { width, height } = this.props;
    const scale = (100 - zoomSize) / 100;
    const offsetX = width * (scale / 2);
    const offsetY = height * (scale / 2);
    // 操作节点边父元素 DOM <g/> 的偏移
    d3.select(this.circleRef).attr(
      'transform',
      `translate(${offsetX} ${offsetY})`,
    );
```

# 结语

好了，以上便是笔者使用 D3.js 力导向图实现关系网的在自定义功能过程中思路和方法。不得不说，D3.js** **的自由度真的高，我们可以尽情地开脑洞实现我们想要的功能。

在这次分享中，笔者分享了图数据库可视化业务中 2 个实用且用户高频使用的功能：任意选中删除节点、自定义缩放并优化视图偏移功能。说到可视化展示一个复杂的关系网，需要考虑的问题还很多，需要优化的交互和显示的地方也很多，我们会持续优化，后续我们会更新 D3.js 优化系列文，[欢迎订阅 NebulaGraph 博客](https://nebula-graph.com.cn/posts/)。

喜欢这篇文章？来来来，给我们的 [GitHub](https://github.com/vesoft-inc/nebula-graph) 点个 star 表鼓励啦~~ 🙇‍♂️🙇‍♀️ [手动跪谢]

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

> 作者有话说：Hi，我是 Nico，是 NebulaGraph 的前端工程师，对数据可视化比较感兴趣，分享一些自己的实践心得，希望这次分享能给大家带来帮助，如有不当之处，欢迎帮忙纠正，谢谢~



在本文中，我们将借助 D3.js 的灵活性这一优势，去新增一些 D3.js 本身并不支持但我们想要的一些常见的功能：NebulaGraph 图探索的删除节点和缩放功能

D3.js 力导向图的显示优化（二）- 自定义功能


![static-site-generator-hugo](https://www-cdn.nebula-graph.com.cn/nebula-blog/static-site-generator-hugo.png)

# 前言

建站工具，早已不是一个新颖的话题，抛开可视化建站单论开发层面，各类语言都有推出广受欢迎的建站框架，比如 Python 开发的 [Pelican](https://github.com/getpelican/pelican)，JavaScript 开发的 [Hexo](https://github.com/hexojs/hexo)，以及市场份额占比最大的 PHP 开发的 [WordPress](https://github.com/WordPress/WordPress) 等等，这些笔者在折腾个人博客时多少都有用过。但当需要**快速搭建**起我们的 [NebulaGraph 官网](https://nebula-graph.com.cn/) 时，小小纠结对比之后，笔者选择了 Golang 语言的 [Hugo](https://gohugo.io/) 来作为我们的技术方案，下面就来分享下个人使用 Hugo 建站的一些个人思考和经验分享。

P.S: 客观来说，各类语言的博客类型框架并无太大差别，更多还是类比语言的个人喜好与审美不同，在此不做叙述。

# 实践介绍

## 我们的需求

- 博客系统，需要支持运营发布我们日常的[技术文章资讯](https://nebula-graph.com.cn/posts/)

Hugo 有灵活强大的内容管理系统，能随着需求，不断增加不同类型的资讯支持，诸如博客、Release Note、技术文档等，详细后面会介绍。

- 品宣介绍，常见就是站点首页、新闻介绍等

同样依赖内容管理系统，能很快支持到不同页面的实现，包括相同组件如导航、页脚等的共享，后面也会介绍。

- SEO 需要

Hugo 本就是类似服务端模板语言的 Web 框架，天然的服务端渲染。

- 国际化支持，Nebula 注重国内外开发者的访问体验

Hugo 能渐进地拓展支持多国语言，只要你有对应的语料配置，就能迅速支撑需求并方便管理。

- 灵活易于管理，能让非技术的运营同学也能参与站点的内容管理

强大的模板系统，让技术人员专心开发完对应模板后，能将内容管理交给运营同学持续运营。

## 特点介绍

### 灵活强大的内容管理系统

```markdown
...
├── config // 模板需要的内容语料
|   ├── default 
|   |   ├── config.toml
|   |   └── config.cn.toml
|   |   └── config.en.toml
|   |   └── footer.cn.toml
|   |   └── footer.en.toml
|   |   └── ...
├── content // 内容部分，日常多由运营同学管理维护
|   ├── en // 国际化支持
|   |   ├── posts // 内置默认的博客（post)类型资讯
|   |   |   ├── post-01.md
|   |   |   ├── post-02.md
|   |   └── release // 新增的 release 类型资讯
|   |   |   ├── release-01.md
|   |   |   └── release-02.md
|   ├── cn
|   |   ├── posts
|   |   |   ├── post-01.md
|   |   |   ├── post-02.md
|   |   └── release
|   |   |   ├── release-01.md
|   |   |   └── release-02.md
...
├── themes // 站点的主题
|   ├── nebula-theme // 主题名
|   |   ├── layout // 模板
|   |   |   ├── _default // 默认的模板
|   |   |   |   ├── baseof.html // 渲染的种子页面定义
|   |   |   |   ├── list.html  // 默认博客 post 类型资讯 - 列表页的使用模板页面
|   |   |   |   ├── single.html // 默认博客 post 类型资讯 - 详情页使用模板页面
|   |   |   ├── partials // 复用的模板片段
|   |   |   |   ├── head.html
|   |   |   |   ├── footer.html
|   |   |   |   ├── menus.html
|   |   |   |   ├── ...
|   |   |   ├── index.html // 首页（'/') 默认会使用的模板
|   |   |   ├── section
|   |   |   |   ├── release.html // 新增资讯类型 release 渲染时使用的模板页面 - 发布历史页面
|   |   |   |   ├── news.html // 新增资讯类型 news 渲染时使用的模板页面 - 媒体新闻页面
...
```
以上，便是 Hugo 用以支撑起灵活强大的模板系统所采用的项目结构，笔者感觉比较能直观反映出对于不同站点需求的支持，它甚至还可以是不断嵌以此结构不断嵌套，外层的配置覆盖内层的，更多信息可以参考官方的[模板系统介绍](https://gohugo.io/templates/)。

### 内置丰富工具集

除了强大的内容管理系统外，Hugo 还有很多很好用的内置模板及工具函数，满足不同需求情况下提升搭建效率，抽象实现细节，更专注于站点的搭建，诸如：

- 资源类型列表的分页模板 - [Pagination](https://gohugo.io/templates/pagination/)

这个针对只有列表页的需求，比如博客，发版历史，新闻类等，好用的分页模板，轻松的就帮你完成了。

- 资源 RSS 模板 - [RSS](https://gohugo.io/templates/rss/)

对于资讯型的站点必不可少，官方已内置了默认的 rss 模板，只需要添加一行代码，即可搞定 rss，当然还支持个性化定制。

- 各类内容及字符串处理工具函数 - [Functions](https://gohugo.io/functions/)

这个不用多说，对应程序中的各类常见的字符串替换，Hugo 都有着良好的支持，同时它还支持类似 Pipe 管道的方式，将处理内容以 | 分隔层层传递下去，就像我们在 Linux 输入的命令一样。

- 好用的 CLI 工具

内置了 http server 方便本地开发，同时又能将整个站点打包成纯静态的资源，方便了对于部署的操作和维护成本，可以一键初始化并启动项目，开箱即用的感觉，上手容易。

- 好用的内容管理工具
   - 迅速提取博客内容的目录导航 - [TableOfContents](https://gohugo.io/content-management/toc/#readout)
  使用此工具函数，会根据你当前的文章内容，提取目录概要，节省了生成锚点内容的时间。
   - 便捷获取文章的概览内容 - [Summary](https://gohugo.io/content-management/summaries/)
   - 便捷获取文章的图片资源 - [Image Processing](https://gohugo.io/content-management/image-processing/)
   - 自定义 URL 的规则 -  [URL Management](https://gohugo.io/content-management/urls/)

以上便是我们在实践中，有接触过的一些 Hugo 比较好用的工具，当然它提供的远比这个更丰富，更多工具可查看[参考官方文档](https://gohugo.io/about/)。

### 社区资源丰富

- 生态很好，现成大量的主题可供选择

作为 Golang 语言最受欢迎的站点框架，随着越来越多人的使用，Hugo 官方鼓励大家开源自己的主题，约定了简易可行的规范，让贡献者的主题能在 Hugo 官网方便地被他人找到，易于复用。非技术的同学，也可以找到符合自己需求的主题，不用写一行 HTML 代码，也能让自己生成自己的站点。

- 答疑途径多样
   - 作为一个 45k+ star 的项目，使用人群众多，知识沉淀很好，网上搜索能解决大部分问题。
   - 有在线的[论坛](https://discourse.gohugo.io/)，维护者也相当活跃，只要提问得当，能及时得到回复，解决疑难杂症。
   - [官方文档](https://gohugo.io/documentation/) 的内容组织，层次也比较清晰，从笔者个人使用来看，体验还是很好的。

# 经验总结

除了上面偏向于 Hugo 本身提供的功能介绍外，下面结合笔者自身的实践经历，阐述一些小小的经验总结，方便后来的朋友：

### 使用现成的主题

基于 DIY 原则来说，结合自身需求，去主题市场找一个符合自己的主题来进行修改，应该是上手最快的方式了，甚至不需要开发就能拿来直接用，即使需要开发，使用他人已开发好的主题，由于 Hugo 框架本身具有很好的约定规范，你也能很快了解到一个 Hugo 项目的结构组成及运行机制，降低调研上手成本。

### 项目结构和内容关系

就像前面介绍的内容管理系统，从结构上了解内容 contents 与模板 layouts 之间的映射关系，适当结合官网文档的[介绍](https://gohugo.io/content-management/organization/)，了解这层映射关系后，能方便在后续的开发过程中，让你的实践更符合 Hugo 期望的形式来进行，这样会让你不论是实现，还是在阅读 Hugo 文档的时候，事半功倍，易于理解。

### 个人定制

除了 Hugo 本身的框架、规范及工具能力外，因为网页的代码最终还是离不开 HTML/CSS/Javascript，自定义相关的内容，只要善用提供的规则（如各个模板的引用，组合），就能在各个模板入口引入你想自己控制的代码部分，为你自己的站点添砖加瓦。结合我们自身的实践，比如第三方站点插件的集成（埋点统计，Discourse、ShareThis等等），一些自定义弹窗等动态 js 的添加，所以只要熟悉网页的常规开发，除了 Hugo 的能力外，你可以做到你以往可做的任何事情。

### 纯静态站点

Hugo 打包构建后输出的是一个纯静态的资源包，这样地好处就是你可以将你的站点部署在任何地方，比如使用 GitHub 免费的 [Pages](https://pages.github.com/)，又或者是随便放在 oss 源中，没有维护服务器，数据库的烦恼。纯静态资源部署很便捷，以 Hugo 为例，他的路由适合文件目录相关的，我们的站点有中英文两个语言版本，开发时都放在一个项目中进行维护共享模板，在构建部署时，会根据语言打成不同的资源包，分别发到不同的国内外 Web 容器，以此优化访问体验。

# 最后

以上便是笔者使用 Hugo 框架搭建公司 [NebulaGraph 官网](https://nebula-graph.com.cn/) 的一些实践心得，希望给有快速建站需求的朋友提供一些思路和参考，我们的站点是基于已有主题二次开发，更多细节感兴趣的朋友也可以看看我们放在 GitHub 的[源站仓库](https://github.com/vesoft-inc/nebula-website)。

也欢迎大家来了解我们的 [NebulaGraph 图数据库产品](https://github.com/vesoft-inc/nebula) 或者前往官方论坛：[https://discuss.nebula-graph.com.cn/](https://discuss.nebula-graph.com.cn/) 的 `建议反馈` 分类下提建议 👏；交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

> 作者有话说：Hi，我是 Jerry，是图数据 NebulaGraph 前端工程师，在前端平台工具开发及工程化方面有些小心得，希望写的经验分享能给大家带来帮助，如有不当之处也希望能帮忙纠正，谢谢~



基于 Golang 语言的 Hugo 来作为 NebulaGraph 建站的技术方案，本文主要分享下前端工程师使用 Hugo 建站的一些个人思考和经验分享。

Hugo 建站经验之谈


![钉钉机器人](https://www-cdn.nebula-graph.com.cn/nebula-blog/ding-ding-chat-bot.png)

在日常工作中，你是否遇到以下场景：

- Github 存在多个 repo，日常工作中需要一个个地手动筛选大量待 merge 的 pull requests
- 要找出多个 repo 中 `ready to review` 的 pull requests，要手动筛选，然后一遍又一遍地粘贴复制提交 dev 进行 review #倍感无聊
- 想自动推送 GitHub 待 merge 的 prs，GitHub Webhooks 却没有该 Event
- ……

用技术来解决 PM 枯燥的 approval pr 工作，本文将阐述如何自动化获取 GitHub Organization 下各个 repo 待 merge 的 pull requests 并通知相关人员，告别每日的手动操作。此文主要提供了解决自动发送 approval prs 的思路，并以钉钉群和 Slack 为例，给出了其 Python 的实现方式，如果你使用其他通讯工具，实现原理是相通的。

# 配置消息接收

## 配置钉钉群机器人

1. 打开机器人管理页面。以 PC 端为例，打开 PC 端钉钉，点击“群设置” => “智能群助手” => “添加机器人”。

![dignding-chat-bot](https://www-cdn.nebula-graph.com.cn/nebula-blog/dignding-chat-bot.png)

2. 点击“添加机器人”，选择“自定义”

![钉钉机器人](https://www-cdn.nebula-graph.com.cn/nebula-blog/钉钉机器人.png)

本例的“安全设置”使用自定义关键词的方式，之后给机器人所发送的消息中必须包含此处设置的关键词。

3. 点击“完成”，获取 Webhook

详细的钉钉 bot 配置文档可参见官方文档：[https://ding-doc.dingtalk.com/doc#/serverapi2/qf2nxq/26eaddd5](https://ding-doc.dingtalk.com/doc#/serverapi2/qf2nxq/26eaddd5)

## 配置 Slack bot

- 创建一个 app（链接：[https://api.slack.com/apps](https://api.slack.com/apps)），设置 App Name，选择目标 Slack Workspace
- 在左侧栏中选择 “Basic Information” => “Add features and functionality” 选在 “Bots”

![slack-bot](https://www-cdn.nebula-graph.com.cn/nebula-blog/slack-bot.png)

- 在左侧栏中选择 “OAuth & Permissions”，在 “Scopes” 中点击 “Add an OAuth Scope”，添加 `chat:write.public` 
- 点击 “Install App to Workspace”
- 获取 OAuth Access Token

详细的 Slack bot 配置步骤参见官方英文文档：[https://slack.com/intl/en-cn/help/articles/115005265703-Create-a-bot-for-your-workspace#add-a-bot-user](https://slack.com/intl/en-cn/help/articles/115005265703-Create-a-bot-for-your-workspace#add-a-bot-user)

# 配置 Github 获取 Personal Access Tokens

生成 Token，赋予相应权限。在此例中，读取了 Organization 下所有 Public 和 Private Repos，需要勾选 repo。

![generate-github-tokens](https://www-cdn.nebula-graph.com.cn/nebula-blog/generate-github-tokens.gif)

详细 GitHub Token 配置步骤参见官方文档：[https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)

# 代码说明

## 获取 Github 待 merge pr

[PyGithub](https://github.com/PyGithub/PyGithub) 提供了访问 Github V3 API 的功能，可以让你用代码去实现 GitHub 上的操作，可通过 `pip install pygithub` 进行安装。

```
FILTER_TEMPLATE = "repo:{org}/{repo} is:pr is:open review:approved"

class GithubPrList:

    @property
    def gh(self):
        return self._gh

    @property
    def org(self):
        return self._org

    FILTER_TEMPLATE = "repo:{org}/{repo} is:pr is:open review:approved"

    def __init__(self,
                 org,
                 repo,
                 login_or_token,
                 password=None,
                 timeout=DEFAULT_CONNECT_TIMEOUT,
                 retry=None,
                 ):
        """
        :param org: string
        :param repo: string
        :param login_or_token: string，token or username
        :param password: string
        :param timeout: integer
        :param retry: int or urllib3.util.retry.Retry object
        """
        #实例化对 Github API v3 的访问
        self._gh = Github(login_or_token=login_or_token,
                          password=password,
                          timeout=timeout,
                          retry=retry)
        self._org = org
        self._repo = repo

		def getIssues(self,
                   		 filter=None,
                       sort=DEFAULT_PR_SORT,
                       order=DEFAULT_ORDER,
                       ):
        """
        :param filter: string
        :param order: string ('asc', 'desc')
        :param sort: string('comments', 'created', 'updated')
        :rtype :class:`List` of :class:`PrList2.PrElement`
        """
        if not filter:
        		#生成查询的 filter，指定org/repo 下已经approved 的pr
            filter = self.FILTER_TEMPLATE.format(org=self._org,
                                                 repo=self._repo)
        #查询
        issues = self._gh.search_issues(filter, sort, order)
        prList = []

        for issue in issues:
            prList.append(PrElement(issue.number, issue.title, issue.html_url))

        return prList
```

函数说明：

- `__init__` 支持使用 username/ password 或者 token 去实例化对 GitHub API V3的访问（英语是 instantiate to access the Github API v3）。
- 在 Github 中，pull requests 也是 issues，`getIssues()` 函数允许用户可使用默认条件（`repo:{org}/{repo} is:pr is:open review:approved`）查找指定 org/repo 下状态是 Approved 的 pull requests，也就是待 merge 的 prs。其中:

| Qualifier | 说明 |
| --- | --- |
| repo:org_/_repo | 查找指定组织 repo 下的projects |
| is:pr | 查找 pull requests |
| is:open | 查找 open 的 issues |
| review:approved | 查找 review 状态是已经 approved，review status 可能取值 _none_、_required_、_approved_、_changes requested_ |

用户也可指定 Github issues 的筛选条件，使用示例：

```
filter = "repo:myOrg/myRepo is:pr is:open review:approved"
GithubPrList(self.org, 
							self.repo, 
              self.token).getIssues(filter)
```

更多筛选条件，请参见官方文档：[https://help.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests](https://help.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests)

## 发送消息

### 发送钉钉消息

DingtalkChatbot 对钉钉消息类型进行了封装。本文使用此工具发送待 merge 的 pr 到钉钉群，可通过 `pip install DingtalkChatbot` 安装 DingtalkChatbot。

```
from dingtalkchatbot.chatbot import DingtalkChatbot

webhook = "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxx"
atPerson = ["123xxx456","123xxx678"]

xiaoding = DingtalkChatbot(webhook)
xiaoding.sendMsg({自定义关键词} + "上文中的 pr list", atPerson)
```

将消息发送到钉钉群，此处需要用到上文中的钉钉群机器人的 Webhook 和自定义的关键词。

### 发送 slack 消息

[Python slackclient](https://github.com/slackapi/python-slackclient) 是 Slack 开发的官方 API 库，能够从 Slack 频道中获取信息，也能将信息发送到Slack频道中，支持 Python 3.6 及以上版本。可通过 `pip3 install slackclient` 进行安装。

```
from slack import WebClient
from slack.errors import SlackApiError

client = WebClient(token={your_token})

try:
    response = client.chat_postMessage(
        channel='#{channel_name}',
        text="Hello world!")
    assert response["message"]["text"] == {pr_list}
except SlackApiError as e:
    # You will get a SlackApiError if "ok" is False
    assert e.response["ok"] is False
    assert e.response["error"]  # str like 'invalid_auth', 'channel_not_found'
    print(f"Got an error: {e.response['error']}")
```

用上文配置的 token 替换此处的 {your_token}，替换 {channel_name}，将 pr_list 发送给目标 channel。

至此，大功告成！来看看效果

![dingding-chat-bot-demo](https://www-cdn.nebula-graph.com.cn/nebula-blog/dingding-chat-demo.png)


本文中如有任何错误或疏漏，欢迎去 GitHub：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula) issue 区向我们提 issue 或者前往官方论坛：[https://discuss.nebula-graph.com.cn/](https://discuss.nebula-graph.com.cn/) 的 `建议反馈` 分类下提建议 👏；交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

> 作者有话说：Hi，Hi，我是 Jude，图数据 NebulaGraph 的 PM，欢迎大家提需求，虽然不一定都会实现，但是我们会认真评估^ ^



用技术来解决 PM 枯燥的 approval pr 工作，本文将阐述如何自动化获取 GitHub Organization 下各个 repo 待 merge 的 pull requests 并通知相关人员，告别每日的手动操作。