跳到主要内容

开发插件

概述​

创建好插件工程之后，还需要指定一个调试环境来承载你的插件，此时需要登录 ONES 来对插件代码进行调试。

在使用 ONES CLI 创建功能时，工具会自动为你内置插件开发脚手架工具op。这个工具可以指引并完成ONES系统登录、团队选择以及本地插件前后端服务启动等工作。

请尽可能升级最新的脚手架工具op版本以保证最佳的体验

调试原理​

调试的本质是在本地机器启动前端服务(webpack-dev-server)和后端服务(node-host)来加载运行插件的前端及后端代码。启动后需要使用提前登录ONES获得的凭据与ONES系统进行消息通讯。

  • 前端服务webpack-dev-server: 是一个用于快速开发应用程序的工具，它提供了一个基本的 web 服务器，支持实时重新加载和热模块替换（Hot Module Replacement, HMR）。
  • 后端服务node-host: 由ONES开放平台提供的基于nodejs的宿主程序。

使用​

第一步：登录调试环境​

在插件工程根目录中执行 npx op login 指令进行登录操作，按照提示依次输入调试环境信息。

备注

名词解释

  • base URL : 对应的ONES调试环境 URL，以http://或https://开头。地址与在浏览器端访问ONES的地址一致。
  • host URL : 开放平台调试地址，以tcp://开头，默认端口是30002。中间地址部分取决于对应ONES部署环境下的网络设置情况，建议获取ONES所在的ip地址作为输入地址。
    • 在最新版本中已经取消了这个地址的输入，以op工具提示要求输入为准。
➜ npx op login
? Please enter the environment base URL: http://172.16.80.211:30011
? Username: test1@ones.com
? Password: [hidden]
? Please enter the environment host URL: tcp://172.16.80.211:30002
  ✔ Converting inputted answers to login params
  ✔ Fetching user profile
  ✔ Updating configuration into config/local.yaml
  ✔ Updating scope info into /Users/username/.ones/cli-plugin.yaml
✔ Login successful
? Do you want to execute 'npx op pickteam' for update team information into config file? (Y/n)

登录操作完成后会将「用户凭证」写入工程下的 config/local.yaml 文件中。

如果你创建的是团队级别的插件，那么还会询问你是否需要执行 pickteam 指令进行团队选择操作，当然你也可以在登录操作完成之后，手动执行 npx op pickteam local 来进行团队选择。

备注
  • 完成团队选择后，那么平台就会在对应的远端调试环境的对应团队下帮你安装一个“开发中”的插件。
  • 如果是组织级别插件，那么平台就会将这个插件安装在【组织级别】-【插件管理】中，也意味着该插件对每一个团队都生效。

第二步：启动本地调试​

完成登录和团队的选择后，你可以在工程根目录下执行 npx op invoke run 启动本地调试

➜ npx op invoke run
  ✔ Validating command options
  ✔ Validating config/local.yaml fields
  ✔ Checking ability relate module
  ✔ Updating min_system_version in plugin.yaml
  ✔ Building plugin project Back-End dist files
  ✔ Initializing the plugin project front-end development server
  ✔ Initializing the node-host params and invoke arguments
✔ Local debug parameters successfully initialized with target lifecycle: 'run'
Now starting dev server and node-host...
<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:3000/
<i> [webpack-dev-server] On Your Network (IPv4): http://10.15.3.38:3000/
<i> [webpack-dev-server] On Your Network (IPv6): http://[fe80::1]:3000/
<i> [webpack-dev-server] Content not from webpack is served from '/Users/dev/ONES/open-platform/public' directory
开始连接!
{
  action: 'run',
  email: 'test1@ones.com',
  password: '********',
  reinstall: false,
  webIp: '10.15.3.38',
  webPort: '3000',
  orgUUID: 'KuLvwHJz',
  teamUUID: 'RWqwp2L8',
  user_uuid: 'SFBs7BHh',
  webServiceUrl: '10.15.3.38:3000'
}
本地调试返回值: {"instance_uuid":"1d99926e"}
[Plugin] Install
插件 Install 钩子函数运行成功!
[Plugin] Enable
插件 Enable 钩子函数运行成功!
收到消息:  all done

tunnel异常情况​

在某些情况下可能会遇到类似以下内容的输出：

Checking node-host available with request: https://all-emus-fix.loca.lt/healthz
Node-host available check failed, retry after 3s
Checking node-host available with request: https://all-emus-fix.loca.lt/healthz
Node-host available check failed, retry after 3s
Checking node-host available with request: https://all-emus-fix.loca.lt/healthz
Node-host available check failed, retry after 3s
Checking node-host available with request: https://all-emus-fix.loca.lt/healthz
Node-host available check failed, retry after 3s
  Host are not ready with url https://all-emus-fix.loca.lt, you can try to rerun the command:
    1.after a while
    2.use your self-defined tunnel url with option '--self-tunnel <endpoint>' provided by other tools

这是因为op内置的开源免费工具localtunnel有可能存在网络不稳定的情况。 这种情况下建议选取稳定的tunnel工具，并使用npx op invoke run --self-tunnel来设置该工具提供的tunnelURL。

调试方法​

当你的接口调试出现意料之外的结果，你可以参考我们提供的断点调试方法进行单步调试，进一步定位问题所在。

接口注册与instance_uuid​

instance_uuid是该插件实例在所在调试的ONES系统中的唯一标识，由该ONES系统生成此实例 uuid。并非固定值。

在接口注册场景中，应该使用该instance_uuid进行插件接口的访问，详情见接口注册。

Headers
{
  "Ones-Plugin-Id": "1d99926e", // instance_uuid
  "Ones-Check-Point": "team"
}
提示
  • **Ones-Plugin-Id：**启动调试环境之后在控制台打印出来的“本地调试返回值”中对应的 instance_uuid 的值
  • Ones-Check-Point：
    团队插件：team
    组织插件：organization

第三步：清除调试状态​

修改配置文件​

如果你修改了插件的配置文件（config/plugin.yaml），你可以运行 npx op invoke clear 再重新运行 npx op invoke run 指令，这样配置才能生效。

移除调试中插件​

如果你想移除远程调试环境中显示为“调试中”的插件,你可以运行 npx op invoke clear 后，待见到Receive msg: all done等字样再中断当前进程（如：command + C），这样远程调试环境中的调试插件就被卸载了。

最后由 ones-dev-jenkins 于 更新