# goiot-java-sdk

**Repository Path**: gdouyang/goiot-java-sdk

## Basic Information

- **Project Name**: goiot-java-sdk
- **Description**: goiot java sdk
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-23
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# goiot Java SDK

对接 go-iot 管理端 HTTP API（默认前缀 `/api`）。覆盖登录、产品/设备 CRUD、时序查询、网络配置、WebSocket 事件订阅。

- Java 8+
- 依赖：OkHttp 4.10、Jackson 2.14
- Token 请求头：`x-access-token`

## 引入

尚未发布到中央仓库时，先本地安装：

```bash
mvn clean install
```

```xml
<dependency>
  <groupId>goiot</groupId>
  <artifactId>java-sdk</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>
```

## 初始化

`Goiot.init` 会设置 host、立即登录，并启动后台刷新（默认每 160 秒；失败则重新登录）。默认会话有效期 1 天。host 末尾 `/` 可有可无。

```java
import goiot.Goiot;
import goiot.api.ApiHolder;
import goiot.dto.PageQuery;
import goiot.dto.PageResult;
import goiot.dto.Product;

Goiot.init("http://127.0.0.1:8088", "admin", "123456");

PageResult<Product> page = ApiHolder.productApi.page(new PageQuery(1, 10)).getResult();
```

只手动登录、不启用看门狗：

```java
import goiot.GoiotHttp;
import goiot.api.ApiHolder;
import goiot.dto.LoginForm;

GoiotHttp.setHost("http://127.0.0.1:8088");
LoginForm form = new LoginForm();
form.setUsername("admin");
form.setPassword("123456");
form.setExpires(86400); // 秒，可选；不传则服务端默认约 1 小时
ApiHolder.loginApi.login(form);
```

看门狗参数（须在 `Goiot.init` / `WatchDog.init` 之前设置）：

```java
WatchDog.refreshIntervalSeconds = 160; // 最小 15
WatchDog.expires = 86400;
```

`WatchDog.init()` 只生效一次。登出：`ApiHolder.loginApi.logout()`。

## 统一响应

所有 HTTP 接口返回 `JsonResp<T>`：

| 字段 | 含义 |
|---|---|
| `success` | 是否成功 |
| `message` | 失败原因 |
| `code` | HTTP 风格状态码（如 200、400） |
| `result` | 业务数据 |

先判断 `success` 再取 `result`。

## 分页

请求 `PageQuery`，响应 `PageResult<T>`。设备/产品列表与属性/日志/事件时序查询共用这套结构。

```java
PageQuery q = new PageQuery(1, 10)
    .addCondition("name", PageQuery.Oper.LIKE, "测试");
PageResult<Device> page = ApiHolder.deviceApi.page(q).getResult();

// 时序查询可用上一页的 searchAfter 做游标翻页
PageQuery next = new PageQuery(1, 10);
next.setSearchAfter(new ArrayList<Object>(page.getSearchAfter()));
```

`Oper`：`IN` `EQ` `NEQ` `GT` `GTE` `LT` `LTE` `LIKE` `BTW` `NOTNULL`。

## 常用接口

通过 `ApiHolder` 取单例。

### 登录

| 方法 | 对应接口 |
|---|---|
| `loginApi.login(form)` | `POST /api/login`，成功后自动写入 token |
| `loginApi.tokenRefresh()` | `GET /api/token/refresh` |
| `loginApi.logout()` | `POST /api/logout`，成功后清除 token |

### 产品 `productApi`

| 方法 | 对应接口 | 说明 |
|---|---|---|
| `page` / `get` / `add` / `delete` | `/api/product/page` 等 | 标准 CRUD |
| `update(product)` | `PUT /api/product/{id}` | 必须带 `Product.id`，与设备 `PUT /api/device` 不同 |
| `list()` | `GET /api/product/list` | |
| `storePolicies()` | `GET /api/product/store-policies` | |
| `deploy` / `undeploy` | `POST .../deploy` `.../undeploy` | |
| `saveTSL` / `saveScript` | `PUT .../tsl` `.../script` | |
| `getNetwork` / `updateNetwork` | `GET/PUT /api/product/network` | |
| `startNetwork` / `stopNetwork` | `POST /api/product/network/{id}/run?state=start\|stop` | |

### 设备 `deviceApi`

| 方法 | 对应接口 | 说明 |
|---|---|---|
| `page` / `get` / `add` / `update` / `delete` | `/api/device` | `update` 为 `PUT /api/device`（id 在 body） |
| `get(id)` | `GET /api/device/{id}` | 含 `metadata`、`productName` |
| `getDetail(id)` | `GET /api/device/{id}/detail` | 另含 `networkType` |
| `queryProperties` / `queryLogs` / `queryEvent` | `POST .../properties` `.../logs` `.../event/{eventId}` | 返回 `PageResult<Map<String,Object>>` |
| `getConnectionInfo` / `connectionCheck` | `GET .../connection-info` `.../connection-check` | |
| `connect` / `disconnect` / `deploy` / `undeploy` | | |
| `batchDeploy` / `batchUndeploy` | | |
| `cmdInvoke` | `POST .../invoke` | `CmdInvokeDTO.timeout`、`offlineCache` |

列表接口里设备 `metaconfig` 可能是 JSON 对象、JSON 字符串或字面量 `"null"` / `"{}"`，SDK 会转成 `Map`。

```java
DeviceApi deviceApi = ApiHolder.deviceApi;
JsonResp<PageResult<Map<String, Object>>> props =
    deviceApi.queryProperties("DEVICE_ID", new PageQuery(1, 20));
```

### 实时消息 `eventbusApi`

WebSocket，路径与 go-iot 一致。`deviceId` 按产品订阅时可用 `*`，类型可用 `IMessage.Type.ALL`（`**`）。

```java
ApiHolder.eventbusApi.product("PRODUCT_ID", "*", IMessage.Type.ALL, new EventbusApi.WebSocketListener() {
    @Override
    public void onMessage(WebSocket webSocket, IMessage msg) {
        System.out.println(msg.getType());
    }
});
```

## 响应约定

- 日期：`yyyy-MM-dd HH:mm:ss` 或带毫秒；字面量 `"null"` 视为空。
- 未知 JSON 字段忽略。
- 请求体不序列化 null 字段。
- HTTP 非 2xx 仍尝试解析 body 为 `JsonResp`，并打日志；以 `success` 为准。

## 本地查询自检

`src/test/java/goiot/QueryCompatTest.java` 对真实 go-iot 只做查询（登录、分页、属性/日志）。修改 host 后：

```bash
mvn -q compile
# 将测试类与依赖加入 classpath 后运行 goiot.QueryCompatTest
```