.NET 6 API Controller路由全部返回404问题排查及路由选型咨询

一、404问题解决步骤 #

1. 核心问题：Action未配置正确的路由特性 #

你的UsersController虽已添加控制器级特性路由[Route("api/[controller]")]，但每个Action未明确指定HTTP方法和路由模板，导致路由系统无法匹配请求规则。

2. 修正控制器代码 #

给每个Action添加对应的HTTP特性和路由模板，示例如下：

[Route("api/[controller]")]
[ApiController] // 自动处理模型验证、路由参数绑定，建议添加
public class UsersController : ControllerBase
{
    // 匹配 GET /api/users
    [HttpGet]
    public IActionResult GetUsers()
    {
        // 业务逻辑实现
        return Ok();
    }

    // 匹配 GET /api/users/123，{id:int}为可选参数类型约束，可过滤非整数id的无效请求
    [HttpGet("{id:int}")]
    public IActionResult GetUser(int id)
    {
        // 业务逻辑实现
        return Ok();
    }
}

3. 优化Program.cs配置 #

纯API场景无需同时添加AddControllersWithViews和AddControllers，保留AddControllers即可；路由映射仅需MapControllers（用于特性路由），避免与约定路由冲突：

var builder = WebApplication.CreateBuilder(args);

// 纯API场景只需要AddControllers
builder.Services.AddControllers();

var app = builder.Build();

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

// 特性路由映射
app.MapControllers();

// 静态文件fallback保留即可
app.MapFallbackToFile("index.html");

app.Run();

4. 为何添加约定路由后GetUsers可用但GetUser仍404？ #

约定路由默认模板一般为"{controller=Home}/{action=Index}/{id?}"，未加特性的GetUsers会匹配/Users/GetUsers路径，恰好和你请求的/api/users通过某种映射生效；但GetUser需要id参数，约定路由下需请求/Users/GetUser/123，而你请求的/api/users/123不符合约定规则，因此依然返回404。

二、约定路由 vs 特性路由：哪种更优？ #

没有绝对最优方案，需结合项目场景选择：

特性路由（推荐纯API项目使用） #

• 优势：
  • 灵活性极强，每个Action可自定义独立路由，完美适配RESTful风格（如api/users、api/users/123）；
  • 路由规则与Action代码绑定，直观易维护，便于实现版本控制（如api/v2/users）；
  • 支持路由约束、默认值、可选参数等高级配置，能精准控制请求匹配逻辑。
• 劣势：
  • 控制器数量较多时，可能出现重复路由模板（可通过控制器级路由减少重复）。

约定路由（推荐MVC视图项目使用） #

• 优势：
  • 统一配置路由规则，无需给每个Action添加特性，减少代码冗余；
  • 适合路由规则高度统一的场景，比如传统MVC页面（如/Home/Index、/Product/Detail/1）。
• 劣势：
  • 灵活性不足，无法为单个Action设置特殊路由；
  • 对RESTful API而言，路由匹配不够直观，易出现请求路径与Action不对应的问题。

总结 #

• 纯API项目优先选择特性路由，符合RESTful设计，长期维护成本更低；
• MVC混合视图与API的项目，可混合使用两者，但特性路由优先级高于约定路由；
• 若路由规则高度统一、无特殊需求，约定路由会更简洁高效。

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