Rest控制器返回HTML而非JSON的问题排查求助

核心原因 #

你的控制器返回HTML而非JSON，本质是Spring Boot默认的静态资源首页映射优先级高于你定义的@GetMapping("/")接口。

Spring Boot的自动配置（WebMvcAutoConfiguration）会注册WelcomePageHandlerMapping，当请求根路径/时：

• 如果项目的classpath:/static/目录下存在index.html，这个静态页面会被优先返回，完全跳过你的Rest控制器映射。
• 这就是为什么你明明返回的是List<GradebookCollegeStudent>，却得到了index.html的原因。

你之前添加produces属性、测试中设置MockHttpServletResponse的ContentType都无效，因为请求根本没到达你的控制器，而是被静态资源处理器直接拦截响应了。

可行解决方案 #

方案1：修改控制器请求路径（最推荐） #

直接给你的Rest接口换一个非根路径，避免和静态首页的默认映射冲突：

@Autowired
private Gradebook gradebook;        

@GetMapping(value = "/api/students", produces = {MediaType.APPLICATION_JSON_VALUE})
public List<GradebookCollegeStudent> getStudents() {
    gradebook = studentService.getGradebook2();
    return gradebook.getStudents();
}

对应的测试代码也要同步修改请求路径：

mock.perform(MockMvcRequestBuilders.get("/api/students"))
    .andExpect(status().isOk())
    .andExpect(content().contentType(APPLICATION_JSON_UTF8))
    .andExpect(jsonPath("$", hasSize(2)));

方案2：禁用默认首页映射（如果必须使用根路径） #

如果业务要求必须用/作为接口路径，可以通过配置覆盖默认的首页映射逻辑：

1. 创建自定义的WebMvcConfigurer配置类：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        // 清空默认的首页映射
        registry.clear();
    }
}

2. 或者在application.properties中添加配置：

spring.mvc.welcome-page.enabled=false

这样请求/时就会路由到你的控制器，而不是静态首页。

方案3：检查其他拦截/路由规则 #

如果以上方案无效，排查是否存在以下情况：

• 自定义的HandlerInterceptor或Filter拦截了请求，强制跳转或返回静态页面
• Spring Security等安全框架的配置，对根路径做了特殊处理
• 其他控制器中存在优先级更高的@GetMapping("/")映射

内容的提问来源于stack exchange，提问作者Jcoder