ASP.NET Web API控制器多Get方法路由冲突问题及解决方案咨询

问题背景 #

使用ASP.NET Web API开发Users控制器时，为实现按不同字段查询用户的功能编写了多个Get方法，运行时触发Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException路由冲突错误。先后尝试两种写法均失败，目前采用动态返回的临时方法实现，需要更优解决方案。

尝试的第一种代码及错误 #

代码：

[HttpGet("{firstName}")]
public List<string> GetByFirstNameContains(string firstName)
{
    return new List<string>()
    {
        "F1", "F2", "F3"
    };
}
    
[HttpGet("{lastName}")]
public List<string> GetByLastNameContains(string lastName)
{
    return new List<string>()
    {
        "L1", "L2", "L3"
    };
}

错误信息：

Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints. Matches:
GettingStartedAPI.Controllers.UsersController.GetByFirstNameContains (GettingStartedAPI)
GettingStartedAPI.Controllers.UsersController.Get (GettingStartedAPI)
GettingStartedAPI.Controllers.UsersController.GetByLastNameContains (GettingStartedAPI)
at Microsoft.AspNetCore.Routing.Matching.DefaultEndpointSelector.ReportAmbiguity(Span`1 candidateState) ...

尝试的第二种代码及错误 #

代码：

[HttpGet("{id}")]
public string Get(int id)
{
    return "value";
}

[HttpGet("{lastName}")]
public List<string> ArgleBargle(string lastName)
{
    return new List<string>()
    {
        "L1", "L2", "L3"
    };
}

错误信息：

Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints. Matches:
GettingStartedAPI.Controllers.UsersController.Get (GettingStartedAPI)
GettingStartedAPI.Controllers.UsersController.ArgleBargle(GettingStartedAPI)

当前临时实现代码 #

[HttpGet("{field},{value}")]
public dynamic Get(UserNameFields field, string value)
{
    if (field == UserNameFields.FirstName)
    {
        return new List<string>()
        {
            "F1", "F2", "F3"
        };
    }
    else if (field == UserNameFields.ID)
    {
        return "value";
    }
    else
    {
        return new List<string>()
        {
            "L1", "L2", "L3"
        };
    }
}

错误原因 #

ASP.NET Web API的路由匹配系统优先根据路由模板结构判断匹配关系：

1. 第一种写法中，{firstName}和{lastName}的路由模板均为users/{参数}，结构完全一致，路由系统无法区分请求应匹配哪个方法。
2. 第二种写法中，{id}（int类型）和{lastName}（string类型）的路由模板结构仍一致，虽然参数类型不同，但路由匹配阶段先校验模板结构，后续的类型约束无法完全避免冲突（比如字符串形式的数字可能同时匹配两个端点）。

优雅解决方案 #

方案1：给路由添加固定区分前缀 #

为不同查询逻辑的路由添加唯一前缀，让路由模板结构差异化，从根源避免冲突：

[HttpGet("by-id/{id:int}")]
public string GetById(int id)
{
    return "value";
}

[HttpGet("by-firstname/{firstName}")]
public List<string> GetByFirstNameContains(string firstName)
{
    return new List<string>() { "F1", "F2", "F3" };
}

[HttpGet("by-lastname/{lastName}")]
public List<string> GetByLastNameContains(string lastName)
{
    return new List<string>() { "L1", "L2", "L3" };
}

请求示例：

• 根据ID查询：GET /users/by-id/1
• 根据FirstName查询：GET /users/by-firstname/F1
• 根据LastName查询：GET /users/by-lastname/L1

方案2：使用查询参数替代路由参数 #

将查询条件放到URL的查询字符串中，通过一个Get方法处理多字段查询，符合RESTful设计规范，同时避免路由冲突：

[HttpGet]
public IActionResult GetUsers(int? id, string firstName, string lastName)
{
    if (id.HasValue)
    {
        // 执行ID查询逻辑
        return Ok("value");
    }
    else if (!string.IsNullOrWhiteSpace(firstName))
    {
        // 执行FirstName查询逻辑
        return Ok(new List<string>() { "F1", "F2", "F3" });
    }
    else if (!string.IsNullOrWhiteSpace(lastName))
    {
        // 执行LastName查询逻辑
        return Ok(new List<string>() { "L1", "L2", "L3" });
    }
    
    // 默认返回所有用户或其他逻辑
    return Ok(new List<string>() { "User1", "User2", "User3" });
}

请求示例：

• 根据ID查询：GET /users?id=1
• 根据FirstName查询：GET /users?firstName=F1
• 根据LastName查询：GET /users?lastName=L1

方案3：使用路由约束明确参数规则 #

如果坚持使用路由参数，通过添加路由约束（如类型、格式限制）让路由系统能精准区分端点：

[HttpGet("{id:int}")]
public string GetById(int id)
{
    return "value";
}

[HttpGet("{lastName:alpha}")]
public List<string> GetByLastNameContains(string lastName)
{
    return new List<string>() { "L1", "L2", "L3" };
}

• {id:int}约束仅匹配整数类型的路由参数，确保/users/123匹配ID查询方法。
• {lastName:alpha}约束仅匹配纯字母的路由参数，确保/users/Smith匹配LastName查询方法。

临时方案的问题 #

当前动态返回的实现方式存在以下不足：

• 动态类型不利于API文档自动生成（如Swagger），前端开发者无法直观了解返回数据结构。
• 违反强类型编程规范，代码维护性差，后续扩展字段时需修改大量if-else逻辑。

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