插件开发工具
本节文档介绍如何使用插件开发工具,在上一节的入门文档中已提供了插件开发工具的安装方式。
插件开发工具主要用于生成插件代码框架文件目录,以及运行和测试插件。通过此工具,可以简化开发流程,提高插件开发效率,降低开发门槛。
通过插件开发工具创建的项目是一个标准的python
插件项目,默认基于Python3
编写。
插件开发工具版本
您可以运行以下命令查看插件开发工具的版本:
$ chariot-plugin -v
1.0.1
通过help
命令获得插件开发工具的帮助信息
$ chariot-plugin -h
usage: chariot-plugin [-h] [-v] [-g GENERATE] [-r RUN] [--http] [-t TEST]
插件生成器
optional arguments:
-h, --help show this help message and exit
-v, --version 查看版本
-g GENERATE, --generate GENERATE
插件生成
-r RUN, --run RUN 运行action
--http 启动api接口
-t TEST, --test TEST 测试
...
插件规范定义
在使用插件开发工具创建插件源码目录之前,我们需要对插件的基本信息和功能进行定义,定义的内容将存放在plugin.spec.yaml
文件中。我们把此文件称为“插件规范定义文件”。
plugin.spec.yaml
的具体定义请参阅后续的插件规范文档,本节我们仅介绍一下plugin.spec.yaml
文件的基本格式:
plugin_spec_version: v2
name: example
title: "Example Plugin"
description: "Example plugin for testing"
version: 1.0.0
vendor: chariot
tags: ["example"]
enable_cache: true
status: [ "supported" ]
types:
connection:
triggers:
actions:
str_upcase:
title: String Upcase
description: 将字符串转换成大写
input:
content:
type: string
description: 被转换的字符串
required: true
default: Just do it
output:
result:
title: Upcase String
description: 转换后的的字符串
type: string
required: true
生成插件框架目录
完成对plugin.spec.yaml
规范文件的编写之后,接下来我们将使用插件开发工具来创建插件框架目录。插件框架目录是根据plugin.spec.yaml
规范文件中的定义自动生成的。
首先创建一个文件夹用于存放插件框架目录,然后在该文件夹下使用chariot-plugin-maker generate
命令生成插件框架目录。
$ mkdir example/
$ cd example/
$ vim plugin.spec.yaml
$ chariot-plugin -g plugin.spec.yaml
INFO | readed plugin.spec.yaml
INFO | generated Dockerfile ok
INFO | generated icon.png ok
INFO | generated Makefile ok
INFO | generated requirements.txt ok
INFO | generated SDK ok
INFO | generated SDK/plugin.py ok
INFO | generated SDK/models.py ok
INFO | generated SDK/cli.py ok
INFO | generated SDK/subassembly.py ok
INFO | generated SDK/__init__.py ok
INFO | generated SDK/base.py ok
INFO | generated SDK/chariot.py ok
INFO | generated SDK/web.py ok
INFO | gnerated actions/str_upcase.py ok
INFO | generated tests/str_upcase.json ok
INFO | generated actions/__init__.py ok
INFO | gnerated actions/models.py ok
INFO | gnerated triggers/models.py ok
INFO | generated main.py ok
INFO | generated help.md ok
INFO | All things done successfully ^_^
其中-g
后面的参数plugin.spec.yaml
表示我们定义的plugin.spec.yaml
文件所在的位置。
命令执行成功后,我们看到当前目录下将出现以下文件结构:
$ tree
.
├── actions
│ ├── __init__.py
│ ├── models.py
│ └── str_upcase.py
├── Dockerfile
├── help.md
├── icon.png
├── main.py
├── Makefile
├── plugin.spec.yaml
├── requirements.txt
├── SDK
│ ├── base.py
│ ├── chariot.py
│ ├── cli.py
│ ├── __init__.py
│ ├── models.py
│ ├── plugin.py
│ ├── subassembly.py
│ └── web.py
├── tests
│ └── str_upcase.json
└── triggers
└── models.py
目录中的大部分文件并不需要我们编辑,它们是根据plugin.spec.yaml
中的定义自动创建的。当再次执行-g
命令时这些文件会被覆盖,因此请不要将你的开发代码随便放在这些文件中。
请根据文件中的提示,完成代码中的write your code
部分。
如果你再次改动了plugin.spec.yaml
规范文件,只需要再次执行-g
命令即可更新目录。
运行测试用例
插件开发工具将自动为每个action
和trigger
生成测试文件,测试文件以json
的形式存放在tests
文件夹中。
一个json
测试文件的数据结构如下:
{
"version": "v1",
"type": "action_start",
"body": {
"action": "str_upcase",
"meta": {},
"connection": {},
"dispatcher": null,
"input": {}
}
}
在运行测试之前,首先我们要实现str_upcase
这个action
的功能。我们对chariot_example/actions/str_upcase/action.py
进行如下编辑:
from SDK.subassembly import Actions
from SDK.base import Core
from .models import CONNECTION, STR_UPCASEINPUT, STR_UPCASEOUTPUT
class STR_UPCASEACTIONS(Actions):
def __init__(self):
# 初始化
self.name = "str_upcase"
self.inputModel = STR_UPCASEINPUT
self.outputModel = STR_UPCASEOUTPUT
self.connModel = CONNECTION
def connection(self, data={}):
# write your code
...
def run(self, params={}):
# write your code
# 增加一下代码
content = params.get("content")
return {
"result": content.upper()
}
我们已经实现了一个简单的插件,里面包含一个将字符串转换成大写的动作(action)
,然后我们执行以下命令对该功能进行测试:
在tests/str_upcase.json写入待测试字符串
{
"version": "v1",
"type": "action_start",
"body": {
"action": "str_upcase",
"meta": {},
"connection": {},
"dispatcher": null,
"input": {
"content": "i am lower!"
}
}
}
输出
$ chariot-plugin -r tests/str_upcase.json
{"version": "v1", "type": "action_event", "body": {"output": {"result": "I AM LOWER!"}, "log": "succ", "status": "ok"}}
运行 REST 服务
本功能用于将插件以REST
服务的形式对外提供服务,从而更方便地测试接口。我们使用http
命令来启动REST
服务。< /p>
$ chariot-plugin --http
INFO: Started server process [35657]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:10001 (Press CTRL+C to quit)
INFO: 127.0.0.1:33758 - "GET /docs HTTP/1.1" 200 OK
INFO: 127.0.0.1:33758 - "GET /openapi.json HTTP/1.1" 200 OK
插件REST
服务默认端口为10001
,接口地址为http://127.0.0.1:10001/actions/$ACTION_NAME
。
接下来你也可通过http://127.0.0.1:10001/docs
查看所有接口的openapi
。并测试接口:
插件打包
插件打包功能tarball
可以将当前插件打包成tar.gz
格式,方便插件的移植和安装,你可以把插件包提交到社区或者通过千乘系统本地安装插件。
$ chariot-plugin -tb
[*] Creating plugin tarball
rm -rf build
rm -rf chariot-example-1.0.0.tar.gz
tar -cvzf chariot-example-1.0.0.tar.gz --exclude=chariot-example-1.0.0.tar.gz --exclude=tests --exclude=run.sh *
Dockerfile
Makefile
SDK/
SDK/plugin.py
SDK/__pycache__/
SDK/__pycache__/base.cpython-39.pyc
SDK/__pycache__/chariot.cpython-39.pyc
SDK/__pycache__/__init__.cpython-39.pyc
SDK/__pycache__/web.cpython-39.pyc
SDK/__pycache__/subassembly.cpython-39.pyc
SDK/__pycache__/plugin.cpython-39.pyc
SDK/__pycache__/cli.cpython-39.pyc
SDK/__pycache__/models.cpython-39.pyc
SDK/models.py
SDK/cli.py
SDK/subassembly.py
SDK/__init__.py
SDK/base.py
SDK/chariot.py
SDK/web.py
actions/
actions/str_upcase.py
actions/__pycache__/
actions/__pycache__/str_upcase.cpython-39.pyc
actions/__pycache__/__init__.cpython-39.pyc
actions/__pycache__/models.cpython-39.pyc
actions/models.py
actions/__init__.py
help.md
icon.png
main.py
plugin.spec.yaml
requirements.txt
triggers/
triggers/models.py
插件源码根目录下会出现一个命名为$VENDOR-$NAME-$VERSION.tar.gz
的压缩包。
下一节我们将介绍一些插件组件的基本概念。