（2481期）Ha Integration Patterns – HA 自定义集成架构最佳实践

HA 自定义集成架构最佳实践 Home Assistant 自定义集成开发指南，涵盖 Service 响应数据、HTTP View、Storage API 等核心架构模式，帮助开发者构建符合 HACS 规范的可靠集成组件。 使用说明 核心功能与用法 本 Skill 提供 Home Assistant 自定义集成的系统化架构指导，主要解决以下开发场景： 1. Service 响应数据模式（HA 2023.7+） 突破传统 "fire-and-forget" 限制，通过 supports_response=SupportsResponse.ONLY 实现带返回值的 Service 调用 调用时附加 ?return_response 参数获取 JSON 响应 适用于需要返回配置数据、实体状态的复杂操作场景 2. HTTP View vs Service 决策矩阵| 场景 | 推荐方案 | 原因 ||------|---------|------|| 返回复杂数据 | HTTP View | 天然支持结构化响应 || 触发自动化 | Service | 与 HA 事件系统深度集成 || 纯查询操作 | HTTP View | RESTful 语义更清晰 || 无返回值动作 | Service | 轻量级，符合 HA 设计哲学 | 3. 存储层架构 小型数据（设置、缓存）：使用 homeassistant.helpers.storage.Store 大型数据（历史、日志）：必须采用外部数据库/文件存储 严禁使用下划线前缀的内部 API 4. HACS 合规结构标准化目录布局包含 init.py、config_flow.py、manifest.json、services.yaml 等必需文件，确保与 HACS 生态兼容。 显著优点 权威性高：基于 HA 官方开发者文档和版本演进实践 版本感知：明确标注各特性引入版本（2022.x - 2025.x+），提供迁移路径 反模式警示：通过 "Wrong vs Right" 对比，避免常见的内部 API 误用 实战验证：包含 HA-OpenClaw Bridge 项目的真实经验教训 潜在局限 版本碎片化：HA 演进速度快，部分模式在旧版本（<2023.7）不可用 Python 专属：示例代码均为 Python，非 Python 开发者需额外转换 未覆盖前端：专注于后端集成，不涉及 Lovelace 卡片开发 测试深度有限：Testing Checklist 较简略，缺乏自动化测试框架指导 适合人群 计划开发 HACS 自定义集成的 Python 开发者 需要将外部系统桥接到 HA 的架构师 维护现有集成需适配新版 HA 的维护者 常规风险 破坏性变更：HA 版本升级可能导致集成失效，需持续关注官方 Blog 认证配置：HTTP View 的 requires_auth=True 若配置不当存在未授权访问风险 存储性能：误用 Store 存储大量数据会导致 HA 启动变慢 并发安全：Storage API 非线程安全，需在 async 上下文正确使用 原始说明 Home Assistant custom integration patterns and architectural decisions. Use when building HACS integrations, custom components, or API bridges for Home Assistant. Covers service response data, HTTP views, storage APIs, and integration architecture.