Webonyx/GraphQL-PHP 文件上传功能实现指南

在基于Webonyx/GraphQL-PHP构建GraphQL服务时，文件上传是一个常见的需求场景。本文将详细介绍如何在该框架中实现完整的文件上传功能，包括类型定义、解析器实现和服务端处理流程。

核心概念理解

GraphQL规范本身并不直接定义文件上传机制，但通过标量类型扩展可以实现。Webonyx/GraphQL-PHP通过Upload标量类型支持文件上传功能，这实际上是一个符合GraphQL多部分请求规范的实现方案。

类型定义实现

在GraphQL Schema中需要明确定义上传类型：

scalar Upload

type Mutation {
  uploadFile(file: Upload!): FileInfo!
}

type FileInfo {
  filename: String!
  mimetype: String!
  size: Int!
  path: String!
}

服务端配置要点

1. 中间件配置： 必须确保服务器能够处理multipart/form-data格式的请求。在PHP环境中需要检查：

• post_max_size 配置足够大
• upload_max_filesize 限制符合需求
• file_uploads 设置为On

2. 解析器实现： 上传文件的解析器需要接收Psr\Http\Message\UploadedFileInterface实例：

'Mutation' => [
    'uploadFile' => function ($root, $args) {
        $file = $args['file'];
        
        // 验证文件类型
        $allowedMimes = ['image/jpeg', 'application/pdf'];
        if (!in_array($file->getClientMediaType(), $allowedMimes)) {
            throw new Exception('不支持的文件类型');
        }

        // 移动文件到持久化存储
        $targetPath = '/uploads/' . uniqid() . '_' . $file->getClientFilename();
        $file->moveTo($targetPath);

        return [
            'filename' => $file->getClientFilename(),
            'mimetype' => $file->getClientMediaType(),
            'size' => $file->getSize(),
            'path' => $targetPath
        ];
    }
]

客户端实现建议

1. 请求构造： 客户端需要使用FormData构造multipart请求：

const formData = new FormData();
formData.append('operations', JSON.stringify({
    query: `mutation ($file: Upload!) {
        uploadFile(file: $file) {
            filename
            size
        }
    }`,
    variables: { file: null }
}));

formData.append('map', JSON.stringify({
    '0': ['variables.file']
}));

formData.append('0', fileInput.files[0]);

fetch('/graphql', {
    method: 'POST',
    body: formData
});

2. 进度监控： 对于大文件上传，建议实现上传进度监控：

const xhr = new XMLHttpRequest();
xhr.upload.onprogress = (event) => {
    const percent = Math.round((event.loaded / event.total) * 100);
    console.log(`上传进度: ${percent}%`);
};

安全注意事项

1. 文件类型白名单验证
2. 文件内容二次校验（如通过finfo）
3. 文件名安全处理（防止路径遍历）
4. 设置合理的上传大小限制
5. 考虑病毒扫描机制

性能优化建议

1. 分块上传支持
2. 断点续传实现
3. 异步处理机制（对于需要后处理的场景）
4. CDN集成

错误处理策略

1. 定义明确的错误代码体系
2. 提供详细的错误信息（开发环境）
3. 实现自动重试机制
4. 日志记录完整的上下文信息

通过以上实现方案，可以在Webonyx/GraphQL-PPHP项目中构建安全可靠的文件上传功能。实际应用中还需要根据具体业务需求进行调整，例如添加水印处理、缩略图生成等扩展功能。