PHP接入华为健康，同步运动睡眠心率数据

本文深入解析了PHP后端集成华为健康服务（Huawei Health Kit）的完整技术路径，强调必须严格遵循OAuth2授权流程——前端引导用户授权、后端中转获取并安全持久化access_token与refresh_token，绝不可绕过授权直连API；针对运动步数、睡眠记录、心率数据三类核心健康信息，详细说明了各自独立的REST接口调用方式、时间参数格式、分页策略及响应解析要点，并直击开发者高频踩坑点：如token过期自动刷新机制缺失、refresh_token误存session、scope变更未同步清理、毫秒级时间戳与单位手动转换、睡眠阶段语义映射不兼容等，为构建稳定可靠的健康数据同步服务提供可落地的全链路实践指南。

华为健康服务 PHP 调用必须走 OAuth2 授权，不能直连 API

华为健康服务（Huawei Health Kit）不提供匿名或 key-based 的 HTTP 接口，所有数据读取都要求用户显式授权。PHP 作为后端，只能做「授权中转」和「token 管理」，真正的数据拉取发生在你拿到 access_token 后调用 Huawei Health Kit REST API —— 这一步必须带上用户授权 scope（比如 https://www.huawei.com/health/sleep.read）。

常见错误现象：
• 直接用 cURL 请求 /v1/users/{userId}/sleep 返回 401 Unauthorized 或 403 Forbidden
• 用自己 App 的 client_secret 拼 token，结果提示 invalid_grant —— 因为 Health Kit 不支持 client credentials 流程

• 必须先在华为开发者联盟配置好 OAuth2 Redirect URI（例如 https://yourdomain.com/huawei/callback），且该地址要能被公网访问
• 前端（App 或 H5）触发授权页：https://oauth-login.cloud.huawei.com/oauth2/v3/authorize?response_type=code&client_id={app_id}&redirect_uri={encoded_uri}&scope=https://www.huawei.com/health/sleep.read%20https://www.huawei.com/health/heart_rate.read%20https://www.huawei.com/health/steps.read
• PHP 后端收到 code 后，用 POST /oauth2/v3/token 换取 access_token 和 refresh_token，注意 body 必须是 application/x-www-form-urlencoded 格式

PHP 获取运动、睡眠、心率数据要用三个不同 endpoint

Health Kit 把数据按类型严格隔离，没有「统一健康数据接口」。同一个 access_token 可以复用，但请求路径、参数结构、返回字段完全不同，混用会导致 404 或字段缺失。

使用场景：你已成功换取 access_token，现在要批量拉取用户最近 7 天数据

• 运动步数：GET https://health-api.cloud.huawei.com/healthkit/v1/users/{userId}/steps?startTime=1717027200000&endTime=1717632000000&pageSize=100（时间单位是毫秒，userId 来自 token 解析或首次 profile 查询）
• 睡眠记录：GET https://health-api.cloud.huawei.com/healthkit/v1/users/{userId}/sleep?startTime=1717027200000&endTime=1717632000000（返回的是每晚一条主记录，含 sleepStages 数组）
• 心率样本：GET https://health-api.cloud.huawei.com/healthkit/v1/users/{userId}/heartRate?startTime=1717027200000&endTime=1717632000000&pageSize=200（注意这是原始采样点，不是分钟均值）

性能影响：单次请求最大 pageSize 是 200；若要拉取大范围数据，必须分页 + 时间窗口滑动，否则丢数据

refresh_token 失效快、scope 不可追加，PHP 必须持久化并预判过期

华为的 refresh_token 默认有效期仅 30 天，且一旦用户在华为帐号里「撤销应用权限」，所有 token 立即作废。PHP 后端如果只存一次 access_token（2 小时过期），不做 refresh 逻辑，第二天就全量失败。

容易踩的坑：
• 把 refresh_token 存 session —— 重启 PHP-FPM 就丢
• 每次都等 401 才去刷新 —— 用户请求已失败，体验断层
• 刷新后没更新数据库里的 access_token 和 expires_in，导致后续请求仍用旧 token

• 必须将 refresh_token、access_token、expires_in、scope 存入数据库（按 huawei_user_id 或 open_id 关联）
• 每次调用前检查 expires_in 是否 POST /oauth2/v3/token 带 grant_type=refresh_token&refresh_token={xxx}
• 刷新响应里 scope 字段可能比原始授权少（比如用户取消了心率权限），PHP 要对比并清理本地缓存的对应数据表

PHP 解析 Health Kit 返回的 timestamp 和 unit 要手动对齐

华为返回的时间戳全是毫秒级 Unix 时间（如 "startTime": 1717027200000），但心率单位是 bpm、步数是 count、睡眠阶段用字符串（"awake"/"light"），PHP 默认不处理这些语义。

示例：解析一段睡眠数据

$sleep = json_decode($response_body, true);
foreach ($sleep['data'] as $item) {
    $start = date('Y-m-d H:i:s', $item['startTime'] / 1000); // 必须除 1000
    $stages = $item['sleepStages'] ?? [];
    foreach ($stages as $stage) {
        // stage['stage'] 是字符串，stage['duration'] 是毫秒，要转成秒或分钟
        $minutes = $stage['duration'] / 1000 / 60;
    }
}

兼容性影响：华为某些设备（如 GT 系列）返回的 heartRate 可能含 "type": "realtime" 或 "type": "average"，PHP 业务逻辑得按 type 分流，不能一概入库

最麻烦的其实是睡眠阶段定义不统一 —— 华为用 5 阶段（deep/light/rem/awake/unknown），而很多国内平台只认 3 阶段，映射时得写死规则，没法靠 API 自动适配

理论要掌握，实操不能落！以上关于《PHP接入华为健康，同步运动睡眠心率数据》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！