在 Vue 3 应用开发中，于 setup 函数内调用 API 接口是常见需求。真正的难点并非发起请求本身，而是如何将异步请求逻辑组织得条理清晰、高度复用，同时避免污染组件的核心业务代码。直接在 setup 中书写 axios.get() 虽然简单直接，但很快会导致代码臃肿，陷入重复处理加载状态、错误捕获、请求缓存与取消等问题的困境。要构建可维护的前端架构，合理运用组合式函数（Composable）对异步请求进行封装，是实现优雅代码的关键路径。
明确职责边界：组合式函数专注“请求逻辑”，分离“UI状态”
一个设计良好的 API 请求组合式函数，其职责应当高度内聚：它只负责发起网络请求、处理响应数据，并暴露一个可控的执行方法。它不应越界去直接修改组件内的 ref 状态，也不应主动触发用户界面更新。
那么，一个理想的封装模式应具备哪些特征？
- 推荐返回解构对象：例如
{ data, error, loading, execute }。这套结构语义明确，调用方可以按需取用，直观易懂。 execute作为可调用函数，而非自动执行：这意味着将请求的触发控制权完全交给组件。数据是在按钮点击后获取，还是在路由进入后加载，完全由调用方决定，灵活性更高。- 内部状态使用
ref包裹：错误信息和加载状态被封装为响应式引用，使得在模板中可以直接通过v-if="loading"或v-if="error"进行绑定，实现 UI 的自动响应式更新。
基础封装实践：集成 loading 与 error 处理的通用模式
掌握理论后，实践是关键。以下是一个可用于生产环境的、最小化且功能完备的封装示例（以 axios 库为例，并完整支持 TypeScript 类型）：
import { ref, Ref } from 'vue'
import axios from 'axios'
interface UseApiOptions {
manual?: boolean // 是否手动触发请求，默认为 false（即自动执行）
}
export function useApi(url: string, options: UseApiOptions = {}) {
const data = ref(null)
const error = ref(null)
const loading = ref(false)
const execute = async () => {
loading.value = true
error.value = null
try {
const res = await axios.get(url)
data.value = res.data
return res.data
} catch (e) {
error.value = e as Error
throw e
} finally {
loading.value = false
}
}
if (!options.manual) {
execute()
}
return {
data,
error,
loading,
execute
}
}
在 Vue 组件中使用时，代码会变得异常简洁和清晰：
import { useApi } from '@/composables/useApi'
export default defineComponent({
setup() {
const { data, loading, error, execute } = useApi('/api/user/1')
const handleRefresh = () => execute()
return () => (
{loading.value ? '加载中...' : null}
{error.value ? `错误：${error.value.message}` : null}
{data.value ?
{data.value.name}
: null}
)
}
})
进阶优化技巧：支持参数、取消请求、缓存与防抖
当然，真实的业务场景远比基础示例复杂。以下几个进阶能力，在开发中很快会用到。关键在于，这些增强逻辑都应该封装在组合式函数内部，而不是分散在各个业务组件中。
- 支持动态参数：将固定的
url字符串改为一个返回 URL 的函数，例如(id: string) => `/api/user/${id}`。让execute方法能够接收调用参数，并在每次执行前重置相关的内部状态。 - 实现请求取消：利用
Axios的CancelToken或浏览器原生的AbortController。在每次execute调用时生成一个新的取消控制器，并在下一次调用前取消上一次未完成的请求。这对于搜索框输入等场景至关重要，能有效避免竞态条件。 - 添加简单内存缓存：使用一个 Map 对象，以
url + JSON.stringify(params)作为键来缓存响应结果。当请求参数相同时，直接返回缓存数据，能显著提升性能并避免不必要的重复网络请求。 - 集成节流与防抖：对于高频触发的
execute调用（例如实时搜索联想），可以使用lodash.debounce或lodash.throttle等工具对执行函数进行包装，返回一个新的、经过防抖或节流处理的函数。
避坑指南：避免让组合式函数变成难以理解的“黑盒”
封装的核心目的是简化使用，而非隐藏必要的复杂性。有几个常见的反模式需要警惕和避免：
- 避免制造“万能函数”：试图将所有类型的 API 请求都塞进一个名为
useRequest的巨型函数中。这会导致函数参数列表不断膨胀，类型推导变得极其困难，最终使得代码维护成本飙升。 - 严格遵守关注点分离原则：不要在组合式函数内部直接调用 UI 相关的副作用，如
notification.success()或router.push()。这违反了单一职责原则，会让组件失去对副作用和导航流程的控制权，降低代码的可测试性。 - 暴露必要的原始响应信息：不要只返回处理后的
data字段，而忽略了完整的响应对象，如res.headers、res.status等。在处理分页、文件下载、鉴权令牌刷新等场景时，这些信息往往是必需的。 - 高度重视类型安全：避免使用
any或unknown类型敷衍了事。应充分利用 TypeScript 的泛型和类型推导，为请求参数和响应数据提供精确的类型定义，这是组合式函数封装带来的核心优势之一。
归根结底，一个优秀的组合式函数应当像一块精心设计的乐高积木：功能纯粹且独立，接口定义清晰，同时又能与其他积木（其他组合式函数或组件逻辑）完美拼接，共同构建出健壮、复杂的应用程序。它不替开发者做所有决定，而是提供一个稳固、可靠且可控的“抽象层”和“执行手柄”。
