SpringBoot 2.x 项目里手动添加webapp目录，解决JSP页面访问404和‘WEB-INF’路径警告
SpringBoot 2.x 项目中手动集成webapp目录的完整实践指南
当我们在现代SpringBoot项目中需要兼容传统JSP页面时，往往会遇到一个尴尬的局面——这个推崇"约定优于配置"的框架竟然默认移除了webapp目录。这背后其实隐藏着Spring团队对模板引擎演进的思考：Thymeleaf等现代模板引擎更适合云原生应用，而JSP这种诞生于J2EE时代的技术正逐渐退出主流舞台。但现实情况是，我们仍然可能面临三种典型场景：
- 老系统渐进式迁移过程中需要新旧技术共存
- 必须使用某些基于JSP的第三方组件
- 团队技术栈存在历史惯性
本文将带你深入理解SpringBoot与JSP的整合机制，不仅解决常见的404问题和路径警告，更会揭示那些官方文档没有明说的配置细节。
1. 理解SpringBoot的目录结构哲学
SpringBoot默认使用src/main/resources/templates作为模板目录，这种设计绝非偶然。与传统的webapp目录相比，这种结构具有三大优势：
- 嵌入性：所有资源被打包进JAR文件，符合微服务架构理念
- 安全性：避免直接暴露WEB-INF等敏感目录
- 一致性：与Thymeleaf、FreeMarker等现代模板引擎完美契合
但当我们确实需要使用JSP时，就需要重建webapp目录结构。这里有个关键认知：SpringBoot支持JSP本质是通过嵌入式Tomcat的Jasper引擎实现的，这与传统War包部署有本质区别。
提示：在IDEA 2021.3之后的版本中，webapp目录需要特殊标记才会被识别为Web资源根目录
2. 正确创建webapp目录结构
在IDEA中创建有效的webapp目录，绝不是简单的新建文件夹那么简单。以下是经过验证的最佳实践：
- 在
src/main下新建webapp目录 - 创建WEB-INF子目录（注意大小写敏感）
- 在WEB-INF下可选择性添加web.xml（SpringBoot其实不需要）
关键步骤是在Project Structure中正确标记：
File -> Project Structure -> Modules -> [你的模块] -> Web添加Web资源目录时，需要特别注意路径映射。推荐使用绝对路径引用：
| 配置项 | 推荐值 | 说明 |
|---|---|---|
| Web Resource Directory | $MODULE_DIR$/src/main/webapp | 必须包含WEB-INF |
| Deployment Descriptor | $MODULE_DIR$/src/main/webapp/WEB-INF/web.xml | 可选 |
完成配置后，检查目录图标是否显示蓝色圆点标记——这是IDEA识别为有效Web资源的视觉提示。
3. 必不可少的依赖配置
仅仅创建目录是不够的，还需要正确引入JSP引擎支持。在pom.xml中添加以下关键依赖：
<!-- 必须的JSP解析引擎 --> <dependency> <groupId>org.apache.tomcat.embed</groupId> <artifactId>tomcat-embed-jasper</artifactId> <scope>provided</scope> </dependency> <!-- JSTL标签库支持 --> <dependency> <groupId>javax.servlet</groupId> <artifactId>jstl</artifactId> </dependency>特别注意scope的配置策略：
- 开发时使用
provided可以避免嵌入式Tomcat冲突 - 如果最终部署到外部容器，需要移除scope或改为
compile
4. 视图解析器的精妙配置
SpringMVC的视图解析机制是JSP能否正常渲染的关键。在application.properties中，有两种主流配置方式：
# 方式一：直接映射到webapp根目录 spring.mvc.view.prefix=/ spring.mvc.view.suffix=.jsp # 方式二：通过WEB-INF增加安全性 spring.mvc.view.prefix=/WEB-INF/ spring.mvc.view.suffix=.jsp这两种方式对应的目录结构差异很大：
根目录映射：
- 优点：直接访问，便于调试
- 缺点：安全性低
- 适合位置：webapp/*.jsp
WEB-INF映射：
- 优点：符合J2EE安全规范
- 缺点：需要Controller中转
- 适合位置：webapp/WEB-INF/*.jsp
实际项目中，我强烈推荐WEB-INF方式，虽然多了一层目录，但能避免直接URL访问风险。
5. 解决恼人的路径警告
当看到日志中出现Path with "WEB-INF" or "META-INF"警告时，不要惊慌。这个警告其实源于SpringBoot的资源处理机制：
2023-03-15 11:22:35.233 WARN 12892 — [nio-8080-exec-4] o.s.w.s.r.ResourceHttpRequestHandler : Path with "WEB-INF" or "META-INF": [WEB-INF/showUserJSP.jsp]这个警告的本质是：SpringBoot的资源处理器默认会阻止对WEB-INF和META-INF的直接访问。解决方案有三：
确保使用Controller转发：这是最规范的解法
@GetMapping("/userList") public String showUsers(Model model) { model.addAttribute("users", userService.findAll()); return "userList"; // 对应/WEB-INF/userList.jsp }调整资源处理策略（不推荐）：
@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/WEB-INF/**") .addResourceLocations("/WEB-INF/"); } }添加特定依赖（最简单）： 确保tomcat-embed-jasper的版本与SpringBoot内置Tomcat版本一致
6. 完整的数据传递示例
让我们通过一个电商场景，演示Controller到JSP的完整数据流：
@Controller @RequestMapping("/products") public class ProductController { @GetMapping public String listProducts( @RequestParam(defaultValue = "1") int page, Model model) { Page<Product> productPage = productService.findPaginated(page, 5); model.addAttribute("products", productPage.getContent()); model.addAttribute("currentPage", page); model.addAttribute("totalPages", productPage.getTotalPages()); return "product/list"; // 映射到/WEB-INF/product/list.jsp } }对应的JSP页面（/WEB-INF/product/list.jsp）:
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %> <div class="product-grid"> <c:forEach items="${products}" var="product"> <div class="product-card"> <h3>${product.name}</h3> <p>价格: ¥${product.price}</p> </div> </c:forEach> <div class="pagination"> <c:forEach begin="1" end="${totalPages}" var="i"> <a href="?page=${i}" class="${i == currentPage ? 'active' : ''}">${i}</a> </c:forEach> </div> </div>7. 进阶配置与疑难排错
当基础配置完成后，可能会遇到一些边界情况：
场景一：热部署不生效
在application.properties中添加：
spring.devtools.restart.additional-paths=src/main/webapp场景二：静态资源冲突
建议的目录结构：
src/ ├── main/ │ ├── java/ │ ├── resources/ │ │ ├── static/ # 静态资源 │ │ └── templates/ │ └── webapp/ # JSP资源 │ └── WEB-INF/场景三：多模块项目配置
对于Maven多模块项目，需要在web模块的pom.xml中添加：
<build> <resources> <resource> <directory>src/main/webapp</directory> <targetPath>META-INF/resources</targetPath> </resource> </resources> </build>在项目实践中，我发现最常出现的三个陷阱是：
- 忘记刷新Maven依赖（特别是修改scope后）
- 视图前缀漏掉结尾斜杠（
/WEB-INF≠/WEB-INF/） - JSP文件编码不是UTF-8导致中文乱码
对于编码问题，一个可靠的解决方案是在JSP顶部添加：
<%@ page contentType="text/html;charset=UTF-8" pageEncoding="UTF-8" %>同时确保IDEA的文件编码设置：
File -> Settings -> Editor -> File Encodings所有选项都设置为UTF-8