ASP.NET Core 8自定义Web API端点报400错误求助

问题分析 #

400错误提示'id'字段值'GetOfferByKey'无效，核心原因是路由匹配规则冲突：ASP.NET Core 8的默认路由模板把你自定义的端点名称误判为某个路由参数（比如id）进行解析，而该参数的类型约束（比如整数）无法兼容字符串值GetOfferByKey，最终触发参数校验失败。

排查与解决步骤 #

1. 修正控制器路由属性配置 #

确保控制器和方法的路由模板清晰区分，避免与默认路由冲突：

• 若控制器标注了[ApiController]和[Route("api/[controller]")]，给自定义方法指定专属路由模板，不要让框架将方法名当作路由参数解析。
• 示例配置：

[HttpGet("offer/by-key")]
public IActionResult GetOfferByKey(string key)
{
    // 业务逻辑代码
    return Ok();
}

此时合法请求路径为GET /api/[控制器名]/offer/by-key?key=xxx，不会与带id参数的路由混淆。

2. 检查Program.cs中的路由注册 #

.NET 8已移除WebConfig.cs，路由配置统一在Program.cs中完成，需确认以下配置正确：

• 确保已添加控制器服务并映射路由：

var builder = WebApplication.CreateBuilder(args);

// 注册控制器服务
builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();

// 映射控制器路由，必须存在该行
app.MapControllers();

app.Run();

3. 验证请求URL的正确性 #

确认请求URL与方法路由模板完全匹配：

• 错误示例：将GetOfferByKey当作id参数放在路径中（如GET /api/[控制器名]/GetOfferByKey，若存在[HttpGet("{id}")]的方法，会触发参数类型不匹配）。
• 正确示例：若方法路由为[HttpGet("GetOfferByKey")]，请求路径应为GET /api/[控制器名]/GetOfferByKey，参数通过QueryString传递（如?key=xxx）。

4. 调整路由顺序避免冲突 #

若控制器中存在带id参数的路由（如[HttpGet("{id:int}")]），需将更具体的自定义路由放在前面，让框架优先匹配明确的模板：

[ApiController]
[Route("api/[controller]")]
public class OfferController : ControllerBase
{
    // 自定义路由放在前面，优先匹配
    [HttpGet("by-key")]
    public IActionResult GetOfferByKey(string key)
    {
        return Ok($"Offer Key: {key}");
    }

    // 带id参数的路由放在后面
    [HttpGet("{id:int}")]
    public IActionResult GetOfferById(int id)
    {
        return Ok($"Offer ID: {id}");
    }
}

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