# 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
**负责人**：待定