feat: 初始化小米 IoT (MIoT) 智能家居 Go 库
- 实现 MIoT 客户端核心功能（MQTT 连接、设备管理、属性读写） - 支持云端 API 调用与局域网设备发现（mDNS） - 集成国际化（i18n）多语言支持 - 添加 MIoT 设备规约解析器（spec_parser） - 包含单元测试与使用示例
This commit is contained in:
@@ -0,0 +1,194 @@
|
||||
# 06 - common.py 移植计划
|
||||
|
||||
## 概览
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **Python 文件** | `py-miot/common.py` (189行) |
|
||||
| **Go 文件** | ❌ 缺失 |
|
||||
| **状态** | ❌ 完全缺失 |
|
||||
| **优先级** | 🔴 P0 |
|
||||
| **预计工作量** | 4-6 小时 |
|
||||
|
||||
**说明**：此文件对应之前分析的 `miot_utils.py`，实际文件名为 `common.py`。
|
||||
|
||||
## Python 版本分析
|
||||
|
||||
### 核心功能
|
||||
|
||||
#### 工具函数
|
||||
|
||||
| 函数名 | 行号 | 功能 | Go 状态 |
|
||||
|--------|------|------|---------|
|
||||
| `gen_absolute_path` | 63 | 生成绝对路径 | ❌ 缺失 |
|
||||
| `calc_group_id` | 68 | 计算组 ID（SHA1 哈希） | ❌ 缺失 |
|
||||
| `load_json_file` | 74 | 加载 JSON 文件 | ❌ 缺失 |
|
||||
| `load_yaml_file` | 80 | 加载 YAML 文件 | ❌ 缺失 |
|
||||
| `randomize_int` | 86 | 随机化整数 | ❌ 缺失 |
|
||||
| `randomize_float` | 91 | 随机化浮点数 | ❌ 缺失 |
|
||||
| `slugify_name` | 96 | 生成 slug（名称） | ❌ 缺失 |
|
||||
| `slugify_did` | 101 | 生成 slug（设备 ID） | ❌ 缺失 |
|
||||
|
||||
#### 类
|
||||
|
||||
##### MIoTMatcher
|
||||
|
||||
**位置**：第 106-124 行
|
||||
|
||||
**功能**：MQTT topic 匹配器（基于 `paho.mqtt.matcher`）
|
||||
|
||||
**Go 状态**：❌ 缺失
|
||||
|
||||
##### MIoTHttp
|
||||
|
||||
**位置**：第 126-189 行
|
||||
|
||||
**功能**：HTTP 请求工具类（同步和异步）
|
||||
|
||||
**核心方法**：
|
||||
|
||||
| 方法名 | 行号 | 功能 | Go 状态 |
|
||||
|--------|------|------|---------|
|
||||
| `get` | 129 | HTTP GET 请求（同步） | ❌ 缺失 |
|
||||
| `get_json` | 143 | HTTP GET 请求并返回 JSON | ❌ 缺失 |
|
||||
| `post` | 150 | HTTP POST 请求（同步） | ❌ 缺失 |
|
||||
| `post_json` | 156 | HTTP POST 请求并返回 JSON | ❌ 缺失 |
|
||||
| `get_async` | 163 | HTTP GET 请求（异步） | ❌ 缺失 |
|
||||
| `get_json_async` | 173 | HTTP GET 请求并返回 JSON（异步） | ❌ 缺失 |
|
||||
| `post_async` | 182 | HTTP POST 请求（异步） | ❌ 缺失 |
|
||||
|
||||
## Go 版本现状
|
||||
|
||||
### 缺失的功能
|
||||
|
||||
整个 `common.py` 模块在 Go 版本中完全缺失。
|
||||
|
||||
Go 版本中可能已经有部分功能：
|
||||
- HTTP 请求 - 可能在 `http_client.go` 中实现
|
||||
- JSON/YAML 加载 - 可能使用标准库
|
||||
|
||||
但是缺少统一的工具类。
|
||||
|
||||
## 移植建议
|
||||
|
||||
### 第一批任务（核心功能）
|
||||
|
||||
1. **创建 `common.go` 文件** (1小时)
|
||||
- 定义工具函数
|
||||
- 定义 `MIoTMatcher` 结构体（如果需要）
|
||||
- 定义 `MIoTHttp` 结构体
|
||||
|
||||
2. **实现工具函数** (2小时)
|
||||
- 实现 `GenAbsolutePath`
|
||||
- 实现 `CalcGroupID`
|
||||
- 实现 `LoadJSONFile`
|
||||
- 实现 `LoadYAMLFile`
|
||||
- 实现 `RandomizeInt` 和 `RandomizeFloat`
|
||||
- 实现 `SlugifyName` 和 `SlugifyDID`
|
||||
|
||||
3. **实现 HTTP 工具类** (2小时)
|
||||
- 实现 `MIoTHttp` 结构体
|
||||
- 实现 GET 和 POST 方法
|
||||
- 实现 JSON 支持
|
||||
|
||||
### 第二批任务（高级功能）
|
||||
|
||||
4. **实现 MQTT 匹配器** (1小时)
|
||||
- 评估是否需要 `MIoTMatcher`
|
||||
- 如果需要，实现 Go 版本
|
||||
|
||||
5. **优化和测试** (1小时)
|
||||
- 单元测试
|
||||
- 性能优化
|
||||
|
||||
## 技术难点
|
||||
|
||||
### 1. Slugify 功能
|
||||
|
||||
**问题**：Python 使用 `python-slugify` 库
|
||||
|
||||
**建议**：
|
||||
- 使用 Go 的 `strings` 包手动实现
|
||||
- 或使用第三方库 `github.com/gosimple/slug`
|
||||
|
||||
### 2. MQTT 匹配器
|
||||
|
||||
**问题**：Python 使用 `paho.mqtt.matcher`
|
||||
|
||||
**建议**：
|
||||
- 评估是否需要在 Go 版本中实现
|
||||
- 如果需要，可以使用 `github.com/eclipse/paho.mqtt.golang` 库
|
||||
|
||||
### 3. 异步 HTTP
|
||||
|
||||
**问题**：Python 使用 `asyncio`，Go 使用 goroutine
|
||||
|
||||
**建议**：
|
||||
```go
|
||||
type MIoTHttp struct{}
|
||||
|
||||
func (h *MIoTHttp) Get(url string, params map[string]string, headers map[string]string) (string, error) {
|
||||
// 实现 GET 请求
|
||||
}
|
||||
|
||||
func (h *MIoTHttp) GetAsync(url string, params map[string]string, headers map[string]string) <-chan HttpResponse {
|
||||
ch := make(chan HttpResponse, 1)
|
||||
go func() {
|
||||
resp, err := h.Get(url, params, headers)
|
||||
ch <- HttpResponse{Body: resp, Err: err}
|
||||
}()
|
||||
return ch
|
||||
}
|
||||
```
|
||||
|
||||
## 测试计划
|
||||
|
||||
### 单元测试
|
||||
|
||||
1. **工具函数测试**
|
||||
- 测试路径生成
|
||||
- 测试哈希计算
|
||||
- 测试文件加载
|
||||
- 测试随机化
|
||||
- 测试 slugify
|
||||
|
||||
2. **HTTP 工具测试**
|
||||
- 测试 GET 请求
|
||||
- 测试 POST 请求
|
||||
- 测试 JSON 解析
|
||||
- 测试错误处理
|
||||
|
||||
## 依赖关系
|
||||
|
||||
| 依赖文件 | 关系 | 说明 |
|
||||
|---------|------|------|
|
||||
| `encoding/json` | 强依赖 | JSON 处理 |
|
||||
| `encoding/yaml` | 强依赖 | YAML 处理 |
|
||||
| `net/http` | 强依赖 | HTTP 请求 |
|
||||
| `github.com/gosimple/slug` | 弱依赖 | Slugify（可选） |
|
||||
|
||||
## 移植优先级
|
||||
|
||||
| 任务 | 优先级 | 理由 |
|
||||
|------|--------|------|
|
||||
| 创建基础结构 | 🔴 高 | 基础框架 |
|
||||
| 实现工具函数 | 🔴 高 | 核心功能 |
|
||||
| 实现 HTTP 工具 | 🔴 高 | 核心功能 |
|
||||
| 实现 MQTT 匹配器 | 🟡 中 | 可选功能 |
|
||||
| 优化和测试 | 🟡 中 | 质量保障 |
|
||||
|
||||
## 进度跟踪
|
||||
|
||||
- [x] 创建 `common.go` 文件 (预计 1小时) — 2026-06-28 完成
|
||||
- [x] 实现工具函数 (预计 2小时) — 2026-06-28 完成
|
||||
- [x] 实现 HTTP 工具类 (预计 2小时) — 已存在 `http_client.go`，跳过
|
||||
- [x] 实现 MQTT 匹配器 (预计 1小时) — 已存在 `miot_matcher.go`，跳过
|
||||
- [ ] 优化和测试 (预计 1小时)
|
||||
|
||||
**总计**：7小时 (已完成核心移植)
|
||||
|
||||
---
|
||||
|
||||
**创建时间**：2026-06-28
|
||||
**最后更新**：2026-06-28
|
||||
**负责人**：待定
|
||||
Reference in New Issue
Block a user