自托管ASP.NET Core 6 Web API系统测试持续返回404 NotFound排查

以下是几个必须检查的关键点，按顺序排查：

• 确认API版本控制服务已正确注册
  不管是原项目还是测试项目的启动配置里，都必须添加API版本控制的服务：

  builder.Services.AddApiVersioning(options =>
  {
      options.DefaultApiVersion = new ApiVersion(1, 0);
      options.AssumeDefaultVersionWhenUnspecified = true;
      options.ReportApiVersions = true;
  });
  

  测试用的TestSetup如果是单独构建WebApplication，不能漏了这段配置，否则版本路由根本不生效。

• 验证控制器的完整标记
  你的HomeController必须同时具备[ApiController]、[ApiVersion]和路由属性，比如：

  [ApiController]
  [ApiVersion("1.0")]
  [Route("api/v{version:apiVersion}/[controller]")]
  public class HomeController : ControllerBase
  {
      [HttpGet]
      public IActionResult Index()
      {
          return Ok("Success");
      }
  }
  

  少了[ApiController]的话，路由匹配逻辑会不一样，很可能导致404；另外版本字符串"1.0"和请求里的v1是兼容的，框架会自动识别，这点不用纠结。

• 检查测试请求的细节
  确认测试发送的请求是GET api/v1/Home，并且对应控制器里有[HttpGet]标记的Action——如果Action用了[HttpPost]或者其他方法，测试用GET肯定会返回404。另外要注意有没有多余的路由前缀，比如原项目或测试项目里加了全局路由前缀，导致实际路径不是api/v1/Home。

• 测试项目的WebApplication启动必须正确配置路由
  如果是用WebApplicationFactory启动，确保指向的是原项目的Program类：

  var client = new WebApplicationFactory<Program>().CreateClient();
  

  如果是手动构建WebApplication，必须调用app.MapControllers()，否则控制器路由不会被注册：

  var builder = WebApplication.CreateBuilder();
  builder.Services.AddControllers();
  builder.Services.AddApiVersioning(...); // 不能少
  var app = builder.Build();
  app.MapControllers(); // 关键步骤，没有这个路由不生效
  app.Run();
  

• 用日志排查路由匹配问题
  在测试项目的启动配置里添加日志，查看路由匹配的详细过程：

  builder.Logging.AddConsole().AddDebug();
  

  运行测试后，查看控制台日志里的路由匹配记录，就能明确知道请求为什么没匹配到控制器。

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