AWS Amplify 存储文件上传的 TypeScript 类型处理指南

问题背景

在使用 AWS Amplify 进行文件上传功能开发时，开发者经常会遇到 TypeScript 类型检查相关的错误。这些错误主要源于对文件对象类型的不正确处理，特别是在 React 状态管理和事件处理方面。

常见错误分析

1. 数组与单个对象的混淆

开发者最初将状态声明为数组类型，但在事件处理中却尝试存储单个文件对象。这种类型不匹配会导致 TypeScript 报错：

// 错误示例
const [files, setFile] = useState<Array<Schema["File_Model"]["type"]>>([]);
const handleChange = (event: any) => {
  setFile(event.target.files[0]); // 类型不匹配
};

2. 可能的 undefined 值

文件上传组件中，用户可能没有选择任何文件就点击上传按钮。此时访问文件对象的属性会导致运行时错误：

// 危险代码
uploadData({
  path: `picture-submissions/${file.name}`, // file 可能为 undefined
  data: file,
})

解决方案

1. 正确的状态类型声明

对于单个文件上传场景，应该使用 File 类型并允许 undefined：

const [file, setFile] = useState<File | undefined>();

2. 安全的事件处理

处理文件选择事件时，需要检查 event.target.files 是否存在：

const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
  if (!event.target.files || event.target.files.length === 0) return;
  setFile(event.target.files[0]);
};

3. 上传前的安全检查

在执行上传操作前，必须确认文件对象存在：

<button
  onClick={() => {
    if (!file) {
      alert('请先选择文件');
      return;
    }
    uploadData({
      path: `picture-submissions/${file.name}`,
      data: file,
    });
  }}
>
  上传
</button>

最佳实践建议

1. 类型注解：始终为状态和事件参数添加明确的类型注解
2. 防御性编程：对可能为 null 或 undefined 的值进行检查
3. 错误处理：为用户提供友好的错误反馈
4. 代码组织：将上传逻辑提取为独立函数，提高可读性

完整示例代码

import { Authenticator } from "@aws-amplify/ui-react";
import "@aws-amplify/ui-react/styles.css";
import { useState } from "react";
import { uploadData } from "aws-amplify/storage";

function FileUploadComponent() {
  const [file, setFile] = useState<File>();

  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFile = event.target.files?.[0];
    if (selectedFile) {
      setFile(selectedFile);
    }
  };

  const handleUpload = async () => {
    if (!file) {
      console.error("未选择文件");
      return;
    }

    try {
      await uploadData({
        path: `uploads/${file.name}`,
        data: file,
      });
      console.log("上传成功");
    } catch (error) {
      console.error("上传失败:", error);
    }
  };

  return (
    <div>
      <input type="file" onChange={handleFileChange} />
      <button onClick={handleUpload} disabled={!file}>
        上传文件
      </button>
    </div>
  );
}

通过遵循这些原则和实践，开发者可以构建出类型安全、健壮可靠的文件上传功能，充分利用 AWS Amplify 提供的存储服务。