Spring Boot 中请求路径冲突导致的类型转换异常解决方案-java教程-PHP中文网

本文详解 Spring Boot 应用中因 server.servlet.context-path 与 @RequestMapping 重复配置引发的路径解析错误，重点说明如何修复 Failed to convert from type [String] to [Long] 这类典型 400 错误。

本文详解 spring boot 应用中因 `server.servlet.context-path` 与 `@requestmapping` 重复配置引发的路径解析错误，重点说明如何修复 `failed to convert from type [string] to [long]` 这类典型 400 错误。

在 Spring Boot 开发中，当控制器方法声明为 @GetMapping("/buscar/{name}")，而实际请求 URL 却使用查询参数形式（如 ?name=Pisicola）时，若路径匹配机制被意外干扰，极易触发底层 HandlerMapping 的误判——将路径片段（如 buscar）错误解析为 @PathVariable Long id 类型参数，从而抛出 For input string: "buscar" 的 NumberFormatException。

根本原因在于 双重上下文路径叠加：
你在 application.properties 中设置了全局上下文路径：

server.servlet.context-path=/api

同时又在控制器上重复声明：

@RestController
@RequestMapping("/api/heroes") // ❌ 冗余前缀！

这导致完整访问路径变为 /api/api/heroes/...，而 Spring 在尝试匹配 @GetMapping("/buscar/{name}") 时，因路径不匹配，fallback 到默认的 REST repository 路由或隐式 ID 解析逻辑，最终将 buscar 当作 id 参数强制转为 Long，引发崩溃。

✅ 正确做法是 只保留一处上下文定义：

LongShot

一款面向长篇内容创作和SEO写作的AI写作工具，可辅助进行文章生成、内容优化和搜索引擎友好的文本制作。

下载

保持 application.properties 中的 server.servlet.context-path=/api；

将控制器 @RequestMapping 改为相对路径：

@RestController
@RequestMapping("/heroes") // ✅ 去掉 "/api"，仅保留业务路径
public class HeroController {
  // ...
}

此时，你的搜索接口真实路径为：
GET http://localhost:8080/api/heroes/buscar?name=Pisicola
⚠️ 注意：这是 @RequestParam 模式，应使用 ?name=xxx，而非 /{name} 路径变量。因此还需同步修正方法签名：

@GetMapping("/buscar") // ✅ 使用查询参数，非路径变量
public ResponseEntity<list>> findHeroByName(@RequestParam String name) {
    List<heroe> heroes = heroesRepository.findByName(name);
    return ResponseEntity.ok(heroes); // 推荐使用静态工厂方法提升可读性
}</heroe></list>

? 验证技巧：启动应用后访问 http://localhost:8080/actuator/mappings（需启用 Actuator），查看实际注册的端点，确认 /api/heroes/buscar 是否正确映射。

此外，请检查 HeroesRepository 是否被 @RepositoryRestResource 意外暴露为 Spring Data REST 端点（它会自动注册 /api/heroes/search/findByName?name=xxx）。若无需 REST 自动导出，建议移除该注解，避免与自定义控制器冲突。

总结：

✅ server.servlet.context-path 是全局前缀，所有 @RequestMapping 应基于此“之后”书写；
✅ @RequestParam 对应 ?key=value，@PathVariable 对应 /value，二者不可混用；
✅ 使用 ResponseEntity.ok() / badRequest() 等静态方法替代 new ResponseEntity(..., HttpStatus.xxx)，代码更简洁安全；
✅ 启用 Actuator 并检查 /mappings，是诊断路径问题最直接的手段。