diff --git a/README.md b/README.md index 0329eab..95f57de 100644 --- a/README.md +++ b/README.md @@ -17,26 +17,34 @@ ## 快速开始 -前置条件:JDK 21(Temurin)、Node.js。 +前置条件:JDK 21(Temurin,含编译工具链与 jpackage)、Node.js(含 npm)。 + +> 首次构建或运行需联网:Gradle 会下载发行版与 Maven 依赖,前端会 `npm install` 安装依赖。使用 wrapper(`./gradlew` / `gradlew.bat`)可自动获取所需 Gradle 版本。 ```bash +# Windows 用 gradlew.bat,Linux/macOS 用 ./gradlew # 后端(默认 8080,接口文档 http://localhost:8080/doc.html) -gradlew.bat bootRun +./gradlew bootRun -# 前端(默认 5173) -cd frontend && npm run dev +# 前端(默认 5173,/api 由 Vite 代理到 8080) +cd frontend && npm install && npm run dev ``` 数据库无需预先准备:启动后在页面按引导选择 SQLite(本地文件,零配置)或 MySQL,保存后立即生效并自动建表;配置持久化于 `config/database.json`。 +## 代码检查 + +- 后端:`./gradlew lint`(Spotless + Checkstyle + SpotBugs)。 +- 前端:`cd frontend && npm run lint`(ESLint;`npm run lint:fix` 自动修复,`npm run format` 用 Prettier 格式化)。 +- `bootJar` / `bootGuiJar` 会先执行后端检查与前端 ESLint,检查不通过则中断打包。 + ## 构建与打包 ```bash -gradle bootJar bootGuiJar # 普通 jar + 带 GUI 启动器的 jar,产物在 build/libs/ -gradle jpackageAppImage # 免安装应用(普通 + GUI),产物在 build/jpackage/ +./gradlew bootJar bootGuiJar # 普通 jar + 带 GUI 启动器的 jar(内嵌前端),产物在 build/libs/ +./gradlew jpackageAppImage # 免安装应用(普通 + GUI),产物在 build/jpackage/ ``` +- 打包前会先安装前端依赖并构建前端产物,再一并打入 jar,无需手动 `npm run build`。 - GUI jar 内嵌前后端与跨平台 JavaFX,单文件即可运行;配置与日志默认落在 jar 所在目录,可用 `--home=<目录>` 或环境变量 `LEDGERLY_HOME` 指定。 - app-image 自带运行时、免安装,但只能为**当前操作系统**生成。 - -> 更详细的目录结构、启动器、jpackage、图标与开发环境说明见 `AGENTS.md`。 diff --git a/build.gradle b/build.gradle index 242fbd7..abbf598 100644 --- a/build.gradle +++ b/build.gradle @@ -1,8 +1,13 @@ +import com.github.spotbugs.snom.Confidence +import com.github.spotbugs.snom.Effort + plugins { id 'java' + id 'checkstyle' id 'org.springframework.boot' version '3.3.6' id 'io.spring.dependency-management' version '1.1.7' id 'com.diffplug.spotless' version '8.10.2' + id 'com.github.spotbugs' version '6.5.12' } group = 'cn.rosercode' @@ -120,6 +125,44 @@ tasks.named('compileJava') { dependsOn 'spotlessJavaCheck' } +// ===== 代码静态检查(Checkstyle / SpotBugs)===== +// 二者挂在 check 任务上,由 ./package.sh(gradle check)触发; +// 不进入 ./reload.sh 的快速热重载路径(compileJava),保持开发体验。 +// 配置文件放在 gradle/ 下(项目根的 config/ 被 .gitignore 忽略,仅用于运行时配置)。 +checkstyle { + configDirectory = file('gradle/checkstyle') + maxWarnings = 0 + ignoreFailures = false +} + +spotbugs { + // 固定 4.8.6:其 BCEL 不依赖 commons-lang3 3.18+ 的 getJdkModulePath, + // 避免与 Spring Boot BOM 选定的 commons-lang3 3.14.0 冲突(NoSuchMethodError)。 + toolVersion = '4.8.6' + effort = Effort.MAX + reportLevel = Confidence.valueOf('MEDIUM') + excludeFilter = file('gradle/spotbugs/exclude.xml') + ignoreFailures = false +} + +tasks.named('spotbugsMain') { + reports { + xml { + required = true + outputLocation = file("${layout.buildDirectory.get().asFile}/reports/spotbugs/main.xml") + } + html { + required = true + outputLocation = file("${layout.buildDirectory.get().asFile}/reports/spotbugs/main.html") + } + } +} + +// 测试源码(src/test)仅本地验证、不提交(见 AGENTS.md),不纳入 Checkstyle/SpotBugs +tasks.matching { it.name == 'checkstyleTest' || it.name == 'spotbugsTest' }.configureEach { + enabled = false +} + // ===== 前端构建与打包 ===== def frontendDir = file("${projectDir}/frontend") def frontendDistDir = file("${frontendDir}/dist") @@ -144,11 +187,23 @@ tasks.register('npmInstall', Exec) { outputs.dir("${frontendDir}/node_modules") } +// 前端代码检查(ESLint),失败则中断构建 +tasks.register('frontendLint', Exec) { + group = 'frontend' + description = '运行前端 ESLint 检查(npm run lint)' + dependsOn 'npmInstall' + workingDir frontendDir + commandLine resolveNpm(), 'run', 'lint' + inputs.dir("${frontendDir}/src") + inputs.file("${frontendDir}/eslint.config.js") + inputs.file("${frontendDir}/package.json") +} + // 构建前端产物 tasks.register('frontendBuild', Exec) { group = 'frontend' description = '构建前端产物(npm run build)' - dependsOn 'npmInstall' + dependsOn 'npmInstall', 'frontendLint' workingDir frontendDir commandLine resolveNpm(), 'run', 'build' inputs.dir("${frontendDir}/src") @@ -158,6 +213,13 @@ tasks.register('frontendBuild', Exec) { outputs.dir(frontendDistDir) } +// 聚合代码检查任务:后端 Spotless/Checkstyle/SpotBugs(主源码)+ 前端 ESLint +tasks.register('lint') { + group = 'verification' + description = '运行全部代码检查(后端 Spotless、Checkstyle、SpotBugs 与前端 ESLint)' + dependsOn 'spotlessCheck', 'checkstyleMain', 'spotbugsMain', 'frontendLint' +} + // 将前端产物打入可执行 jar 的静态资源目录,实现前后端一体化部署 tasks.named('bootJar') { dependsOn 'frontendBuild' diff --git a/frontend/.prettierignore b/frontend/.prettierignore new file mode 100644 index 0000000..695fe50 --- /dev/null +++ b/frontend/.prettierignore @@ -0,0 +1,4 @@ +dist +node_modules +package-lock.json +public diff --git a/frontend/.prettierrc.json b/frontend/.prettierrc.json new file mode 100644 index 0000000..c591ee2 --- /dev/null +++ b/frontend/.prettierrc.json @@ -0,0 +1,7 @@ +{ + "semi": false, + "singleQuote": true, + "printWidth": 120, + "trailingComma": "all", + "endOfLine": "lf" +} diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js new file mode 100644 index 0000000..f57a3fe --- /dev/null +++ b/frontend/eslint.config.js @@ -0,0 +1,42 @@ +import js from '@eslint/js' +import pluginVue from 'eslint-plugin-vue' +import globals from 'globals' +import tseslint from 'typescript-eslint' +import prettier from 'eslint-config-prettier' + +export default tseslint.config( + // 忽略构建产物与依赖目录 + { ignores: ['dist/**', 'node_modules/**', 'public/**', 'src/**/*.d.ts'] }, + js.configs.recommended, + ...tseslint.configs.recommended, + ...pluginVue.configs['flat/recommended'], + { + // Vue 单文件组件的