如何利用 `TypeScript` 的类型系统，为 Vue 3 `Composition API` 编写可维护、类型安全的自定义 Hook？

各位前端同僚，大家好！

今天，我们来聊聊如何用 TypeScript 为 Vue 3 的 Composition API 打造坚如磐石、类型安全的自定义 Hook。 咱们要打造的，可不是那种用完就扔的一次性用品，而是可以长期维护、扩展性强的精品。准备好了吗？Let’s dive in!

开场白：为什么要重视类型安全？

想象一下，你在凌晨三点钟调试代码，发现一个变量的值和你预期的完全不一样，而 TypeScript 可以早早地在编码阶段就帮你发现这类问题。 别说凌晨三点了，谁也不想花时间debug类型错误不是？ 所以，重视类型安全，就是重视你的睡眠质量，以及项目的长期健康。

第一部分：自定义 Hook 的基础骨架

首先，我们来构建一个最简单的自定义 Hook 的骨架。一个 Hook 本质上就是一个函数，它内部使用 Vue 的 Composition API，并返回一些值（可以是 reactive 对象、函数等等）。

// useCounter.ts
import { ref, computed } from 'vue';

export function useCounter(initialValue: number = 0) {
  const count = ref(initialValue);

  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  const doubleCount = computed(() => count.value * 2);

  return {
    count,
    increment,
    decrement,
    doubleCount,
  };
}

这个 useCounter Hook 简单明了：它维护一个 count 状态，并提供 increment、decrement 两个操作，以及一个计算属性 doubleCount。

类型推断：TypeScript 的自动挡

在这个例子中，TypeScript 已经为我们做了很多类型推断的工作。例如，count 被推断为 Ref<number>，doubleCount 被推断为 ComputedRef<number>。 我们可以省下不少力气！

第二部分：显式类型注解：手动挡更灵活

虽然类型推断很方便，但在某些情况下，我们需要手动添加类型注解，以提供更精确的类型信息。

1. Hook 的参数类型

在上面的例子中，initialValue 的类型被指定为 number。 这确保了我们只能传递数字作为初始值。 如果我们尝试传递一个字符串，TypeScript 会立即报错。

2. Hook 的返回值类型

为了让 Hook 的返回值类型更加明确，我们可以使用 ReturnType 工具类型。

import { ref, computed, Ref, ComputedRef } from 'vue';

interface UseCounterReturnType {
  count: Ref<number>;
  increment: () => void;
  decrement: () => void;
  doubleCount: ComputedRef<number>;
}

export function useCounter(initialValue: number = 0): UseCounterReturnType {
  const count = ref(initialValue);

  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  const doubleCount = computed(() => count.value * 2);

  return {
    count,
    increment,
    decrement,
    doubleCount,
  };
}

或者使用as const简化:

import { ref, computed } from 'vue';

export function useCounter(initialValue: number = 0) {
  const count = ref(initialValue);

  const increment = () => {
    count.value++;
  };

  const decrement = () => {
    count.value--;
  };

  const doubleCount = computed(() => count.value * 2);

  return {
    count,
    increment,
    decrement,
    doubleCount,
  } as const;
}

// 使用ReturnType推断类型
type UseCounterReturnType = ReturnType<typeof useCounter>;

现在，我们显式地指定了 useCounter Hook 的返回值类型为 UseCounterReturnType。 这使得其他开发者在使用这个 Hook 时，可以清楚地知道它返回了哪些值，以及这些值的类型。

第三部分：处理复杂类型：泛型登场

当 Hook 需要处理更复杂的数据类型时，泛型就派上用场了。

1. 泛型参数

假设我们要创建一个 Hook，用于管理一个列表数据，列表中的元素类型可以是任意的。我们可以使用泛型来定义这个 Hook。

import { ref, Ref } from 'vue';

export function useList<T>(initialList: T[] = []) {
  const list: Ref<T[]> = ref(initialList);

  const addItem = (item: T) => {
    list.value.push(item);
  };

  const removeItem = (index: number) => {
    list.value.splice(index, 1);
  };

  return {
    list,
    addItem,
    removeItem,
  };
}

在这个例子中，T 是一个泛型类型参数，它可以代表任意类型。 我们将 list 的类型定义为 Ref<T[]>，这意味着 list 是一个包含 T 类型元素的数组的 Ref 对象。addItem 接受一个 T 类型的参数，removeItem 接受一个数字类型的参数。

使用示例：

import { useList } from './useList';
import { onMounted } from 'vue';

export default {
  setup() {
    const { list, addItem, removeItem } = useList<string>(['apple', 'banana']);

    onMounted(() => {
      addItem('orange');
      removeItem(0);
      console.log(list.value); // 输出：['banana', 'orange']
    });

    return {
      list,
    };
  },
};

2. 泛型约束

有时候，我们希望对泛型类型参数进行一些约束。例如，我们可能希望泛型类型参数必须是某个接口的子类型。

interface Person {
  name: string;
  age: number;
}

export function usePersonList<T extends Person>(initialList: T[] = []) {
  const list: Ref<T[]> = ref(initialList);

  const addPerson = (person: T) => {
    list.value.push(person);
  };

  return {
    list,
    addPerson,
  };
}

在这个例子中，我们使用 extends 关键字来约束泛型类型参数 T 必须是 Person 接口的子类型。 这意味着我们只能将实现了 Person 接口的对象添加到 list 中。

第四部分：响应式 Props：让 Hook 动起来

有时候，我们需要让 Hook 能够响应组件的 props 变化。 这可以通过 watch 函数来实现。

import { ref, watch, Ref } from 'vue';

export function useSearch(initialSearchTerm: string = '', props: { searchTerm: string }) {
  const searchTerm = ref(initialSearchTerm);

  watch(
    () => props.searchTerm,
    (newSearchTerm) => {
      searchTerm.value = newSearchTerm;
    }
  );

  return {
    searchTerm,
  };
}

在这个例子中，useSearch Hook 接受一个 initialSearchTerm 参数和一个 props 对象。 我们使用 watch 函数来监听 props.searchTerm 的变化，并将新的值赋给 searchTerm。

在组件中使用：

<template>
  <input type="text" v-model="searchTerm" />
  <p>Search Term: {{ searchTerm }}</p>
</template>

<script lang="ts">
import { ref } from 'vue';
import { useSearch } from './useSearch';

export default {
  props: {
    initialSearch: {
      type: String,
      default: '',
    },
  },
  setup(props) {
    const searchTerm = ref(props.initialSearch);
    const { searchTerm: searchHookTerm } = useSearch(props.initialSearch, { searchTerm: searchTerm.value });

    return {
      searchTerm:searchHookTerm
    };
  },
};
</script>

第五部分：异步操作：Promise 和 async/await

如果 Hook 需要执行异步操作，例如从 API 获取数据，我们可以使用 Promise 和 async/await。

import { ref, onMounted, Ref } from 'vue';

interface User {
  id: number;
  name: string;
  email: string;
}

export function useFetchUsers(url: string) {
  const users: Ref<User[]> = ref([]);
  const loading = ref(false);
  const error = ref<string | null>(null);

  const fetchUsers = async () => {
    loading.value = true;
    error.value = null;

    try {
      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const data: User[] = await response.json();
      users.value = data;
    } catch (e: any) {
      error.value = e.message;
    } finally {
      loading.value = false;
    }
  };

  onMounted(() => {
    fetchUsers();
  });

  return {
    users,
    loading,
    error,
    refetch: fetchUsers, // 暴露一个重新获取数据的函数
  };
}

在这个例子中，useFetchUsers Hook 接受一个 url 参数，用于指定 API 的地址。 我们使用 async/await 来简化异步操作，并使用 try...catch...finally 块来处理错误和加载状态。

第六部分：高级技巧：依赖注入

Vue 3 提供了依赖注入的功能，允许我们在组件树中共享数据和方法。 我们可以在自定义 Hook 中使用依赖注入，以实现更灵活的组件通信。

1. Provide/Inject

// provideKey.ts
import { InjectionKey } from 'vue';

export const counterKey: InjectionKey<{ count: Ref<number>; increment: () => void }> = Symbol('counter');

// useCounterProvider.ts
import { ref, provide } from 'vue';
import { counterKey } from './provideKey';

export function useCounterProvider() {
  const count = ref(0);

  const increment = () => {
    count.value++;
  };

  provide(counterKey, { count, increment });

  return {
    count,
    increment,
  };
}

// useCounterConsumer.ts
import { inject, Ref } from 'vue';
import { counterKey } from './provideKey';

export function useCounterConsumer() {
  const counter = inject(counterKey);

  if (!counter) {
    throw new Error('useCounterConsumer must be used within a useCounterProvider');
  }

  return counter;
}

在这个例子中，我们使用 provide 函数将 count 和 increment 方法提供给组件树。 然后，我们使用 inject 函数在其他组件中获取这些值。

第七部分：最佳实践：让你的 Hook 更加健壮

• 单一职责原则： 每个 Hook 应该只负责一个特定的功能。
• 可测试性： 编写可测试的 Hook，并编写相应的单元测试。
• 文档： 为你的 Hook 编写清晰的文档，说明它的用途、参数和返回值。
• 可配置性： 允许用户通过参数来配置 Hook 的行为。
• 错误处理： 妥善处理 Hook 中可能出现的错误，并提供友好的错误信息。

总结

特性	描述	示例
类型推断	TypeScript 自动推断变量类型，减少手动类型注解的工作量。	const count = ref(0); // count 被推断为 Ref<number>
显式类型注解	手动指定类型，提供更精确的类型信息，尤其是在 Hook 的参数和返回值上。	function useCounter(initialValue: number = 0): { count: Ref<number>; increment: () => void } { ... }
泛型	允许 Hook 处理各种类型的数据，提高 Hook 的复用性。	function useList<T>(initialList: T[] = []) { ... }
响应式 Props	使用 watch 函数监听组件 props 的变化，让 Hook 能够响应 props 的变化。	watch(() => props.searchTerm, (newSearchTerm) => { searchTerm.value = newSearchTerm; });
异步操作	使用 Promise 和 async/await 处理 Hook 中的异步操作，例如从 API 获取数据。	async function fetchUsers() { ... }
依赖注入	使用 provide 和 inject 在组件树中共享数据和方法，实现更灵活的组件通信。	provide(counterKey, { count, increment }); 和 inject(counterKey);
最佳实践	遵循单一职责原则、可测试性、文档、可配置性和错误处理等最佳实践，让你的 Hook 更加健壮。	例如，每个 Hook 只负责一个特定的功能，并编写相应的单元测试。

通过今天的学习，相信你已经掌握了如何使用 TypeScript 为 Vue 3 的 Composition API 编写类型安全、可维护的自定义 Hook。记住，好的代码就像一首优美的诗歌，它不仅能够完成任务，还能让人赏心悦目。

希望这些内容对你有所帮助！下次再见！