Class ClientIpResolver

java.lang.Object
tech.riemann.nif.utils.ClientIpResolver
public class ClientIpResolver extends Object
统一客户端真实 IP 解析器（secure-by-default）。

框架级单一信任源：将此前散落在白名单过滤器、限流拦截器、Ips.getIP、Actuator 过滤器等多处的 X-Forwarded-For 信任逻辑收敛为一处，避免各过滤器各自实现、导致安全默认分化。

安全契约（secure-by-default）：

  • 默认（trustForwardedHeader=false）不采信任何转发头，一律只认 直连地址 HttpServletRequest.getRemoteAddr()——这是唯一客户端无法伪造的地址。
  • 仅当显式开启 trustForwardedHeader 且直连方（remote）命中登记的可信代理清单 （trustedProxies，精确 IP 或 CIDR）时，才解析 X-Forwarded-For 的最左一段 （即可信代理链中最先记录的原始客户端地址）；其余情况（未开启、直连方非可信代理、转发头缺失/非法） 一律退回直连地址。
  • 仅读取标准 X-Forwarded-For 链头，不读 X-Real-IP 等非标准头，避免语义歧义与信任点分散。

不可变：构造后配置不可变，实例可安全被多线程共享（如注入为 Spring 单例 bean）。

Author:
Kerbores(kerbores@riemann.tech)

  • Constructor Details

    • ClientIpResolver

      public ClientIpResolver()
      secure-by-default 构造：不信任转发头，仅取直连地址。

    • ClientIpResolver

      public ClientIpResolver(boolean trustForwardedHeader, List<String> trustedProxies)

  • Method Details

    • secure

      public static ClientIpResolver secure()
      静态工厂：返回 secure-by-default 实例（不信任转发头）。

    • resolve

      public String resolve(jakarta.servlet.http.HttpServletRequest request)
      解析客户端真实 IP。
      Parameters:
      request - 当前请求（不可为 null）
      Returns:
      用于信任判定的客户端 IP（直连地址，或经可信代理解析的最左段）
      Throws:
      IllegalArgumentException - 当 request 为 null