emqx/apps/emqx_exproto/docs/sdk-specification.md

SDK 规范

动机

SDK 的目的在于方便用户使用 IDE 集成开发、和模拟调试。

位置

    +------------------+
    |   User's Codes   |
    +------------------+
    |       SDK        |    <====   The SDK Located
    +------------------+
    |     Raw APIs     |
    +------------------+
    |      Driver      |
    +==================+
             ||
    +==================+
    |   EMQ X Plugin   |
    +------------------+

因此，SDK 的作用在于封装底层的比较晦涩的数据格式和方法，屏蔽驱动的细节。直接提供优化后的 API 供用户使用。

实现要求

声明： stdin, stdout 已用于和 EMQ X 通信，请不要使用。stderr 用于日志输出。

基础项

1. 必须实现 emqx-exproto 要求的回调函数和 API 接口，并能够暴露给用户使用

2. 可以将 conn() 类型，封装成为一个连接类。并：

   • 将各层的回调函数写为不同的 Interface，连接类实现该 Interface，并强制子类实现其方法。
   • 将各层的 API 接口写为连接类的方法 用户继承该连接类，并实现各个回调。

3. 必须将各个专有的，晦涩的数据类型封装为清晰的类型结构，例如：

   • 连接类型 conn()
   • 连接层信息：conninfo()
   • 客户端信息：clientinfo()
   • 消息：message()

4. 必须要有对应的开发、部署文档说明

高级项

1. 应能方便用户能在 IDE 中进行编译，开发
2. 应提供集成测试用的模拟代码。
   • 例如，生成模拟的数据，发送至用户的程序，方便直接断点调试，而不需要先部署才能使用。
3. 提供日志输出的方法

部署结构

代码依赖结构

从部署的角度看，代码的依赖关系为：

1. 用户代码：
   • 一定会依赖 SDK
   • 允许依赖 某个位置的三方/系统库
2. SDK 代码：
   • 只能依赖 erlport

部署

从文件存放的位置来看，一个标准的部署结构为：

emqx
|
|--- data
|------- extension
|---------- <some-sdk-package-name>
|--------------- <some-classes/scripts-in-sdk>
|---------- <user's classes/scripts>
|
|---------- <another-sdk-package-name>
|--------------- <some-classes/scripts-in-sdk>
|---------- <user's classes/scripts>

它表达了：在 data/extension 目录下安装了两个 SDK，并且用户都基于 SDK 编写了其回调的代码模块。