80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
# NixMsg Java / Android SDK
|
||
|
||
坐标：`asia.asio.nixmsg:nixmsg-sdk`
|
||
包名：`asia.asio.nixmsg`
|
||
字节码目标：Java 8（`maven.compiler.release=8`）
|
||
接口：`CompletableFuture`
|
||
|
||
## Android
|
||
|
||
最低 API **24**。MQTT 长连接由应用自行放入**前台服务**，SDK 不创建也不托管服务生命周期。
|
||
|
||
## 依赖
|
||
|
||
Maven / Gradle 仓库：
|
||
|
||
```
|
||
https://git.asio.asia/api/packages/nixevol/maven
|
||
```
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>asia.asio.nixmsg</groupId>
|
||
<artifactId>nixmsg-sdk</artifactId>
|
||
<version>0.1.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
HiveMQ MQTT Client（WebSocket：`webSocketConfig` + `netty-codec-http`）。
|
||
|
||
## 最小示例
|
||
|
||
```java
|
||
Client c = new Client();
|
||
c.onSession(token -> { /* 应用保存 */ });
|
||
c.onMessage(msg -> System.out.println(msg.id + " " + msg.body.data));
|
||
c.connect("ws://127.0.0.1:7443/mqtt", "device-1", "secret", null)
|
||
.thenCompose(v -> {
|
||
Types.SendOptions opt = new Types.SendOptions();
|
||
opt.delayMs = 0L;
|
||
return c.send(new Types.Target("endpoint", "device-2"), new Types.Body("hello"), opt);
|
||
})
|
||
.join();
|
||
c.close();
|
||
```
|
||
|
||
命令行示例类：`asia.asio.nixmsg.examples.MinimalExample`。
|
||
|
||
## 行为约定
|
||
|
||
四种 SDK 同一套对外语义，详见仓库 `docs/DEVELOPMENT.md` 第 9 节附录「SDK 行为约定」。要点：
|
||
|
||
- 首次连接默认 30 秒内未握手则停止重连，以 `not_connected` 失败；Client 可再次 `connect`。
|
||
- 顶号原因一律 `taken_over`；DISCONNECT `0x8B` 可重试；CONNECT 不带 Receive Maximum；心跳默认 30 秒。
|
||
- 重连退避只维护一个计数 n：第 n 次等待 `min(1s×2^(n-1), 30s)×随机(0.7,1.3)`。仅 `connect` 后第一次可不等待；断线后首次重连也约 1 秒；在线不足 60 秒断开则 n+1，稳定 60 秒后断开 n=1。
|
||
- `rate_limited` 与断线重交：每次重新生成 `rid` 并重新序列化；消息 `id`、正文、`send_at_ms` 不变。
|
||
- `logout` 请求失败时 future 以异常完成；本地仍停止重连、清空令牌、结束队列并发 `offline`。
|
||
- 时长与时间戳用 `long` / `Long`（含 `updateSelf` 的 `defaultDelayMs`）。`sendAt` 是本机时间（epoch 毫秒或 `java.util.Date`，入队时加偏差）；`sendAtMs` 是服务器时间。两者与 `delayMs` 同时给时本地 `bad_request`。停止重连后再 `send` 立即失败。
|
||
- 取消尚未发出的条目即出队；已发出的返回 `result_unknown`，应用应以同一消息号重试。
|
||
|
||
## 打包（不发布）
|
||
|
||
```bash
|
||
mvn package -DskipTests
|
||
# 产物 target/nixmsg-sdk-0.1.0.jar；勿部署到 Maven 仓库；正式发布由总控在阶段 3 执行
|
||
```
|
||
|
||
确认字节码为 8：`javap -v target/classes/asia/asio/nixmsg/Client.class | findstr major`（应为 52）。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
mvn test
|
||
```
|
||
|
||
含假传输单元测试与 DEVELOPMENT 第 9 节接入清单（会编译并启动真实 `nixmsg`）。可用环境变量 `NIXMSG_BIN` 指定已编译二进制。跳过仅 JS 的跨域项。
|
||
|
||
## 许可证
|
||
|
||
见 `LICENSE`（Proprietary）。
|