Flutter三方库nhost_sdk鸿蒙适配全攻略

yao lifu

1. Flutter 三方库 nhost_sdk 的鸿蒙化适配指南

在鸿蒙生态中构建全栈应用时，后端服务的选择往往成为开发效率的关键制约因素。Nhost 作为一套开箱即用的后端解决方案，为开发者提供了身份认证、文件存储和 GraphQL API 等核心功能。而 nhost_sdk 则是连接鸿蒙应用与 Nhost 后端的重要桥梁。

1.1 Nhost 生态体系解析

Nhost 的核心价值在于它将多个优秀的开源项目整合为一个完整的后端平台：

Hasura GraphQL：提供即时生成的 GraphQL API
PostgreSQL：作为底层数据库
S3 兼容存储：用于文件管理
JWT 认证：基于 GoTrue 的身份验证服务

nhost_sdk 对这些服务进行了 Dart 语言层面的封装，使得鸿蒙开发者可以专注于业务逻辑的实现，而不必关心底层复杂的网络通信和状态管理。

2. 环境准备与基础配置

2.1 开发环境要求

在开始集成 nhost_sdk 前，请确保你的开发环境满足以下条件：

Flutter SDK ≥ 3.0.0
Dart SDK ≥ 2.17.0
鸿蒙开发环境已配置完成
有效的 Nhost 项目账户

2.2 项目依赖配置

在项目的 pubspec.yaml 中添加依赖：

yaml复制dependencies:
  nhost_sdk: ^1.0.0
  dio: ^4.0.0 # 网络请求库
  shared_preferences: ^2.0.0 # 本地存储

运行 flutter pub get 安装依赖后，需要在鸿蒙的 module.json5 中声明必要的权限：

json复制{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.READ_IMAGEVIDEO",
        "reason": "用于选择用户头像"
      }
    ]
  }
}

3. Nhost 客户端初始化与配置

3.1 创建 NhostClient 实例

dart复制import 'package:nhost_sdk/nhost_sdk.dart';

final nhostClient = NhostClient(
  subdomain: 'your-subdomain',
  region: 'ap-southeast-1', // 根据实际区域选择
);

关键参数说明：

subdomain：在 Nhost 控制台创建项目时设置的子域名
region：建议选择离目标用户群体最近的区域
autoRefreshToken：默认为 true，建议保持开启以自动维护会话

3.2 持久化会话管理

为了在应用重启后保持用户登录状态，我们需要配置本地存储：

dart复制import 'package:nhost_sdk/nhost_sdk.dart';
import 'package:shared_preferences/shared_preferences.dart';

Future<NhostClient> initNhostClient() async {
  final prefs = await SharedPreferences.getInstance();
  return NhostClient(
    subdomain: 'your-subdomain',
    storage: await NHostLocalStorage.init(store: prefs),
  );
}

这种实现方式利用了鸿蒙兼容的 shared_preferences 插件，将会话信息安全地存储在设备本地。

4. 身份认证功能实现

4.1 邮箱密码认证流程

dart复制Future<void> handleEmailPasswordAuth(
  String email, 
  String password,
  bool isLogin,
) async {
  try {
    if (isLogin) {
      await nhostClient.auth.signInEmailPassword(
        email: email,
        password: password,
      );
    } else {
      await nhostClient.auth.signUpEmailPassword(
        email: email,
        password: password,
      );
    }
    print('当前用户: ${nhostClient.auth.currentUser?.email}');
  } on AuthException catch (e) {
    print('认证错误: ${e.message}');
  }
}

注意事项：

密码需满足 Nhost 的强度要求（默认至少6位）
新用户注册后会收到验证邮件
建议在 UI 层添加加载状态，防止重复提交

4.2 社交账号登录集成

Nhost 支持 Google、GitHub 等多种社交登录方式：

dart复制// 初始化时配置提供商
final nhostClient = NhostClient(
  subdomain: 'your-subdomain',
  authProviders: [
    AuthProvider.github,
    AuthProvider.google,
  ],
);

// 触发社交登录
void signInWithProvider(AuthProvider provider) {
  final url = nhostClient.auth.getOAuthUrl(provider);
  // 使用鸿蒙的 WebView 或外部浏览器打开授权页面
  openWebView(url);
}

关键点：

需要在 Nhost 控制台预先配置各提供商的 OAuth 凭据
鸿蒙端需要处理授权回调 URL
建议添加防 CSRF 保护

5. 文件存储操作实践

5.1 文件上传实现

dart复制Future<String?> uploadFile(File file) async {
  if (!nhostClient.auth.isAuthenticated) {
    throw Exception('请先登录');
  }

  final fileBytes = await file.readAsBytes();
  final fileName = 'user_uploads/${DateTime.now().millisecondsSinceEpoch}';

  try {
    final response = await nhostClient.storage.uploadBytes(
      fileName: fileName,
      fileContents: fileBytes,
      mimeType: lookupMimeType(file.path) ?? 'application/octet-stream',
    );
    return response.id;
  } on StorageException catch (e) {
    print('上传失败: ${e.message}');
    return null;
  }
}

性能优化建议：

大文件（>10MB）应采用分片上传
显示上传进度提升用户体验
后台任务中处理失败重试逻辑

5.2 文件访问与下载

dart复制Future<Uint8List?> downloadFile(String fileId) async {
  try {
    return await nhostClient.storage.downloadBytes(fileId);
  } on StorageException catch (e) {
    print('下载失败: ${e.message}');
    return null;
  }
}

// 获取文件公开URL
String getPublicUrl(String fileId) {
  return nhostClient.storage.getPublicUrl(fileId);
}

安全注意事项：

文件权限默认跟随存储桶设置
敏感文件应设置适当的访问策略
考虑使用预签名URL实现临时访问

6. 鸿蒙平台特定适配

6.1 生命周期管理

鸿蒙应用的特殊生命周期需要额外处理：

dart复制class AppLifecycleObserver with WidgetsBindingObserver {
  final NhostClient client;

  AppLifecycleObserver(this.client);

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.resumed) {
      // 应用回到前台时刷新会话
      client.auth.refreshSession().catchError((e) {
        print('会话刷新失败: $e');
      });
    }
  }
}

// 在应用初始化时注册观察者
WidgetsBinding.instance.addObserver(AppLifecycleObserver(nhostClient));

6.2 后台任务处理

对于大文件传输等耗时操作，建议使用鸿蒙的后台任务机制：

dart复制void startBackgroundUpload(List<File> files) {
  // 配置后台任务参数
  final taskParams = {
    'files': files.map((f) => f.path).toList(),
    'authToken': nhostClient.auth.currentSession?.accessToken,
  };

  // 启动后台任务
  BackgroundTask.start(
    'file_upload_task',
    inputData: taskParams,
  );
}

注意事项：

后台任务有执行时间限制
需要处理Token过期的情况
建议添加任务状态通知

7. 实战案例：用户资料管理系统

7.1 数据模型设计

dart复制class UserProfile {
  final String id;
  final String email;
  final String? avatarUrl;
  final DateTime createdAt;

  UserProfile({
    required this.id,
    required this.email,
    this.avatarUrl,
    required this.createdAt,
  });

  factory UserProfile.fromJson(Map<String, dynamic> json) {
    return UserProfile(
      id: json['id'],
      email: json['email'],
      avatarUrl: json['avatar_url'],
      createdAt: DateTime.parse(json['created_at']),
    );
  }
}

7.2 完整CRUD实现

dart复制class ProfileService {
  final NhostClient client;

  ProfileService(this.client);

  Future<UserProfile?> getProfile() async {
    if (!client.auth.isAuthenticated) return null;
    
    final userId = client.auth.currentUser!.id;
    final response = await client.graphql.request('''
      query GetProfile($userId: uuid!) {
        profiles_by_pk(id: $userId) {
          id
          email
          avatar_url
          created_at
        }
      }
    ''', variables: {'userId': userId});

    return UserProfile.fromJson(response.data['profiles_by_pk']);
  }

  Future<void> updateAvatar(String fileId) async {
    await client.graphql.request('''
      mutation UpdateAvatar($userId: uuid!, $fileId: uuid!) {
        update_profiles_by_pk(
          pk_columns: {id: $userId}
          _set: {avatar_url: $fileId}
        ) {
          id
        }
      }
    ''', variables: {
      'userId': client.auth.currentUser!.id,
      'fileId': fileId,
    });
  }
}

8. 性能优化与调试技巧

8.1 网络请求优化

dart复制final optimizedClient = NhostClient(
  subdomain: 'your-subdomain',
  dio: Dio()
    ..interceptors.add(LogInterceptor()) // 请求日志
    ..interceptors.add(QueuedInterceptor()) // 请求队列
    ..interceptors.add(RetryInterceptor()), // 自动重试
);

8.2 常见问题排查

认证失败
- 检查Nhost控制台的认证设置
- 验证客户端时钟是否准确
- 检查网络拦截规则
上传中断
- 确认文件权限
- 检查存储桶策略
- 分片大小调整（默认5MB）
GraphQL错误
- 使用Nhost控制台的API Explorer测试查询
- 检查字段权限设置
- 验证变量类型匹配

9. 安全最佳实践

9.1 敏感数据处理

dart复制// 使用鸿蒙的安全存储保存敏感信息
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final secureStorage = FlutterSecureStorage();
await secureStorage.write(
  key: 'nhost_refresh_token',
  value: nhostClient.auth.currentSession?.refreshToken,
);

9.2 权限控制策略

在Nhost控制台配置行级安全策略：

sql复制-- 示例：限制用户只能访问自己的资料
create policy profile_access_policy
on profiles
for select
using (id = auth.uid());

10. 扩展与进阶用法

10.1 实时数据订阅

dart复制final subscription = nhostClient.graphql.subscribe('''
  subscription GetMessages {
    messages(order_by: {created_at: desc}, limit: 10) {
      id
      content
      created_at
    }
  }
''').listen((result) {
  print('新消息: ${result.data}');
});

10.2 自定义函数调用

dart复制Future<void> callCustomFunction() async {
  final response = await nhostClient.functions.call(
    'generate-report',
    body: {'month': '2023-10'},
  );
  print('函数响应: ${response.data}');
}