Java HttpClient 重定向怎么配：认证请求的跳转边界与安全验收

线上调用一个旧版文件服务时，最容易被忽略的不是请求能不能发出去，而是 301/302 之后请求到底去了哪里。Java 11 的 HttpClient 默认不自动跟随重定向；一旦打开跟随策略，认证头、跨主机跳转和最终响应状态就必须一起验收。

普通站内跳转可以按业务需要选择 NORMAL，带认证信息的请求不要直接使用 ALWAYS；先限制目标主机，再检查每一次跳转后的 URI 和响应头。

先看清 HttpClient 的三种重定向策略

HttpClient.Builder.followRedirect 接收的是 HttpClient.Redirect 枚举。它控制客户端遇到 3xx 响应时是否继续请求，而不是替应用完成授权判断。三种值的行为可以先压缩成一张表：

这里有个容易混淆的点：NORMAL 不是“自动安全模式”，它只是比 ALWAYS 保守。是否应继续访问，仍然取决于跳转后的主机、协议、路径和请求方法。

带认证头时，为什么我更建议先用 NEVER

假设客户端请求 https://api.example.test/export，服务端返回：

HTTP/1.1 302 Found
Location: https://download.example.test/file/42

这时真正需要回答的问题不是“要不要跟随”，而是 download.example.test 是否仍属于允许的资源域名。若把认证头、Cookie 或签名参数无条件带到新主机，跳转链路就可能扩大凭据暴露面。即使库本身对部分敏感头有保护，也不应该把安全边界交给一个看不见的默认行为。

最小的可控写法是先禁止自动跟随，然后只接受明确的 HTTPS 目标：

var client = HttpClient.newBuilder()
        .followRedirect(HttpClient.Redirect.NEVER)
        .connectTimeout(Duration.ofSeconds(3))
        .build();

var request = HttpRequest.newBuilder(URI.create("https://api.example.test/export"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/octet-stream")
        .GET()
        .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
if (response.statusCode() / 100 == 3) {
    var location = response.headers().firstValue("Location")
            .orElseThrow(() -> new IllegalStateException("redirect without Location"));
    var target = URI.create(location);
    if (!"https".equalsIgnoreCase(target.getScheme())
            || !Set.of("download.example.test").contains(target.getHost())) {
        throw new SecurityException("redirect target is not allowed: " + target);
    }
    // 重新构造请求；是否携带认证头由业务规则决定，不复用原请求的全部头。
}

示例特意没有把原请求复制成新请求。重定向目标即使是同一家公司，也可能有不同的权限域；重新列出允许的头，比“把所有头搬过去”更容易审查。

什么时候可以用 NORMAL，什么时候应该停在 3xx

如果接口只在同一个受控域名内从旧路径跳到新路径，且请求本身不携带用户凭据，可以考虑 NORMAL。但要给它加上可观测性：记录原始 URI、最终 URI 和状态码，必要时限制最大跳转次数。对于下载、登录回调、对象存储签名 URL，建议使用 NEVER，因为这些场景的跳转本身就是业务数据。

还要留意请求方法。浏览器和不同客户端对 301、302、303、307、308 的处理并不完全相同；尤其是 POST 被转成 GET，可能让服务端看到一个与原意不同的请求。自动跟随之后如果只检查最终的 200，很容易漏掉中间的行为变化。

用一个本地重定向服务做可重复验收

不要只在浏览器里点一次链接。可以准备两个本地端口：第一个返回 302，第二个记录收到的请求头。测试至少覆盖以下四项：

• 同主机、同协议的路径跳转是否符合预期。
• 跳到不在白名单的主机时，客户端是否停止。
• 跳转后的请求是否出现不应转移的 Authorization、Cookie 或签名头。
• 无 Location 的 3xx、循环跳转和超过上限时，调用方是否能得到明确异常。

日志建议只记录头名称，不记录令牌值。一个够用的验收行类似这样：

redirectCount=1 original=https://api.example.test/export
target=https://download.example.test/file/42 status=302 authForwarded=false result=accepted

authForwarded=false 不是永远正确的答案，它代表当前规则选择了重新授权或使用一次性下载凭据。关键是让这个选择出现在测试结果里，而不是藏在 HTTP 客户端的隐式行为中。

相关问题

HttpClient 默认会自动跟随 302 吗？

不会。没有显式设置时，默认策略相当于 NEVER，调用方会直接看到 3xx 响应。

只要是 HTTPS 跳转到 HTTPS 就可以放行吗？

不可以。还要检查目标主机、端口、路径和凭据传递规则；协议相同不代表信任边界相同。

为什么不直接用 ALWAYS 省掉代码？

因为自动跟随解决的是传输流程，不是授权决策。对签名下载、登录回调和跨域资源，显式处理 3xx 更容易发现错误。

把重定向当成一次新的授权决策

对普通静态资源，NORMAL 可以减少无意义的手工代码；对携带认证头的请求，NEVER 往往更适合生产排查和安全验收。无论采用哪种策略，都应把跳转次数、目标 URI、最终状态和凭据边界纳入测试。这样以后修改网关规则或迁移下载域名时，失败会出现在测试里，而不是出现在一条已经发出的请求之后。