51工具盒子
如何在 Spring Boot 3.3 中实现请求 IP 白名单拦截功能
在微服务和分布式系统中，确保系统的安全性至关重要。其中一种常见的安全措施是实现 IP 白名单功能，即只允许特定的 IP 地址访问系统。在这篇文章中，我们将深入探讨如何在 Spring Boot 3.3 中实现 IP 白名单拦截功能，并结合具体的代码示例来详细说明。
运行效果：
正常访问
受限访问
若想获取项目完整代码以及其他文章的项目源码，且在代码编写时遇到问题需要咨询交流，欢迎加入下方的知识星球。
1. 项目环境配置
首先，我们需要创建一个 Spring Boot 项目，并添加必要的依赖。
pom.xml 配置
在 pom.xml 中添加以下依赖：
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.3.3</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.icoderoad</groupId> <artifactId>IpWhitelist</artifactId> <version>0.0.1-SNAPSHOT</version> <name>IpWhitelist</name> <description>IpWhitelist Demo project for Spring Boot</description><properties> <java.version>17</java.version> <bootstrap.version>5.1.0</bootstrap.version> <jquery.version>3.6.0</jquery.version> </properties> <dependencies> <!-- Spring Boot Starter Web --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Thymeleaf --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> <!-- Bootstrap & jQuery --> <dependency> <groupId>org.webjars</groupId> <artifactId>bootstrap</artifactId> <version>${bootstrap.version}</version> </dependency> <dependency> <groupId>org.webjars</groupId> <artifactId>jquery</artifactId> <version>${jquery.version}</version> </dependency>&lt;dependency&gt; &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt; &lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt; &lt;scope&gt;test&lt;/scope&gt; &lt;/dependency&gt;</dependencies>
<build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build>
</project>
application.yml 配置
在 src/main/resources/application.yml 中添加以下配置：
server: port: 8080
ip: whitelist: - 192.168.0.1 - 127.0.0.1 - 0:0:0:0:0:0:0:1
这里我们配置了一个 ip.whitelist 属性，用于指定允许访问系统的 IP 地址列表。
2. 创建 IP 拦截器
属性读取类
package com.icoderoad.IpWhitelist.config;import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Configuration;
import java.util.List;
@Configuration @ConfigurationProperties(prefix = "ip") public class IpWhitelistProperties {
private List<String> whitelist;
public List<String> getWhitelist() { return whitelist; }
public void setWhitelist(List<String> whitelist) { this.whitelist = whitelist; } }
接下来，我们将创建一个自定义拦截器 IpWhitelistInterceptor，用于拦截请求并检查请求的 IP 是否在白名单中。
package com.icoderoad.IpWhitelist.interceptor;import java.util.List;
import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import org.springframework.web.servlet.HandlerInterceptor;
import com.icoderoad.IpWhitelist.config.IpWhitelistProperties;
import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse;
@Component public class IpWhitelistInterceptor implements HandlerInterceptor {
private final List<String> whitelist;
@Autowired public IpWhitelistInterceptor(IpWhitelistProperties properties) { this.whitelist = properties.getWhitelist(); }
@Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String remoteIp = request.getRemoteAddr(); String requestUri = request.getRequestURI(); // 排除错误页面路径，避免重定向循环 if ("/error/ip".equals(requestUri)) { return true; }
if (whitelist.contains(remoteIp)) { return true; } else { // 如果 IP 不在白名单中，重定向到错误页面 response.sendRedirect("/error/ip"); return false; } } }
视图控制器
package com.icoderoad.IpWhitelist.controller;import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.web.bind.annotation.GetMapping;
@Controller public class IndexController {
@GetMapping("/") public String index(Model model) { return "index"; }
}
配置错误控制器
最后，我们需要创建一个控制器来处理 /error/ip 请求，并返回错误页面。
package com.icoderoad.IpWhitelist.controller;import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.GetMapping;
@Controller public class ErrorController {
@GetMapping("/error/ip") public String ipError() { // 返回自定义的错误页面 return "error/ip"; } }
代码说明：
-
ErrorController控制器负责处理/error/ip请求，并返回ip.html页面。
创建错误页面
接下来，我们创建一个新的错误页面，提示用户 IP 不在白名单中。
在 src/main/resources/templates/error/ip.html 中创建错误页面：
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>访问受限</title>
<link rel="stylesheet" th:href="@{/webjars/bootstrap/css/bootstrap.min.css}">
<script th:src="@{/webjars/jquery/jquery.min.js}"></script>
<script th:src="@{/webjars/bootstrap/js/bootstrap.bundle.min.js}"></script>
</head>
<body>
<div class="container">
<h1 class="mt-5">访问受限</h1>
<div class="alert alert-danger" role="alert">
您的 IP 地址不在白名单中，无法访问此页面。
</div>
</div>
</body>
</html>
代码说明：
-
页面标题为"访问受限"。
-
页面内容包含一个警告信息，告知用户其 IP 地址不在白名单中，因此无法访问。
3. 注册拦截器
为了使拦截器生效，我们需要将其注册到 Spring Boot 的拦截器链中。创建一个 WebConfig 类来注册拦截器。
package com.icoderoad.IpWhitelist.config;import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import com.icoderoad.IpWhitelist.interceptor.IpWhitelistInterceptor;
@Configuration public class WebConfig implements WebMvcConfigurer {
@Autowired private IpWhitelistInterceptor ipWhitelistInterceptor;
@Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(ipWhitelistInterceptor).addPathPatterns("/**"); } }
代码说明：
addInterceptors方法：将IpWhitelistInterceptor注册到拦截器链中，拦截所有路径的请求。
4. 前端页面展示
我们使用 Thymeleaf、Bootstrap 和 jQuery 创建一个简单的页面，展示请求 IP 的拦截情况。
在 src/main/resources/templates/index.html 中创建一个简单的前端页面：
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>IP 白名单示例</title>
<link rel="stylesheet" th:href="@{/webjars/bootstrap/css/bootstrap.min.css}">
<script th:src="@{/webjars/jquery/jquery.min.js}"></script>
<script th:src="@{/webjars/bootstrap/js/bootstrap.bundle.min.js}"></script>
</head>
<body>
<div class="container">
<h1 class="mt-5">IP 白名单示例</h1>
<div class="alert alert-info" role="alert">
只有在白名单中的 IP 地址才能访问此页面。
</div>
</div>
</body>
</html>
代码说明：
-
使用 Bootstrap 提供了简单的页面样式。
-
使用 Thymeleaf 渲染 HTML 页面。
5. 测试与验证
启动 Spring Boot 应用程序，在浏览器中访问 http://localhost:8080/ 。尝试从不同的 IP 地址访问系统。
-
如果请求 IP 在白名单中，将看到页面正常显示。
-
如果请求 IP 不在白名单中，将返回 403 Forbidden 错误。
结语
通过以上步骤，我们在 Spring Boot 3.3 中实现了一个简单的 IP 白名单拦截功能。这个功能在实际应用中非常实用，可以有效地限制对系统的访问，确保系统的安全性。通过自定义拦截器和配置文件的结合，我们可以灵活地控制允许访问的 IP 地址列表。这种方法不仅实现简单，而且易于扩展和维护。
