Knife4j文档请求异常问题及解决过程

最近在黑马苍穹外卖项目里折腾 Swagger 集成时，碰上一个挺典型的问题：按照常规配置改完数据库用户名和密码后，项目一启动，Knife4j 生成的接口文档直接罢工，报了个莫名其妙的异常。前后折腾了几个小时，总算找到症结所在，这里把解决路径梳理一下，给碰到类似情况的朋友一个参考。

一、先按官方异常处理走一遍

遇到问题第一反应当然是查官方说明。Knife4j 官方提供了专门的异常处理 FAQ，可以对照着做一次自检：

​​​​​​https://doc.xiaomi nfo.com/docs/faq/knife4j-exception​​​​​​

二、检查 Spring Boot 版本兼容性

如果官方步骤没解决问题，下一步就要确认你项目用的 Spring Boot 版本和 Knife4j 版本是否匹配。这俩东西的版本对应关系挺细，稍不注意就会踩坑。下面这张表梳理了常见 Spring Boot 版本与 Knife4j 的兼容建议：

Knife4j 在后续版本中逐步增强了一些服务端适配特性，所以版本选对了，很多兼容问题自然就消失了。

三、动手调整项目版本

回头看手里这个项目，Spring Boot 版本偏旧，干脆直接升级到 2.7.3，Knife4j 也同步到 3.0.2。具体操作分几步：

1. 修改父模块 pom.xml
把 sky-take-out 父模块中的 Spring Boot 父依赖版本改成 2.7.3：

    
        spring-boot-starter-parent
        org.springframework.boot
        2.7.3
    

2. 更新 Knife4j 依赖版本
项目里所有 knife4j 依赖统一改为 3.0.2：

            
                com.github.xiaoymin
                knife4j-spring-boot-starter
                3.0.2
            

3. 调整 Ja va 编译器版本
把 Ja va 版本切到 JDK 11。操作路径：File → Project Structure → Project Settings → Project。

4. Spring Boot 编译版本同步
同样在 Project Structure 中，把 Spring Boot 的编译版本也改为 11。

5. Ma ven 重新安装父工程
以上配置改完后，最后一步：在 Ma ven 侧边栏对父工程执行 install，确保所有依赖和版本变更生效。

四、启动验证

全部完成后重启项目，访问 http://localhost:8080/doc.html，Knife4j 接口文档页面正常加载，所有接口一览无余——问题彻底解决。

总结

这类问题本质上还是版本兼容性导致的，Spring Boot 2.7.x + Knife4j 3.0.x + JDK 11 这个组合在目前大多数主流项目里都比较稳当。如果后续升级到 Spring Boot 3.x，记得同步把 Knife4j 切到 4.0 以上版本，OpenAPI3 规范也要对应调整。希望这份排查过程能帮你省下一些调试时间。