HarmonyOS鸿蒙Next开发者技术支持-泛型理解与项目实践

前言：

在开发过程中很多小伙伴们经常会使用单泛型，开发中也挺常见的，本文将从泛型的基础概念出发，结合鸿蒙 ArkTS API12 + 的特性，通过网络请求封装和 UI 组件设计等实际场景，详细讲解泛型在鸿蒙项目中的应用方法。特别针对 ArkTS 的严格类型检查机制，提供符合规范的泛型实现方案，帮助开发者在避免any、unknown等不安全类型的同时，充分发挥泛型的优势，构建高质量的鸿蒙应用。

一、泛型的核心概念

泛型（Generics）是一种类型抽象机制，允许在定义组件、函数或接口时不指定具体类型，而在使用时再确定类型。在 ArkTS 中，泛型是实现类型安全和代码复用的关键技术，尤其适合开发可复用组件和工具类。

核心价值：

• 类型安全：在编译期检查类型，避免运行时类型错误
• 代码复用：一套逻辑适配多种数据类型
• 可读性：明确代码的使用意图，提高可维护性

二、泛型基础语法

1. 泛型函数

// 定义泛型函数：交换数组中两个元素的位置
function swap<T>(array: T[], index1: number, index2: number): T[] {
  if (index1 < 0 || index2 < 0 || index1 >= array.length || index2 >= array.length) {
    return [...array];
  }
  const newArray = [...array];
  const temp = newArray[index1];
  newArray[index1] = newArray[index2];
  newArray[index2] = temp;
  return newArray;
}

// 使用泛型函数
const numberArray = [1, 2, 3, 4];
const swappedNumbers = swap(numberArray, 0, 2); // [3, 2, 1, 4]

const stringArray = ['a', 'b', 'c'];
const swappedStrings = swap(stringArray, 1, 2); // ['a', 'c', 'b']

2. 泛型接口

// 定义泛型接口：数据响应模型
export interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}
// 具体类型实现
interface User {
  id: string;
  name: string;
  age: number;
}

interface Article {
  id: string;
  title: string;
  content: string;
}

// 使用泛型接口
const userResponse: ApiResponse<User> = {
  code: 200,
  message: 'success',
  data: { id: '1', name: '张三', age: 25 },
};

const articleResponse: ApiResponse<Article> = {
  code: 200,
  message: 'success',
  data: { id: '101', title: '泛型教程', content: '...' },
};

3. 泛型类

// 定义泛型类：栈数据结构
class Stack<T> {
  private elements: T[] = [];

  // 入栈
  push(element: T): void {
    this.elements.push(element);
  }

  // 出栈
  pop(): T | undefined {
    return this.elements.pop();
  }

  // 获取栈顶元素
  peek(): T | undefined {
    return this.elements[this.elements.length - 1];
  }

  // 检查是否为空
  isEmpty(): boolean {
    return this.elements.length === 0;
  }

  // 获取栈大小
  size(): number {
    return this.elements.length;
  }
}

// 使用泛型类
const numberStack = new Stack<number>();
numberStack.push(1);
numberStack.push(2);
console.log(numberStack.pop()?.toString()); // 2

const stringStack = new Stack<string>();
stringStack.push('Hello');
stringStack.push('ArkTS');
console.log(stringStack.peek()); // ArkTS

三、项目中泛型的实际应用

网络请求封装

import http from '@ohos.net.http';
import { BusinessError } from '@ohos.base';

// 定义请求头接口
export interface HttpHeaders {
  contentType?: string;
  authorization?: string;
  accept?: string;
  userAgent?: string;
  // 可以根据需要添加其他常用头字段
}

// 定义API响应泛型接口
export interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}

// 定义请求参数泛型接口
export interface RequestOptions<T = void> {
  url: string;
  method: http.RequestMethod;
  headers?: HttpHeaders;
  customHeaders?: Record<string, string>; // 用于存储自定义头
  data?: T;
  timeout?: number;
}

// 默认请求头常量
const DEFAULT_HEADERS: HttpHeaders = {
  contentType: 'application/json'
};

// 将头信息转换为http请求所需格式
function convertHeaders(headers?: HttpHeaders, customHeaders?: Record<string, string>): Record<string, string> {
  const result: Record<string, string> = {};

  // 处理标准头
  if (headers) {
    if (headers.contentType) result['Content-Type'] = headers.contentType;
    if (headers.authorization) result['Authorization'] = headers.authorization;
    if (headers.accept) result['Accept'] = headers.accept;
    if (headers.userAgent) result['User-Agent'] = headers.userAgent;
  }

  // 处理自定义头
  if (customHeaders) {
    Object.keys(customHeaders).forEach(key => {
      result[key] = customHeaders![key];
    });
  }

  return result;
}

// 泛型API客户端
export class ApiClient {
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  // 泛型请求方法
  async request<T, D = void>(options: RequestOptions<D>): Promise<ApiResponse<T>> {
    const httpRequest = http.createHttp();

    try {
      const fullUrl = this.baseUrl + options.url;
      // 转换并合并请求头
      const requestHeaders = convertHeaders(options.headers || DEFAULT_HEADERS, options.customHeaders);

      const requestOptions: http.HttpRequestOptions = {
        method: options.method,
        header: requestHeaders,
        extraData: options.data ? JSON.stringify(options.data) : '',
        connectTimeout: options.timeout || 5000,
        readTimeout: options.timeout || 10000
      };

      const response = await httpRequest.request(fullUrl, requestOptions);

      if (response.responseCode === 200) {
        return JSON.parse(response.result as string) as ApiResponse<T>;
      } else {
        throw new Error(`Request failed with code: ${response.responseCode}`);
      }
    } catch (error) {
      const businessError = error as BusinessError;
      throw new Error(`Network error: ${businessError.message || 'Unknown error'}`);
    } finally {
      httpRequest.destroy();
    }
  }

  // GET请求快捷方法
  get<T>(url: string, headers?: HttpHeaders, customHeaders?: Record<string, string>): Promise<ApiResponse<T>> {
    return this.request<T>({
      url,
      method: http.RequestMethod.GET,
      headers,
      customHeaders
    });
  }

  // POST请求快捷方法
  post<T, D>(url: string, data: D, headers?: HttpHeaders, customHeaders?: Record<string, string>): Promise<ApiResponse<T>> {
    return this.request<T, D>({
      url,
      method: http.RequestMethod.POST,
      data,
      headers,
      customHeaders
    });
  }
}

四、泛型约束与高级用法

1. 泛型约束

// 定义带约束的泛型接口
interface HasId {
  id: string;
}

// 泛型约束：T必须实现HasId接口
function findById<T extends HasId>(items: T[], id: string): T | undefined {
  return items.find(item => item.id === id);
}

// 符合约束的类型
interface Book extends HasId {
  title: string;
  author: string;
}

// 使用带约束的泛型函数
const books: Book[] = [
  { id: 'b1', title: 'ArkTS入门', author: '张三' },
  { id: 'b2', title: '鸿蒙开发实战', author: '李四' }
];

const book = findById(books, 'b1'); // 正确，返回Book类型

2. 泛型默认值

// 定义一个基础空类型作为默认值
interface EmptyData {
  // 空接口，作为默认数据类型
}

// 带默认值的泛型接口，使用具体类型替代unknown
interface DataResult<T = EmptyData> {
  success: boolean;
  data: T;
  error?: string;
}

// 使用默认类型（EmptyData）
const defaultResult: DataResult = {
  success: true,
  data: {} // 符合EmptyData类型
};

// 指定字符串类型
const stringResult: DataResult<string> = {
  success: true,
  data: 'some data'
};

// 指定数字类型
const numberResult: DataResult<number> = {
  success: true,
  data: 42
};

// 定义用户类型
interface User {
  id: string;
  name: string;
}


// 指定复杂类型
const userResult: DataResult<User> = {
  success: true,
  data: {
    id: '123',
    name: '张三'
  }
};

// 错误结果示例
const errorResult: DataResult = {
  success: false,
  data: {},
  error: '操作失败'
};

五、泛型在项目中的最佳实践

1. 保持类型清晰：为泛型参数使用有意义的名称（T, U, V 适合简单场景，复杂场景使用如 TItem, TResponse 等）

2. 适度使用约束：合理的约束可以提高类型安全性，避免过度约束降低灵活性

3. 优先考虑泛型而非 any：任何使用 any 的场景都应首先考虑是否可以用泛型替代

4. 封装通用逻辑：将网络请求、数据存储、列表展示等通用逻辑用泛型封装

5. 配合接口使用：泛型与接口结合可以创建灵活且类型安全的组件系统

通过泛型，我们可以在鸿蒙 ArkTS 应用中创建既灵活又类型安全的代码，减少重复代码的同时保持编译期类型检查，这对于构建可维护、高质量的应用至关重要。