A Comprehensive Guide to Extracting Client IP Address in Spring MVC Controllers

Introduction

In modern web application development, obtaining client IP addresses is a common requirement, particularly in scenarios such as user behavior analysis, security auditing, and access control. Spring MVC, as a widely used web framework in the Java ecosystem, offers multiple flexible approaches to address this need. This article systematically introduces various methods for extracting client IP addresses in Spring MVC controllers.

Basic Method: Using HttpServletRequest

The most straightforward approach is to add an HttpServletRequest parameter to the controller method and then invoke its getRemoteAddr() method. This method is simple and effective, suitable for most standard deployment environments.

@RequestMapping(value = "processing", method = RequestMethod.GET)
public @ResponseBody ProcessResponse processData(@RequestParam("workflow") final String workflow,
    @RequestParam("conf") final String value, @RequestParam("dc") final String dc, HttpServletRequest request) {

    System.out.println(workflow);
    System.out.println(value);
    System.out.println(dc);
    String clientIP = request.getRemoteAddr();
    System.out.println("Client IP Address: " + clientIP);
    // Other business logic code
}

Spring Framework's @RequestMapping annotation supports flexible handler method parameter types, including HttpServletRequest from the Servlet API. When the method is invoked, Spring automatically injects the current request object, allowing developers to directly use standard Servlet API to access request information.

Special Handling in Proxy Environments

In actual production environments, applications are typically deployed behind proxy servers or load balancers. In such cases, the getRemoteAddr() method may return the IP address of the proxy server rather than the real client IP. To resolve this issue, it is necessary to inspect specific HTTP headers.

X-Forwarded-For is one of the most commonly used headers, containing the original client IP address and the chain of intermediate proxy server IP addresses. When processing this header, note that it may contain multiple IP addresses separated by commas, with the first address usually being the original client IP.

String xForwardedFor = request.getHeader("X-FORWARDED-FOR");
if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
    String[] ips = xForwardedFor.split(",");
    String clientIP = ips[0].trim();
    System.out.println("Client IP obtained via X-Forwarded-For: " + clientIP);
} else {
    String clientIP = request.getRemoteAddr();
    System.out.println("Directly obtained client IP: " + clientIP);
}

Complete IP Address Extraction Utility Class

To handle various complex network deployment scenarios, a dedicated utility class can be created to intelligently extract client IP addresses. This utility class sequentially checks multiple potential IP address headers to ensure accurate client IP retrieval across different environments.

import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import javax.servlet.http.HttpServletRequest;

public class HttpReqRespUtils {

    private static final String[] IP_HEADER_CANDIDATES = {
        "X-Forwarded-For",
        "Proxy-Client-IP",
        "WL-Proxy-Client-IP",
        "HTTP_X_FORWARDED_FOR",
        "HTTP_X_FORWARDED",
        "HTTP_X_CLUSTER_CLIENT_IP",
        "HTTP_CLIENT_IP",
        "HTTP_FORWARDED_FOR",
        "HTTP_FORWARDED",
        "HTTP_VIA",
        "REMOTE_ADDR"
    };

    public static String getClientIpAddress() {
        if (RequestContextHolder.getRequestAttributes() == null) {
            return "0.0.0.0";
        }

        HttpServletRequest request = ((ServletRequestAttributes) 
            RequestContextHolder.getRequestAttributes()).getRequest();
        
        for (String header : IP_HEADER_CANDIDATES) {
            String ipList = request.getHeader(header);
            if (ipList != null && ipList.length() != 0 && 
                !"unknown".equalsIgnoreCase(ipList)) {
                String ip = ipList.split(",")[0];
                return ip;
            }
        }

        return request.getRemoteAddr();
    }
}

The design of this utility class considers multiple scenarios: first, it checks for the existence of a request context, then it inspects various possible IP address headers in order of priority. If no headers contain valid information, it falls back to using the getRemoteAddr() method. This design ensures accurate client IP address retrieval in the vast majority of deployment environments.

Technical Details and Best Practices

When using these methods, several important technical details must be noted. First, the X-Forwarded-For header can be maliciously forged, so in high-security scenarios, this header should only be trusted from reliable proxy servers. Second, handling IPv6 addresses requires special attention to ensure the application correctly processes IP addresses in various formats.

Another important consideration is performance. Frequently creating utility class instances may impact performance, so it is advisable to design the utility class with static methods or manage its instances via dependency injection. Additionally, for high-concurrency applications, caching some parsing results can enhance performance.

Integration into Spring MVC Controllers

When integrating IP address extraction functionality into Spring MVC controllers, choose the appropriate method based on specific requirements. For simple applications, directly using HttpServletRequest in the controller method is sufficient. For scenarios requiring unified IP address handling across the entire application, AOP (Aspect-Oriented Programming) or custom annotations can be employed.

@RequestMapping(value = "processing", method = RequestMethod.GET)
public @ResponseBody ProcessResponse processData(@RequestParam("workflow") final String workflow,
    @RequestParam("conf") final String value, @RequestParam("dc") final String dc) {

    String clientIP = HttpReqRespUtils.getClientIpAddress();
    System.out.println("Client IP: " + clientIP);
    
    // Business logic processing based on IP address
    if (isAllowedIP(clientIP)) {
        // Process allowed IP address access
        return processAllowedRequest(workflow, value, dc);
    } else {
        // Process denied IP address access
        return processDeniedRequest();
    }
}

Security Considerations

Security is a factor that cannot be overlooked when obtaining and using client IP addresses. Beyond the aforementioned risks of header forgery, consider the storage and usage of IP addresses. It is recommended to apply appropriate anonymization to IP addresses, especially in log records. Additionally, regularly review and update IP address validation logic to address evolving security threats.

Conclusion

Obtaining client IP addresses in Spring MVC applications is a seemingly simple yet practically complex issue. Through the methods introduced in this article, developers can select suitable technical solutions based on specific deployment environments and requirements. Whether for straightforward direct retrieval or complex proxy environment handling, Spring MVC provides sufficient flexibility to meet various needs. Correctly implementing IP address retrieval functionality not only enhances application features but also improves security and maintainability.