192 lines
5.3 KiB
Markdown
192 lines
5.3 KiB
Markdown
# mijia-go-api
|
|
|
|
`mijia-go-api` 是一个纯 Go 米家 API 库，支持二维码登录与 token 刷新、家庭/设备/场景/耗材查询、属性读写、action 执行、统计查询，以及基于 MIoT 设备描述的高级 `Device` 操作。
|
|
|
|
本项目只提供 Go 库，不提供 CLI、MCP、skills 或 HAR decrypt 功能。
|
|
|
|
## 安装
|
|
|
|
```bash
|
|
go get git.misaka.ren/m1saka/mijia-go-api
|
|
```
|
|
|
|
## 登录
|
|
|
|
`NewClient` 的认证路径传空字符串时，默认使用 `~/.config/mijia-api/auth.json`。`Login` 会优先尝试刷新已有 token；需要重新登录时，会在终端输出二维码供米家 App 扫描。
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
|
|
mijia "git.misaka.ren/m1saka/mijia-go-api"
|
|
)
|
|
|
|
func main() {
|
|
client, err := mijia.NewClient("")
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
if _, err := client.Login(context.Background()); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
auth := client.AuthData()
|
|
log.Printf("已登录 userId=%s", auth.UserID)
|
|
}
|
|
```
|
|
|
|
`auth.json` 包含 `serviceToken`、`passToken`、`ssecurity` 等敏感认证数据。库写入该文件时使用 `0600` 权限；请保持此权限，并且不要将该文件提交到版本库。
|
|
|
|
Web/GUI 应用可通过 `WithQRWriter` 接收登录输出，并在阻塞的 `Login` 等待期间实时展示给用户：
|
|
|
|
```go
|
|
import (
|
|
"bufio"
|
|
"context"
|
|
"io"
|
|
|
|
mijia "git.misaka.ren/m1saka/mijia-go-api"
|
|
)
|
|
|
|
func streamLogin(ctx context.Context, renderLoginLine func(string)) error {
|
|
reader, writer := io.Pipe()
|
|
defer reader.Close()
|
|
|
|
client, err := mijia.NewClient("", mijia.WithQRWriter(writer))
|
|
if err != nil {
|
|
writer.Close()
|
|
return err
|
|
}
|
|
|
|
loginDone := make(chan error, 1)
|
|
go func() {
|
|
_, err := client.Login(ctx)
|
|
writer.CloseWithError(err)
|
|
loginDone <- err
|
|
}()
|
|
|
|
scanner := bufio.NewScanner(reader)
|
|
for scanner.Scan() {
|
|
renderLoginLine(scanner.Text())
|
|
}
|
|
|
|
loginErr := <-loginDone
|
|
if loginErr != nil {
|
|
return loginErr
|
|
}
|
|
return scanner.Err()
|
|
}
|
|
```
|
|
|
|
`Login` 会阻塞等待扫码，因此必须同步消费 Writer 输出。Writer 可能由另一个 goroutine 写入，不能无同步地并发读写 `bytes.Buffer`。Writer 接收的内容包含登录二维码 URL，属于敏感登录信息；调用方不得将其写入日志、监控事件或其他持久化记录。
|
|
|
|
## 底层 API
|
|
|
|
以下示例展示设备、属性和 action 的直接调用。`GetDevices` 的 `homeID` 传空字符串时查询所有家庭。
|
|
|
|
```go
|
|
devices, err := client.GetDevices(ctx, "")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
properties, err := client.GetProperties(ctx, []mijia.PropertyRequest{
|
|
{DID: devices[0].DID, SIID: 2, PIID: 1},
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
_, err = client.SetProperties(ctx, []mijia.PropertySetRequest{
|
|
{DID: devices[0].DID, SIID: 2, PIID: 1, Value: true},
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
_, err = client.RunActions(ctx, []mijia.ActionRequest{
|
|
{DID: devices[0].DID, SIID: 2, AIID: 1},
|
|
})
|
|
```
|
|
|
|
家庭、场景、耗材和统计分别使用 `GetHomes`、`GetScenes`、`RunScene`、`GetConsumables` 和 `GetStatistics`。
|
|
|
|
## 高级 Device
|
|
|
|
`NewDevice` 可通过 `DeviceSelector.DID` 或 `DeviceSelector.Name` 选择设备；名称匹配到多个设备时会返回 `MultipleDevicesFoundError`。通过文件认证的 `NewClient` 默认把设备描述缓存到认证文件所在目录；`NewClientWithAuthData` 默认不启用缓存，调用方需要在创建 `Device` 时传入 `WithDeviceCacheDir` 才会缓存。每次成功的 `Get`、`Set`、`RunAction` 后默认等待 `500ms`。
|
|
|
|
```go
|
|
device, err := mijia.NewDevice(ctx, client, mijia.DeviceSelector{DID: "设备 DID"})
|
|
// 也可以按名称选择：mijia.DeviceSelector{Name: "客厅灯"}
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
value, err := device.Get(ctx, "on")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
if err := device.Set(ctx, "on", true); err != nil {
|
|
return err
|
|
}
|
|
|
|
_, err = device.RunAction(ctx, "toggle", nil)
|
|
_ = value
|
|
```
|
|
|
|
执行 action 前可通过 `device.Actions()["toggle"].Inputs` 检查可信 MIoT 描述中的参数类型、范围和值列表。
|
|
|
|
可通过实际导出的 `DeviceOption` 调整行为：
|
|
|
|
```go
|
|
device, err := mijia.NewDevice(
|
|
ctx,
|
|
client,
|
|
mijia.DeviceSelector{Name: "客厅灯"},
|
|
mijia.WithDeviceDelay(0),
|
|
// 使用 NewClientWithAuthData 时，显式指定目录才能缓存设备描述。
|
|
mijia.WithDeviceCacheDir("./miot-cache"),
|
|
mijia.WithDeviceHTTPClient(http.DefaultClient),
|
|
)
|
|
```
|
|
|
|
## 超时与错误
|
|
|
|
所有网络和设备操作都接收 `context.Context`，建议设置超时：
|
|
|
|
```go
|
|
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
|
|
defer cancel()
|
|
|
|
devices, err := client.GetDevices(ctx, "")
|
|
```
|
|
|
|
API 错误和高级设备错误可使用 `errors.As` 判断：
|
|
|
|
```go
|
|
var apiErr *mijia.APIError
|
|
var deviceErr *mijia.DeviceGetError
|
|
|
|
switch {
|
|
case errors.As(err, &apiErr):
|
|
log.Printf("API 错误: code=%d message=%s", apiErr.Code, apiErr.Message)
|
|
case errors.As(err, &deviceErr):
|
|
log.Printf("设备读取错误: device=%s property=%s code=%d", deviceErr.DeviceName, deviceErr.Name, deviceErr.Code)
|
|
}
|
|
```
|
|
|
|
Token 刷新失败且必须重新扫码授权时，可使用 `errors.Is` 稳定判断，同时仍可通过 `errors.As` 获取 `LoginError` 详情：
|
|
|
|
```go
|
|
if errors.Is(err, mijia.ErrReauthenticationRequired) {
|
|
log.Print("认证已失效，请重新扫码授权")
|
|
}
|
|
```
|
|
|
|
写属性和执行 action 时，对应错误类型为 `DeviceSetError` 和 `DeviceActionError`；设备选择还可能返回 `DeviceNotFoundError` 或 `MultipleDevicesFoundError`。
|