HarmonyOS 接入教程

可直接运行的示例请参考 HarmonyOS 示例。

前置条件

• DevEco Studio ≥ 4.0，HarmonyOS SDK API ≥ 11
• ApiSorcery CLI 已安装（npm i -g @apisorcery/cli）
• 设备已注册（apisorcery register）
• 已配置 .apisorceryrc.json（参考服务配置）

生成文件结构

执行 apisorcery generate 后，以下文件将创建在 outputDir（如 entry/src/main/ets/api/auto/）下：

auto/
└── {service_code}/
    ├── Api{Tag}.ets           # 每个 Swagger Tag 对应一个文件 — 勿手动修改
    ├── model.ets              # 所有请求/响应类型 — 勿手动修改
    ├── base.ets               # 基础工具 — 勿手动修改
    └── httpClient/
        ├── interceptors/
        │   ├── request.ets    # ✏️ 在此添加鉴权 Token
        │   └── response.ets   # ✏️ 在此处理全局错误
        └── requests/
            └── json.ets       # 使用 @ohos.net.http — ✏️ 在此修改 Base URL

ArkTS vs TypeScript

HarmonyOS 使用 ArkTS，是 TypeScript 的严格超集。生成的客户端使用 @ohos.net.http，无需安装第三方依赖包。

配置 Base URL

打开 httpClient/requests/json.ets，设置你的 API 服务地址：

const BASE_URL = 'https://your-api.com'; // ✏️ 修改这里

配置鉴权 Token

打开 httpClient/interceptors/request.ets：

export function requestInterceptor(options: RequestOptions): RequestOptions {
  const token = AppStorage.get<string>('token'); // ✏️ 替换为你自己的 Token 来源
  if (token) {
    options.header = {
      ...options.header,
      'Authorization': `Bearer ${token}`,
    };
  }
  return options;
}

打开 httpClient/interceptors/response.ets，处理鉴权失效：

export function responseInterceptor(response: HttpResponse): HttpResponse {
  if (response.responseCode === 401) {
    // ✏️ 跳转到登录页
    router.pushUrl({ url: 'pages/Login' });
  }
  return response;
}

网络权限配置

在 entry/src/main/module.json5 中添加：

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

调用生成的 API

import { ApiUser } from '../api/auto/demo/ApiUser';
import { UserPageQueryDto } from '../api/auto/demo/model';

async function loadUsers() {
  const params: UserPageQueryDto = { page: 1, limit: 10 };
  const users = await ApiUser.getUserList(params);
  console.info('users:', JSON.stringify(users));
}

常见问题

returnLevel 应该选哪个？

大多数后端将响应包裹为 { code, data, message } 格式。使用默认的 "returnLevel": "second" 可自动解包 data 字段。如果你的接口直接返回数据体（无外层包裹），则使用 "returnLevel": "first"。

中文 Tag 名称导致生成的类名无法编译

在服务配置中添加 tagNameMap：

"tagNameMap": { "用户管理": "User", "订单管理": "Order" }

详见服务配置。