小米智能家居集成开发规范指南

一、核心开发原则

小米智能家居集成项目（ha_xiaomi_home）遵循四大核心开发原则，确保代码质量与生态兼容性：

用户体验优先：所有功能设计需以普通用户可理解的方式呈现，避免技术术语直接暴露在交互界面

稳定性第一：任何变更必须经过严格测试，确保对现有设备和场景的向后兼容性

性能优化：本地控制优先于云端控制，减少延迟并提升断网时的可用性

开放协作：代码必须遵循开源协议，文档需中英文双语维护

架构设计理念

项目采用分层架构设计，主要分为：

• 设备抽象层（miot_device.py）：统一设备接口定义
• 通信层（miot_cloud.py/miot_lan.py）：处理云端与局域网通信
• 实体转换层（specv2entity.py）：将设备特性映射为Home Assistant实体

图1：云控制模式下的设备通信架构，通过MQTT Broker和HTTP API实现状态同步与命令下发

图2：本地控制模式架构，通过小米中枢网关直接与设备通信，降低延迟并提高可靠性

二、实施路径指南

故障诊断三步法

当遇到设备连接或功能异常时，按以下步骤诊断：

1. 信息收集

   • 记录设备型号、固件版本
   • 截取问题发生时间点
   • 描述复现步骤（精确到操作顺序）

2. 日志获取 在Home Assistant配置文件中添加调试日志配置：

   logger:
     default: critical  # 保持系统日志简洁
     logs:
       custom_components.xiaomi_home: debug  # 仅开启小米组件调试
   

   重启Home Assistant后，收集home-assistant.log中相关记录

3. 问题提交 提交包含以下要素的报告：

   • 完整日志片段（使用代码块格式）
   • 设备信息与环境配置
   • 问题截图或录屏
   • 已尝试的解决方法

代码开发规范

基础约定

规范类型	具体要求	设计理念
缩进格式	4个空格，禁止使用Tab	统一跨编辑器显示效果
行长度	最大80字符	提高代码可读性，便于分屏查看
命名规则	变量用snake_case，类用CamelCase	符合Python社区通用实践
导入顺序	标准库 > 第三方库 > 项目内部	清晰区分依赖来源

进阶实践

1. 设备集成步骤

   • 先定义设备规格（specs目录）
   • 实现通信协议（miot_client.py）
   • 创建实体映射（sensor.py/switch.py等）
   • 添加测试用例（test/目录下）

2. 提交记录规范

   <类型>: <简短描述> (不超过50字符)
   
   <详细说明，解释变更原因和实现方式>
   
   Fixes #<issue编号> (如适用)
   

   类型包括：feat(功能)、fix(修复)、refactor(重构)、docs(文档)等

禁忌清单

• 禁止硬编码设备IP或令牌
• 避免在主线程中进行网络请求
• 不要修改第三方库代码
• 禁止使用print语句（使用logger替代）

三、质量保障体系

质量门禁矩阵

检查类型	工具	要求	自动化状态
代码风格	pylint	分数≥8.5/10	pre-commit钩子
类型检查	mypy	无错误提示	CI流程
单元测试	pytest	覆盖率≥80%	CI流程
文档完整性	pdoc	100%公共接口覆盖	手动检查

测试实施指南

1. 单元测试

   def test_device_connection():
       # 模拟设备响应
       mock_client = MockMiotClient()
       device = MiotDevice(mock_client, "device_id")
       
       # 执行测试
       result = device.connect()
       
       # 验证结果
       assert result is True
       assert device.connected is True
   

2. 兼容性测试

   • 必须测试至少3个不同固件版本
   • 验证新旧设备混合场景
   • 测试断网重连机制

四、协作规范

开发流程

规范执行流程图

1. 分支管理

   • main：稳定发布分支
   • dev：开发分支
   • feature/*：功能分支
   • fix/*：修复分支

2. 代码审查要点

   • 是否遵循命名规范
   • 是否处理异常情况
   • 是否有适当注释
   • 是否添加测试用例

文档规范

1. 中英文混排规则

   • 中英文之间保留一个空格
   • 技术术语使用英文并添加中文注释
   • 界面元素名称保持与官方一致

2. 文档更新要求

   • 接口变更必须同步更新文档
   • 新增功能需提供使用示例
   • 复杂流程使用流程图辅助说明

版本兼容处理

1. 向前兼容策略

   # 兼容旧版API响应
   if "old_field" in response:
       value = response["old_field"]
   else:
       value = response["new_field"]
   

2. 版本控制建议

   • 使用语义化版本（MAJOR.MINOR.PATCH）
   • 重大变更递增MAJOR版本
   • 新增功能递增MINOR版本
   • 问题修复递增PATCH版本

通过遵循以上规范，我们能够构建一个高质量、易维护的小米智能家居集成项目，为用户提供稳定可靠的智能家居体验。