麻雀窝 Sparrow Zoo

DOCUMENTATION / 开发文档

开发文档

从工程架构、接口集成到问题排查,查阅项目中的实现说明与实践记录。

开发工具

IDEA 启动读不到环境变量:从报错定位到运行配置修复

终端能读取环境变量,IDEA 启动的 Spring Boot 应用却提示未配置。以 skills 目录变量为例,说明如何定位进程环境差异、配置运行参数并验证修复。

面向使用 macOS、Zsh 和 IntelliJ IDEA 启动 Spring Boot 应用的开发者;界面选项随 IDEA 版本有所差异。
IntelliJ IDEA环境变量macOSZshSpring Boot启动失败运行配置
后端工程
Spring AI

Spring AI 工具调用源码解析:一段天气问答背后的完整执行过程

从天气穿衣建议示例出发,沿 Spring AI 2.1.0-M1 源码解释 ChatClient 自动配置、@Tool 参数 Schema、ToolCallingAdvisor 多轮循环、反射执行、日志顺序与异常处理,并说明当前气温与全天建议的能力差别。

面向掌握 Java 与 Spring Boot 基础的开发者;基于 Spring AI 2.1.0-M1、Spring Boot 4.0.7,Java 编译目标 17。
Spring AITool CallingChatClientToolCallingAdvisorToolCallingManagerMethodToolCallbackAnthropic源码分析天气工具
后端工程
Maven

为什么 mvn 能过,IDEA 却飘红:多模块 Maven 项目排障指南

命令行 mvn clean install 编译通过,IntelliJ IDEA 里却代码飘红、找不到类。根因是 IDEA 与命令行各持一套 Maven 配置、本地仓库与索引缓存。本文给出配置对齐、依赖版本、索引缓存、模块导入、手工模型冲突五类根因与可直接照做的菜单操作。

Java 后端开发者(Maven 3.x + IntelliJ IDEA,多模块项目)
IntelliJ IDEAMaven多模块Reload All Maven ProjectsInvalidate Caches本地仓库SNAPSHOT代码飘红
后端工程
Thymeleaf

Thymeleaf 配置踩坑:prefix 不能带尾斜杠

记录 Thymeleaf 视图解析「找不到资源」报错的根因:Controller 视图名带前导斜杠时,spring.thymeleaf.prefix 一旦多出尾斜杠就会拼出双斜杠路径;给出正确配置与踩坑清单。

使用 Spring Boot + Thymeleaf 的后端开发者(Thymeleaf 3.1 / Spring Boot 2.x、3.x)
ThymeleafSpring Bootprefix模板配置尾斜杠
后端工程
OpenAPI

springdoc-openapi 集成说明:webmvc-ui 与 webflux-ui 如何选对

讲清 springdoc-openapi 的 webmvc-ui 与 webflux-ui 两组 starter 的本质区别、阻塞 Servlet 与非阻塞 Netty 的技术栈差异、互斥的自动装配条件,以及依赖选择、配置项与分组隔离的正确做法。

后端开发者,使用 Spring Boot Servlet/MVC 栈集成 springdoc-openapi(webmvc-ui,版本 2.8.8)
springdoc-openapiSwagger UIwebmvcwebfluxOpenAPI
后端工程
Spring Boot

Spring Boot 静态资源 URL 查找:分类、优先级与访问方式

梳理 Spring Boot 默认的 URL 查找流程与处理器优先级,分类说明静态资源的存放位置与访问方式,并用表格对比;强调按默认优先级使用、不强行修改以保障安全。

后端开发者(Spring Boot 2.x / 3.x)
Spring Boot静态资源WebJarHandlerMapping静态资源优先级
后端工程
Maven

Sparrow Parent 与 BOM:从内部构建到业务接入

Sparrow 平台的 Maven 架构设计:以 sparrow-parent 统一稳定构建基线,以 sparrow-bom 交付组件版本组合,说明 parent、import 与多模块业务项目的最佳实践。

Sparrow 平台组与业务开发者;基于 Maven 3.x、Spring Boot 3.5.0 / JDK 18 的构建基线讨论
MavenparentBOMdependencyManagement多模块
后端工程
OpenAPI

OpenAPI 分组策略:多 starter 共存下的接口文档分组

记录 Sparrow File 接入 springdoc-openapi 时遇到的两个问题、根因与最终方案,并给出「多 starter 共存」场景下给接口文档分组的通用做法。

后端开发者(Spring Boot + springdoc-openapi,多模块 / 多 starter 项目)
OpenAPISwaggerspringdoc-openapiGroupedOpenApi接口文档分组
后端工程
Netty

Netty 入站消息未释放导致 OOM:引用计数泄漏与心跳吞帧

从一段真实的 Netty 报错出发,定位自定义 handler 继承 ChannelInboundHandlerAdapter 后既不 release 也不 fireChannelRead,导致入站 ByteBuf 引用计数不归零、缓冲持续泄漏直至 OOM,并连带吞掉心跳、拖垮 IM 消息;含代码对比、泄漏链推导与三种修复方案。

使用 Netty 4.x 构建 IM / 长连接服务的后端开发者
NettyOOM内存泄漏ByteBuf 引用计数SimpleChannelInboundHandler入站消息释放
后端工程
Netty

Netty 内存共享与释放机制:引用计数、零拷贝与一处直接内存泄漏

结合 WebSocketFrameHandler 案例,梳理 Netty 的引用计数模型、框架自动释放点与手动释放,对比 retainedDuplicate 零拷贝共享与 newFrame 深拷贝,并定位一处「分配后未写入也未释放」导致的直接内存泄漏。

具备 Netty 基础、关注 ByteBuf 引用计数与内存泄漏排查的后端开发者(Netty 4.x)
NettyByteBuf引用计数内存泄漏零拷贝
后端工程
Maven

Maven 依赖调试:找不到源码导致断点行号错位

依赖 jar 时找不到源代码,class 文件与源文件代码行对不齐,导致 debug 断点误判的根因与解决方案:补齐 -sources.jar、保证源码与字节码同一次构建。

Java 后端开发者与排障人员(Maven 3.x + IntelliJ IDEA,JDK 8 及以上)
Maven源码调试sources.jarLineNumberTablejavap
后端工程
Java

如何学好 Java:从语法到工程的可执行学习路线

零基础也能上手的 Java 学习路线:以官方文档与手写代码为锚点,循序渐进掌握语法、面向对象、集合与并发,最终靠项目实战把知识变成能力。

零基础或转行的 Java 学习者,示例基于 Java 21 LTS
JavaJava 学习学习路线面向对象集合并发编程入门后端开发
后端工程