ArkTS 项目示例

概述

本示例展示了如何在鸿蒙 ArkTS 项目中集成 ApiSorcery。ArkTS 是华为用于鸿蒙开发的编程语言，为构建原生鸿蒙应用程序提供现代化的开发体验。

特性

• 鸿蒙原生：针对鸿蒙生态系统和 API 进行优化
• 类型安全：完整的 ArkTS 类型支持，生成接口定义
• @ohos/axios 集成：内置支持鸿蒙适配的 HTTP 客户端
• 分布式能力：支持鸿蒙分布式特性
• 性能优化：针对鸿蒙运行时和内存管理进行优化

快速设置

1. 安装 ApiSorcery

npm install -g autoapi

2. 初始化配置

autoapi init -l arkTs

这将创建一个 .autoapirc.json 配置文件：

{
  "application": {
    "name": "鸿蒙 API 客户端",
    "language": "arkTs",
    "outputDir": "./src/main/ets/api/auto"
  },
  "services": [
    {
      "code": "main",
      "name": "主服务",
      "source": "https://your-api.com/swagger.json",
      "enabled": true
    }
  ]
}

3. 安装依赖

在 oh-package.json5 中添加所需依赖：

{
  "dependencies": {
    "@ohos/axios": "^2.2.0"
  }
}

4. 配置网络权限

在 src/main/module.json5 中添加网络权限：

{
  "requestPermissions": [
    {
      "name": "ohos.permission.INTERNET"
    }
  ]
}

5. 生成 API 客户端

autoapi generate

6. 在 ArkTS 中使用

import { ApiMain } from '../api/auto/main/api';
import { User } from '../api/auto/main/model';

@Entry
@Component
struct UserPage {
  @State users: User[] = [];
  @State loading: boolean = false;
  private apiMain = new ApiMain();

  async aboutToAppear() {
    await this.loadUsers();
  }

  async loadUsers() {
    this.loading = true;
    try {
      const response = await this.apiMain.getUsers();
      this.users = response.data || [];
    } catch (error) {
      console.error('获取用户失败:', error);
    } finally {
      this.loading = false;
    }
  }

  build() {
    Column() {
      if (this.loading) {
        LoadingProgress()
          .width(50)
          .height(50)
      } else {
        List() {
          ForEach(this.users, (user: User) => {
            ListItem() {
              Text(user.name)
                .fontSize(16)
                .padding(10)
            }
          })
        }
      }
    }
    .width('100%')
    .height('100%')
  }
}

鸿蒙特有功能

分布式数据管理

import distributedKVStore from '@ohos.data.distributedKVStore';

class UserService {
  private apiMain = new ApiMain();
  private kvStore?: distributedKVStore.SingleKVStore;

  async syncUserData(userId: string) {
    const userData = await this.apiMain.getUser(userId);
    // 与分布式 KV 存储同步
    if (this.kvStore) {
      await this.kvStore.put(`user_${userId}`, JSON.stringify(userData.data));
    }
  }
}

后台任务集成

import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';

class DataSyncService {
  private apiMain = new ApiMain();

  async startBackgroundSync() {
    const requestInfo: backgroundTaskManager.BackgroundTaskInfo = {
      bgMode: backgroundTaskManager.BackgroundMode.DATA_TRANSFER,
      wantAgent: undefined
    };

    backgroundTaskManager.startBackgroundRunning(getContext(), requestInfo)
      .then(() => {
        this.performDataSync();
      });
  }

  private async performDataSync() {
    try {
      const response = await this.apiMain.syncData();
      console.log('后台同步完成:', response.data);
    } catch (error) {
      console.error('后台同步失败:', error);
    }
  }
}

最佳实践

1. 权限管理：正确请求和处理网络权限
2. 生命周期管理：将 API 调用与鸿蒙组件生命周期集成
3. 错误处理：实现鸿蒙特定的错误处理模式
4. 性能优化：使用鸿蒙性能优化技术
5. 分布式特性：在适用时利用鸿蒙分布式能力