✨ 梳理文档。

CHANGELOG.md

@@ -9,6 +9,7 @@
 - :sparkles: 考虑使用 udp 多播做集群。
 - :sparkles: MqttServer、MqttServerTemplate 添加 close、getChannelContext 等方法。
 - :sparkles: 重构 MqttServerConfiguration 简化代码。
+- :sparkles: 配置项 `mqtt.server.websocket-port` 改为 `mqtt.server.web-port`。
 - :memo: 添加 JetBrains 连接。
 - :bug: 修复默认的消息转发器逻辑。
 

README.md

@@ -15,6 +15,7 @@
 ## 功能
 - [x] 支持 MQTT v3.1、v3.1.1 以及 v5.0 协议。
 - [x] 支持 websocket mqtt 子协议（支持 mqtt.js）。
+- [x] 支持 http rest api，[http api 文档详见](docs/http-api.md)。
 - [x] 支持 MQTT client 客户端。
 - [x] 支持 MQTT server 服务端。
 - [x] 支持 MQTT 遗嘱消息。
@@ -54,6 +55,7 @@
 ## 文档
 - [mica-mqtt-spring-boot-starter 使用文档](mica-mqtt-spring-boot-starter/README.md)
 - [mica-mqtt 使用文档](mica-mqtt-core/README.md)
+- [mica-mqtt http api 文档详见](docs/http-api.md)
 - [mica-mqtt 发行版本](CHANGELOG.md)
 - [t-io 官方文档](https://www.tiocloud.com/doc/tio/85)
 - [mqtt 协议文档](https://github.com/mcxiaoke/mqtt)

docs/http-api.md

+# Http Api 接口
+
+### HTTP 状态码 (status codes)
+
+接口在调用成功时总是返回 200 OK，响应内容则以 JSON 格式返回。
+
+可能的状态码如下：
+
+| Status Code | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| 200         | 成功，返回的 JSON 数据将提供更多信息                     |
+| 400         | 客户端请求无效，例如请求体或参数错误                     |
+| 401         | 客户端未通过服务端认证，使用无效的身份验证凭据可能会发生 |
+| 404         | 找不到请求的路径或者请求的对象不存在                     |
+| 405         | 请求方法错误                     						 |
+| 500         | 服务端处理请求时发生内部错误                             |
+
+### 返回码 (result codes)
+
+接口的响应消息体为 JSON 格式，其中总是包含返回码 `code`。
+
+可能的返回码如下：
+
+| Return Code | Description                |
+| ----------- | -------------------------- |
+| 1           | 成功                       |
+| 101         | 关键请求参数缺失           |
+| 102         | 请求参数错误               |
+| 103         | 用户名或密码错误           |
+| 104         | 请求方法错误               |
+| 105         | 未知错误                   |
+
+## 
+
+## 消息发布
+
+### POST /api/v1/mqtt/publish
+
+发布 MQTT 消息。
+
+**Parameters (json):**
+
+| Name     | Type    | Required | Default | Description                                                 |
+| -------- | ------- | -------- | ------- | ----------------------------------------------------------- |
+| topic    | String  | Optional |         | 主题，与 `topics` 至少指定其中之一                          |
+| clientid | String  | Required |         | 客户端标识符                                                |
+| payload  | String  | Required |         | 消息正文                                                    |
+| encoding | String  | Optional | plain   | 消息正文使用的编码方式，目前仅支持 目前仅支持 `plain`、`hex`、`base64` |
+| qos      | Integer | Optional | 0       | QoS 等级                                                    |
+| retain   | Boolean | Optional | false   | 是否为保留消息                                              |
+
+**Success Response Body (JSON):**
+
+| Name | Type    | Description |
+| ---- | ------- | ----------- |
+| code | Integer | 0           |
+
+**Examples:**
+
+```bash
+$ curl -i --basic -u mica:mica -X POST "http://localhost:8083/api/v1/mqtt/publish" -d '{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example"}'
+
+{"code":0}
+ 
+Copied!    
+```
+
+## 主题订阅
+
+### POST /api/v1/mqtt/subscribe
+
+订阅 MQTT 主题。
+
+**Parameters (json):**
+
+| Name     | Type    | Required | Default | Description                                           |
+| -------- | ------- | -------- | ------- | ----------------------------------------------------- |
+| topic    | String  | Optional |         | 主题，与 `topics` 至少指定其中之一                    |
+| clientid | String  | Required |         | 客户端标识符                                          |
+| qos      | Integer | Optional | 0       | QoS 等级                                              |
+
+**Success Response Body (JSON):**
+
+| Name | Type    | Description |
+| ---- | ------- | ----------- |
+| code | Integer | 0           |
+
+**Examples:**
+
+同时订阅 `a`, `b`, `c` 三个主题
+
+```bash
+$ curl -i --basic -u mica:mica -X POST "http://localhost:8083/api/v1/mqtt/subscribe" -d '{"topics":"a,b,c","qos":1,"clientid":"example"}'
+
+{"code":0}
+ 
+Copied! 
+```
+
+### POST /api/v1/mqtt/unsubscribe
+
+取消订阅。
+
+**Parameters (json):**
+
+| Name     | Type   | Required | Default | Description  |
+| -------- | ------ | -------- | ------- | ------------ |
+| topic    | String | Required |         | 主题         |
+| clientid | String | Required |         | 客户端标识符 |
+
+**Success Response Body (JSON):**
+
+| Name | Type    | Description |
+| ---- | ------- | ----------- |
+| code | Integer | 0           |
+
+**Examples:**
+
+取消订阅 `a` 主题
+
+```bash
+$ curl -i --basic -u mica:mica -X POST "http://localhost:8083/api/v1/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'
+
+{"code":0}
+ 
+Copied!
+```
+
+## 消息批量发布
+
+### POST /api/v1/mqtt/publish/batch
+
+批量发布 MQTT 消息。
+
+**Parameters (json):**
+
+| Name         | Type    | Required | Default | Description                                                 |
+| ------------ | ------- | -------- | ------- | ----------------------------------------------------------- |
+| [0].topic    | String  | Optional |         | 主题，与 `topics` 至少指定其中之一                          |
+| [0].clientid | String  | Required |         | 客户端标识符                                                |
+| [0].payload  | String  | Required |         | 消息正文                                                    |
+| [0].encoding | String  | Optional | plain   | 消息正文使用的编码方式，目前仅支持 `plain`、`hex`、`base64` |
+| [0].qos      | Integer | Optional | 0       | QoS 等级                                                    |
+| [0].retain   | Boolean | Optional | false   | 是否为保留消息                                              |
+
+**Success Response Body (JSON):**
+
+| Name | Type    | Description |
+| ---- | ------- | ----------- |
+| code | Integer | 0           |
+
+**Examples:**
+
+```bash
+$ curl -i --basic -u mica:mica -X POST "http://localhost:8083/api/v1/mqtt/publish/batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example"},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example"}]'
+
+{"code":0}
+ 
+Copied!
+```
+
+## 主题批量订阅
+
+### POST /api/v1/mqtt/subscribe/batch
+
+批量订阅 MQTT 主题。
+
+**Parameters (json):**
+
+| Name         | Type    | Required | Default | Description                                           |
+| ------------ | ------- | -------- | ------- | ----------------------------------------------------- |
+| [0].topic    | String  | Optional |         | 主题，与 `topics` 至少指定其中之一                    |
+| [0].clientid | String  | Required |         | 客户端标识符                                          |
+| [0].qos      | Integer | Optional | 0       | QoS 等级                                              |
+
+**Success Response Body (JSON):**
+
+| Name | Type    | Description |
+| ---- | ------- | ----------- |
+| code | Integer | 0           |
+
+**Examples:**
+
+一次性订阅 `a`, `b`, `c` 三个主题
+
+```bash
+$ curl -i --basic -u mica:mica -X POST "http://localhost:8083/api/v1/mqtt/subscribe/batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"},{"topic":"c","qos":1,"clientid":"example"}]'
+
+{"code":0}
+ 
+Copied!
+```
+
+### POST /api/v1/mqtt/unsubscribe/batch
+
+批量取消订阅。
+
+**Parameters (json):**
+
+| Name         | Type   | Required | Default | Description  |
+| ------------ | ------ | -------- | ------- | ------------ |
+| [0].topic    | String | Required |         | 主题         |
+| [0].clientid | String | Required |         | 客户端标识符 |
+
+**Success Response Body (JSON):**
+
+| Name | Type    | Description |
+| ---- | ------- | ----------- |
+| code | Integer | 0           |
+
+**Examples:**
+
+一次性取消订阅 `a`, `b` 主题
+
+```bash
+$ curl -i --basic -u mica:mica -X POST "http://localhost:8083/api/v1/mqtt/unsubscribe/batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"}]'
+
+{"code":0}
+ 
+Copied!
+```

mica-mqtt-example/src/main/java/net/dreamlu/iot/mqtt/server/MqttServerTest.java

@@ -49,6 +49,10 @@ public class MqttServerTest {
 			.messageListener((clientId, topic, mqttQoS, payload) -> {
 				logger.info("clientId:{} topic:{} mqttQoS:{} message:{}", clientId, topic, mqttQoS, ByteBufferUtil.toString(payload));
 			})
+			// 开启 http
+			.httpEnable(true)
+			// http basic 认证，自定义认证，实现 HttpFilter， 注册到 MqttHttpRoutes 即可
+			.httpBasicAuth("mica", "mica")
 			.debug() // 开启 debug 信息日志
 			.start();
 

mica-mqtt-spring-boot-example/src/main/resources/application-dev.yml

@@ -9,8 +9,13 @@ mqtt:
     read-buffer-size: 8092      # 接收数据的 buffer size，默认：8092
     max-bytes-in-message: 8092  # 消息解析最大 bytes 长度，默认：8092
     debug: true                 # 如果开启 prometheus 指标收集建议关闭
+    web-port: 8083              # http、websocket 端口，默认：8083
     websocket-enable: true      # 是否开启 websocket，默认： true
-    websocket-port: 8083        # websocket 端口，默认：8083
+    http-enable: false          # 是否开启 http api，默认： false
+    http-basic-auth:
+      enable: false             # 是否开启 http basic auth，默认： false
+      username: "mica"          # http basic auth 用户名
+      password: "mica"          # http basic auth 密码
   client:
     enabled: true               # 是否开启客户端，默认：false 使用到的场景有限，非必要请不要启用
     ip: 127.0.0.1               # 连接的服务端 ip ，默认：127.0.0.1

mica-mqtt-spring-boot-example/src/main/resources/application-prod.yml

@@ -9,6 +9,13 @@ mqtt:
     read-buffer-size: 8092      # 接收数据的 buffer size，默认：8092
     max-bytes-in-message: 8092  # 消息解析最大 bytes 长度，默认：8092
     debug: true                 # 如果开启 prometheus 指标收集建议关闭
+    web-port: 8083              # http、websocket 端口，默认：8083
+    websocket-enable: true      # 是否开启 websocket，默认： true
+    http-enable: false          # 是否开启 http api，默认： false
+    http-basic-auth:
+      enable: false             # 是否开启 http basic auth，默认： false
+      username: "mica"          # http basic auth 用户名
+      password: "mica"          # http basic auth 密码
   client:
     enabled: true               # 是否开启客户端，默认：false 使用到的场景有限，非必要请不要启用
     ip: 127.0.0.1               # 连接的服务端 ip ，默认：127.0.0.1

mica-mqtt-spring-boot-starter/README.md

@@ -25,16 +25,20 @@
 | mqtt.server.max-bytes-in-message | 8092 | 消息解析最大 bytes 长度，默认：8092 |
 | mqtt.server.max-client-id-length | 23 | mqtt 3.1 会校验此参数，其它协议版本不会 |
 | mqtt.server.debug | false | debug，如果开启 prometheus 指标收集建议关闭 |
+| mqtt.server.web-port | 8083 | http、websocket 端口，默认：8083 |
 | mqtt.server.websocket-enable | true | 开启 websocket 服务，默认：true |
-| mqtt.server.websocket-port | 8083 | websocket 端口，默认：8083 |
+| mqtt.server.http-enable | false | 开启 http 服务，默认：true |
+| mqtt.server.http-basic-auth.enable | false | 是否启用，默认：关闭 |
+| mqtt.server.http-basic-auth.password |  | http Basic 认证密码 |
+| mqtt.server.http-basic-auth.username |  | http Basic 认证账号 |
 
 ### 2.2 配置项示例
 
 ```yaml
 mqtt:
   server:
-    enabled: true               # 是否开启，默认：true
-    ip: 127.0.0.1               # 服务端 ip 默认：127.0.0.1
+    enabled: true               # 是否开启服务端，默认：true
+#    ip: 0.0.0.0                 # 服务端 ip 默认为空，0.0.0.0
     port: 5883                  # 端口，默认：1883
     name: Mica-Mqtt-Server      # 名称，默认：Mica-Mqtt-Server
     buffer-allocator: HEAP      # 堆内存和堆外内存，默认：堆内存
@@ -42,8 +46,13 @@ mqtt:
     read-buffer-size: 8092      # 接收数据的 buffer size，默认：8092
     max-bytes-in-message: 8092  # 消息解析最大 bytes 长度，默认：8092
     debug: true                 # 如果开启 prometheus 指标收集建议关闭
-    websocket-enable: true      # 开启 websocket 子协议，默认开启
-    websocket-port: 8083        # websocket 端口，默认：8083
+    web-port: 8083              # http、websocket 端口，默认：8083
+    websocket-enable: true      # 是否开启 websocket，默认： true
+    http-enable: false          # 是否开启 http api，默认： false
+    http-basic-auth:
+      enable: false             # 是否开启 http basic auth，默认： false
+      username: "mica"          # http basic auth 用户名
+      password: "mica"          # http basic auth 密码
 ```
 
 ### 2.3 可实现接口（注册成 Spring Bean 即可）