小米智能家居集成开发协作指南

作为小米智能家居与Home Assistant平台的桥梁，ha_xiaomi_home项目致力于为开发者提供标准化的设备接入方案。遵循统一的开发规范不仅能保证代码质量的稳定性和项目的可维护性，更是高效协作的基础。本文将帮助你快速掌握项目贡献的全流程规范，从问题报告到代码提交的每一步都有章可循。

一、项目基础指南：构建可靠的开发环境

学习目标

• 了解项目架构与核心价值
• 掌握问题反馈的有效方法
• 配置符合要求的开发环境

1.1 项目架构概览

ha_xiaomi_home采用双层控制架构，支持云端和本地两种设备管理模式：

云端控制模式：通过小米云平台(MIoT Cloud)实现设备通信，适用于需要远程访问的场景。系统通过MQTT Broker接收设备状态消息，通过HTTP API发送控制指令。

本地控制模式：通过小米中枢网关实现局域网内通信，响应速度更快且不受互联网状态影响。

1.2 问题报告三步法

当你遇到功能异常或bug时，请按照以下步骤提交高质量的问题报告：

步骤一：信息收集

• 记录设备型号、固件版本和Home Assistant版本
• 描述问题发生的具体场景和复现步骤
• 保存问题前后的系统状态变化

步骤二：开启调试日志 在Home Assistant配置文件中添加调试配置：

logger:
  default: critical  # 其他组件保持最低日志级别
  logs:
    custom_components.xiaomi_home: debug  # 仅小米集成组件输出详细日志

💡 技巧：调试完成后记得恢复默认日志级别，避免日志文件过大影响系统性能。

步骤三：提交规范报告 报告应包含：

• 清晰的问题标题（如"小米空气净化器在自动模式下状态更新延迟"）
• 详细的环境信息和复现步骤
• 完整的调试日志（使用代码块格式）
• 问题截图或录屏（如适用）

⚠️ 注意：不要在报告中包含敏感信息，如账号密码、设备Token等。

1.3 开发环境准备

环境配置检查清单：

• [ ] Python 3.9+ 环境
• [ ] Home Assistant 2023.12+ 开发环境
• [ ] 代码检查工具：pylint, flake8
• [ ] 版本控制：Git
• [ ] 测试框架：pytest

项目克隆：

git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
cd ha_xiaomi_home

二、进阶开发实践：代码规范与质量保障

学习目标

• 掌握项目代码风格要求
• 理解命名规范的设计原则
• 学会编写符合要求的测试用例

2.1 代码风格指南

项目采用Google Python风格指南，核心规范包括：

格式要求：

• 使用4个空格缩进，不使用Tab
• 每行代码不超过80个字符
• 函数与类之间空两行，类内方法之间空一行
• 导入语句按标准库→第三方库→项目本地库顺序排列

示例代码：

# 正确示例
from typing import List, Dict  # 标准库导入

import requests  # 第三方库导入

from custom_components.xiaomi_home.miot.miot_client import MiotClient  # 项目本地导入


class XiaomiDevice:
    """小米设备基类"""
    
    def __init__(self, device_id: str, name: str):
        self.device_id = device_id  # 设备唯一标识
        self.name = name  # 设备名称
        self.connected = False  # 连接状态标志
        
    def connect(self) -> bool:
        """建立设备连接
        
        Returns:
            bool: 连接成功返回True，否则返回False
        """
        # 连接逻辑实现
        return True

💡 技巧：使用black工具可自动格式化代码，确保符合项目风格要求。

2.2 命名规范详解

项目命名采用场景化分类，确保代码可读性和一致性：

命名对象	规范要求	示例	为什么这样做
小米相关	正式文档用"Xiaomi"，代码变量用"xiaomi"或"mi"	xiaomi_device = XiaomiDevice()	保持品牌名称一致性，代码中简化为"mi"可减少冗余
米家相关	正式文档用"Xiaomi Home"，代码用"mihome"或"MiHome"	mihome_api = MiHomeAPI()	区分"小米品牌"和"米家平台"的概念边界
Home Assistant相关	正式文档用全名，代码用"hass"前缀	hass_config = HassConfiguration()	遵循Home Assistant生态通用命名习惯，提高代码辨识度
设备类型	使用设备功能描述词，采用小写蛇形命名	air_purifier.py, smart_light.py	直观反映文件功能，便于模块定位

⚠️ 常见误区：不要在代码中混合使用"mi"和"xiaomi"指代同一概念，如mi_device和xiaomi_client同时存在会造成混淆。

2.3 测试规范与实践

所有代码提交前必须通过以下质量关卡：

静态代码检查：

pylint custom_components/xiaomi_home/

单元测试：

pytest test/

测试覆盖率要求：

• 新功能代码覆盖率≥80%
• 核心功能代码覆盖率≥90%
• 修复bug必须添加对应的回归测试

测试用例编写规范：

• 测试类以Test开头，如TestMiotClient
• 测试方法以test_开头，如test_device_connection
• 使用pytest.mark.parametrize实现参数化测试
• 模拟外部依赖，避免测试需要真实设备

三、协作规范：从代码提交到PR合入

学习目标

• 掌握Git工作流与提交规范
• 理解代码审查的重点关注项
• 学会编写清晰的文档

3.1 Git工作流程

项目采用Feature Branch工作流，完整流程如下：

main分支 ────────●─────────────●─────── (稳定版本)
                 /             /
feature分支 ────●─●─●───────●─●
                 \         /
bugfix分支   ─────●───────●

工作流程步骤：

1. 从main分支创建功能分支：git checkout -b feat/device-support
2. 完成开发后提交变更，遵循提交信息规范
3. 推送分支到远程：git push -u origin feat/device-support
4. 创建Pull Request，等待代码审查
5. 根据审查意见修改代码
6. 审查通过后合并到main分支

3.2 提交信息规范

提交信息采用"类型: 简短描述"的格式，完整结构：

类型: 简短描述(不超过50字符)

详细说明(可选，每行不超过72字符)

相关issue: #123(可选)

提交类型说明：

• feat: 新功能（如"feat: 添加扫地机器人支持"）
• fix: 缺陷修复（如"fix: 修复温湿度传感器数据异常"）
• docs: 文档更新（如"docs: 完善设备配置说明"）
• style: 代码格式调整（不影响功能）
• refactor: 代码重构（如"refactor: 优化设备发现逻辑"）
• perf: 性能优化
• test: 测试相关
• chore: 构建或依赖变更

💡 技巧：提交前使用git commit --amend可以修改最近一次提交，保持提交历史清晰。

3.3 文档规范与维护

文档编写要求：

• 中英文混排时，中英文之间保留一个空格
• API变更必须同步更新文档
• 新增功能需包含使用场景和配置示例

文档类型及位置：

• 开发指南：CONTRIBUTING.md
• 用户手册：README.md
• API文档：doc/api.md(如存在)
• 设备支持列表：doc/supported_devices.md(如存在)

规范自查表

在提交代码前，请检查以下项目：

• [ ] 代码符合Google Python风格指南
• [ ] 命名符合项目规范
• [ ] 新增功能包含单元测试
• [ ] 所有测试通过
• [ ] 提交信息符合规范格式
• [ ] 文档已同步更新
• [ ] 调试日志已移除或禁用

遵循这些规范将帮助你更高效地参与项目开发，同时确保代码质量和项目的长期可维护性。我们期待你的贡献，共同打造更完善的小米智能家居集成方案！