WebApiClient中multipart/form-data接口的声明方法

在WebApiClient项目中，处理multipart/form-data类型的接口请求是一个常见需求。这类请求通常用于文件上传与表单数据混合提交的场景。下面将详细介绍如何在WebApiClient中正确声明这类接口。

基本概念

multipart/form-data是HTTP协议中用于表单提交的一种编码方式，特别适合同时传输二进制数据和文本数据的情况。与application/x-www-form-urlencoded不同，它能够有效地处理文件上传。

接口声明方法

在WebApiClient中，我们可以通过特性标注来声明multipart/form-data类型的接口。对于文件上传和表单数据混合的请求，主要使用以下特性：

1. FormDataTextAttribute - 用于标记文本表单字段
2. FormDataFileAttribute - 用于标记文件表单字段

具体实现

针对问题中的curl示例，我们可以这样声明接口：

public interface IDatasetApi
{
    [HttpPost("v1/datasets/{dataset_id}/documents/{document_id}/update-by-file")]
    Task<HttpResponseMessage> UpdateDocumentByFileAsync(
        [Path] string dataset_id,
        [Path] string document_id,
        [Headers] IDictionary<string, string> headers,
        [FormDataText("data")] string jsonData,
        [FormDataFile("file")] string filePath);
}

使用说明

1. 路径参数：使用[Path]特性标注路径参数
2. 请求头：使用[Headers]特性添加Authorization等请求头
3. 表单文本数据：使用[FormDataText]特性标记JSON字符串等文本数据
4. 文件上传：使用[FormDataFile]特性指定文件路径

实际调用示例

var api = HttpApi.Create<IDatasetApi>();
var response = await api.UpdateDocumentByFileAsync(
    "dataset123",
    "doc456",
    new Dictionary<string, string> { ["Authorization"] = "Bearer api_key_here" },
    "{\"name\":\"Dify\",\"indexing_technique\":\"high_quality\"}",
    "/path/to/file");

注意事项

1. JSON数据需要先序列化为字符串再传入
2. 文件路径需要确保应用有访问权限
3. 对于大文件上传，建议使用流式处理方式
4. 可以设置Content-Type等额外参数

通过以上方式，我们就能在WebApiClient中轻松实现multipart/form-data类型的接口调用，满足文件上传与表单数据混合提交的需求。