TypeBox 与 Fastify 文件上传集成实践

前言

在使用 TypeBox 和 Fastify 构建 Web 应用时，文件上传是一个常见需求。本文将深入探讨如何正确配置 TypeBox 和 Fastify 来实现文件上传功能，并确保 Swagger 文档能够正确显示文件上传界面。

核心问题分析

在 Fastify 中实现文件上传通常需要使用 fastify-multipart 插件。当与 TypeBox 结合使用时，开发者可能会遇到以下两个主要问题：

1. Swagger UI 无法正确显示文件上传控件
2. 请求验证失败，提示"body must be object"或"body/file must be string"等错误

解决方案探索

基础配置

首先需要确保正确配置 fastify-multipart 插件：

fastify.register(require('@fastify/multipart'), {
  attachFieldsToBody: 'keyValues'
})

TypeBox 模式定义

对于文件上传，我们需要定义一个特殊的 TypeBox 模式：

const FileUploadSchema = Type.Unsafe<{
  file: Uint8Array | ReadableStream,
  fileName: string,
  description?: string
}>({
  type: 'object',
  required: ['file'],
  properties: {
    file: {
      type: 'object'  // 实际文件类型
    },
    fileName: {
      type: 'string'
    },
    description: {
      type: 'string',
      maxLength: 255
    }
  }
})

路由配置

在路由定义中，需要特别注意 schema 的配置：

fastify.post('/upload', {
  schema: {
    consumes: ['multipart/form-data'],  // 必须声明
    body: FileUploadSchema
  }
}, async (req, reply) => {
  const data = await req.file()
  // 处理文件逻辑
})

常见问题解决

Swagger UI 不显示文件上传控件

如果 Swagger UI 没有显示文件上传控件，通常是因为：

1. 缺少 consumes: ['multipart/form-data'] 声明
2. 文件字段没有正确标记为二进制格式

请求验证失败

当遇到验证错误时，可以尝试以下解决方案：

1. 确保 attachFieldsToBody 配置正确
2. 检查 TypeBox 模式中文件字段的类型定义
3. 验证请求头是否包含 Content-Type: multipart/form-data

最佳实践建议

1. 类型安全：使用 Type.Unsafe 来精确控制类型推断和模式定义
2. 文档生成：确保 Swagger 配置与 TypeBox 模式保持一致
3. 错误处理：为文件上传添加适当的错误处理逻辑
4. 性能考虑：对于大文件上传，考虑使用流式处理

总结

通过合理配置 TypeBox 和 Fastify，可以实现既类型安全又符合 OpenAPI 规范的文件上传功能。关键在于理解 multipart/form-data 的特殊性，并在 TypeBox 模式中正确表达这些特性。当遇到问题时，建议先验证纯 JSON Schema 是否工作，再逐步引入 TypeBox 的类型支持。