本文详解 Spring Boot 应用中 REST API 无法通过 localhost 访问（如 ECONNREFUSED 错误）的典型成因，重点分析控制器配置、启动类注解、端口绑定及请求映射写法问题，并提供可立即验证的修复方案。
本文详解 spring boot 应用中 rest api 无法通过 localhost 访问（如 `econnrefused` 错误）的典型成因，重点分析控制器配置、启动类注解、端口绑定及请求映射写法问题，并提供可立即验证的修复方案。
在 Spring Boot 开发中，出现 Error: connect ECONNREFUSED 127.0.0.1:6069 这类错误，表面看是网络连接被拒绝，但根本原因几乎总是应用未成功启动 HTTP 服务——即内嵌 Tomcat（或其他 Web 容器）根本未监听指定端口。结合您提供的代码，问题并非出在依赖缺失或端口配置，而在于一个关键且易被忽视的细节：控制器类命名与 Spring Boot 的组件扫描/启动逻辑冲突。
? 核心问题定位
您的控制器类名为 MyApplication：
@RestController
public class MyApplication { // ❌ 危险命名！
@RequestMapping(method = {RequestMethod.GET}, value = "/myApi", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String> myApiHandler() {
return new ResponseEntity<>("Successfully called API", HttpStatus.OK);
}
}而主启动类也叫 MyApplication：
@SpringBootApplication(exclude = { ErrorMvcAutoConfiguration.class })
public class MyApplication { // ✅ 启动类应唯一
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}这会导致 Spring 在组件扫描时将控制器类误识别为主配置类，进而跳过其作为 @RestController 的注册流程——结果就是：应用看似启动成功，但实际未注册任何 HTTP 端点，内嵌服务器自然不会响应 /myApi 请求。
此外，@RequestMapping 写法虽语法合法，但在 Spring Boot 2.x 及 1.5.8 中已不推荐；更简洁、语义明确的 @GetMapping 能避免 produces 类型推导异常（尤其当 Content-Type 头未正确协商时）。
✅ 正确实践：三步修复
1. 重命名控制器类（强制要求）
将控制器类名改为语义清晰且与启动类区分的名称，例如 MyApiController：
@RestController
@RequestMapping("/api") // 可选：添加统一路径前缀
public class MyApiController { // ✅ 命名清晰，无歧义
@GetMapping("/myApi") // ✅ 推荐写法：简洁、类型安全、自动设置 produces=application/json
public ResponseEntity<String> myApiHandler() {
return ResponseEntity.ok("Successfully called API");
}
}? 提示：ResponseEntity.ok(...) 是 new ResponseEntity<>(..., HttpStatus.OK) 的语义化简写，更符合 Spring 风格。
2. 确保启动类正确引导
主类保持 @SpringBootApplication 注解，并确认 main 方法存在：
@SpringBootApplication(exclude = {ErrorMvcAutoConfiguration.class})
@ComponentScan(basePackages = "com.example") // 显式声明包路径，增强可读性
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}⚠️ 注意：@ComponentScan({"com.example"}) 已包含在 @SpringBootApplication 中，显式声明非必需，但可避免因包结构变更导致扫描遗漏。
3. 验证应用是否真正启动成功
启动应用后，务必检查控制台日志，确认出现以下关键行：
Tomcat started on port(s): 6069 (http) Started MyApplication in X.XXX seconds
若未见 Tomcat started...，说明 Web 层未激活——此时即使 spring-boot-starter-web 已引入，也可能因 @SpringBootApplication 注解失效（如类名冲突）而退化为普通 Java 应用。
? 验证步骤（Postman / curl）
启动成功后，使用以下 URL 测试：
GET http://localhost:6069/api/myApi
✅ 正确响应：HTTP 200 + JSON 字符串 "Successfully called API"
❌ 若仍失败，请检查：
- application.properties 中 server.port=6069 是否拼写正确（无空格、无注释符号干扰）；
- 是否有防火墙/代理拦截本地端口；
- IntelliJ 中 Run Configuration 的 Working directory 和 Use classpath of module 是否指向正确模块。
? 总结
| 问题环节 | 错误表现 | 解决方案 |
|---|---|---|
| 类名冲突 | ECONNREFUSED，日志无 Tomcat 启动信息 | 严格区分启动类与控制器类名（如 MyApplication vs MyApiController） |
| 请求映射冗余 | @RequestMapping 易漏配 produces 或 consumes | 优先使用 @GetMapping/@PostMapping 等组合注解 |
| 启动验证缺失 | 误以为“控制台无报错=启动成功” | 必查 Tomcat started on port(s) 日志行 |
遵循以上规范，99% 的“API 访问失败”问题可立即解决。记住：Spring Boot 的约定优于配置，命名规范即是配置的一部分。
