麻雀窝 Sparrow Zoo

DOCUMENTATION / 开发文档

开发文档

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

开发工具

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

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

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

Spring AI 自定义模型接入:让 Codex 的 tools 与 Advisors 真正生效

结合 Spring AI 2.0.1 与 Codex 适配案例,分清 ChatClient 与 ChatModel 的职责,定位工具声明丢失、底层协议缺失两个问题,并说明修复、验证与上游 issue #7238。

面向接入自定义 ChatModel 的 Java 开发者;案例基于 Spring AI 2.0.1 与 Codex CLI 0.158.0。
Spring AIChatModelCodex工具调用ToolCallingAdvisorToolCallingChatOptionsJava模型适配
工程
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源码分析天气工具
后端工程
前后端

HTTP 状态码与 Result:前后端同步的底层接口协议

从业务异常、MVC 解析错误到认证过滤器与 Fetcher,说明 HTTP 状态和 Result 各管什么、如何同步处理,以及当前仍需补齐的边界。

适合维护 Spring MVC、统一 Result 响应体和 sparrow-js Fetcher 的前后端开发者。
HTTP 状态码ResultSpring MVCControllerAdviceBusinessExceptionFetcher前后端协议国际化
工程
移动端

从 Expo 57 脚手架到双端模拟器:一次完整的安装与验证记录

记录 Expo 57 移动端脚手架的版本选择、依赖安装、Android 与 iOS 工具链、原生构建、模拟器故障排查和实际交互验证,并解释每一层验证能证明什么。

准备在 macOS 上搭建 Expo 57、构建 iOS 与 Android 开发版的开发者;环境记录为 2026-10-21。
Expo 57React NativeExpo RouterNativeWindAndroid 模拟器iOS Simulator原生构建Metro
前端开发
AI 工程

OpenAI 计费指南:ChatGPT、Codex CLI 与 API 的区别及实操

从认证与账单归属解释为什么 Codex CLI 能用而 API 不通,提供登录检查、API 最小请求、token 费用核算、硬限额配置与 429 排查步骤,并附官方依据和团队记录规范。

适合 Codex 用户、Spring AI 开发者及费用负责人;官方资料核对至 2026-10-15。
OpenAI 计费Codex CLIChatGPT 订阅API KeySpring AITokenSpend limits429
工程
前端架构

跨域 SSO 下的用户信息共享与解耦:Context、职责边界与 token 重签

结合一次登录用户重构,说明跨域 SSO 中 token 即用户信息唯一载体,父子组件通过 Context 共享 LoginUser,HTTP 与 WebSocket 各司其职,修改头像后端重签 token 以守护数据一致。

前端与全栈工程师(涉及跨域登录、React Context、WebSocket 集成)
跨域 SSOReact ContextJWTtoken 一致性WebSocketFetcheruseLoginUser头像重签职责解耦LoginUserProvider
前端开发
Mail

Gmail 550-5.7.26 退信排查:SPF、DKIM 与 DMARC 报告邮箱怎么配

从一封脱敏退信出发,定位 SPF 与 DKIM 均未通过的原因,区分 SMTP 中继和直接投递,并解释 rua 报告邮箱、QQ 跨域授权及 p=none 的适用边界。

使用企业邮箱、应用通知邮件或自建 SMTP 服务的开发与运维人员。
Gmail550-5.7.26SPFDKIMDMARCrua邮件退信DNS
运维
JavaScript

0 == "" == true:JavaScript 宽松相等的类型强制陷阱

0 == "" == true 为什么等于 true?本文从宽松相等(==)与严格相等(===)的区别出发,拆解 JavaScript 隐式类型转换的完整规则,覆盖 falsy 值、字符串转数字、数组 ToPrimitive、null/undefined/NaN 特例与链式比较的左结合陷阱,附常见结果速查表与工程最佳实践。

前端 / 全栈开发者(了解基础 JS 语法)
JavaScript类型强制宽松相等严格相等=====falsyToPrimitive抽象相等
前端开发
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代码飘红
后端工程
Web Storage

Web Storage 的边界与跨域 SSO:从 Safari 差异到客户端 RPC

结合手机 localStorage 返回 null 的反馈,解释同源、同站与存储分区,重点说明 Cookie 承载登录凭据如何消除 iframe 存储依赖,以及 HttpOnly、凭据请求和跨站限制。

前端与集成开发者(涉及跨域登录、iframe 集成)
Web StoragesessionStoragelocalStorage存储分区postMessage客户端 RPC跨域 SSOCookieHttpOnly
前端开发
Thymeleaf

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

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

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

腾讯企业邮箱完整配置指南

从管理员与成员权限、客户端专用密码,到 SMTP/IMAP/POP3 参数、Foxmail/Outlook、JavaMail/Spring Boot 示例及 535 认证失败排查的完整指南。

使用腾讯企业邮箱 / 企业微信邮件的运维与后端开发者,覆盖 Foxmail、Outlook 客户端及 JavaMail / Spring Boot 程序接入。
腾讯企业邮箱SMTPIMAP客户端专用密码JavaMailSpring Boot
运维
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多模块
后端工程
React

useCaptcha 验证码 Hook 源码解析

拆解前端验证码自定义 Hook 的「两阶段加载」设计、会话与图片的先后时序,以及缓存击穿、事件监听累积等值得注意的隐患。

前端开发者(React 18)
React验证码useCaptcha自定义 Hook两阶段加载useEffectuseRef
前端开发
React

把 React 组件嵌入非 React 页面:HtmlFragment 与客服挂件

用 createRoot 与 useEffect 把客服组件接进官网、商城等非 React 架构:讲清 HTML 片段如何生成、注入,以及为什么静态导出会多出文档外壳。

前端与集成开发者(React 18 / Next.js App Router)
ReactcreateRootuseEffectHtmlFragment客服挂件Next.js静态导出
前端开发
OpenAPI

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

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

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

Nginx 全站 HTTPS 上线:从证书签发到平滑切换

为对外公开域名统一启用 HTTPS:用 Certbot(Let's Encrypt)签发证书,80 端口 301 跳转 443,内部管理域名保持 80 不变;含域名清单、配置改动、七步上线流程与本机自测排障。

运维与后端开发者(Nginx + Certbot / Let's Encrypt)
NginxHTTPSCertbotLet's Encrypt301 跳转
运维
Next.js

Next.js 15 四站静态上线

本机用 build-static.sh 打包单个 tar.gz,上传服务器后执行 deploy.sh 切换版本,浏览器验收;出问题用 rollback 恢复上一版。

前端 / 运维工程师(Next.js 15 静态导出 · next-intl 4.x)
Next.js 15静态导出Nginx静态部署回滚
前端开发
Next.js

next-intl 国际化权威指南及使用说明

讲清 Next.js App Router 下 next-intl 的「URL 前缀 + 中间件 + Context」三位一体方案:标准配置五步、多消息分组落地,以及语言切换失效的排查表。

前端开发者(Next.js 15 App Router + next-intl v4)
next-intlNext.jsApp Router国际化i18nmiddlewareuseTranslations
前端开发
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 学习学习路线面向对象集合并发编程入门后端开发
后端工程
Codex

Codex Skill 跨项目复用:本地迭代与 GitHub 同步

把 Codex skill 源码放入独立 Git 仓库,通过用户级软链接跨项目复用;从目录设计、SKILL.md、首次配置到 GitHub 同步,建立可持续迭代的工作流程。

使用 Codex 进行 AI 编程的开发者(macOS / Linux 终端,Bash 或 Zsh)
CodexSkill软链接GitHub跨项目复用
AI 编程