.NET 7 Web API自定义路由问题：无法识别/api/Person前缀路由

核心问题分析 #

你的问题根源在于ASP.NET Core路由系统默认只识别控制器类上的路由特性，而你将路由配置放在了ViewService接口的自定义ControllerEndpoint属性上，同时泛型抽象控制器的路由关联逻辑未被框架感知，导致路由无法被发现，Swagger也无法抓取到端点信息。以下是分步解决方法：

1. 实现自定义控制器约定，关联ViewService的路由配置 #

创建IControllerModelConvention的实现，将ViewService接口上的ControllerEndpoint属性信息映射到对应的控制器上，让路由系统识别这些配置。

首先确保你的ControllerEndpoint属性定义正确：

[AttributeUsage(AttributeTargets.Interface)]
public class ControllerEndpointAttribute : Attribute
{
    public string RoutePrefix { get; }
    public Type[] TargetControllers { get; }

    public ControllerEndpointAttribute(string routePrefix, params Type[] targetControllers)
    {
        RoutePrefix = routePrefix;
        TargetControllers = targetControllers;
    }
}

然后实现约定类：

public class EndpointRouteConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        // 验证当前控制器是否继承自你的泛型抽象基类
        var baseType = controller.ControllerType.BaseType;
        if (!baseType.IsGenericType || baseType.GetGenericTypeDefinition() != typeof(ActionControllerBase<,,>))
            return;

        // 获取泛型参数中的ViewService类型
        var viewServiceType = baseType.GetGenericArguments()[2];
        var endpointAttr = viewServiceType.GetCustomAttribute<ControllerEndpointAttribute>();
        if (endpointAttr == null)
            return;

        // 检查当前控制器是否在属性指定的目标控制器列表中
        if (!endpointAttr.TargetControllers.Contains(controller.ControllerType))
            return;

        // 为控制器添加路由前缀
        controller.Selectors.Add(new SelectorModel
        {
            AttributeRouteModel = new AttributeRouteModel(new RouteAttribute(endpointAttr.RoutePrefix))
        });

        // 标记为API控制器，启用自动验证、路由绑定等特性
        controller.ControllerType.AddAttribute(new ApiControllerAttribute());
    }
}

在Program.cs中注册该约定：

builder.Services.AddControllers(options =>
{
    options.Conventions.Add(new EndpointRouteConvention());
});

2. 确保控制器方法的HTTP动词配置正确 #

每个具体控制器（如PersonReadController）的CRUD方法必须添加对应的HTTP动词特性，路由会自动与前缀拼接：

public class PersonReadController : ActionControllerBase<Person, PersonDatabaseService, IPersonViewService>
{
    [HttpGet("{id:int}")]
    public async Task<IActionResult> GetById(int id)
    {
        // 业务逻辑
    }

    [HttpGet]
    public async Task<IActionResult> GetAll()
    {
        // 业务逻辑
    }
}

此时/api/Person和/api/Person/1这类路由就能被正确识别。

3. 修复Swagger端点显示问题 #

Swagger依赖路由系统的元数据生成文档，只要上面的约定生效，Swagger就能自动抓取到端点。确保你的Swagger配置正确：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API", Version = "v1" });
    // 可选：添加XML注释增强文档
    var xmlPath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
    c.IncludeXmlComments(xmlPath);
});

// 中间件配置
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API V1");
});

4. 路由调试（可选） #

如果仍有问题，可添加路由调试中间件，查看请求是否匹配到预期路由：

app.UseRouting();

// 路由调试中间件
app.Use(async (context, next) =>
{
    var endpoint = context.GetEndpoint();
    if (endpoint != null)
    {
        var routePattern = endpoint.Metadata.GetMetadata<RoutePatternMetadata>()?.RoutePattern?.RawText;
        Console.WriteLine($"匹配到路由: {routePattern}");
    }
    await next();
});

app.UseAuthorization();
app.MapControllers();

5. 验证ViewService的属性标记 #

确保你的ViewService接口正确标记了ControllerEndpoint属性：

[ControllerEndpoint("/api/Person", typeof(PersonReadController), typeof(PersonInsertController))]
public interface IPersonViewService
{
    // 视图转换、验证方法
}

内容的提问来源于stack exchange，提问作者Goran Petrović