ASP.NET Core 6 Web API如何生成分页HATEOAS链接写入Link头

核心组件选型说明 #

• 旧版UriHelper强依赖当前执行的请求上下文，仅能在控制器/视图的请求生命周期内使用，灵活性差，属于已被替代的旧实现。
• LinkGenerator是ASP.NET Core 2.2及以上版本官方推荐的URI生成组件，与请求上下文解耦，可在中间件、服务层等任意位置使用，且会自动处理反向代理、PathBase前缀等特殊部署场景，避免手动拼接URI出现的路径错误，是当前的首选方案。

LinkGenerator核心方法适用场景 #

LinkGenerator不同重载的适用边界非常清晰：

• GetUriByAction/GetPathByAction：面向MVC控制器Action，基于控制器名、Action名、路由参数生成完整URI/相对路径，是当前控制器分页接口场景的最适配方法。
• GetUriByRouteValues/GetPathByRouteValues：面向自定义命名路由，基于预先定义的路由名称和参数生成URI，适合全局通用路由场景。
• GetUriByName/GetPathByName：面向命名端点，适合最小API、端点路由定义的命名资源场景。

分页链接具体实现 #

生成链接时不需要手动拼接查询字符串，可直接提取当前请求的原始查询参数，排除分页相关参数后，与不同分页的页码参数合并传入LinkGenerator即可，自动保留所有排序、过滤、搜索等非分页参数，也会原样兼容自定义[CommaSeparated]特性对应的逗号分隔参数格式。
参考实现代码如下：

// 提前通过构造函数注入LinkGenerator实例
private readonly LinkGenerator _linkGenerator;

public IActionResult GetCountries(/* 接口参数保持原有声明即可 */)
{
    // 假设这是应用层返回的分页结果
    PagedResultDTO<GetCountriesDTO> pagedResult = _appService.GetCountries(/* 传入业务参数 */);
    
    // 1. 提取当前请求中所有非分页类的原始查询参数
    var preservedQueryParams = HttpContext.Request.Query
        .Where(param => param.Key != nameof(pageNumber) && param.Key != nameof(pageSize))
        .ToDictionary(param => param.Key, param => param.Value.ToString());

    var linkHeaderItems = new List<string>();

    // 2. 逐个生成各分页关系的链接
    // 首页链接
    var firstPageValues = new Dictionary<string, object?>(preservedQueryParams)
    {
        [nameof(pageNumber)] = 1,
        [nameof(pageSize)] = pagedResult.PageSize
    };
    var firstPageUri = _linkGenerator.GetUriByAction(
        httpContext: HttpContext,
        action: nameof(GetCountries),
        controller: "Countries", // 替换为当前控制器的实际名称
        values: firstPageValues
    );
    linkHeaderItems.Add($"<{firstPageUri}>; rel=\"first\"");

    // 尾页链接
    var lastPageValues = new Dictionary<string, object?>(preservedQueryParams)
    {
        [nameof(pageNumber)] = pagedResult.PageCount,
        [nameof(pageSize)] = pagedResult.PageSize
    };
    var lastPageUri = _linkGenerator.GetUriByAction(
        httpContext: HttpContext,
        action: nameof(GetCountries),
        controller: "Countries",
        values: lastPageValues
    );
    linkHeaderItems.Add($"<{lastPageUri}>; rel=\"last\"");

    // 上一页链接（仅当前页不是第一页时生成）
    if (pagedResult.PageNumber > 1)
    {
        var prevPageValues = new Dictionary<string, object?>(preservedQueryParams)
        {
            [nameof(pageNumber)] = pagedResult.PageNumber - 1,
            [nameof(pageSize)] = pagedResult.PageSize
        };
        var prevPageUri = _linkGenerator.GetUriByAction(
            httpContext: HttpContext,
            action: nameof(GetCountries),
            controller: "Countries",
            values: prevPageValues
        );
        linkHeaderItems.Add($"<{prevPageUri}>; rel=\"prev\"");
    }

    // 下一页链接（仅当前页不是最后一页时生成）
    if (pagedResult.PageNumber < pagedResult.PageCount)
    {
        var nextPageValues = new Dictionary<string, object?>(preservedQueryParams)
        {
            [nameof(pageNumber)] = pagedResult.PageNumber + 1,
            [nameof(pageSize)] = pagedResult.PageSize
        };
        var nextPageUri = _linkGenerator.GetUriByAction(
            httpContext: HttpContext,
            action: nameof(GetCountries),
            controller: "Countries",
            values: nextPageValues
        );
        linkHeaderItems.Add($"<{nextPageUri}>; rel=\"next\"");
    }

    // 3. 将拼接完成的Link值写入响应头
    Response.Headers.Append("Link", string.Join(", ", linkHeaderItems));

    return Ok(pagedResult);
}

框架内置能力说明 #

目前ASP.NET Core没有提供专门针对RFC 8288规范的Link头格式化内置组件，上述直接拼接符合规范格式字符串的方式是官方推荐的常规实现，不需要引入额外第三方依赖。

不推荐完全基于Request对象手动拼接整个URI：手动拼接很容易遗漏反向代理、应用PathBase前缀等部署配置，导致生成的链接无法访问，LinkGenerator会自动处理这些场景，兼容性远高于手动拼接。

内容的提问来源于stack exchange，提问作者M. Koch