在 ASP.NET Core 中，自定义约定（Custom Conventions）主要用于 Web API 的路由和控制器行为的配置，特别是在使用 API 探索工具如 Swagger（Swashbuckle）或进行基于约定的配置时。它们允许你在不修改每个控制器或动作方法的前提下，统一应用某些规则。
什么是自定义约定？
自定义约定是通过实现特定接口来扩展 ASP.NET Core MVC 行为的机制。常见的应用场景包括：
自动为所有控制器添加路由前缀 统一设置响应格式（如强制返回 JSON） 为 API 添加版本号或公共查询参数 与 Swagger 集成时自动添加注释或标签主要涉及两类约定：
• 控制器级别约定（IControllerModelConvention）• 操作级别约定（IActionModelConvention）
如何创建并注册自定义控制器约定
以添加全局路由前缀为例：
// 自定义控制器约定：为所有控制器添加前缀public class RoutePrefixConvention : IControllerModelConvention
{
private readonly string _prefix;
public RoutePrefixConvention(string prefix)
{
_prefix = prefix;
}
public void Apply(ControllerModel controller)
{
// 只对没有显式标记 [Route] 的控制器生效
if (controller.Selectors.Any(s => s.AttributeRouteModel != null))
return;
foreach (var selector in controller.Selectors)
{
selector.AttributeRouteModel = new AttributeRouteModel
{
Template = $"/{_prefix}/{controller.ControllerName}"
};
}
}
}
在 Program.cs 中注册：
builder.Services.AddControllers(options =>
{
options.Conventions.Add(new RoutePrefixConvention("api/v1"));
});
这样所有控制器默认都会映射到
/api/v1/控制器名路径下。
操作级别的自定义约定示例
比如你想为所有 GET 方法自动添加缓存头说明：
public class AddCacheConvention : IActionModelConvention
{
public void Apply(ActionModel action)
{
if (action.HttpMethods != null && action.HttpMethods.Contains("GET"))
{
// 可用于记录或标记，例如配合过滤器使用
action.Properties["IsCached"] = true;
}
}
}
注册方式相同：
options.Conventions.Add(new AddCacheConvention());
后续可在中间件、过滤器或文档生成中读取
action.Properties进行处理。
与 Swagger 结合使用
常用于自动添加标签或描述：
public class SwaggerTagByAreaConvention : IControllerModelConvention
{
public void Apply(ControllerModel controller)
{
var area = controller.RouteValues["area"];
if (!string.IsNullOrEmpty(area))
{
foreach (var action in controller.Actions)
{
action.ApiExplorer.GroupName = area;
}
}
}
}
这能让 Swagger UI 按 Area 分组展示 API。
基本上就这些。自定义约定适合做“批量配置”，避免重复代码。只要搞清楚 ControllerModel 和 ActionModel 的结构，就能灵活控制路由、元数据和文档行为。关键是注册位置要正确，在 AddControllers 里添加即可生效。不复杂但容易忽略细节，比如判断是否已有 AttributeRouteModel。
