SpringBoot接口调不通排查终极方案

本地正常、上线就 Connection refused,日志却同样写着 Started------「启动成功但接口调不通」最磨人的地方,是日志先骗了你。这篇给一套从外到内的 7 步排查顺序,每步看哪行日志、跑哪条命令都列清楚,看完能直接照着定位。

上周帮同事看的就是这个:重启、改端口、怀疑打包漏了 Controller,折腾一上午。最后 ss -lntp 里一行说明白------应用在服务器上只监听 127.0.0.1:8080,压根没对外开。

这类问题不止绑定地址一种。404、405、401、超时、服务间调用失败,各有各的查法。文末有流程图、速查卡和上线前清单,存下来下次直接过一遍。

先把 7 步摆出来。 这一段可以单独存,图看不清的时候照着走:

  1. 确认应用是否真正启动 ------ 认 Started XxxApplication 和 Tomcat started on port(s)

  2. 确认监听的 IP 和端口 ------ ss -lntp / netstat -ano,看是不是 0.0.0.0

  3. 确认 URL 和请求方式 ------ context-path、HTTP 方法、尾斜杠

  4. 确认 Controller 与路径映射 ------ 问 /actuator/mappings

  5. 检查拦截器与 Spring Security ------ permitAll()、CSRF、Token

  6. 检查防火墙、Docker、反向代理 ------ 本机 → 内网 → 公网三层 curl

  7. 检查服务发现与调用链路 ------ 注册中心实例列表 + 直连实例做二分


第 1 步 · 先别急着改代码,确认「启动成功」是真的

现象 :日志里能看到 Tomcat initialized with port(s): 8080 (http),甚至能看到端口打印,但请求全挂。

原因:初始化不等于启动完成。容器线程起来了,Bean 还在初始化,中途抛异常没打全日志;或者旧进程还占着 8080,你看到的日志是另一个实例的;K8s 里更常见------进程在跑,readinessProbe 没过,流量压根没切过来。

检查方法:只认两行日志,缺一不可。

bash 复制代码
tail -n 100 app.log | grep -E "Started|Tomcat started|APPLICATION FAILED|Caused by"
# Windows PowerShell
Select-String -Path app.log -Pattern "Started|Tomcat started|APPLICATION FAILED|Caused by" | Select-Object -Last 30

jps -l
ps -ef | grep java
docker logs --tail 100 order-service

要看到 Tomcat started on port(s): 8080 (http) with context path '/api' 和最后的 Started OrderApplication in x seconds。另外往上翻 100 行,别漏掉 APPLICATION FAILED TO START 下面的 Caused by------很多人只看最后 10 行,正好把根因翻过去。

解决与验证:进程在、两行日志都在、本地 health 能通,才算第一层过。

bash 复制代码
curl -i http://127.0.0.1:8080/api/actuator/health

返回 {"status":"UP"} 再往下走。这一步不通,后面六步都是白跑。


第 2 步|Connection refused

现象 :curl: (7) Failed to connect to 127.0.0.1 port 8080: Connection refused,或者 Feign 抛 java.net.ConnectException。请求根本没进 Tomcat。

原因 :目标端口没有进程监听。四种可能------应用没真起来;端口被 --server.port、环境变量或配置中心覆盖了;测试代码里写了 server.port=0 用随机端口;应用只绑了 127.0.0.1 或 IPv6 的 ::1。

检查与验证:

bash 复制代码
# Linux / macOS:重点看 Local Address 是 0.0.0.0、127.0.0.1 还是 :::
ss -lntp | grep 8080
lsof -i :8080

# Windows
netstat -ano | findstr :8080
tasklist | findstr java

顺手确认最终生效的配置:spring.profiles.active 是不是你以为的那份,命令行有没有带 --server.port。我见过最隐蔽的一次,是 CI 启动脚本里写死了 --server.port=8081,开发对着 application-dev.yml 里的 8080 查了一下午。

第 3 步|405 Method Not Allowed

现象 :Request method 'POST' not supported,响应头带 Allow: GET,HEAD。

原因 :路径对,方法不对。前端发 POST、后端写 @GetMapping;网关或中间层改写了方法;CORS 预检的 OPTIONS 被当成业务请求拦了。

检查与验证 :Allow 头就是答案,它直接列出这个路径接受哪些方法。

bash 复制代码
curl -i -X POST http://127.0.0.1:8080/api/order/list
curl -i -X OPTIONS \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: POST" \
  http://127.0.0.1:8080/api/order/list

浏览器 DevTools 里「Copy as cURL」把前端真实请求复制出来跑一遍,比对着代码猜快得多。这一步顺带把 context-path、Content-Type、参数位置一起核对掉,能挡掉后面一大半的 404。

第 4 步|404 Not Found

现象 :连得上,返回 Whitelabel 错误页,或者 {"status":404,"error":"Not Found","path":"/order/list"}。

原因:路径没有对应的 Handler 映射。按出现频率排:

  • 漏了 context-path ------ 配了 /api 却请求 /order/list。严格说这是上一步该拦住的,但因为它表现为 404,放这里一起讲。

  • Controller 没被扫到 ------ @SpringBootApplication 默认只扫启动类同包及子包,启动类挪到别的包、Controller 留在原包,就直接不注册。

  • 注解写错 ------ 用了 @Controller 没加 @ResponseBody,返回的是视图名不是 JSON。

  • Spring Boot 3 的尾斜杠 ------ Spring Framework 6 起 useTrailingSlashMatch 默认关掉,/order/list/ 不再自动命中 /order/list。从 Boot 2 升级上来最容易中招。

  • 网关削前缀 ------ Gateway 的 StripPrefix 或 Nginx rewrite 把路径改了,到后端时已经不是原来那个 URL。

检查与验证:直接问应用「你到底注册了哪些映射」。

bash 复制代码
curl -s http://127.0.0.1:8080/api/actuator/mappings | grep order
# Windows:把 grep 换成 findstr

查不到,就回启动日志看 Mapped "{[/order/list]}" onto ... 有没有打印,再查扫描包和注解。开头那份配置里已经把 RequestMappingHandlerMapping 调到 TRACE,会打出完整注册明细。

这里有个坑:/actuator/mappings 自己也可能返回 404。Actuator 默认 Web 只暴露 health 和 info,不配 management.endpoints.web.exposure.include,排查工具本身就先把你带偏一次。


第 5 步 · 401 / 403 与请求超时:两类「软故障」

5.1 401 和 403

现象:401 Unauthorized、403 Forbidden,或者被重定向到登录页------前端框架拿到一段 HTML 当 JSON 解析,看起来像接口挂了。

原因 :最常见的是引入了 spring-boot-starter-security 却没自定义 SecurityFilterChain。默认规则是所有请求都要 HTTP Basic,用户名 user,密码在启动日志里随机生成。

bash 复制代码
grep "Using generated security password" app.log

其它几类:permitAll() 没覆盖该路径;Security 默认对 POST / PUT / DELETE 开启 CSRF,没带 token 直接 403;JWT 过期、Header 名写错、漏了 Bearer 前缀;@PreAuthorize 方法级权限。还有一种容易误判的------401 是网关鉴权返回的,根本不是业务服务的响应,先看响应体和服务标识再动手。

检查与验证 (开头配置里已开 org.springframework.security: DEBUG):

bash 复制代码
# 返回 401 且带 WWW-Authenticate: Basic,基本坐实是 Security 默认配置
curl -i http://127.0.0.1:8080/api/order/list
# 显式带 token 对比
curl -i -H "Authorization: Bearer TOKEN" http://127.0.0.1:8080/api/order/list

DEBUG 下 FilterChainProxy 会逐个打印经过的 Filter,卡在哪一层一目了然。本地或测试环境可以临时 permitAll() 做二分定位,测完记得还原。

要自己接管规则,最小配置长这样(Spring Boot 3 / Spring Security 6 用 requestMatchers;Security 5.x 是 antMatchers):

bash 复制代码
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health", "/order/list").permitAll()
                .anyRequest().authenticated())
            .csrf(csrf -> csrf.disable());   // 仅为定位问题,生产按实际评估
        return http.build();
    }
}

注意 requestMatchers 里写的是去掉 context-path 之后 的路径,所以是 /order/list 而不是 /api/order/list。csrf.disable() 只是排查期的临时手段,别原样抄进生产。

5.2 请求超时(不是独立一步,是沿各层继续定位)

现象 :java.net.SocketTimeoutException: Read timed out、Feign 的 Read timed out executing GET ...、网关 504、前端一直转圈。

原因 :接口本身慢(慢 SQL、外部 HTTP 调用没设超时、大对象序列化);Tomcat 工作线程打满(默认 max 200)或 HikariCP / HTTP 连接池耗尽;下游级联拖慢;网关和 Feign 的超时设得比业务耗时短;只配了 connectTimeout 忘了 readTimeout;卡在分布式锁或数据库行锁上。

检查与验证:先把「慢」量化,再决定往哪查。

bash 复制代码
# 业务接口耗时
curl -w "connect=%{time_connect} total=%{time_total}\n" -o /dev/null -s \
  http://127.0.0.1:8080/api/order/list
# 对照:一个几乎不干活的健康检查
curl -w "total=%{time_total}\n" -o /dev/null -s \
  http://127.0.0.1:8080/api/actuator/health

jcmd PID Thread.print > thread.txt

健康检查也慢,问题在全局(线程池、连接池、GC);只有业务接口慢,去看 SQL 和外部调用。线程 dump 里如果一大片线程停在 JDBC、socketRead 或锁等待,方向就定了。

Feign 的超时配置项换过路径,下面两块按你的 Spring Cloud 版本二选一,不要同时复制:

bash 复制代码
# 选 A:Spring Cloud 2022.x / OpenFeign 4.x
spring:
  cloud:
    openfeign:
      client:
        config:
          default:
            connectTimeout: 3000
            readTimeout: 10000
bash 复制代码
# 选 B:早期 Hoxton / OpenFeign 2.x
feign:
  client:
    config:
      default:
        connectTimeout: 3000
        readTimeout: 10000

照着旧博客抄错路径,配置会静默不生效,接口照样超时。


第 6 步 · 本地能调、服务器调不了:网络层的几个断点

这个我自己踩过。Windows 上跑了个本地服务,想用 cloudflared 隧道暴露出去,隧道配置指向 127.0.0.1:8080,结果怎么都连不上。查到最后是 8080 只绑了 IPv6 的 ::1,没绑 127.0.0.1------应用活着,隧道也活着,两边就是没对上。

现象 :开发机 localhost:8080 正常,换成服务器 IP 就连接失败或超时;或者服务器本机 curl 通,办公网不通。

原因 :绑定地址只对内;Linux firewalld / iptables 或云厂商安全组没放通;Docker 没做 -p 8080:8080,或者容器内应用绑到了容器自己的 127.0.0.1;反向代理 proxy_pass 指错(容器里写 localhost 指向的是代理容器自己,不是宿主机);公司网络只放行 80/443。

★

方法卡 · 三层 curl 服务器本机 → 同网段内网 IP → 公网 IP,依次打一遍,哪一层开始断,问题就在那一层 。 第一层通、第二层断 → 查 server.address 和防火墙;前两层通、第三层断 → 查安全组、DNS 和反向代理。 一句话能讲清,不用装任何工具,也最适合直接丢到技术群里。

bash 复制代码
# 第一层:应用本身
curl -i http://127.0.0.1:8080/api/actuator/health

# 第二层:绑定地址 / 防火墙
curl -i --connect-timeout 3 http://INNER_IP:8080/api/actuator/health
nc -zv INNER_IP 8080
firewall-cmd --list-all
iptables -L -n

# 第三层:链路与代理
docker ps                                   # 看 PORTS 列有没有 0.0.0.0:8080->8080/tcp
docker inspect order-service
nginx -t && nginx -T | grep proxy_pass

第 7 步 · 微服务场景:注册中心看得到,调用链路却断了

现象 :A 调 B 报 java.net.UnknownHostException: order-service、No instances available for ORDER-SERVICE 或 Load balancer does not contain an instance for the service。可 B 的日志好好的,直接 curl B 也返回数据。

原因 :服务名对不上(spring.application.name 与 @FeignClient(name = ...)、网关 lb:// 在大小写或中划线上不一致);B 没注册上(缺 discovery 依赖、server-addr 写错、namespace / group 不一致、到注册中心网络不通);注册了但健康检查失败被摘除;容器里注册的是容器内部 IP,别的节点访问不到;客户端服务列表缓存还没刷新;Feign 调用路径漏了 B 的 context-path。

★

方法卡 · 直连二分 绕过服务发现,直接 curl http://实例IP:端口/接口。 直连通、走服务名不通 → 问题在注册中心或负载均衡层;直连就不通 → 回到第 1~6 步,毛病在 B 自己身上。 两分钟定下「到底是谁的锅」,比两边团队互相猜快得多。

bash 复制代码
spring:
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: dev-space-id
        group: DEFAULT_GROUP
bash 复制代码
# ① 注册中心里到底有没有这个实例(注意带上实际 namespaceId / groupName)
curl -s "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=order-service&namespaceId=dev-space-id&groupName=DEFAULT_GROUP"

# ② 绕过服务发现,直连实例
curl -i http://INSTANCE_IP:8080/api/order/list

# ③ 看负载均衡实际选了谁:打开开头配置里注释掉的两行 DEBUG

两个版本上的旧结论别再套:新版 Spring Cloud Alibaba 不需要 @EnableDiscoveryClient,照着老教程加这个注解,反而会让人误以为「没开注解所以没注册」;Spring Cloud 2020 之后 Ribbon 已移除,换成 Spring Cloud LoadBalancer,服务列表的缓存行为不一样。

顺带说一句,服务注册和配置中心是两码事。Nacos 配置改了应用没生效,属于配置刷新链路的问题(配置变更通知、Spring Environment 更新、Bean 刷新是三件事),跟这里讲的「实例能不能被发现」不是一条线,别混着查。那部分单独一篇再展开。


把 7 步串起来

单看每一类问题都不难,难的是顺序。跳步最常见的结果,就是改了半天配置,其实只是 URL 少写了个 /api。下面三张图各管一件事,手机上看不清就点开大图:

先理清顺序 ------ 七步从外到内,每步标了看哪行日志、查哪个配置、跑哪条命令,底部还有现象到方向的速判。

Spring Boot 接口故障排查流程图

再按报错查方向 ------ Connection refused、404、405、401、403、超时、服务器不通、服务间调用失败,八类现象各配一条验证命令。

HTTP 错误码与排查方向速查卡

发布前最后过一遍 ------ 12 条勾选式清单,从绑定地址到服务发现,打印或截图存手机都能用。

上线前接口检查清单

一键排查命令包 ,按 7 步顺序排好,整块复制即可。TOKEN、INNER_IP、INSTANCE_IP、PID 按实际替换。

bash 复制代码
# Linux / macOS
# 1 启动
tail -n 100 app.log | grep -E "Started|Tomcat started|APPLICATION FAILED|Caused by"
jps -l
# 2 监听
ss -lntp | grep 8080
# 3 URL 与方法
curl -i -X POST http://127.0.0.1:8080/api/order/list
# 4 映射
curl -s http://127.0.0.1:8080/api/actuator/mappings | grep order
# 5 权限与耗时
curl -i http://127.0.0.1:8080/api/order/list
curl -w "total=%{time_total}\n" -o /dev/null -s http://127.0.0.1:8080/api/actuator/health
jcmd PID Thread.print > thread.txt
# 6 网络
curl -i --connect-timeout 3 http://INNER_IP:8080/api/actuator/health
nc -zv INNER_IP 8080
firewall-cmd --list-all
docker ps
nginx -T | grep proxy_pass
# 7 服务发现
curl -s "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=order-service&namespaceId=dev-space-id&groupName=DEFAULT_GROUP"
curl -i http://INSTANCE_IP:8080/api/order/list
bash 复制代码
# Windows PowerShell ------ 注意这里必须写 curl.exe
# PowerShell 里的 curl 是 Invoke-WebRequest 的别名,参数完全不通用
# 1 启动
Select-String -Path app.log -Pattern "Started|Tomcat started|APPLICATION FAILED|Caused by" | Select-Object -Last 30
jps -l
# 2 监听
netstat -ano | findstr :8080
# 3 URL 与方法
curl.exe -i -X POST http://127.0.0.1:8080/api/order/list
# 4 映射
curl.exe -s http://127.0.0.1:8080/api/actuator/mappings | findstr order
# 5 权限与耗时
curl.exe -i http://127.0.0.1:8080/api/order/list
curl.exe -w "total=%{time_total}" -o NUL -s http://127.0.0.1:8080/api/actuator/health
jcmd PID Thread.print > thread.txt
# 6 网络
curl.exe -i --connect-timeout 3 http://INNER_IP:8080/api/actuator/health
Test-NetConnection -ComputerName INNER_IP -Port 8080
docker ps
# 7 服务发现
curl.exe -s "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=order-service&namespaceId=dev-space-id&groupName=DEFAULT_GROUP"
curl.exe -i http://INSTANCE_IP:8080/api/order/list

这类问题没有诀窍,就是别跳步。我现在会先敲一条 ss -lntp,把「应用到底在不在」钉死,再往下走。查到最后,毛病多半不在代码里,而在某个没人想起来核对过的配置上。上面那份清单是按这个顺序整理的,下次碰到,从头过一遍就够了。

bye!关注我!我们下期再见!

相关推荐
泡海椒1 小时前
jquick-pdf echart风格预算执行进度报表模板:市财政局汇报页的一条条追问与回答
后端
利威尔xu1 小时前
Go channel 关闭 3 个 panic:向已关闭 channel 发送,服务当场崩溃
开发语言·后端·golang·并发编程·channel
山楂树の1 小时前
Java BigDecimal笔记
java·开发语言
旋风菠萝2 小时前
HashMap和CurrentHashMap的key可以为空吗
java·数据库·redis
Csvn2 小时前
Nginx 反向代理入门:proxy_pass 两种形态、超时链与 502/504 分辨
后端·nginx
LVZ2 小时前
AI Agent 缺的不是更强的模型,而是一个运行时
前端·javascript·后端
开开心心就好2 小时前
PDF水印怎么去掉?勾选对象再点匹配
java·前端·mysql·支持向量机·pdf·音视频·模拟退火算法
鶴哥只手遮天3 小时前
《VulkanSceneGraph 1.1.16 源码深度解析》第二章 内存工程:Allocator、MemoryBlock 与场景图的物理布局
后端
im_AMBER3 小时前
IO 多路复用:select、poll 和 epoll
后端·面试·架构