firebase-cloud-functions

Firebase Cloud Functions 技能

此技能介绍如何在 Flutter 应用中正确调用 Firebase Cloud Functions。

使用场景

在以下情况下使用此技能：

• 在 Flutter 项目中实现可调用的 Cloud Functions。
• 向服务器端函数传递结构化数据并处理结果。
• 处理函数调用中的错误、超时和重试。
• 配置特定区域的函数部署。
• 使用 Firebase Emulator Suite 在本地测试 Cloud Functions。

---

1. 设置和配置

flutter pub add cloud_functions

import 'package:cloud_functions/cloud_functions.dart';

// After Firebase.initializeApp():
final functions = FirebaseFunctions.instance;

• 使用任何 Cloud Functions 功能前，先初始化 Firebase。
• 对于特定区域的部署，请指定区域：

final functions = FirebaseFunctions.instanceFor(region: 'europe-west1');

• 从 Flutter 应用调用可调用函数前，先将其部署到 Firebase。
• 考虑实施 App Check，以防止 Cloud Functions 遭到滥用。

---

2. 调用函数

使用 httpsCallable 引用函数，然后使用 call 调用它：

final result = await FirebaseFunctions.instance
  .httpsCallable('functionName')
  .call(data);

• 将数据作为 Map 传递 — 它会自动序列化为 JSON：

final result = await FirebaseFunctions.instance
  .httpsCallable('addMessage')
  .call({
    "text": messageText,
    "push": true,
  });

• 通过 data 属性访问结果 — 它会自动从 JSON 反序列化：

final responseData = result.data;
// Cast to expected type if needed:
final message = result.data as Map<String, dynamic>;
final status = message['status'] as String;

• 不要在函数参数中传递身份验证令牌 — SDK 会自动包含这些令牌。
• 确保客户端代码与服务器端实现中的函数名称一致。

---

3. 错误处理

始终使用 try-catch 包装函数调用，并检查 FirebaseFunctionsException：

try {
  final result = await FirebaseFunctions.instance
    .httpsCallable('functionName')
    .call(data);
  // Handle successful result
} on FirebaseFunctionsException catch (e) {
  switch (e.code) {
    case 'not-found':
      // Function does not exist
      break;
    case 'permission-denied':
      // User lacks permission
      break;
    case 'unavailable':
      // Service temporarily unavailable — retry
      break;
    default:
      debugPrint('Function error [${e.code}]: ${e.message}');
  }
} catch (e) {
  debugPrint('Unexpected error: $e');
}

• 妥善处理网络连接问题和超时。
• 函数调用失败时，向用户提供有意义的错误消息。
• 对暂时性错误（unavailable、deadline-exceeded）实施指数退避重试逻辑。

---

4. 性能优化

根据预期执行时间设置合适的超时时间：

final callable = FirebaseFunctions.instance.httpsCallable(
  'functionName',
  options: HttpsCallableOptions(
    timeout: const Duration(seconds: 30),
  ),
);

• 尽可能减少传入和传出函数的数据量，以降低延迟。
• 尽可能使用批量操作，以减少函数调用次数。
• 考虑在客户端缓存经常使用的函数结果。
• 对不常使用的函数，考虑 冷启动 的影响。
• 在等待函数响应时，在 UI 中实现恰当的加载状态。

---

5. 测试和开发

使用 Firebase Emulator Suite 进行本地开发和测试：

FirebaseFunctions.instance.useFunctionsEmulator('localhost', 5001);

• 使用有效和无效的输入测试函数，确保验证逻辑正确。
• 验证函数能否正确处理身份验证。
• 使用不同的用户角色和权限进行测试，确保访问控制正确。
• 为客户端的函数调用逻辑编写单元测试。

---

参考资料

• Cloud Functions for Firebase Flutter 文档
• Firebase Emulator Suite