鸿蒙ArkTS实战：5分钟搞定阿里云通义千问API对接（API9/Stage模型）

最近在鸿蒙生态中尝试对接大模型API时，发现很多教程都过于复杂，包含了大量非核心的UI设计和项目结构内容。对于只想快速验证功能是否可行的开发者来说，这种"大而全"的教程反而增加了学习成本。本文将聚焦最核心的HTTP请求模块，带你用最短的代码实现阿里云通义千问API的对接。

1. 准备工作：API Key获取与权限配置

在开始编码前，我们需要完成两项基础工作：获取API Key和配置网络权限。这两步看似简单，但往往是新手最容易卡住的地方。

获取API Key的步骤 ：

1. 访问阿里云DashScope控制台（需注册账号）
2. 在"API-KEY管理"页面创建新的密钥
3. 复制生成的 sk- 开头的密钥字符串

注意：API Key相当于你的身份凭证，请妥善保管不要泄露。测试阶段可以使用临时密钥，正式环境建议定期轮换。

配置网络权限需要在 module.json5 文件中添加以下内容：

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

这个配置允许应用访问互联网，没有它我们的HTTP请求将无法发出。很多开发者第一次对接API时遇到的"网络请求失败"问题，90%都是因为这个权限没配置。

2. 极简HTTP请求实现

现在进入核心部分——实现HTTP请求。我们创建一个独立的 ALiYunHttpUtils.ts 文件，避免与UI代码混在一起。这是保持代码整洁的关键。

import http from '@ohos.net.http';
import hilog from '@ohos.hilog';

class ALiYunHttpUtils {
  private static readonly TAG: string = 'ALiYunHttpUtils';
  private static readonly ENDPOINT: string = 
    'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation';

  static async request(apiKey: string, question: string): Promise<string> {
    const httpRequest = http.createHttp();
    
    try {
      const response = await new Promise<http.HttpResponse>((resolve, reject) => {
        httpRequest.request(
          this.ENDPOINT,
          {
            method: http.RequestMethod.POST,
            header: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
            },
            extraData: JSON.stringify({
              model: 'qwen-turbo',
              input: {
                messages: [{
                  role: 'user',
                  content: question
                }]
              }
            })
          },
          (err, data) => err ? reject(err) : resolve(data)
        );
      });

      const result = JSON.parse(response.result.toString());
      return result.output.text;
    } catch (error) {
      hilog.error(0x0000, this.TAG, 'Request failed: %{public}s', error.message);
      throw error;
    } finally {
      httpRequest.destroy();
    }
  }
}

export default ALiYunHttpUtils;

这段代码有几个值得注意的优化点：

• 使用了 async/await 语法，让异步代码更易读
• 将端点URL定义为常量，方便后续修改
• 添加了完整的错误处理逻辑
• 使用Promise包装回调函数，符合现代编程习惯

3. 调用验证与日志查看

实现请求模块后，我们需要一个简单的验证方式。在EntryAbility的 onWindowStageCreate 方法中添加测试代码：

import ALiYunHttpUtils from './ALiYunHttpUtils';

onWindowStageCreate(windowStage: Window.WindowStage) {
  // ...其他初始化代码
  
  // 测试API调用
  ALiYunHttpUtils.request('your-api-key', '鸿蒙系统有什么特点？')
    .then(response => {
      hilog.info(0x0000, 'TestAPI', 'Response: %{public}s', response);
    })
    .catch(error => {
      hilog.error(0x0000, 'TestAPI', 'Error: %{public}s', error.message);
    });
}

查看日志是调试API的关键。在DevEco Studio中：

1. 点击底部工具栏的"Log"标签
2. 选择设备为"Previewer"
3. 过滤标签为"TestAPI"

成功时你会看到类似这样的响应：

{
  "output": {
    "text": "鸿蒙系统是华为推出的分布式操作系统，主要特点包括...",
    "finish_reason": "stop"
  }
}

4. 常见问题排查指南

即使按照步骤操作，仍可能遇到各种问题。以下是几个典型问题及解决方案：

问题1：网络请求返回403错误

可能原因 ：

• API Key不正确或已过期
• 请求头Authorization格式错误
• 服务未开通

解决方案 ：

// 正确的Authorization格式
header: {
  'Authorization': 'Bearer sk-0b...' // 注意Bearer后面有空格
}

问题2：预览器无法输出日志

检查步骤 ：

1. 确认已添加hilog权限
2. 检查日志过滤条件是否正确
3. 尝试重启预览器

问题3：请求超时无响应

优化建议 ：

// 添加超时设置
httpRequest.request(
  // ...其他参数
  {
    // ...
    connectTimeout: 10000, // 10秒连接超时
    readTimeout: 30000     // 30秒读取超时
  }
);

5. 进阶：参数调优与性能考量

当基础功能跑通后，可以考虑对请求参数进行优化。通义千问API支持多个可调参数：

参数名	类型	默认值	说明
model	string	qwen-turbo	可选qwen-plus等更强模型
temperature	number	0.85	控制生成随机性
top_p	number	0.8	核采样概率
max_tokens	number	1500	最大生成token数

一个优化后的请求示例：

extraData: JSON.stringify({
  model: 'qwen-plus',
  parameters: {
    temperature: 0.7,
    top_p: 0.9,
    max_tokens: 1000
  },
  input: {
    messages: [{
      role: 'user',
      content: question
    }]
  }
})

性能方面需要注意：

• 避免在UI线程直接发起网络请求
• 考虑添加本地缓存减少重复请求
• 对长文本响应实现流式输出

// 在TaskPool中执行耗时操作
import taskpool from '@ohos.taskpool';

@Concurrent
async function callAPI(apiKey: string, question: string) {
  return ALiYunHttpUtils.request(apiKey, question);
}

// 调用方式
taskpool.execute(callAPI, [apiKey, question]).then(response => {
  // 更新UI
});