本文详解 spring boot 项目中因 server.servlet.context-path 与 @requestmapping 重复配置引发的路径解析错误，重点解决 failed to convert from type [string] to [long] 这类典型 400 异常，并提供规范的 rest 接口设计实践。
本文详解 spring boot 项目中因 server.servlet.context-path 与 @requestmapping 重复配置引发的路径解析错误，重点解决 failed to convert from type [string] to [long] 这类典型 400 异常，并提供规范的 rest 接口设计实践。
在 Spring Boot 应用中，当控制器方法抛出类似 Failed to convert from type [java.lang.String] to type [java.lang.Long] for value ["buscar"] 的异常时，根本原因并非参数绑定逻辑错误，而是请求路径被错误解析为 ID 参数——Spring 尝试将路径片段 "buscar" 强制转换为 Long 类型，说明框架误认为该路径段应匹配 @PathVariable Long id 形式的参数（例如 @GetMapping("/{id}")），而实际代码中并未定义此类映射。
问题根源在于 server.servlet.context-path 与 @RequestMapping 的双重前缀叠加。您在 application.properties 中配置了：
server.servlet.context-path=/api
同时又在控制器上声明：
@RestController
@RequestMapping("/api/heroes") // ❌ 错误：/api 已由 context-path 提供，此处重复
public class HeroController { ... }这导致完整路径变为 /api/api/heroes/...，而 Spring 在路由匹配失败后，会尝试回退解析——将 /api/heroes/buscar?name=Pisicola 中的 buscar 视为 @PathVariable 的 id 值，从而触发 String → Long 的强制转换，最终失败。
✅ 正确做法是：仅保留一处上下文路径定义。推荐移除控制器中的冗余前缀，改为：
@RestController
@RequestMapping("/heroes") // ✅ 仅保留业务路径，/api 由 context-path 统一管理
public class HeroController {
@Autowired
private HeroesRepository heroesRepository;
// POST /api/heroes → 实际访问: http://localhost:8080/api/heroes
@PostMapping
public ResponseEntity<Heroe> createHeroe(@RequestBody Heroe heroe) {
Heroe savedHeroe = heroesRepository.save(heroe);
return new ResponseEntity<>(savedHeroe, HttpStatus.CREATED);
}
// GET /api/heroes/buscar?name=Pisicola → 注意：使用 @RequestParam，非路径变量
@GetMapping("/buscar")
public ResponseEntity<List<Heroe>> findHeroByName(@RequestParam String name) {
List<Heroe> heroes = heroesRepository.findByName(name);
return ResponseEntity.ok(heroes); // 推荐使用静态工厂方法提升可读性
}
// 其他方法同理，确保路径语义清晰
}⚠️ 关键注意事项：
- @GetMapping("/buscar/{name}") 与 @RequestParam String name 冲突：路径变量 {name} 应配合 @PathVariable 使用；若需查询参数，必须用 @RequestParam 并改用 @GetMapping("/buscar")；
- HeroesRepository.findByName() 默认执行模糊匹配（%name%），如需精确匹配，建议在方法名中明确标注：findByNombreEquals(String nombre) 或添加 @Query 自定义 SQL；
- 所有未标注 @RequestMapping 的方法（如 getHeroeById）不会被自动注册为 HTTP 端点——当前代码中该方法缺少 @GetMapping("/{id}") 注解，属于无效方法，需补全；
- 生产环境建议统一使用 ResponseEntity.ok()、ResponseEntity.notFound() 等静态工厂方法替代 new ResponseEntity<>(...)，提升代码简洁性与可维护性。
通过合理分离全局上下文路径与业务路径层级，可彻底规避此类隐式转换异常，确保 REST API 设计符合 Spring MVC 路由机制的最佳实践。
