dr-jskill

遵循 Julien Dubois 最佳实践的 Spring Boot 技能。

概述

此 Agent 技能可帮助你遵循 Julien Dubois 的最佳实践创建 Spring Boot 项目。它提供工具和脚本，让你通过 https://start.spring.io 快速搭建 Spring Boot 应用。

推荐模型： Dr JSkill 最适合使用 GPT-5.5。

版本管理

集中管理的版本信息位于 versions.json 中。所有脚本都会通过 scripts/lib/versions.mjs（JavaScript）读取该文件。更新此文件即可升级 Java、Spring Boot 回退版本、Postgres、Node/npm、Testcontainers 等。

前提条件

1. 已安装 Java 25
2. Node.js 24.x 和 NPM 11.x（用于前端开发）
3. 已安装并运行 Docker

功能

• 使用预定义配置生成 Spring Boot 项目
• 支持各种 Spring Boot 版本和依赖项
• 遵循项目结构和配置的最佳实践
• 为常见用例提供快速设置脚本
• 支持 Docker 容器化部署
• 提供多种框架选项，支持前端开发：
  • Vue.js 3（默认）- 基于 Composition API 的渐进式框架
  • React 19 - 用于构建用户界面的热门库
  • Angular 22 - 功能全面的 TypeScript 框架
  • Vanilla JavaScript - 无框架，使用纯 ES6+ 和 Vite

用法

使用脚本

此技能在 scripts/ 目录中包含跨平台 JavaScript（Node.js）脚本，可用于从 start.spring.io 下载预配置的 Spring Boot 项目。这些脚本适用于 Linux、macOS 和 Windows。

统一启动器（跨平台）：

node scripts/create-project my-app com.myco my-app com.myco.myapp 25 fullstack --output-dir /absolute/path/to/user/workspace

直接调用：

node scripts/create-project-latest.mjs my-app com.myco my-app com.myco.myapp 25 fullstack --output-dir /absolute/path/to/user/workspace

支持的标志：

• --boot-version <x.y.z> / -BootVersion：覆盖 Spring Boot 版本
• --project-type basic|web|fullstack / -ProjectType
• --output-dir <absolute-path>：在此目录下创建生成的项目文件夹

输出目录规则（对 Agent Skills 很重要）： 随附脚本从技能目录根目录运行。用户要求创建应用时，请将 Agent 会话中的用户当前工作目录作为 --output-dir 的值，以便在用户的工作区中创建生成的项目文件夹，而不是创建在 dr-jskill 技能文件夹中。只有在运行 Dr JSkill 自身测试时才省略 --output-dir，因为此时有意在技能仓库目录中生成项目。

提示：create-project-latest 脚本会自动解析首选的 Boot 4.x 版本；如果尚不可用，则回退到配置的 springBootFallback。如有需要，可通过 --boot-version 覆盖。

最新版本项目 ⭐

使用 create-project-latest.mjs 脚本创建使用最新 Spring Boot 版本的项目（自动获取）：

node scripts/create-project-latest.mjs my-app com.mycompany my-app com.mycompany.myapp 25 web

可用的项目类型：

• basic - 最简 Spring Boot 项目
• web - 具备 REST API 功能的 Web 应用
• fullstack - 包含数据库和安全功能的完整应用

基础 Spring Boot 项目

使用 create-basic-project.mjs 脚本创建包含必要依赖项的基础 Spring Boot 项目：

node scripts/create-basic-project.mjs

Web 应用

使用 create-web-project.mjs 脚本创建包含 Web 依赖项的 Spring Boot Web 应用：

node scripts/create-web-project.mjs

全栈应用

使用 create-fullstack-project.mjs 脚本创建包含数据库、安全和 Web 依赖项的综合型 Spring Boot 应用：

node scripts/create-fullstack-project.mjs

最佳实践

创建 Spring Boot 项目时：

1. 使用最新的 Spring Boot 版本（当前为 4.x）——create-project-latest.mjs 脚本会自动获取该版本
2. 查看 Spring Boot 4 的重要注意事项：参见 Spring Boot 4 Migration Guide，了解 Jackson 3 注解和 TestContainers 配置
3. 引入 Spring Boot Actuator，以使用适用于生产环境的功能
4. 使用 Spring Data JPA 访问数据库
5. 使用 PostgreSQL 数据库——有关优化，请参见 Database Best Practices
6. 使用 properties 文件进行配置——参见 Configuration Best Practices
7. 设置基础 dotfiles：.gitignore、.env.sample、.editorconfig、.gitattributes、.dockerignore，以及可选的 .vscode/、.devcontainer/——参见 Project Setup & Dotfiles
   • .env 文件是本地密钥的规范存放位置；请指导用户复制 .env.sample → .env，并填入实际值
   • 切勿读取或泄露 .env：其中包含真实密钥——不要使用 cat、查看或打印其内容；只可读取或显示包含占位值的 .env.sample
8. 遵循日常 Git 最佳实践，包括使用小型分支、审查差异、安全提交、创建拉取请求和使用工作树——参见 Git Best Practices
9. 使用 spring-boot-docker-compose，在开发期间自动启动数据库——参见 Docker Guide
10. 遵循 RESTful API 设计原则
11. 使用 Logback 配置适当的日志记录——参见 Logging Best Practices
12. 使用 Maven 管理依赖
13. 引入 Spring Boot DevTools，提高开发效率
14. 仅在需要时添加 Spring Security——有关最佳实践，请参见 Security Guide
15. 配置 Docker，以便进行容器化部署——参见 Docker Guide
16. 启用 GraalVM 原生镜像支持，加快启动速度——参见 GraalVM Guide
17. 始终提供启动横幅，在应用就绪时打印访问 URL——参见 Startup Banner
18. 用户必须在更改提交到 git 之前进行审查。初始化 Git 仓库或运行 git 命令前，请先询问用户。

Java 代码智能（JDTLS）⭐

生成的项目集成了 Eclipse JDT Language Server（JDTLS），因此 AI Agent 可以通过语义理解来导航、重构和诊断 Java 代码，而不是使用文本搜索。脚本会提供 .github/lsp.json，自动将 JDTLS 接入 GitHub Copilot CLI。

对于 AI Agent：处理 Java 文件时，优先使用 lsp 工具，而非 grep/view/sed。它能够理解导入、泛型、继承和 Javadoc。

任务	使用
查找类或方法的定义位置	lsp goToDefinition
更改签名前查找调用方	lsp findReferences 或 incomingCalls
查询类型、参数和 Javadoc	lsp hover
列出文件中的符号	lsp documentSymbol
在项目中搜索类或方法	lsp workspaceSymbol
安全地跨文件重命名	lsp rename（绝不使用 sed）
在运行 ./mvnw verify 前检查编译错误	ide-get_diagnostics

Java 开发的优先顺序：lsp → 使用 .java glob 的 grep → view。

安装一次 JDTLS：brew install jdtls（或参见适用于其他平台的 JDTLS guide）。完整设置说明、注意事项和编辑器集成见 references/JDTLS.md。

项目结构

仅当服务层能够带来价值时才纳入项目（例如，包含复杂业务逻辑）。对于简单的 CRUD 应用，控制器可以直接调用仓库。

生成的项目遵循以下推荐结构：

my-spring-boot-app/
├── .gitignore                 # Java + front-end + secrets (see references/PROJECT-SETUP.md)
├── .env.sample                # Template for local env vars; .env is gitignored
├── .editorconfig              # Consistent formatting across IDEs
├── .gitattributes             # Normalize line endings, better diffs
├── .dockerignore              # Slim Docker build contexts
├── .vscode/                   # Optional editor recommendations
│   ├── extensions.json
│   └── settings.json
├── .devcontainer/             # Optional Dev Container (Java 25 + Node 24 + PostgreSQL)
│   ├── devcontainer.json
│   └── docker-compose.yml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/app/
│   │   │       ├── Application.java
│   │   │       ├── config/
│   │   │       ├── controller/
│   │   │       ├── service/         # Only included if needed
│   │   │       ├── repository/
│   │   │       └── domain/
│   │   └── resources/
│   │       ├── static/              # Front-end web assets (HTML, CSS, JS)
│   │       │   ├── index.html
│   │       │   ├── css/
│   │       │   │   └── styles.css
│   │       │   ├── js/
│   │       │   │   └── app.js
│   │       │   └── images/
│   │       └── application.properties
│   └── test/
│       └── java/
│           └── com/example/app/
│               ├── config/
│               ├── controller/
│               ├── service/         # Only included if needed
│               ├── repository/
│               └── domain/
├── Dockerfile                   # JVM image (jlink runtime + distroless)
├── Dockerfile-aot               # JVM + Spring AOT image
├── Dockerfile-native            # GraalVM native image
├── Dockerfile-crac              # CRaC (fast-restore) image
├── checkpoint-and-run.sh        # CRaC entrypoint helper
├── compose.yaml                 # Dev database (spring-boot-docker-compose)
├── docker-compose.yml           # Full stack with PostgreSQL (JVM)
├── docker-compose-aot.yml       # Full stack with PostgreSQL (AOT)
├── docker-compose-native.yml    # Full stack with PostgreSQL (native)
├── docker-compose-crac.yml      # CRaC app (database-free)
├── pom.xml
└── README.md

依赖项

生成的项目包含：Spring Web、Spring Data JPA、Spring Boot Actuator、DevTools、PostgreSQL、Validation、Docker Compose 支持、使用 JUnit 5 的 Test Starter，以及 TestContainers。

配置

使用 .properties 文件（而非 YAML），通过环境变量将密钥外置，并利用 @ConfigurationProperties 确保类型安全。有关配置文件、密钥管理和常见模式，请参阅配置指南。

.env 文件是唯一的本地密钥存储——切勿读取或打印该文件；只能显示 .env.sample（占位值）。

有关数据库优化，请参阅数据库最佳实践指南。

安全性（可选）

Spring Security 为可选项——仅在需要身份验证或授权时添加。有关 JWT、OAuth2、基于角色的访问控制和 CORS 配置，请参阅安全指南。

测试

有关单元测试（Mockito、@WebMvcTest）、集成测试（TestContainers + @ServiceConnection）以及使用 AssertJ 的 Given-When-Then 模式，请参阅测试指南。

前端开发

选择一个前端框架：

• Vue.js 3（默认）⭐ → Vue.js 指南
• React 19 → React 指南
• Angular 22 → Angular 指南
• 原生 JavaScript（无框架）→ 原生 JS 指南

所有选项均包含：带热重载的 Vite/CLI 开发服务器、Bootstrap 5.3+、SPA 路由，以及自动构建到 Spring Boot JAR 中。

配置 frontend-maven-plugin 时，将 Node 安装、npm install 和 npm run build 这几项执行绑定到 generate-resources 阶段。这样，./mvnw spring-boot:run 会在 Spring Boot 启动前构建前端，而不是仅在显式执行面向打包的命令时构建。

非交互式脚手架生成（对 CI 和 AI Agent 很重要）。 必须分别禁用两个提示：

1. npm 自带的“Ok to proceed?” 安装提示——将 -y 放在包名之前即可禁用（-- 后的标志会传给脚手架，而不是 npm）。使用 npm create -y vite@latest … 或 npx --yes create-vite@latest …。
2. 脚手架自身的提示——create-vite 9.x 和 Angular CLI 22 仍会提出交互式问题（例如“Use rolldown-vite?”、是否选择加入分析），而 -y / --yes 无法禁用这些提示。可靠的解决方法是关闭标准输入：在命令前通过管道输入 echo |，让脚手架立即收到 EOF 并接受默认选项。

标准用法：

• React / 原生 JavaScript：echo | npx --yes create-vite@latest frontend --template react（或 --template vanilla）
• Vue：npm create -y vue@latest frontend -- --router --pinia --vitest --eslint --prettier（create-vue 不会提出额外提示）
• Angular：echo | npx --yes @angular/cli@22 new frontend --style=css --ssr=false --skip-git --defaults --skip-install，然后运行 npm install

Vue：首次运行 npm install 前进行规范化（必需）。 create-vue 生成的 oxlint 和 eslint-plugin-oxlint 固定在不匹配的次要版本，因此 npm install 会因 ERESOLVE 对等依赖冲突而失败，进而导致 frontend-maven-plugin 步骤失败，最终使整个 Maven 构建失败。完成脚手架生成后，立即运行：

# 在 Dr JSkill skill 目录中运行（`scripts/` 位于该目录），
# 并传入生成的项目 frontend/ 目录路径。
node scripts/normalize-vue-frontend.mjs /absolute/path/to/my-app/frontend

该脚本会移除 oxlint 双重检查工具链，保留单一 ESLint 流程，并添加 create-vue 不会生成、但 Maven frontend-maven-plugin 构建会运行的 lint:check 脚本。该脚本可重复运行，且 --check 只报告、不写入。参见 Vue.js 指南。

Vitest + 回调式 Vite 配置。 如果 vite.config.js 导出 defineConfig(({ mode }) => ...)，不要让生成的 vitest.config.js 调用 mergeConfig(viteConfig, ...)。先通过 viteConfig({ mode: 'test', command: 'serve' }) 解析回调，否则 Vitest 会因 Cannot merge config in form of callback 而失败。参见 Vue.js 指南。

Docker 部署

Spring Boot 在开发期间通过 spring-boot-docker-compose 自动管理 Docker 容器。生产环境可选择提供的四种镜像之一：Dockerfile（JVM、jlink + distroless）、Dockerfile-aot（JVM + Spring AOT）、Dockerfile-native（GraalVM 原生镜像）或 Dockerfile-crac（CRaC 快速恢复）。完整设置说明、对应的 Maven 配置文件和部署模式，请参见 Docker 指南。

GraalVM 原生镜像

可通过 Docker 构建原生镜像（无需本地安装 GraalVM），也可在本地使用 ./mvnw -Pnative -DskipTests package native:compile 构建。有关配置、运行时提示、测试和 CI/CD 集成，请参见 GraalVM 指南。

Azure 部署

部署到 Azure Container Apps，并可选择使用注入 VNET 的 Azure Database for PostgreSQL Flexible Server。使用 GitHub Container Registry (GHCR) 存储镜像（CI 中通过 GITHUB_TOKEN 推送，Container Apps 使用已存储的 PAT 拉取），并使用 Container Apps 机密保存数据库密码——源码、环境变量转储或 shell 历史记录中均不包含机密。包含 GitHub Actions OIDC 工作流，并支持 JVM 和 GraalVM 原生镜像变体。请参阅 Azure 部署指南。

验证

#	内容	命令
1	构建后端	./mvnw clean install
2	单元测试	./mvnw test
3	集成测试	./mvnw verify（使用 Testcontainers 2 和 @ServiceConnection）
4	前端开发服务器	cd frontend && npm run dev

请先执行验证步骤。如果有任何步骤失败，请先修复再继续。

项目生成后，请按上述步骤操作，确保生成的项目功能完整并遵循最佳实践。如果任何验证步骤失败，请尝试找出问题并修复，然后再继续。这样可确保生成的项目质量上乘，能够随时开始开发。

其他资源

随附的参考指南

Spring Boot 核心：

• Spring Boot 4 迁移指南 - Spring Boot 3 的关键变更、Jackson 3 注解
• 配置最佳实践 - 属性文件、配置档案、机密管理
• 日志最佳实践 - Logback 配置和模式
• Java 代码智能（JDTLS） - 基于 LSP 的导航、重构和诊断

数据与持久化：

• 数据库最佳实践 - PostgreSQL 和 Hibernate 优化

安全（可选）：

• 安全指南 - Spring Security、JWT、OAuth2、身份验证模式

测试：

• 测试指南 - 使用 TestContainers 进行单元测试和集成测试

前端开发：

• Vue.js 开发指南 - 使用 Vite 的 Vue.js 3（默认）
• React 开发指南 - 使用 Vite 的 React 19
• Angular 开发指南 - 使用 Angular CLI 的 Angular 22
• 原生 JS 开发指南 - 使用 Vite 的纯 ES6+

项目设置：

• 项目设置与 Dotfiles - .gitignore、.env.sample、.editorconfig、.gitattributes、.dockerignore、.devcontainer/
• Git 最佳实践 - 日常 Git 工作流、分支、提交、拉取请求、安全撤销、暂存和工作树

部署：

• Docker 部署指南 - Docker、Docker Compose、开发自动化
• GraalVM 原生镜像指南 - 基于 Docker 的原生构建、优化
• Azure 部署指南 - Azure Container Apps、PostgreSQL Flexible Server、GitHub Container Registry (GHCR) 镜像推送/拉取、用于数据库密码的 Container Apps 机密、GitHub Actions OIDC