自定义约定是通过实现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 方法自动添加缓存头说明：
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。
以上就是ASP.NET Core 中的自定义约定如何应用？的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1440815.html
微信扫一扫 
支付宝扫一扫 
