自定义约定是通过实现IControllerModelConvention或IActionModelConvention接口，统一配置Web API路由与行为的机制。它可用于自动添加路由前缀、设置响应格式、集成Swagger等。例如，RoutePrefixConvention为所有控制器添加“/api/v1”前缀，需在AddControllers时注册；AddCacheConvention标记GET方法以启用缓存，通过action.Properties传递状态；SwaggerTagByAreaConvention则按Area分组API。关键在于操作ControllerModel或ActionModel的属性，并注意避免覆盖显式路由设置，适合批量配置以减少重复代码。
在 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 方法自动添加缓存头说明：
一个用C#开的网站购物交易系统，带源码仅供学习参考，应用了WebCalendar控件。后台登陆帐号和密码分别为：admin admin WebCalendar控件是一个ASP.Net Web应用程序的日期控件,您可以通过设置控制控件中不同部分的样式的属性，来自定义 WebCalendar 控件的外观和图片；支持手动输入日期,支持输入时间,不会被TextBox,DropDownList遮挡。并且她是
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。
