Solon v4.1.0

Nami - 文件上传

</> markdown
2026年9月14日 上午5:58:34

Nami 的 HTTP 通道支持以表单方式上传文件。当前实现会识别 java.io.File 和 Solon 的 UploadedFile 参数，并将请求按 multipart/form-data 处理。

1、服务接口

@NamiClient(url = "http://localhost:9001/files")
public interface FileService {
    String upload(File file);
}

调用方传入 File 即可：

FileService fileService = Nami.builder()
        .url("http://localhost:9001/files")
        .create(FileService.class);

String result = fileService.upload(new File("demo.txt"));

如果接口需要同时传递普通表单字段，可以将字段作为方法参数；集合参数会按同名表单字段重复提交。服务端应明确限制文件大小、文件类型和文件名，不要直接信任客户端文件名。

2、使用 UploadedFile

当调用链已经拿到 Solon 的 UploadedFile 时，也可以将其作为 Nami 参数转发。它会携带原文件名、内容和内容类型：

String upload(String category, UploadedFile file);

文件上传依赖 HTTP channel；不要把 HTTP 表单上传示例直接套用到 Socket.D 通道。大文件、超时和失败重试需要结合服务端存储策略单独设计。

3、安全检查清单

  • 限制单文件和请求总大小。
  • 使用服务端生成的存储名，避免路径穿越。
  • 对扩展名、Content-Type 和文件内容做校验。
  • 将文件存储在 Web 根目录之外，并执行病毒扫描（如业务需要）。
  • 上传接口尽量设计为幂等，避免网络重试产生重复文件。