打造高复用 Ant Design Vue 文件上传校验 Hook 的工程化实践

在当今前端开发中，文件上传功能几乎成为每个管理后台的标配需求。从用户头像到产品图片，从文档附件到批量导入，我们总在重复处理类似的校验逻辑：文件大小、格式、数量限制，甚至更复杂的图片分辨率验证。每次遇到上传需求就重写一遍校验代码，不仅效率低下，还容易导致团队内部实现不一致。本文将带你从工程化角度，基于 Ant Design Vue 的 a-upload 组件，构建一个高度可配置、易扩展的文件上传校验 Hook，彻底告别重复劳动。

1. 为什么需要封装上传校验 Hook

在团队协作中，我们经常发现不同开发者对同一业务的上传校验实现五花八门。有的在组件 methods 中直接写死校验逻辑，有的将部分校验提取为工具函数但接口不统一，更常见的是复制粘贴旧代码导致历史问题不断重现。

以一个电商平台为例，商品主图要求 800x800 以上分辨率且小于 2MB，用户头像需要 1:1 比例且仅限 JPG/PNG，而资质文件则要求 PDF 格式且不超过 5MB。这些校验规则分散在各处组件中，当业务规则变更时，开发者需要全局搜索修改，极易遗漏。

通过封装统一的校验 Hook，我们可以获得以下优势：

• 一致性：全项目使用相同接口和错误提示风格
• 可维护性：业务规则变更只需修改一处
• 可测试性：独立单元测试覆盖所有校验场景
• 可扩展性：轻松添加新的校验类型而不影响现有逻辑

2. 设计校验 Hook 的核心接口

优秀的接口设计应该做到"开箱即用"的同时保持高度灵活性。我们的校验 Hook 将接收一个配置对象，返回可直接用于 a-upload 组件的 beforeUpload 函数。以下是基础接口设计：

typescript复制interface UploadValidatorOptions {
  maxSize?: number // 文件大小上限（字节）
  allowedTypes?: string[] // 允许的文件类型扩展名
  maxCount?: number // 最大上传数量
  dimensions?: { // 图片尺寸限制
    minWidth?: number
    maxWidth?: number
    minHeight?: number
    maxHeight?: number
  }
  customValidator?: (file: File) => Promise<boolean> // 自定义校验函数
}

function useUploadValidator(options: UploadValidatorOptions): (file: File) => Promise<boolean>

实际使用示例：

javascript复制const beforeUpload = useUploadValidator({
  maxSize: 2 * 1024 * 1024, // 2MB
  allowedTypes: ['jpg', 'jpeg', 'png'],
  dimensions: {
    minWidth: 400,
    minHeight: 400
  }
})

<a-upload :beforeUpload="beforeUpload" />

3. 实现基础校验功能

让我们从核心校验逻辑开始构建。首先创建一个新的 composable 文件 useUploadValidator.ts：

typescript复制import { message } from 'ant-design-vue'
import { ref } from 'vue'

export function useUploadValidator(options: UploadValidatorOptions) {
  const isLoading = ref(false)
  
  return async (file: File) => {
    try {
      isLoading.value = true
      
      // 校验文件大小
      if (options.maxSize && file.size > options.maxSize) {
        throw new Erro