ASP.NET Core中Open API控制器自动识别机制及设计原因问询

我使用NSwag生成C# OpenAPI控制器代码后，在Program.cs中使用了如下基础代码：

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

服务可正常运行测试，但有几个疑问需要解答：

疑问1：未指定控制器类名，运行时如何识别要使用的控制器？ #

ASP.NET Core会通过约定驱动的程序集扫描机制自动识别控制器：

• 只要类满足以下任一条件，就会被判定为控制器：
  • 继承自ControllerBase或Controller基类
  • 带有[ApiController]特性
  • 类名以Controller结尾（默认约定）
• builder.Services.AddControllers()方法内部已经封装了扫描逻辑，会自动在当前应用程序集及引用的程序集中查找符合条件的类，无需手动指定类名。

疑问2：该机制是否基于反射遍历筛选类？ #

是的，核心就是反射+约定筛选：

• 调用AddControllers()时，框架会触发程序集扫描，通过反射遍历程序集中的所有类型
• 按照预设的控制器约定（继承关系、特性、命名规则）筛选出符合要求的类
• 将这些控制器类型注册到依赖注入容器中，并为它们生成对应的路由规则

疑问3：为何OpenAPI控制器无需像gRPC或托管服务那样指定类？ #

这种设计差异源于不同技术栈的定位和设计原则：

• 约定优于配置：ASP.NET Core Web API的核心设计理念之一，通过约定减少重复配置，让开发者聚焦业务逻辑，无需手动注册每个控制器
• 路由模型差异：gRPC基于强契约的服务定义，每个服务必须明确绑定实现类；而Web API支持灵活的路由配置（特性路由、约定路由），自动扫描更适配这种动态路由模式
• 场景适配：托管服务是后台运行的单例任务，需明确指定启动类；控制器是HTTP请求入口，数量通常较多，自动扫描更高效，契合Web开发快速迭代的需求

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