suanpan-go-sdk组件开发说明
1 前言
用户在算盘上开发组件，就需要使用到SDK。SDK能够实现下列的作用：
- 在算盘平台上消息队列之间的通讯功能。
- 在算盘平台上临时文件和配置的存储功能。
- 在算盘平台上获取右面板的参数，
总的来说，用户代码调用了SDK，然后将所有代码和依赖库打包成docker镜像，在算盘网页上制作一个组件，填写做好的docker镜像的url，就可以完成一个组件的开发。此文会介绍SDK的使用并且展示一个实例。
2 SDK目录介绍
suanpan-go-sdk/
├── config //环境配置
│ └── args.go
│ └── env.go
├── examples //使用例子
│ └── main.go
├── logkit //日志
├── mq //消息队列配置
├── scripts //构建sdk的脚本
├── storage //存储配置
├── suanpan //Go组件定义
├── util //函数包
├── web //网络配置
...
SDK包含了构成组件所需要的库和头文件。拿到SDK之后，就可以使用标准的Go语言进行开发。如果您的主语言要是Python/Nodejs/Java/C等其他语言，需要使用算盘的其他语言的SDK。SDK支持Windows和Linux两个操作系统。注意Windows下推荐使用Visual Studio来进行开发。
| 平台 | 镜像类型 | 开发环境 |
|---|---|---|
| 算盘私有云/公有云 | docker | 任意 |
| 算盘Windows客户端 | 包含exe的文件夹 | Visual Studio 2019 |
SDK对于用户来说，跟调用一个普通的Go库没有区别。在SDK内部，用户必须用到的库和头文件有：
├── github.com/xuelang-group/suanpan-go-sdk/suanpan/v1/app //基础应用
├── github.com/xuelang-group/suanpan-go-sdk/suanpan/v1/log //日志
├── github.com/xuelang-group/suanpan-go-sdk/suanpan/v1/stream //流计算
3 SDK涉及的算盘概念介绍
3.1 环境变量
用户可以在算盘的右面板做一些初始化的参数配置。当节点启动的时候可以去获取这些配置，在SDK里面是以环境变量的接口暴露出来。可以传入环境变量的名称得到环境变量的值。
3.2 消息队列
算盘模板上节点和节点之间的数据传递使用了消息队列技术。当用户调用SDK往消息队列发送数据之后，指定了端口和数据，那么下一个节点对应的端口会收到发送的数据。消息从一个节点发出之后，接收方和接收端口是由算盘的后面板流程图决定的。由于算盘是一个多进程技术，每一个节点是一个进程，消息队列是一个单独的进程，负责在节点之间搬运数据。当节点数据处理不过来时，数据将会被缓存在消息队列里面，直到节点处理完当前数据并且开始接收下一个消息队列中的数据。
3.3 配置文件
算盘上的某个节点可能因为业务关系需要保存自己的数据。当算盘模板被释放，这个节点的生命周期就已经结束了，这也就意味着这个节点所在的进程被终止。因为算盘上使用了docker技术，docker被运行之后写入的文件都会在临时区域。算盘模板被释放，也就是docker被释放之后，算盘上的节点数据都会被删除。所以如果算盘上的节点需要保存数据，需要将数据保存在另一个区域。
配置文件节点可以让节点将自己的配置文件保存在oss/minio存储上面，节点释放了之后，配置文件不会被删除。当节点再次被启动，需要自行从oss/minio上面将自己的配置加载回来。
3.4 临时文件
算盘节点和节点之间的数据传递目前只能走文本形式，如字符串，json等。图片、模型等大型二进制文件并不在消息队列之间传递。目前的做法是将二进制文件存储在临时文件区域，然后存储之后会得到一个链接，将此连接通过消息队列发送给下一个节点。下一个节点根据此链接得到文件的路径，最后得到文件即完成整个流程。
4 组件开发流程
用户开发算盘组件包括下面几个流程。
4.1 接入算盘go-sdk的接口
用户将自己的代码接入到C-SDK的接口（消息队列，本地存储，后面板参数等），对组件之间的文本传递可以之间使用消息队列，对于图片等大文件的通讯先使用本地存储接口将文件存储，然后将uri通过消息队列发出。最后暴露给用户的接口是后面板参数接口，用户可以通过读取后面板参数来做一些功能的设置。
4.2 打包应用为docker
对于算盘上的每一个组件都是一个docker，用户需要写一个dockerfile来将整个应用打包成docker，并且上传到docker服务器中。
4.3 在算盘网页上面添加组件
上面两步已经将组件核心功能做好，接下来就是在算盘的网页上，新建一个组件，填入docker地址/启动命令/后面板参数等界面设置，这一步完成之后，组件就已经做好了。
4.4 测试组件功能
新建模板，从组件列表搜索/拉出组件并部署，测试其功能是否正常。
5 开发实例
5.1 安装依赖
开发实例依赖SDK中的样例目录。首先准备一台虚拟机，安装centos 7.9版本。然后将sdk拷贝到虚拟机中。
展示SDK的目录如下。
$ suanpan-go-sdk#
├── config //环境配置
│ └── args.go
│ └── env.go
├── examples //使用例子
│ └── main.go
├── logkit //日志
├── mq //消息队列配置
├── scripts //构建sdk的脚本
├── storage //存储配置
├── suanpan //Go组件定义
├── util //函数包
├── web //网络配置
如果是第一次使用SDK，需要运行一下scripts目录下的install.sh，他会帮助你将依赖环境安装上。
5.2 打包docker
在suanpan-go-sdk路径下执行scripts目录下的build.sh，即可将此docker打包。
$ suanpan-c-sdk_x64_1.2.23# ./examples/suanpan/docker/build.sh
[root@localhost suanpan-go-sdk]# ./scripts/build.sh
Sending build context to Docker daemon 241.2kB
Step 1/12 : FROM golang:1.16
---> 972d8c0bc0fc
Step 2/12 : WORKDIR /usr/src/app
---> Using cache
---> 1db6282ea9ae
Step 3/12 : ENV GOPROXY=https://goproxy.cn
---> Using cache
---> a133bbc8dead
Step 4/12 : COPY ./go.mod ./
---> Using cache
---> fad0969f1381
Step 5/12 : COPY ./go.sum ./
---> Using cache
---> 32e881606f36
Step 6/12 : COPY ./example/main.go ./
---> Using cache
---> 5a665172de0a
Step 7/12 : COPY . .
---> 82d2633ad237
Step 8/12 : RUN go mod download
---> Running in c6579b6888c5
...
latest: digest: sha256:15180261ae15c703000440212586f93c756b05026b23c75486c2176aa29b2863 size: 3471
最终形成三个镜像：
- registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development:0
- registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development:0_0.0.1
- registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development:latest
[root@localhost suanpan-go-sdk]# docker images | grep suanpan_go
registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development 0 d28daa69a9ef 5 minutes ago 1.14GB
registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development 0_0.0.1 d28daa69a9ef 5 minutes ago 1.14GB
registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development latest d28daa69a9ef 5 minutes ago 1.14GB
将此镜像保存到本地文件file.tar，然后拷贝到算盘私有云的机器：
docker save registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development:0 -o file.tar
在算盘私有云上加载此docker
E:\GO>docker load -i ./file.tar
89fda00479fc: Loading layer [==================================================>] 129.1MB/129.1MB
26d5108b2cba: Loading layer [==================================================>] 11.3MB/11.3MB
48144a6f44ae: Loading layer [==================================================>] 19.31MB/19.31MB
e3f84a8cee1f: Loading layer [==================================================>] 156.5MB/156.5MB
6c14e994de3a: Loading layer [==================================================>] 230.2MB/230.2MB
0a1d4a3b8621: Loading layer [==================================================>] 394.8MB/394.8MB
c9e1d21878c4: Loading layer [==================================================>] 3.072kB/3.072kB
0ba389f65486: Loading layer [==================================================>] 3.072kB/3.072kB
5abc8e085d2c: Loading layer [==================================================>] 4.096kB/4.096kB
9acbd0e0f3d0: Loading layer [==================================================>] 19.46kB/19.46kB
6fe794a174a2: Loading layer [==================================================>] 4.096kB/4.096kB
d1821120a92d: Loading layer [==================================================>] 247.8kB/247.8kB
d285807a2f7d: Loading layer [==================================================>] 160.5MB/160.5MB
e646b158f9d0: Loading layer [==================================================>] 51.24MB/51.24MB
e02b5514db71: Loading layer [==================================================>] 17.84MB/17.84MB
Loaded image: registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development:0
5.3 在算盘上面添加组件界面
在算盘上新建一个空白模板，然后点击加号，添加一个服务组件。
然后对组件名称进行填写：
填写Docker镜像类型为: [SuanpanV2]
填写Docker镜像为：registry.xuelangyun.com/shuzhi-amd64/suanpan_go_sdk_development:0
填写入口命令为：/usr/src/app/server
然后点击完成，组件就添加好了。
5.4 测试组件功能
在左边栏目搜索此组件，则可以找到刚才做好的组件。将这个组件拖拽到画布上（画布需要处于编辑模式）。
在左边栏目搜索web input组件，将这个组件拖拽到画布上（画布需要处于编辑模式）。
在左边栏目搜索web output组件，将这个组件拖拽到画布上（画布需要处于编辑模式）。
然后点击运行按钮运行。
运行成功后，点击web input组件，在右面板测试标签页的测试输入窗口中输入测试请求，点击发送请求，即可在测试输出中查看请求结果。
