鸿蒙端云一体联调笔记：FunctionGraph + APIG 的两个实测坑（base64 与冷启动 504）

背景

最近在鸿蒙开发实践中心走了一遍“云同步待办清单”端云一体案例：端侧是 HarmonyOS ArkTS 应用，云侧是华为云 FunctionGraph 云函数 + APIG 专享版网关 + RDS for MySQL，8 个云函数负责注册登录与任务增删改查，端侧每 30 秒轮询一次做多端同步。这篇笔记记下联调时真实遇到的两个坑，都是案例文档里有实测记录的问题，照着修就能过。

坑一：POST body 被 base64 编码，JSON.parse 直接报错

现象：接口一调用就报服务器错误，FunctionGraph 日志里抛 Unexpected token e in JSON。

原因：APIG 会把 POST body 做 base64 编码后传给函数，函数没有解码就直接 JSON.parse，解析到的其实是 base64 字符串。

修复：8 个函数统一补一个 parseBody()，先判断再解码：

function parseBody(event) {
  let body = event.body || '';
  if (event.isBase64Encoded) {
    body = Buffer.from(body, 'base64').toString('utf8');
  }
  return JSON.parse(body);
}

修完的标志是接口返回 code: 0。注意这个坑只影响 POST，pull 是唯一 GET 接口，要分开验证。

坑二：首次调用 504，越重试越慢

现象：首次调用报 504；反复 504 之后，热实例的数据库查询也稳定在 5–6 秒。

原因：挂了 VPC 的函数冷启动挂 ENI 约 6 秒，超过了 APIG 后端默认超时 5000ms；客户端一看超时就重试，重试风暴又打坏了实例连接池，形成“实例劣化级联”。

修复：

1. 函数超时调到 30s；
2. APIG 后端超时调到 30000ms（单位是毫秒；改完触发器要删除重建再重新发布 API，否则不生效）；
3. 冷启动首次 504 属于正常，重试 2–5 次即恢复，不要一上来就认定服务挂了；
4. 用一个临时 diag 函数（与业务函数同款连接池 + 一条简单查询）判定到底是冷启动还是真故障。

另外两个顺手记下的点

时区差 8 小时：云函数环境是 UTC，mysql2 又可能把 DATETIME 按 UTC 转换，两端叠加正好差 8 小时。连接池加 dateStrings: true，写入统一用北京时间函数，三张表的时间字段注释都写明“北京时间”，改造时不要退化。

幂等写入：APIG 超时返回 504 不会取消函数执行，客户端重试就会重复写入。写操作按幂等设计：客户端 UUID 做主键 + ON DUPLICATE KEY UPDATE；排查“失败”时先查库确认数据是否已写入，联调脏数据按文档清理。

小结

联调先分 GET / POST 单独验证；改了云函数必须重传代码 + 重新发布 API，否则测的是旧代码；超时参数按实测设定，不要照抄无 VPC 场景的 5000ms 示例。把这两个坑修掉，端云链路基本就能一次跑通。