Vendure电商平台文件上传功能深度解析-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00924/article/details/148487746

Vendure电商平台文件上传功能深度解析

vendure A headless GraphQL commerce platform for the modern web 项目地址: https://gitcode.com/gh_mirrors/ve/vendure

前言

在电商系统开发中，文件上传是一个基础但至关重要的功能。Vendure作为现代化的电商框架，提供了完善的文件上传解决方案。本文将全面解析Vendure的文件上传机制，帮助开发者掌握这一核心功能。

文件上传基础原理

Vendure采用GraphQL多部分请求规范来处理文件上传，这是一种专门为GraphQL设计的文件上传协议。其核心优势在于：

标准化：遵循行业规范，确保与各种客户端兼容
高效性：支持流式传输，适合大文件上传
灵活性：可以与GraphQL查询和变更操作无缝结合

在底层实现上，Vendure使用了graphql-upload包来处理上传流程，上传后的文件在系统中被统一管理为"资产"(Asset)实体。

客户端上传实现

客户端工具选择

开发者可以根据项目需求选择合适的客户端上传工具：

Apollo Client：推荐使用apollo-upload-client包
其他GraphQL客户端：需支持多部分请求规范
测试用途：甚至可以使用简单的curl命令

基础上传示例

以下是使用React和Apollo Client实现的基础文件上传组件：

import { gql, useMutation } from "@apollo/client";

const UPLOAD_MUTATION = gql`
  mutation UploadFiles($files: [Upload!]!) {
    uploadFiles(files: $files) {
      id
      name
      size
      mimeType
    }
  }
`;

function FileUploader() {
  const [uploadFiles] = useMutation(UPLOAD_MUTATION);
  
  const handleFileChange = async (e) => {
    const files = Array.from(e.target.files);
    if (files.length > 0) {
      try {
        const result = await uploadFiles({
          variables: {
            files: files.map(file => file)
          }
        });
        console.log('上传结果:', result.data.uploadFiles);
      } catch (error) {
        console.error('上传失败:', error);
      }
    }
  };

  return (
    <div>
      <input 
        type="file" 
        multiple
        onChange={handleFileChange}
      />
      <p>支持多文件选择</p>
    </div>
  );
}

高级应用：自定义头像上传

让我们通过一个实际案例来展示如何扩展Vendure的文件上传功能。

1. 架构设计

要实现客户头像上传功能，我们需要：

扩展Customer实体，添加头像字段
创建专用的GraphQL mutation
实现文件处理逻辑

2. 插件开发

import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { AssetService, CustomerService } from '@vendure/core';
import { shopApiExtensions } from './api/extensions';
import { AvatarResolver } from './api/resolver';

@VendurePlugin({
  imports: [PluginCommonModule],
  shopApiExtensions: {
    schema: shopApiExtensions,
    resolvers: [AvatarResolver],
  },
  configuration: config => {
    config.customFields.Customer.push({
      name: 'avatar',
      type: 'relation',
      entity: 'Asset',
      label: '用户头像',
      description: '用户的个人资料图片',
      nullable: true,
    });
    return config;
  },
})
export class AvatarUploadPlugin {}

3. 解析器实现

解析器是处理上传逻辑的核心：

import { Args, Mutation, Resolver } from '@nestjs/graphql';
import { AssetService, CustomerService } from '@vendure/core';

@Resolver()
export class AvatarResolver {
  constructor(
    private assetService: AssetService,
    private customerService: CustomerService
  ) {}

  @Mutation()
  async uploadAvatar(
    @Ctx() ctx: RequestContext,
    @Args() { file }: { file: Promise<FileUpload> }
  ) {
    // 验证用户
    const userId = ctx.activeUserId;
    if (!userId) throw new Error('未授权');
    
    // 处理文件上传
    const assetResult = await this.assetService.create(ctx, {
      file: await file,
      tags: ['avatar', `user-${userId}`],
    });
    
    if (isGraphQlErrorResult(assetResult)) {
      throw assetResult; // 处理错误
    }
    
    // 关联到用户
    await this.customerService.update(ctx, {
      id: userId,
      customFields: { avatarId: assetResult.id },
    });
    
    return assetResult;
  }
}

4. 前端集成

前端实现需要注意的几个关键点：

function AvatarUpload() {
  const [uploadAvatar] = useMutation(UPLOAD_AVATAR_MUTATION);
  
  const handleUpload = async (e) => {
    const file = e.target.files[0];
    if (!file) return;
    
    // 客户端验证
    if (file.size > 5 * 1024 * 1024) {
      alert('文件大小不能超过5MB');
      return;
    }
    
    try {
      const { data } = await uploadAvatar({ 
        variables: { file },
        context: {
          headers: {
            'Apollo-Require-Preflight': 'true',
          },
        },
      });
      
      if (data.uploadAvatar) {
        // 更新UI显示新头像
      }
    } catch (error) {
      console.error('上传失败:', error);
    }
  };

  return (
    <div className="avatar-uploader">
      <label>
        <input 
          type="file" 
          accept="image/*"
          onChange={handleUpload}
          style={{ display: 'none' }}
        />
        <Button variant="contained" component="span">
          上传头像
        </Button>
      </label>
      <Typography variant="caption">
        支持JPG, PNG格式，建议尺寸200x200像素
      </Typography>
    </div>
  );
}

最佳实践与注意事项

文件验证：
- 在服务端验证文件类型和大小
- 使用白名单限制允许的MIME类型
- 设置合理的文件大小限制

错误处理：

try {
  // 上传逻辑
} catch (error) {
  if (error instanceof MimeTypeError) {
    // 处理文件类型错误
  } else if (error instanceof FileSizeError) {
    // 处理文件大小错误
  } else {
    // 其他错误
  }
}