如何自定义UseDocEndpoints自动为非API端点应用默认约定？

你想要的方案完全可行，不需要自定义IEndpointConventionBuilder或EndpointDataSource，通过**装饰器模式包装IEndpointRouteBuilder**就能实现自动给文档端点应用RequireHost等约定，代码结构清晰且符合ASP.NET Core的扩展规范。

实现步骤 #

1. 编写自定义扩展方法与装饰类 #

创建一个扩展方法UseDocEndpoints，内部通过包装原有的IEndpointRouteBuilder，拦截所有端点注册操作，自动应用约定：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Routing;

public static class DocEndpointExtensions
{
    // 可将host参数化，让用户按需配置
    public static IApplicationBuilder UseDocEndpoints(this IApplicationBuilder app, Action<IEndpointRouteBuilder> configure, string[] requiredHosts = null)
    {
        requiredHosts ??= new[] { "*:5656" };
        
        return app.UseEndpoints(innerBuilder =>
        {
            var docBuilder = new DocEndpointRouteBuilder(innerBuilder, requiredHosts);
            configure(docBuilder);
        });
    }

    // 装饰类：包装原有IEndpointRouteBuilder，自动给所有注册的端点添加约定
    private class DocEndpointRouteBuilder : IEndpointRouteBuilder
    {
        private readonly IEndpointRouteBuilder _innerBuilder;
        private readonly string[] _requiredHosts;

        public DocEndpointRouteBuilder(IEndpointRouteBuilder innerBuilder, string[] requiredHosts)
        {
            _innerBuilder = innerBuilder;
            _requiredHosts = requiredHosts;
        }

        // 实现接口的基础属性
        public IServiceProvider ServiceProvider => _innerBuilder.ServiceProvider;
        public ICollection<EndpointDataSource> DataSources => _innerBuilder.DataSources;

        // 重写Map方法：自动给返回的端点构建器添加RequireHost约定
        public IEndpointConventionBuilder Map(string pattern, RequestDelegate requestDelegate)
        {
            return _innerBuilder.Map(pattern, requestDelegate)
                               .RequireHost(_requiredHosts)
                               // 可在此添加更多通用约定，比如RequireAuthorization、CORS策略等
                               ;
        }

        // 重写MapGroup方法：保证分组内的端点也自动应用约定
        public IEndpointRouteBuilder MapGroup(string prefix)
        {
            var group = _innerBuilder.MapGroup(prefix);
            return new DocEndpointRouteBuilder(group, _requiredHosts);
        }
    }
}

2. 按需求分离API与文档端点配置 #

使用UseDocEndpoints替代原有的UseEndpoints配置文档类端点，约定会自动生效：

// API端点：单独配置，不应用文档类约定
app.UseEndpoints(builder =>
{
    builder.MapGraphQL();
    builder.MapControllers();
});

// 文档类端点：自动应用RequireHost("*:5656")约定
app.UseDocEndpoints(builder =>
{
    builder.MapSwagger();
    builder.MapSwaggerUI();
    builder.MapGraphQLPlayground();
    builder.MapHangfireDashboard(); // 新增的文档类端点也会自动应用约定
});

方案优势 #

• 代码分离清晰：API与文档端点的配置完全分开，维护性更强。
• 约定自动复用：不需要每个端点手动调用RequireHost，新增文档端点时直接添加即可。
• 扩展性强：可在装饰类的Map方法中添加更多通用约定，比如统一的授权规则、自定义元数据等，一次修改全局生效。

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