RESTful API含ICollection参数的GET请求实现方案咨询

针对需要把GeneratePermissionUrls接口从POST改为GET的需求，以下是几种可落地的实现方案：

方案1：将集合参数序列化为JSON字符串放在查询参数中 #

把FilesInfo集合序列化为JSON字符串，作为单个查询参数传递，后端接收后反序列化为集合类型。

后端修改 #

替换HTTP方法特性并调整响应状态码（GET接口通常返回200而非201），同时处理JSON反序列化：

[HttpGet("GeneratePermissionUrls")]
[ProducesResponseType(200)]
[ProducesResponseType(400)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GeneratePermissionUrls(
    [FromQuery] int AnimalId,
    [FromQuery] double ClientUploadSpeed,
    [FromQuery] int ClientInternetLatency,
    [FromQuery] string FilesInfoJson,
    CancellationToken cancellationToken = default)
{
    // 反序列化JSON字符串为集合
    var filesInfo = JsonSerializer.Deserialize<ICollection<AnimalGeneratePermissionUrlsFileInfoDTO>>(FilesInfoJson);
    if (filesInfo == null)
    {
        return BadRequest("无效的文件信息参数");
    }

    var result = await animalService.GenerateSASUrls(filesInfo, AnimalId, ClientUploadSpeed, ClientInternetLatency, nameof(AnimalsController));
    return result.Match<IActionResult>(
                   success => Ok(success.AttachedData),
                   error => NotFound(error));
}

如果想保留原有的AnimalGeneratePermissionUrlsParameters模型，可以自定义模型绑定器自动处理：

public class AnimalGeneratePermissionUrlsParametersModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var animalIdStr = bindingContext.ValueProvider.GetValue("AnimalId").FirstValue;
        var uploadSpeedStr = bindingContext.ValueProvider.GetValue("ClientUploadSpeed").FirstValue;
        var latencyStr = bindingContext.ValueProvider.GetValue("ClientInternetLatency").FirstValue;
        var filesInfoJson = bindingContext.ValueProvider.GetValue("FilesInfoJson").FirstValue;

        if (int.TryParse(animalIdStr, out var animalId) &&
            double.TryParse(uploadSpeedStr, out var uploadSpeed) &&
            int.TryParse(latencyStr, out var latency) &&
            !string.IsNullOrEmpty(filesInfoJson))
        {
            var filesInfo = JsonSerializer.Deserialize<ICollection<AnimalGeneratePermissionUrlsFileInfoDTO>>(filesInfoJson);
            if (filesInfo != null)
            {
                bindingContext.Result = ModelBindingResult.Success(new AnimalGeneratePermissionUrlsParameters
                {
                    AnimalId = animalId,
                    ClientUploadSpeed = uploadSpeed,
                    ClientInternetLatency = latency,
                    FilesInfo = filesInfo
                });
            }
            else
            {
                bindingContext.ModelState.AddModelError("FilesInfoJson", "无效的文件信息JSON");
            }
        }
        else
        {
            bindingContext.ModelState.AddModelError("", "参数格式错误");
        }

        return Task.CompletedTask;
    }
}

// 为参数模型绑定自定义绑定器
[ModelBinder(BinderType = typeof(AnimalGeneratePermissionUrlsParametersModelBinder))]
public class AnimalGeneratePermissionUrlsParameters
{
    [Required]
    public int AnimalId { get; set; }

    [Required]
    public double ClientUploadSpeed { get; set; }

    [Required]
    public int ClientInternetLatency { get; set; }

    public ICollection<AnimalGeneratePermissionUrlsFileInfoDTO> FilesInfo { get; set; } = null!;
}

// 控制器方法简化为：
[HttpGet("GeneratePermissionUrls")]
[ProducesResponseType(200)]
[ProducesResponseType(400)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GeneratePermissionUrls(
    [FromQuery] AnimalGeneratePermissionUrlsParameters parameters,
    CancellationToken cancellationToken = default)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }

    var result = await animalService.GenerateSASUrls(parameters.FilesInfo, parameters.AnimalId, parameters.ClientUploadSpeed, parameters.ClientInternetLatency, nameof(AnimalsController));
    return result.Match<IActionResult>(
                   success => Ok(success.AttachedData),
                   error => NotFound(error));
}

前端注意事项 #

将FilesInfo序列化为URL安全的JSON字符串（用encodeURIComponent处理）后传递：

const filesInfo = [{ FileName: "cat.jpg", FileSize: 1024 }];
const filesInfoJson = encodeURIComponent(JSON.stringify(filesInfo));
const url = `/api/Animals/GeneratePermissionUrls?AnimalId=1&ClientUploadSpeed=100&ClientInternetLatency=50&FilesInfoJson=${filesInfoJson}`;

方案2：使用查询字符串的数组/对象语法 #

ASP.NET Core原生支持通过索引格式的查询字符串绑定复杂集合，比如FilesInfo[0].FileName=xxx&FilesInfo[0].FileSize=123。

后端修改 #

仅需替换HTTP方法特性，保留原参数模型即可：

[HttpGet("GeneratePermissionUrls")]
[ProducesResponseType(200)]
[ProducesResponseType(400)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GeneratePermissionUrls(
    [FromQuery] AnimalGeneratePermissionUrlsParameters parameters,
    CancellationToken cancellationToken = default)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }

    var result = await animalService.GenerateSASUrls(parameters.FilesInfo, parameters.AnimalId, parameters.ClientUploadSpeed, parameters.ClientInternetLatency, nameof(AnimalsController));
    return result.Match<IActionResult>(
                   success => Ok(success.AttachedData),
                   error => NotFound(error));
}

前端注意事项 #

按索引格式拼接查询参数：

const filesInfo = [{ FileName: "cat.jpg", FileSize: 1024 }, { FileName: "dog.png", FileSize: 2048 }];
const queryParams = new URLSearchParams();
queryParams.append("AnimalId", "1");
queryParams.append("ClientUploadSpeed", "100");
queryParams.append("ClientInternetLatency", "50");
filesInfo.forEach((file, index) => {
    queryParams.append(`FilesInfo[${index}].FileName`, file.FileName);
    queryParams.append(`FilesInfo[${index}].FileSize`, file.FileSize.toString());
});
const url = `/api/Animals/GeneratePermissionUrls?${queryParams.toString()}`;

注意：如果集合元素较多，查询字符串会过长，需考虑浏览器和服务器的URL长度限制（通常建议不超过2000字符）。

方案3：使用Base64编码集合参数 #

如果JSON序列化后的字符串过长，可将其转为Base64编码，减少URL转义带来的额外字符体积。

后端修改 #

接收Base64参数后解码并反序列化：

[HttpGet("GeneratePermissionUrls")]
[ProducesResponseType(200)]
[ProducesResponseType(400)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GeneratePermissionUrls(
    [FromQuery] int AnimalId,
    [FromQuery] double ClientUploadSpeed,
    [FromQuery] int ClientInternetLatency,
    [FromQuery] string FilesInfoBase64,
    CancellationToken cancellationToken = default)
{
    try
    {
        var jsonBytes = Convert.FromBase64String(FilesInfoBase64);
        var filesInfoJson = Encoding.UTF8.GetString(jsonBytes);
        var filesInfo = JsonSerializer.Deserialize<ICollection<AnimalGeneratePermissionUrlsFileInfoDTO>>(filesInfoJson);
        if (filesInfo == null)
        {
            return BadRequest("无效的文件信息参数");
        }

        var result = await animalService.GenerateSASUrls(filesInfo, AnimalId, ClientUploadSpeed, ClientInternetLatency, nameof(AnimalsController));
        return result.Match<IActionResult>(
                       success => Ok(success.AttachedData),
                       error => NotFound(error));
    }
    catch (FormatException)
    {
        return BadRequest("无效的Base64编码参数");
    }
}

前端注意事项 #

先序列化集合为JSON，再转为Base64：

const filesInfo = [{ FileName: "cat.jpg", FileSize: 1024 }];
const filesInfoJson = JSON.stringify(filesInfo);
const filesInfoBase64 = btoa(unescape(encodeURIComponent(filesInfoJson)));
const url = `/api/Animals/GeneratePermissionUrls?AnimalId=1&ClientUploadSpeed=100&ClientInternetLatency=50&FilesInfoBase64=${filesInfoBase64}`;

内容的提问来源于stack exchange，提问作者strypperjason115