.NET Core Web API：解决请求匹配多个端点问题的最佳实践

你当前的两个HttpGet端点路由模板仅参数名不同，本质都是接收整数的"{id}"结构，ASP.NET Core路由系统无法区分传入的整数对应哪个业务ID，因此会触发多端点匹配错误。以下是通用的解决最佳实践：

1. 给路由模板添加明确前缀区分 #

这是最直观且易维护的方案，通过给不同业务场景的路由添加独特前缀，让路由系统能精准识别请求指向：

[HttpGet("highscore/{highScoreId}")]
public async Task<IActionResult> GetHighScoreById(int highScoreId)
{
    var highScore = await _highScoreRepo.GetHighScoreById(highScoreId);
    return Ok(highScore);
}

[HttpGet("game/{gameId}")]
public async Task<IActionResult> GetHighScoresByGame(int gameId)
{
    var highScores = await _highScoreRepo.GetHighScoresByGame(gameId);
    return Ok(highScores);
}

此时请求可通过/highscore/123获取单个高分记录，/game/456获取某游戏的所有高分列表，彻底避免路由冲突。

2. 使用查询参数区分 #

若不想修改路由路径结构，可将其中一个参数改为查询参数，通过请求的参数名差异来匹配对应端点：

// 保留原路由作为获取单个高分的端点
[HttpGet("{highScoreId}")]
public async Task<IActionResult> GetHighScoreById(int highScoreId)
{
    var highScore = await _highScoreRepo.GetHighScoreById(highScoreId);
    return Ok(highScore);
}

// 改用查询参数gameId获取游戏高分
[HttpGet]
public async Task<IActionResult> GetHighScoresByGame([FromQuery] int gameId)
{
    var highScores = await _highScoreRepo.GetHighScoresByGame(gameId);
    return Ok(highScores);
}

对应的请求分别为/123和/?gameId=456，路由系统会根据是否存在指定查询参数来匹配正确端点。

3. 给路由参数添加语义约束（进阶方案） #

如果业务上两个ID的取值范围有明确边界（比如高分ID≥1000，游戏ID≤999），可给路由参数添加数值约束，让路由系统根据数值范围匹配：

// 约束highScoreId必须大于等于1000
[HttpGet("{highScoreId:int:min(1000)}")]
public async Task<IActionResult> GetHighScoreById(int highScoreId)
{
    var highScore = await _highScoreRepo.GetHighScoreById(highScoreId);
    return Ok(highScore);
}

// 约束gameId必须小于1000
[HttpGet("{gameId:int:max(999)}")]
public async Task<IActionResult> GetHighScoresByGame(int gameId)
{
    var highScores = await _highScoreRepo.GetHighScoresByGame(gameId);
    return Ok(highScores);
}

注意：该方案依赖业务规则的稳定性，若后续ID范围调整，需同步修改路由约束，仅适合业务规则明确且长期稳定的场景。

4. 合并端点并通过逻辑区分（不推荐） #

可以将两个接口合并为一个，通过业务逻辑判断传入ID的类型，但这种方式会模糊接口职责，增加维护成本，还可能因ID重叠导致逻辑错误，除非特殊情况不建议使用：

[HttpGet("{id}")]
public async Task<IActionResult> GetHighScore(int id)
{
    // 先尝试按高分ID查询
    var highScore = await _highScoreRepo.GetHighScoreById(id);
    if (highScore != null)
    {
        return Ok(highScore);
    }
    // 再尝试按游戏ID查询
    var gameHighScores = await _highScoreRepo.GetHighScoresByGame(id);
    if (gameHighScores.Any())
    {
        return Ok(gameHighScores);
    }
    return NotFound();
}

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