本文详解 Spring Boot 中因 server.servlet.context-path 与 @RequestMapping 重复配置引发的路径解析异常，重点解决 Failed to convert from type [String] to [Long] 错误，并提供正确配置方式与最佳实践。

本文详解 spring boot 中因 `server.servlet.context-path` 与 `@requestmapping` 重复配置引发的路径解析异常，重点解决 `failed to convert from type [string] to [long]` 错误，并提供正确配置方式与最佳实践。

在 Spring Boot 应用中，当同时配置了全局上下文路径（server.servlet.context-path）和控制器级请求映射（@RequestMapping），若两者前缀重复，将导致请求路径被错误解析，进而触发类型转换异常——典型表现为：访问 /api/heroes/buscar?name=Pisicola 时抛出 Failed to convert from type [java.lang.String] to type [java.lang.Long] for value [buscar]。

该异常的根本原因在于：

• application.properties 中设置了 server.servlet.context-path=/api；
• HeroController 又声明了 @RequestMapping("/api/heroes")；
• 最终实际匹配路径变为 /api/api/heroes/buscar?name=...；
• Spring MVC 尝试将路径段 buscar（而非预期的 ID 数值）绑定到方法参数（如 long id），从而触发 String → Long 强制转换失败。

? 关键修复步骤：

1. 统一路径层级：移除 @RequestMapping 中已由 context-path 承担的前缀。
   ✅ 正确写法：

   @RestController
   @RequestMapping("/heroes") // 不再包含 "/api"
   public class HeroController { ... }

2. 保持 URL 调用一致性：

   

   Wordpress REST API

   OpenClaw技能，提供WordPress REST API命令行工具，支持通过原生HTTP处理文章、页面、分类、标签、用户及自定义请求。

   下载
   • 启动后实际访问地址应为：
     http://localhost:8080/heroes/buscar?name=Pisicola（因 /api 已自动前置）
   • 若坚持使用 /api/heroes/... 形式，则需注释或删除 server.servlet.context-path=/api。

3. 修正控制器方法签名（补充建议）：
   当前 findHeroByName 使用 @RequestParam，但路径定义为 /buscar/{name}，存在语义矛盾。推荐两种规范方案：

   • ✅ 方案一（查询参数风格，推荐）：

     @GetMapping("/buscar")
     public ResponseEntity<List<Heroe>> findHeroByName(@RequestParam String name) {
         List<Heroe> heroes = heroesRepository.findByName(name);
         return ResponseEntity.ok(heroes); // 更简洁的构建方式
     }

     对应调用：GET /api/heroes/buscar?name=Pisicola

   • ✅ 方案二（路径变量风格）：

     @GetMapping("/buscar/{name}")
     public ResponseEntity<List<Heroe>> findHeroByName(@PathVariable String name) {
         List<Heroe> heroes = heroesRepository.findByName(name);
         return ResponseEntity.ok(heroes);
     }

     对应调用：GET /api/heroes/buscar/Pisicola

⚠️ 注意事项：

• @RequestParam 用于查询参数（URL ?key=value），@PathVariable 用于路径占位符（URL /path/{value}），二者不可混用；
• 检查所有 @GetMapping、@PostMapping 等方法是否隐式依赖了 id 参数（如未标注 @PathVariable 或 @RequestParam），避免 Spring 尝试自动绑定路径片段；
• 使用 ResponseEntity.ok() 替代 new ResponseEntity<>(..., HttpStatus.OK) 提升可读性；
• 开发阶段建议启用 spring.mvc.throw-exception-if-no-handler-found=true 并配合 @ControllerAdvice 统一处理路径不匹配异常，便于快速定位问题。

✅ 总结：Spring Boot 的路径解析是“全局 context-path + 控制器 @RequestMapping + 方法 @GetMapping”三级拼接的结果。务必确保三者无冗余叠加，优先通过 application.properties 配置全局前缀，控制器层仅关注业务路径片段，才能避免此类隐蔽的类型转换陷阱。