---
title: "Nami - 文件上传"
---

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

### 1、服务接口

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

调用方传入 `File` 即可：

```java
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 参数转发。它会携带原文件名、内容和内容类型：

```java
String upload(String category, UploadedFile file);
```

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

### 3、安全检查清单

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