diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e3f732793fa8b0d8bc9b99b2565f246b6364dda..b694a4e083a14e0907fe7ebc0f37b00014c0c1b0 100644 --- a/CHANGELOG.md +++ b/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: 修复默认的消息转发器逻辑。 diff --git a/README.md b/README.md index 47d4dbca322c55748970d3a33b6d195af7b8e755..0ad63af124560f17e1b40511e1dcb32e5330f144 100644 --- a/README.md +++ b/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) diff --git a/docs/http-api.md b/docs/http-api.md new file mode 100644 index 0000000000000000000000000000000000000000..36ced57dc037a835e7127da22ece578a1c0b5fc5 --- /dev/null +++ b/docs/http-api.md @@ -0,0 +1,221 @@ +# 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! +``` diff --git a/mica-mqtt-example/src/main/java/net/dreamlu/iot/mqtt/server/MqttServerTest.java b/mica-mqtt-example/src/main/java/net/dreamlu/iot/mqtt/server/MqttServerTest.java index a1113d37152c165357e4c43c63d2afa8d7f102d7..78ea7d8464c98ecb87b719abd3f58f84d39c8f2f 100644 --- a/mica-mqtt-example/src/main/java/net/dreamlu/iot/mqtt/server/MqttServerTest.java +++ b/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(); diff --git a/mica-mqtt-spring-boot-example/src/main/resources/application-dev.yml b/mica-mqtt-spring-boot-example/src/main/resources/application-dev.yml index d1e5bd54c3ef545adcd8fbfb1fbe034d123a5aea..dfdaf1fa8784ecd4eae8a77d4647df1c58c53924 100644 --- a/mica-mqtt-spring-boot-example/src/main/resources/application-dev.yml +++ b/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 diff --git a/mica-mqtt-spring-boot-example/src/main/resources/application-prod.yml b/mica-mqtt-spring-boot-example/src/main/resources/application-prod.yml index c190482097e5f4b5c266af2837aceaee4117398d..dfdaf1fa8784ecd4eae8a77d4647df1c58c53924 100644 --- a/mica-mqtt-spring-boot-example/src/main/resources/application-prod.yml +++ b/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 diff --git a/mica-mqtt-spring-boot-starter/README.md b/mica-mqtt-spring-boot-starter/README.md index 7d7c7eeb99bedde54dcb5c3bb23f0e23b04cfb70..0708b302973ce8c17a32d573c556fc38b410f53c 100644 --- a/mica-mqtt-spring-boot-starter/README.md +++ b/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 即可）