xiaomihome/miot/migration/06-miot-utils.md

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

建议：

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 匹配器	🟡 中	可选功能
优化和测试	🟡 中	质量保障

进度跟踪

• 创建 common.go 文件 (预计 1小时) — 2026-06-28 完成
• 实现工具函数 (预计 2小时) — 2026-06-28 完成
• 实现 HTTP 工具类 (预计 2小时) — 已存在 http_client.go，跳过
• 实现 MQTT 匹配器 (预计 1小时) — 已存在 miot_matcher.go，跳过
• 优化和测试 (预计 1小时)

总计：7小时 (已完成核心移植)

---

创建时间：2026-06-28 最后更新：2026-06-28 负责人：待定