Spring应用/mealplanner系列GET接口返回404问题排查求助

基础信息 #

• 项目类型：集成第三方餐食数据API的测试项目，核心能力为拉取每日、每周餐食JSON数据
• 技术栈：Spring RESTController、Java 11、Spring Initializr脚手架生成、Maven构建
• 预期运行效果：本地以localhost启动服务后，访问对应接口可直接输出上游接口返回的JSON数据
• 当前进度：已完成初始问题修复，进入接口联调阶段

故障现象 #

• 本地服务启动后，访问/mealplanner/day、/mealplanner/week两个端点均返回404状态码
• IDE运行控制台无任何错误日志输出
• 浏览器、Postman发起请求返回结果完全一致
• 初步预判：故障与apiKey配置关联度较高，排除控制器核心逻辑错误诱因

针对性排查步骤 #

1. 校验Spring组件扫描范围
   确认启动类所在包路径是否覆盖RESTController所属类的包路径，若控制器类放置在启动类所在包的上层、或未纳入扫描范围，会出现服务正常启动但接口映射未注册、访问返回404且无报错的情况，可在启动类添加@ComponentScan("控制器根包路径")显式指定扫描范围，启动后查看日志里的Mapped关键字打印的接口列表，确认两个目标路径是否完成注册。
2. 核对接口访问路径映射
   检查类级别的@RequestMapping前缀、方法级别的@GetMapping路径拼接后是否和访问路径完全一致，同时检查配置文件中是否配置了server.servlet.context-path上下文路径，若存在额外配置，实际访问路径需要拼接该前缀。
3. 全链路校验apiKey配置
   • 检查配置文件中存储的apiKey是否存在拼写错误、首尾多余空格、特殊字符未转义问题
   • 确认申请的apiKey是否拥有餐食计划相关接口的调用权限，部分封装逻辑会在上游返回无权限错误时直接透传404状态码
   • 编写独立单元测试，携带配置的apiKey直接发起对第三方API的调用，验证上游接口是否可正常返回数据，排除上游接口地址变更、权限不足的问题
4. 排查拦截处理逻辑
   检查项目中是否存在自定义过滤器、拦截器、全局异常处理逻辑，若apiKey校验逻辑放在拦截层，校验失败直接返回404且未打印错误日志，就会出现控制台无报错、访问全量404的现象。

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