6.45ForwardAttribute 转发特性

创建于 2026 年 8 月 17 日约 4 分钟读完

为了简化转发操作，框架提供了便捷的 [Forward] 控制器操作转发特性。相较于手动调用 HttpContext 的 Forward 扩展方法，该特性显著减少了重复的硬编码工作。以下是使用 [Forward] 特性的示例代码：

cs
[ApiController][Route("[controller]/[action]")]public class GetStartController : ControllerBase{    /// <summary>    ///     转发代理到网站    /// </summary>    /// <returns></returns>    [HttpGet]    [ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)] // 禁用浏览器缓存    [Forward("https://github.com", AllowedHosts = ["*"])]    public Task<IActionResult?> ForwardToWebSite()    {        throw new NotImplementedException();    }    /// <summary>    ///     转发代理到图片    /// </summary>    /// <returns></returns>    [HttpGet]    [ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)] // 禁用浏览器缓存    [Forward("https://img-s-msn-com.akamaized.net/tenant/amp/entityid/AA1u7RJI.img?w=584&h=326&m=6", AllowedHosts = ["*"])]    public Task<IActionResult?> ForwardToImage()    {        throw new NotImplementedException();    }    /// <summary>    ///     转发代理到文件    /// </summary>    /// <returns></returns>    [HttpGet]    [ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)] // 禁用浏览器缓存    [Forward("https://download.visualstudio.microsoft.com/download/pr/a17b907f-8457-45a8-90db-53f2665ee49e/49bccd33593ebceb2847674fe5fd768e/aspnetcore-runtime-8.0.10-win-x64.exe", AllowedHosts = ["*"])]    public Task<IActionResult?> ForwardToDownload()    {        throw new NotImplementedException();    }    /// <summary>    ///     转发代理到表单    /// </summary>    /// <param name="id"></param>    /// <param name="model"></param>    /// <returns></returns>    [HttpPost]    [Forward("https://localhost:7044/HttpRemote/AddForm", AllowedHosts = ["*"])]    public Task<YourRemoteFormResult?> ForwardToForm(int id, [FromForm] YourRemoteFormModel model)    {        throw new NotImplementedException();    }    /// <summary>    ///     转发代理到字符串    /// </summary>    /// <returns></returns>    [HttpGet]    [Forward("https://localhost:7044/GetStart/PostRawString", AllowedHosts = ["*"])]    public Task<string> ForwardToString()    {        throw new NotImplementedException();    }    /// <summary>    ///     转发代理到无返回值    /// </summary>    /// <returns></returns>    [HttpGet]    [Forward("https://localhost:7044/GetStart/PostRawString", AllowedHosts = ["*"])]    public Task ForwardToVoid()    {        throw new NotImplementedException();    }}

在上述代码中，我们只需为需要转发的控制器操作添加 [Forward] 特性，并指定目标 URL。框架会自动处理转发逻辑，因此方法体内无需编写任何实现代码（通常抛出 NotImplementedException 以表明这是一个由框架自动处理的转发操作）。这种方式在微服务应用中尤为便捷，极大地简化了代码编写和维护工作。

ForwardAttribute 包含以下属性：

  • 属性：
    • RequestUri：转发地址（string 类型）。
    • Method：转发方式，若未设置，则自动采用当前请求方式作为转发方式（HttpMethod 类型）。
    • HttpClientName：HttpClient 实例的配置名称，默认值为 null（string 类型）。
    • CompletionOption：指示响应内容操作方式，默认值为 ResponseHeadersRead（HttpCompletionOption 类型）。
    • AllowedHosts：允许转发的目标主机白名单（string[]? 类型）。
      用于防范 服务端请求伪造（SSRF） 攻击。仅当目标地址的主机（含端口、协议）与列表中的某一项匹配时，转发才会被允许。
      支持的格式（匹配均忽略大小写）：
      • "furion.net" – 仅主机名，匹配任意协议（http/https）的默认端口（80/443）。
      • "furion.net:8080" – 主机+端口，匹配任意协议的指定端口。
      • "furion.net:*" – 主机+端口通配符，匹配任意协议下的任意端口。
      • "https://furion.net" – 协议+主机，只匹配指定协议的默认端口。
      • "http://furion.net:8080" – 协议+主机+端口，精确匹配。
      • "https://furion.net:*" – 协议+主机+端口通配符，只匹配指定协议的任意端口。
      • "*" – 全局通配符，允许任意主机和协议（完全绕过验证，高风险）。
        若未配置或为空，所有通过 X-Forward-To 请求头指定的目标地址都将被拒绝，以防止未经授权的转发。建议尽可能使用精确规则，仅对完全可信的来源开放通配符。
    • WithQueryParameters：是否转发查询参数（URL 参数），默认值为 true（bool 类型）。
    • WithRequestHeaders：是否转发请求标头，默认值为 true（bool 类型）。
    • WithResponseStatusCode：是否转发响应状态码，默认值为 true（bool 类型）。
    • WithResponseHeaders：是否转发响应标头，默认值为 true（bool 类型）。
    • WithResponseContentHeaders：是否转发响应内容标头，默认值为 true（bool 类型）。
    • ResetHostRequestHeader：是否重新设置 Host 请求标头，默认值为 false（bool 类型）。
    • IgnoreQueryParameters：忽略在转发时需要跳过的查询参数（URL 参数）列表（string[]? 类型）。
    • IgnoreRequestHeaders：忽略在转发时需要跳过的请求标头列表（string[]? 类型）。
    • IgnoreResponseHeaders：忽略在转发时需要跳过的响应标头列表（string[]? 类型）。