digital-pilates/docs/background-tasks-implementation.md

后台任务系统实现文档

概述

本项目已成功集成iOS后台任务支持，使用Expo官方的 expo-task-manager 和 expo-background-task 库。该系统提供了完整的后台任务管理功能，支持任务注册、执行、状态监控等。

技术栈

• expo-task-manager: Expo官方后台任务管理库
• expo-background-task: Expo官方后台任务库
• React Native: 跨平台移动应用框架
• TypeScript: 类型安全的JavaScript超集

文件结构

services/
├── backgroundTaskManager.ts    # 后台任务管理器核心逻辑
├── backgroundTasks.ts          # 示例任务定义
hooks/
├── useBackgroundTasks.ts       # 后台任务自定义Hook
components/
├── BackgroundTaskTest.tsx      # 后台任务测试组件

核心功能

1. 后台任务管理器 (services/backgroundTaskManager.ts)

主要特性

• 单例模式: 确保全局只有一个任务管理器实例
• 任务注册: 支持注册自定义后台任务
• 状态管理: 完整的任务状态跟踪和持久化
• 错误处理: 完善的错误处理和日志记录
• 后台获取: 自动注册后台获取任务

核心方法

// 初始化后台任务管理器
await backgroundTaskManager.initialize();

// 注册自定义任务
await backgroundTaskManager.registerTask({
  id: 'my-task',
  name: '我的任务',
  handler: async (data) => {
    // 您的任务逻辑
    console.log('执行任务:', data);
  },
  options: {
    minimumInterval: 300, // 5分钟最小间隔
    stopOnTerminate: false,
    startOnBoot: true,
  }
});

// 手动执行任务
await backgroundTaskManager.executeTask('my-task', { customData: 'value' });

// 执行所有任务
const results = await backgroundTaskManager.executeAllTasks();

// 获取任务状态
const status = backgroundTaskManager.getTaskStatus('my-task');

2. 自定义Hook (hooks/useBackgroundTasks.ts)

主要特性

• 状态管理: 管理任务状态和初始化状态
• 自动初始化: 组件挂载时自动初始化任务管理器
• 便捷接口: 提供简化的任务操作方法
• 实时更新: 任务状态实时更新

使用示例

const {
  isInitialized,
  taskStatuses,
  registeredTasks,
  registerTask,
  executeTask,
  executeAllTasks,
} = useBackgroundTasks();

// 注册任务
await registerTask({
  id: 'data-sync',
  name: '数据同步',
  handler: async () => {
    // 数据同步逻辑
  }
});

// 执行任务
await executeTask('data-sync');

3. 示例任务 (services/backgroundTasks.ts)

预定义任务类型

• 数据同步任务: 同步用户数据、运动记录等
• 健康数据更新任务: 更新步数、心率等健康数据
• 通知检查任务: 检查是否需要发送通知
• 缓存清理任务: 清理过期缓存文件
• 用户行为分析任务: 分析用户使用模式

创建自定义任务

import { createCustomTask } from '@/services/backgroundTasks';

const myTask = createCustomTask(
  'my-custom-task',
  '我的自定义任务',
  async (data) => {
    // 您的任务逻辑
    console.log('执行自定义任务:', data);
  },
  {
    minimumInterval: 120, // 2分钟
    stopOnTerminate: false,
    startOnBoot: true,
  }
);

使用指南

1. 基本使用

import { useBackgroundTasks } from '@/hooks/useBackgroundTasks';
import { createCustomTask } from '@/services/backgroundTasks';

const MyComponent = () => {
  const { registerTask, executeTask } = useBackgroundTasks();

  const handleCreateTask = async () => {
    const task = createCustomTask(
      'my-task',
      '我的任务',
      async (data) => {
        // 实现您的后台任务逻辑
        console.log('后台任务执行中...');
        
        // 例如：数据同步
        await syncUserData();
        
        // 例如：健康数据更新
        await updateHealthData();
        
        // 例如：发送通知
        await checkAndSendNotifications();
      }
    );

    await registerTask(task);
  };

  const handleExecuteTask = async () => {
    await executeTask('my-task', { customData: 'value' });
  };

  return (
    <View>
      <Button title="创建任务" onPress={handleCreateTask} />
      <Button title="执行任务" onPress={handleExecuteTask} />
    </View>
  );
};

2. 任务状态监控

const { taskStatuses, getTaskStatus } = useBackgroundTasks();

// 获取特定任务状态
const taskStatus = getTaskStatus('my-task');
console.log('任务状态:', {
  isRegistered: taskStatus?.isRegistered,
  executionCount: taskStatus?.executionCount,
  lastExecution: taskStatus?.lastExecution,
  lastError: taskStatus?.lastError,
});

3. 批量操作

const { executeAllTasks, cleanupTaskStatuses } = useBackgroundTasks();

// 执行所有任务
const results = await executeAllTasks();
console.log('执行结果:', results);

// 清理过期任务状态
await cleanupTaskStatuses();

配置说明

iOS配置

在 app.json 中已配置后台模式：

{
  "expo": {
    "ios": {
      "infoPlist": {
        "UIBackgroundModes": ["remote-notification"]
      }
    }
  }
}

后台获取配置

系统自动配置后台获取任务，支持：

• 最小间隔时间设置
• 应用终止时继续运行
• 设备重启时自动启动

最佳实践

1. 任务设计原则

• 轻量级: 后台任务应该快速执行，避免长时间运行
• 幂等性: 任务应该可以重复执行而不产生副作用
• 错误处理: 完善的错误处理和重试机制
• 资源管理: 合理管理内存和网络资源

2. 性能优化

• 最小间隔: 根据任务重要性设置合适的最小间隔
• 批量处理: 将多个小任务合并为一个大任务
• 缓存策略: 合理使用缓存减少重复计算

3. 用户体验

• 静默执行: 后台任务应该静默执行，不打扰用户
• 状态反馈: 通过UI显示任务执行状态
• 错误提示: 在任务失败时提供友好的错误提示

测试

使用 BackgroundTaskTest 组件进行功能测试：

import { BackgroundTaskTest } from '@/components/BackgroundTaskTest';

// 在您的页面中使用
<BackgroundTaskTest />

该组件提供：

• 任务注册和取消注册测试
• 任务执行测试
• 状态监控测试
• 后台获取状态测试

注意事项

1. iOS限制: iOS对后台任务有严格限制，系统会根据电池状态和用户使用模式调整执行频率
2. 权限要求: 某些后台任务可能需要特殊权限
3. 调试模式: 在开发模式下，后台任务行为可能与生产环境不同
4. 网络状态: 后台任务执行时需要考虑网络状态变化

故障排除

常见问题

1. 任务不执行: 检查iOS后台模式配置和任务注册状态
2. 执行频率低: 系统会根据电池状态自动调整，这是正常行为
3. 任务被终止: 检查任务执行时间，避免长时间运行

调试技巧

1. 使用 console.log 记录任务执行状态
2. 检查任务状态和错误信息
3. 使用Xcode查看后台任务日志
4. 测试不同的最小间隔设置