Spring Boot 404错误排查指南

Spring MVC 请求映射基础

在Spring Boot应用中，我们通常使用@Controller注解标记控制器类，并通过@GetMapping、@PostMapping等注解来定义HTTP请求与处理方法之间的映射关系。这些注解使得开发者能够清晰地将特定的URL路径绑定到对应的业务逻辑。

例如，以下PostController定义了处理/posts/new路径的GET和POST请求的方法：

@Controller
public class PostController {

    @Autowired
    private PostService postService;

    // ... 其他方法 ...

    @GetMapping("/posts/new")
    public String createNewPost(Model model){
        // 调用服务层逻辑准备数据并返回视图名称
        return postService.createNewPost(model);
    }

    @PostMapping("/posts/new")
    public String saveNewPost(@ModelAttribute Post post){
        // 处理表单提交，保存数据并重定向
        postService.save(post);
        return "redirect:/posts/" + post.getId();
    }
}

从上述代码看，/posts/new路径的GET和POST请求都已明确映射到createNewPost和saveNewPost方法。然而，即使映射看起来完全正确，客户端仍可能收到404错误。这通常不是因为Spring无法找到控制器方法，而是因为控制器方法内部的逻辑导致了404的返回。

业务逻辑层导致的404：深入分析

当Spring MVC成功将请求路由到控制器方法后，该方法的执行结果将决定最终的响应。如果控制器方法返回一个视图名称，Spring会尝试解析并渲染该视图。但如果业务逻辑判断某种条件不满足，例如所需数据不存在，它可能会显式地返回一个表示“未找到”的视图名称，从而导致应用层面的404。

在上述博客应用场景中，@GetMapping("/posts/new")方法调用了postService.createNewPost(model)。让我们深入查看PostService中的实现：

@Service
public class PostService {

    @Autowired
    private AccountService accountService;;

    // ... 其他方法 ...

    public String createNewPost(Model model){
        // 尝试通过硬编码的邮箱查找账户
        Optional optionalAccount = accountService.findByEmail("[email protected]");

        if(optionalAccount.isPresent()){
            // 如果找到账户，则创建新帖子对象并添加到模型
            Post post = new Post();
            post.setAccount(optionalAccount.get());
            model.addAttribute("post", post);
            // 返回“post_new”视图
            return "post_new";
        }else{
            // 如果未找到账户，则直接返回“404”字符串
            return "404";
        }
    }
}

问题根源分析：

从createNewPost方法中可以看出，它尝试通过一个硬编码的邮箱地址[email protected]去查找一个Account。如果accountService.findByEmail()方法返回的Optional为空（即没有找到对应的账户），那么该方法会直接返回字符串"404"。

当Spring MVC接收到"404"这个字符串作为视图名称时，它会尝试去寻找名为404.html（或其他配置的视图文件）的模板并渲染。如果该模板不存在，或者即便存在，但用户期望的是一个功能页面而非错误页面，这都会导致用户体验上的问题，并且在某些情况下可能被误认为是URL映射错误。

解决方案：

1. 确保数据存在： 检查accountService.findByEmail方法所查找的账户是否存在于数据库中。在开发和测试阶段，确保有相应的测试数据。
2. 合理处理业务异常： 在实际应用中，不建议直接返回"404"作为视图名称来处理业务逻辑上的“未找到”情况。更专业的做法是：
   • 抛出自定义业务异常（例如ResourceNotFoundException）。
   • 使用@ControllerAdvice和@ExceptionHandler来统一处理这些异常，并返回一个友好的错误页面或HTTP状态码（例如HttpStatus.NOT_FOUND）。
   • 或者，如果只是需要重定向到另一个页面，可以使用return "redirect:/some/other/path"。
3. 日志与调试： 在PostService的createNewPost方法中添加日志输出，或设置断点，以确认optionalAccount.isPresent()的实际结果。这有助于快速定位是数据问题还是其他逻辑问题。

Thymeleaf URL表达式的最佳实践

在Thymeleaf模板中，th:action属性用于定义表单提交的目标URL。Spring EL表达式@{...}用于生成URL。

原始的post_new.html中使用了：

这里的th:action="@{'/posts/new'}"是有效的。Thymeleaf的URL表达式处理器可以正确解析带引号的路径。然而，对于简单的、不包含特殊字符的路径，通常推荐使用不带引号的形式，这样更简洁明了：

虽然这并不是导致404错误的原因（因为GET请求的URL访问已经出问题，与表单提交的th:action无关），但这是一个良好的编码习惯，值得在教程中提及。

Spring Boot 404错误排查清单

当遇到Spring Boot应用中的404错误时，可以遵循以下系统化的排查步骤：

1. 检查控制器路径映射：

   • 仔细核对@RequestMapping, @GetMapping, @PostMapping等注解中的URL路径是否与请求的URL完全匹配（包括大小写）。
   • 注意路径变量（{id}）和请求参数（?param=value）的使用。
   • 如果使用了@RequestMapping在类级别，确保方法级别的路径是相对路径或完整路径。

2. 验证视图解析器配置：

   • 如果控制器方法返回一个字符串（例如"post_new"），Spring会尝试通过视图解析器找到对应的模板文件。
   • 确保src/main/resources/templates目录下存在post_new.html文件（对于Thymeleaf）。
   • 检查application.properties或application.yml中是否有spring.thymeleaf.prefix和spring.thymeleaf.suffix等相关配置是否正确。

3. 审查服务层业务逻辑：

   • 如本文案例所示，控制器方法可能调用服务层方法，而服务层方法可能基于业务条件返回一个错误视图或导致异常。
   • 使用日志和调试工具跟踪控制器方法内部的执行流程，特别是对外部服务或数据库的调用结果。
   • 确认所有Optional类型的数据是否按预期isPresent()。

4. 确认组件扫描与依赖注入：

   • 确保@Controller, @Service, @Repository等注解的类位于Spring Boot应用主类（带有@SpringBootApplication）的包或其子包中，以便被正确扫描。
   • 检查所有@Autowired的依赖是否成功注入，避免NullPointerException。

5. 检查部署环境与上下文路径：

   • 如果应用部署在Servlet容器（如Tomcat）的特定上下文路径下（例如http://localhost:8080/myapp/posts/new），确保请求URL包含了正确的上下文路径。
   • 在application.properties中，server.servlet.context-path属性可以配置应用的上下文路径。

6. 查看控制台日志：

   • Spring Boot会在启动时打印出所有注册的请求映射。仔细检查这些日志，确认你的/posts/new映射是否真的被Spring识别。
   • 运行时，任何异常或错误信息都会在控制台输出，这通常是定位问题的关键线索。

总结

Spring Boot中的404错误并非总是由于URL映射配置不当。它可能源于控制器方法内部的业务逻辑，特别是当应用层根据某些条件显式地返回错误视图时。通过系统化地排查控制器映射、视图解析、服务层逻辑以及部署环境等多个层面，结合日志分析和调试工具，开发者可以高效地定位并解决这些看似棘手的404问题。同时，遵循Thymeleaf URL表达式的最佳实践，有助于代码的清晰性和可维护性。