ASP.NET Core中OData如何使用与控制器名不同的路由？

需求与目标 #

• 安全需求：避免暴露内部控制器实现细节
• 可用性需求：重构/重命名控制器时不引入破坏性API变更
• 核心目标：通过AddRouteComponents()注册OData控制器，使外部访问路由与控制器真实名称完全解耦

测试环境控制器说明 #

搭建了3个测试控制器：

• PresentationLayerExampleAEntityOData01Controller：无RouteAttribute
• PresentationLayerExampleAEntityOData02Controller：带有[Route("PresentationLayerExampleAEntityOData02")]（路由与控制器名匹配）
• PresentationLayerExampleAEntityOData03Controller：带有[Route("AnyOtherRouteName")]（路由与控制器名不匹配）

启动注册代码 #

启动时已完成实体模型注册，指定控制器名并设置路由前缀api/odata/，核心代码如下：

const string routePrefix = "api/odata/";
// 省略实体模型构建、类型遍历定义等逻辑
string controllerName = typeof(PresentationLayerExampleAEntityOData01Controller).GetODataControllerModelName();
// 省略其他控制器名获取逻辑
var catwalkModel = edmBuidler.GetEdmBuilder();
opt.AddRouteComponents(routePrefix, catwalkModel);

所有控制器均继承自带有[ODataAttributeRouting]特性的ODataController基类，Swagger可识别控制器并返回标准OData格式结果，但未达成核心目标。

案例1：约定路由问题 #

控制器代码：

// 无Route特性
public class PresentationLayerExampleAEntityOData01Controller : ModuleQueryableODataControllerBase<ExampleAEntityDto>
{
    [HttpGet("")]
    [HttpGet("Get")]
    [EnableQuery(PageSize = 100)]
    public IActionResult Get()
    {
        return Ok(_exampleEntityAService.Get());
    }     
}

问题 #

• 有效路由：/api/odata/PresentationLayerExampleAEntityOData01/Get、/api/odata/PresentationLayerExampleAEntityOData01/，可正常返回OData格式结果
• 无效路由：Swagger额外显示/PresentationLayerExampleAEntityOData01/Get、/PresentationLayerExampleAEntityOData01/，此类路由无法正常工作，需排除

案例2：Route特性使用误区 #

最初尝试带前缀的Route特性时，返回数据未被OData包裹，且构建时提示无法从路径模板确定控制器部分：

// 无效：返回非OData格式数据，且路由报错
[Route(ApiConstants.RestApiRoutePrefix+"[controller]")]
[ApiController]
[ForDemoOnly]
public class PresentationLayerExampleAEntityController : ControllerBase 

移除前缀后可正常返回OData格式数据，但未解决路由解耦问题：

// 有效：返回OData格式数据，但路由仍依赖控制器名
[Route("[controller]")]
[ApiController]
[ForDemoOnly]
public class PresentationLayerExampleAEntityController : ControllerBase 

案例3：自定义路由目标未达成 #

尝试用自定义路由名解耦控制器，但OData无法识别控制器，Swagger显示的路由无api/odata/前缀，调用失败：

[Route("AnyOtherRouteName")]
public class PresentationLayerExampleAEntityOData03Controller : ModuleQueryableODataControllerBase<ExampleAEntityDto>
{
    // 省略Action方法
}

解决方案建议 #

针对核心目标（路由与控制器名解耦），需结合OData的路由映射规则调整配置：

1. 手动指定控制器路由别名
   在AddRouteComponents时，通过自定义IODataControllerConvention为控制器指定路由别名，无需依赖RouteAttribute：

   opt.AddRouteComponents(routePrefix, catwalkModel, config =>
   {
       // 为目标控制器绑定自定义路由名
       config.Conventions.Add(new ControllerRoutingConvention(
           typeof(PresentationLayerExampleAEntityOData03Controller), 
           "AnyOtherRouteName"));
   });
   

   自定义约定实现：

   public class ControllerRoutingConvention : IODataControllerConvention
   {
       private readonly Type _controllerType;
       private readonly string _routeAlias;
   
       public ControllerRoutingConvention(Type controllerType, string routeAlias)
       {
           _controllerType = controllerType;
           _routeAlias = routeAlias;
       }
   
       public bool AppliesToController(ODataControllerModel controller)
       {
           return controller.ControllerType == _controllerType;
       }
   
       public void Apply(ODataControllerModel controller)
       {
           controller.ControllerName = _routeAlias;
       }
   }
   

2. 禁用常规Web API路由
   在Program.cs中仅启用OData路由，避免生成无效的非前缀路由：

   app.MapODataRoute("ODataRoute", routePrefix, catwalkModel);
   // 注释或移除常规API路由配置：app.MapControllers();
   

3. 修正Swagger路由显示
   配置Swagger过滤无效路由，并确保路径带有OData前缀：

   builder.Services.AddSwaggerGen(options =>
   {
       options.DocumentFilter<ODataRoutePrefixFilter>(routePrefix);
   });
   

   自定义文档过滤器实现：

   public class ODataRoutePrefixFilter : IDocumentFilter
   {
       private readonly string _prefix;
   
       public ODataRoutePrefixFilter(string prefix)
       {
           _prefix = prefix.TrimEnd('/');
       }
   
       public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
       {
           var invalidPaths = swaggerDoc.Paths.Where(p => !p.Key.StartsWith(_prefix)).ToList();
           foreach (var path in invalidPaths)
           {
               swaggerDoc.Paths.Remove(path.Key);
           }
       }
   }
   

4. 避免混合路由特性
   不要在OData控制器上添加[Route]或[ApiController]特性，此类特性会触发常规Web API路由逻辑，导致OData路由失效或数据未被正确包裹。

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