如何设计RESTful接口以支持单个与多个Entity的POST请求？

嗨，这个问题太常见了！你现在碰到的是ASP.NET Web API路由系统的典型冲突——两个POST方法用了完全相同的路由模板，框架根本没法判断该把请求转发给哪个方法。

核心原因 #

Web API的路由匹配逻辑是先匹配Http谓词和路由模板，只有这两项完全匹配后，才会去看参数类型。但你的两个方法都是[HttpPost]+v1/entities，所以在路由匹配的第一步就撞车了，直接抛出“多个匹配的操作”的异常，根本到不了参数绑定那一步。

可行的解决方案 #

1. 修改批量接口的路由模板（最推荐）

这是最简单也最符合REST风格的做法，给批量添加的接口加一个语义明确的子路由，比如/batch，比entitieslist更直观。代码示例：

// 单条添加
[HttpPost]
[Route("v1/entities")]
public IHttpActionResult AddEntity([FromBody] Entity entity)
{
    // 单条实体添加逻辑
    return Ok();
}

// 批量添加
[HttpPost]
[Route("v1/entities/batch")]
public IHttpActionResult AddEntities([FromBody] IEnumerable<Entity> entities)
{
    // 批量实体添加逻辑
    return Ok();
}

2. 通过请求内容类型区分（进阶玩法）

如果你不想改路由，也可以给两个方法指定不同的[Consumes]特性，让框架根据请求的Content-Type来区分：

[HttpPost]
[Route("v1/entities")]
[Consumes("application/json")] // 单条用普通JSON
public IHttpActionResult AddEntity([FromBody] Entity entity)
{
    // 逻辑
}

[HttpPost]
[Route("v1/entities")]
[Consumes("application/vnd.myapp.batch+json")] // 批量用自定义媒体类型
public IHttpActionResult AddEntities([FromBody] IEnumerable<Entity> entities)
{
    // 逻辑
}

不过这种方式需要客户端配合指定特殊的Content-Type，不如改路由来得直接。

3. 合并成一个方法（折中方案）

如果不想维护两个接口，也可以把逻辑合并到一个方法里，判断传入的内容是单个实体还是数组：

[HttpPost]
[Route("v1/entities")]
public IHttpActionResult AddEntities([FromBody] dynamic entities)
{
    if (entities is JArray)
    {
        // 批量添加逻辑
    }
    else if (entities is JObject)
    {
        // 单条添加逻辑
    }
    else
    {
        return BadRequest("无效的请求格式");
    }
}

但这种方式会让方法逻辑变复杂，还需要处理动态类型的转换，不推荐长期维护。

总结 #

最省心的方案还是给批量接口改个语义清晰的路由，比如v1/entities/batch，既符合REST规范，又不会给客户端和后端带来额外的复杂度。

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