1. Vue 3.4+ 异步副作用管理革命：onCleanup 深度解析
在构建现代前端应用时，异步操作无处不在。从简单的数据获取到复杂的实时通信，我们经常需要在组件中处理各种异步任务。然而，这些异步操作带来的副作用管理问题一直困扰着开发者。Vue 3.4 引入的 onCleanup 功能彻底改变了这一局面，它为我们提供了一种优雅的方式来处理异步副作用的清理工作。
onCleanup 是 Vue 响应式系统的一个重要补充，它允许我们在 watch 和 watchEffect 中注册清理函数，当依赖变化或组件卸载时自动执行这些清理操作。这个特性特别适合处理以下几种常见场景：
- 取消进行中的网络请求
- 清除定时器和轮询任务
- 关闭 WebSocket 和事件订阅
- 清理任何可能产生内存泄漏的资源
2. onCleanup 核心机制解析
2.1 基础使用模式
onCleanup 的基本用法非常简单，它作为第三个参数传递给 watch 回调函数，或者作为唯一参数传递给 watchEffect 的回调函数。让我们看一个最基本的示例：
javascript复制import { ref, watch } from 'vue'
const searchQuery = ref('')
watch(searchQuery, async (newValue, oldValue, onCleanup) => {
let cancelled = false
// 注册清理函数
onCleanup(() => {
cancelled = true
})
// 模拟异步操作
await new Promise(resolve => setTimeout(resolve, 1000))
// 检查是否已被取消
if (!cancelled) {
console.log('处理结果:', newValue)
}
})
在这个例子中，每当 searchQuery 发生变化时，Vue 会先执行上一次注册的清理函数（如果有的话），然后再执行新的回调。这确保了旧的操作不会干扰新的操作。
2.2 与 AbortController 集成
在实际应用中，我们经常需要取消网络请求。AbortController 是现代浏览器提供的原生 API，正好可以与 onCleanup 完美配合：
javascript复制watch(searchQuery, async (newValue, oldValue, onCleanup) => {
const controller = new AbortController()
// 注册清理函数
onCleanup(() => {
controller.abort()
})
try {
const response = await fetch(`/api/search?q=${newValue}`, {
signal: controller.signal
})
const data = await response.json()
// 处理数据...
} catch (error) {
if (error.name !== 'AbortError') {
console.error('请求失败:', error)
}
}
})
这种模式解决了前端开发中常见的竞态条件问题——当用户快速输入时，确保只有最后一次搜索请求的结果会被处理。
3. 实战应用场景
3.1 搜索功能与防抖优化
搜索功能是 onCleanup 最典型的应用场景之一。结合防抖技术，我们可以创建出用户体验极佳的搜索组件：
javascript复制import { ref, watch } from 'vue'
export function useSearch() {
const searchQuery = ref('')
const results = ref([])
const isLoading = ref(false)
const error = ref(null)
watch(searchQuery, async (newValue, oldValue, onCleanup) => {
if (newValue.trim().length < 2) {
results.value = []
return
}
let cancelled = false
const controller = new AbortController()
// 注册清理函数
onCleanup(() => {
cancelled = true
controller.abort()
isLoading.value = false
})
// 添加防抖延迟
await new Promise(resolve => setTimeout(resolve, 300))
if (cancelled) return
isLoading.value = true
error.value = null
try {
const response = await fetch(`/api/search?q=${encodeURIComponent(newValue)}`, {
signal: controller.signal
})
if (cancelled) return
const data = await response.json()
if (!cancelled) {
results.value = data
}
} catch (err) {
if (err.name !== 'AbortError' && !cancelled) {
error.value = err
results.value = []
}
} finally {
if (!cancelled) {
isLoading.value = false
}
}
})
return {
searchQuery,
results,
isLoading,
error
}
}
这个实现有几个关键点值得注意：
- 防抖处理：通过 300ms 的延迟减少不必要的 API 调用
- 取消机制：使用
AbortController确保只有最后一次请求会被处理 - 状态管理：正确维护加载状态和错误状态
- 最小查询长度：避免对空或过短查询的无效请求
3.2 数据轮询模式
另一个常见场景是实现数据的定期轮询。onCleanup 让这种模式的实现变得异常简单：
javascript复制import { ref, watch } from 'vue'
export function usePollingData() {
const isPolling = ref(false)
const data = ref(null)
const error = ref(null)
watch(isPolling, (shouldPoll, _, onCleanup) => {
if (!shouldPoll) {
data.value = null
return
}
let cancelled = false
let intervalId
// 清理函数
onCleanup(() => {
cancelled = true
clearInterval(intervalId)
})
const fetchData = async () => {
if (cancelled) return
try {
const response = await fetch('/api/data')
const result = await response.json()
if (!cancelled) {
data.value = result
error.value = null
}
} catch (err) {
if (!cancelled) {
error.value = err
}
}
}
// 立即获取一次数据
fetchData()
// 设置轮询间隔
intervalId = setInterval(fetchData, 5000)
})
return {
isPolling,
data,
error,
togglePolling: () => isPolling.value = !isPolling.value
}
}
这个轮询实现的特点是：
- 可以通过
isPollingref 轻松控制轮询的开启和关闭 - 在组件卸载或停止轮询时自动清理定时器
- 错误处理机制确保应用稳定性
- 初始立即获取数据，避免等待第一个间隔
3.3 实时通信（WebSocket）
对于实时通信场景，如聊天应用或实时数据展示，onCleanup 同样大显身手：
javascript复制import { ref, watch, onUnmounted } from 'vue'
export function useChatRoom(roomId) {
const messages = ref([])
const isConnected = ref(false)
let socket = null
let reconnectTimer = null
watch(() => roomId.value, (newRoomId, oldRoomId, onCleanup) => {
if (!newRoomId) {
messages.value = []
isConnected.value = false
return
}
let cancelled = false
onCleanup(() => {
cancelled = true
if (socket) {
socket.close()
socket = null
}
if (reconnectTimer) {
clearTimeout(reconnectTimer)
reconnectTimer = null
}
})
const connectWebSocket = () => {
if (cancelled) return
socket = new WebSocket(`wss://api.example.com/chat/${newRoomId}`)
socket.onopen = () => {
if (!cancelled) {
isConnected.value = true
}
}
socket.onmessage = (event) => {
if (!cancelled) {
const message = JSON.parse(event.data)
messages.value.push(message)
}
}
socket.onclose = () => {
if (!cancelled) {
isConnected.value = false
// 尝试重连
if (!cancelled) {
reconnectTimer = setTimeout(connectWebSocket, 3000)
}
}
}
socket.onerror = (error) => {
if (!cancelled) {
console.error('WebSocket 错误:', error)
}
}
}
connectWebSocket()
}, { immediate: true })
const sendMessage = (content) => {
if (socket && socket.readyState === WebSocket.OPEN) {
socket.send(JSON.stringify({ content }))
}
}
onUnmounted(() => {
if (socket) {
socket.close()
}
})
return { messages, isConnected, sendMessage }
}
这个 WebSocket 实现考虑了以下重要方面：
- 自动重连机制，确保连接中断后能够恢复
- 房间切换时自动关闭旧连接并建立新连接
- 组件卸载时正确清理资源
- 提供简单的消息发送接口
4. 高级模式与组合式函数封装
4.1 通用异步监听封装
为了在多个组件中复用 onCleanup 的逻辑，我们可以创建高阶的组合式函数：
javascript复制import { ref, watch, onUnmounted } from 'vue'
export function useAsyncWatch(source, asyncFn, options = {}) {
const {
immediate = false,
debounce = 0,
deep = false
} = options
const data = ref(null)
const error = ref(null)
const isLoading = ref(false)
let cleanupFn = null
const stop = watch(source, async (newValue, oldValue, onCleanup) => {
let cancelled = false
if (debounce > 0) {
await new Promise(resolve => setTimeout(resolve, debounce))
if (cancelled) return
}
isLoading.value = true
error.value = null
onCleanup(() => {
cancelled = true
isLoading.value = false
})
cleanupFn = () => {
cancelled = true
isLoading.value = false
}
try {
const result = await asyncFn(newValue, oldValue, () => cancelled)
if (!cancelled) {
data.value = result
}
} catch (err) {
if (!cancelled) {
error.value = err
}
} finally {
if (!cancelled) {
isLoading.value = false
}
}
}, { immediate, deep })
const cancel = () => {
if (cleanupFn) {
cleanupFn()
cleanupFn = null
}
}
const trigger = () => {
const currentValue = typeof source === 'function'
? source()
: source.value
cancel()
}
onUnmounted(() => {
stop()
cancel()
})
return {
data,
error,
isLoading,
cancel,
trigger,
stop
}
}
这个 useAsyncWatch 封装提供了以下功能：
- 内置防抖支持
- 自动管理加载状态和错误状态
- 提供手动取消和重新触发的方法
- 组件卸载时自动清理
使用示例：
javascript复制const searchQuery = ref('')
const { data: results, isLoading, cancel } = useAsyncWatch(
searchQuery,
async (query, oldValue, isCancelled) => {
if (!query.trim() || isCancelled()) return null
const controller = new AbortController()
const timeoutId = setTimeout(() => controller.abort(), 10000)
try {
const response = await fetch(`/api/search?q=${query}`, {
signal: controller.signal
})
if (isCancelled()) return null
return await response.json()
} finally {
clearTimeout(timeoutId)
}
},
{ debounce: 300, immediate: false }
)
4.2 竞态条件安全处理
在处理可能发生竞态条件的场景时，我们可以进一步封装专门的 Hook：
javascript复制export function useRaceConditionWatch(source, asyncFn, options = {}) {
const {
immediate = false,
cancelPrevious = true
} = options
const data = ref(null)
const error = ref(null)
const isLoading = ref(false)
let currentToken = null
const stop = watch(source, async (newValue, oldValue, onCleanup) => {
const token = Symbol('request')
currentToken = token
let cancelled = false
let abortController = null
onCleanup(() => {
cancelled = true
if (abortController) {
abortController.abort()
}
if (currentToken === token) {
isLoading.value = false
}
})
if (cancelPrevious && currentToken !== token) {
return
}
isLoading.value = true
error.value = null
try {
abortController = new AbortController()
const result = await asyncFn(newValue, abortController.signal, () => cancelled)
if (!cancelled && currentToken === token) {
data.value = result
}
} catch (err) {
if (err.name !== 'AbortError' && !cancelled && currentToken === token) {
error.value = err
}
} finally {
if (!cancelled && currentToken === token) {
isLoading.value = false
}
}
}, { immediate })
return { data, error, isLoading, stop }
}
这个实现通过使用唯一 token 来标识每个请求，确保只有最新的请求会被处理，完美解决了竞态条件问题。
5. 最佳实践与常见陷阱
5.1 正确的清理顺序
在使用 onCleanup 时，清理函数的注册顺序非常重要。推荐的最佳实践是：
javascript复制watch(source, async (value, oldValue, onCleanup) => {
// 首先设置取消标志
let cancelled = false
onCleanup(() => {
cancelled = true
})
// 然后创建可取消的资源
const controller = new AbortController()
onCleanup(() => {
controller.abort()
})
// 最后执行异步操作
const data = await fetchData(value, controller.signal)
if (!cancelled) {
// 处理结果
}
})
这种顺序确保了：
- 当清理发生时，首先设置取消标志，阻止后续逻辑执行
- 然后取消具体的资源（如网络请求）
- 最后在异步操作完成后检查取消状态
5.2 避免内存泄漏
常见的导致内存泄漏的错误包括：
- 忘记清理定时器：
javascript复制// 错误示例
watch(source, () => {
setInterval(() => {
// 一些操作
}, 1000)
// 忘记清理！
})
// 正确示例
watch(source, (value, oldValue, onCleanup) => {
const timer = setInterval(() => {
// 一些操作
}, 1000)
onCleanup(() => {
clearInterval(timer)
})
})
- 忘记取消事件监听器：
javascript复制// 错误示例
watch(source, () => {
window.addEventListener('resize', handleResize)
// 忘记移除！
})
// 正确示例
watch(source, (value, oldValue, onCleanup) => {
const handler = () => {
// 处理resize
}
window.addEventListener('resize', handler)
onCleanup(() => {
window.removeEventListener('resize', handler)
})
})
5.3 处理复杂清理逻辑
当需要清理多个资源时，可以考虑以下模式：
javascript复制watch(source, async (value, oldValue, onCleanup) => {
// 创建所有需要清理的资源
const controller = new AbortController()
const timer1 = setTimeout(() => {}, 1000)
const timer2 = setInterval(() => {}, 5000)
const socket = new WebSocket('wss://example.com')
// 注册单个清理函数来清理所有资源
onCleanup(() => {
controller.abort()
clearTimeout(timer1)
clearInterval(timer2)
socket.close()
})
// 剩余逻辑...
})
这种模式将所有清理逻辑集中在一个函数中，更易于维护且不易遗漏。
6. 性能考量与优化建议
虽然 onCleanup 极大地简化了异步副作用的管理，但在性能敏感的场景中仍需注意以下几点：
-
避免过度清理：不必要的清理操作也会消耗性能，确保只清理真正需要清理的资源。
-
合理使用防抖：对于高频变化的值，结合防抖可以显著减少不必要的操作：
javascript复制watch(source, async (value, oldValue, onCleanup) => {
let cancelled = false
onCleanup(() => {
cancelled = true
})
// 添加防抖
await new Promise(resolve => setTimeout(resolve, 300))
if (cancelled) return
// 实际操作...
})
-
批量清理：当有多个相关资源需要清理时，考虑将它们组织在一起批量清理，而不是为每个资源注册单独的清理函数。
-
懒初始化：对于开销较大的资源，考虑懒初始化模式：
javascript复制watch(source, (value, oldValue, onCleanup) => {
let resource = null
const initializeResource = () => {
if (!resource) {
resource = createExpensiveResource()
onCleanup(() => {
resource.cleanup()
resource = null
})
}
return resource
}
// 只有当真正需要时才初始化
if (needResource(value)) {
const res = initializeResource()
// 使用资源...
}
})
7. 测试策略
测试使用 onCleanup 的代码时，需要考虑以下几种情况：
-
正常流程测试：验证主要功能是否按预期工作。
-
取消流程测试：验证在操作中途取消时，清理函数是否正确执行。
-
竞态条件测试：快速触发多次变化，验证只有最后一次操作的结果被处理。
-
内存泄漏测试：验证所有资源都被正确清理。
以下是使用 Vitest 的测试示例：
javascript复制import { ref } from 'vue'
import { useAsyncOperation } from './useAsyncOperation'
import { describe, it, expect, vi, beforeEach } from 'vitest'
describe('useAsyncOperation', () => {
beforeEach(() => {
vi.useFakeTimers()
})
it('should cancel previous operation when source changes', async () => {
const source = ref('initial')
const { result } = useAsyncOperation(source)
// 触发第一次操作
source.value = 'first'
await vi.advanceTimersByTimeAsync(100)
// 在完成前触发第二次操作
source.value = 'second'
await vi.runAllTimersAsync()
expect(result.value).toBe('second result')
})
it('should cleanup resources when unmounted', () => {
const source = ref('test')
const { stop } = useAsyncOperation(source)
const cleanupSpy = vi.fn()
stop()
expect(cleanupSpy).toHaveBeenCalled()
})
})
8. 与其他响应式 API 的协作
onCleanup 不仅可以与 watch 和 watchEffect 一起使用，还可以与其他响应式 API 协作，创建更强大的抽象。
8.1 与 computed 结合
虽然 computed 本身不支持 onCleanup，但我们可以创建依赖计算属性的 watch：
javascript复制const searchQuery = ref('')
const trimmedQuery = computed(() => searchQuery.value.trim())
watch(trimmedQuery, async (query, oldQuery, onCleanup) => {
// 使用 onCleanup 管理异步操作
})
8.2 与 provide/inject 结合
可以在提供者组件中使用 onCleanup 管理资源，然后通过 provide 将这些资源暴露给后代组件：
javascript复制// 提供者组件
setup() {
const sharedResource = ref(null)
watch(someSource, (value, oldValue, onCleanup) => {
const resource = createSharedResource(value)
sharedResource.value = resource
onCleanup(() => {
resource.cleanup()
sharedResource.value = null
})
})
provide('sharedResource', sharedResource)
}
// 消费者组件
setup() {
const sharedResource = inject('sharedResource')
// 使用共享资源...
}
8.3 与 Suspense 结合
在使用 Vue 的 Suspense 特性时，onCleanup 可以确保异步操作在组件挂起或卸载时被正确清理：
javascript复制async function setup() {
const data = ref(null)
watch(someSource, async (value, oldValue, onCleanup) => {
let cancelled = false
onCleanup(() => {
cancelled = true
})
const result = await fetchData(value)
if (!cancelled) {
data.value = result
}
})
return {
data
}
}
9. 与第三方库的集成
许多第三方库都有自己的资源清理机制，我们可以将这些机制与 onCleanup 集成：
9.1 与 Axios 集成
javascript复制watch(source, async (value, oldValue, onCleanup) => {
const cancelTokenSource = axios.CancelToken.source()
onCleanup(() => {
cancelTokenSource.cancel('Operation cancelled due to new request')
})
try {
const response = await axios.get('/api/data', {
cancelToken: cancelTokenSource.token
})
// 处理响应...
} catch (error) {
if (!axios.isCancel(error)) {
// 处理真实错误...
}
}
})
9.2 与 RxJS 集成
javascript复制watch(source, (value, oldValue, onCleanup) => {
const subscription = someObservable.subscribe({
next: value => {
// 处理值...
},
error: err => {
// 处理错误...
}
})
onCleanup(() => {
subscription.unsubscribe()
})
})
9.3 与 Three.js 集成
javascript复制watch(source, (value, oldValue, onCleanup) => {
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
const renderer = new THREE.WebGLRenderer()
// 渲染循环
const animate = () => {
requestAnimationFrame(animate)
renderer.render(scene, camera)
}
animate()
onCleanup(() => {
// 清理 Three.js 资源
renderer.dispose()
// 其他清理...
})
})
10. 总结与个人实践建议
经过对 onCleanup 的深入探索，我认为这是 Vue 3.4+ 中最有价值的特性之一。在实际项目中，我总结了以下经验：
-
始终考虑清理：对于任何可能产生副作用的操作，第一时间考虑如何清理它。
-
分层清理策略：
- 第一层：设置取消标志，阻止后续逻辑执行
- 第二层：取消具体的异步操作（如网络请求）
- 第三层：释放资源（如定时器、事件监听器）
-
测试清理逻辑：编写专门的测试用例验证清理函数是否按预期工作。
-
组合式函数优先：将复杂的异步逻辑封装在组合式函数中，提高复用性。
-
性能敏感操作：对于高频操作，合理使用防抖和节流，避免过度清理带来的性能开销。
-
文档化清理行为：在团队项目中，明确记录哪些资源需要清理以及如何清理。
onCleanup 不仅是一个 API，更是一种编程范式的转变。它鼓励我们以更声明式的方式管理副作用，让我们的代码更健壮、更易于维护。随着 Vue 生态的不断发展，我相信这个特性将成为 Vue 开发者工具包中不可或缺的一部分。