更新了框架开发，并进行了文档整合
This commit is contained in:
ProjectFrameWork2025
parent
4a16886686
commit
745a270db1
117
.gitignore
vendored
117
.gitignore
vendored
@ -32,73 +32,50 @@ build/
|
|||||||
|
|
||||||
### VS Code ###
|
### VS Code ###
|
||||||
.vscode/
|
.vscode/
|
||||||
src/main/resources/static/favicon.ico
|
|
||||||
src/main/resources/static/index.html
|
framework/src/main/resources/static/assets/401-099a3a32.js
|
||||||
src/main/resources/static/assets/401-88639a9f.js
|
framework/src/main/resources/static/assets/401-fffd1e4b.css
|
||||||
src/main/resources/static/assets/401-a61ddb94.gif
|
framework/src/main/resources/static/assets/404-6dcbdda2.js
|
||||||
src/main/resources/static/assets/401-d244ab29.css
|
framework/src/main/resources/static/assets/404-51ac6f86.css
|
||||||
src/main/resources/static/assets/404_cloud-98e7ac66.png
|
framework/src/main/resources/static/assets/BarChart-efd5cbe1.js
|
||||||
src/main/resources/static/assets/404-7ca1fe28.css
|
framework/src/main/resources/static/assets/editor-b13c93a6.js
|
||||||
src/main/resources/static/assets/404-7d365cf6.js
|
framework/src/main/resources/static/assets/FunnelChart-79f3d5f7.js
|
||||||
src/main/resources/static/assets/404-538aa4d7.png
|
framework/src/main/resources/static/assets/index-1a396a09.css
|
||||||
src/main/resources/static/assets/BarChart-4fa92581.js
|
framework/src/main/resources/static/assets/index-01e2cfa9.js
|
||||||
src/main/resources/static/assets/BarChart.vue_vue_type_script_setup_true_lang-2e88c556.js
|
framework/src/main/resources/static/assets/index-2b88764d.css
|
||||||
src/main/resources/static/assets/editor-1fcae90e.js
|
framework/src/main/resources/static/assets/index-04bb232d.js
|
||||||
src/main/resources/static/assets/editor-501cf061.css
|
framework/src/main/resources/static/assets/index-5a5afaa7.css
|
||||||
src/main/resources/static/assets/FunnelChart-54cd9c1c.js
|
framework/src/main/resources/static/assets/index-6cf33161.js
|
||||||
src/main/resources/static/assets/index-0c0fc4d5.js
|
framework/src/main/resources/static/assets/index-6ee17396.css
|
||||||
src/main/resources/static/assets/index-0c6de5c4.css
|
framework/src/main/resources/static/assets/index-9c04fca4.css
|
||||||
src/main/resources/static/assets/index-0e353610.js
|
framework/src/main/resources/static/assets/index-63bba755.js
|
||||||
src/main/resources/static/assets/index-0fdbb0c3.css
|
framework/src/main/resources/static/assets/index-70f67d2a.js
|
||||||
src/main/resources/static/assets/index-2a2e686f.js
|
framework/src/main/resources/static/assets/index-98c36269.js
|
||||||
src/main/resources/static/assets/index-2d8a94de.js
|
framework/src/main/resources/static/assets/index-362b32fa.css
|
||||||
src/main/resources/static/assets/index-3c8b576d.js
|
framework/src/main/resources/static/assets/index-486d1d98.js
|
||||||
src/main/resources/static/assets/index-3e4e0c0c.css
|
framework/src/main/resources/static/assets/index-2814df08.js
|
||||||
src/main/resources/static/assets/index-3ea31a03.css
|
framework/src/main/resources/static/assets/index-5282e30f.js
|
||||||
src/main/resources/static/assets/index-4a40522c.js
|
framework/src/main/resources/static/assets/index-9057b190.js
|
||||||
src/main/resources/static/assets/index-4af6c095.js
|
framework/src/main/resources/static/assets/index-968257e1.css
|
||||||
src/main/resources/static/assets/index-4b2c54eb.css
|
framework/src/main/resources/static/assets/index-b25f0d08.js
|
||||||
src/main/resources/static/assets/index-4e9a4a3c.css
|
framework/src/main/resources/static/assets/index-b98a9d85.js
|
||||||
src/main/resources/static/assets/index-4e36f11e.css
|
framework/src/main/resources/static/assets/index-bca4e108.js
|
||||||
src/main/resources/static/assets/index-5b909b30.js
|
framework/src/main/resources/static/assets/index-c2e52e75.js
|
||||||
src/main/resources/static/assets/index-6cfbc6e9.js
|
framework/src/main/resources/static/assets/index-c03bc2fe.js
|
||||||
src/main/resources/static/assets/index-6d369684.js
|
framework/src/main/resources/static/assets/index-cdc0bc49.css
|
||||||
src/main/resources/static/assets/index-9cdf102e.js
|
framework/src/main/resources/static/assets/index-ce8e85c4.js
|
||||||
src/main/resources/static/assets/index-013c92bf.css
|
framework/src/main/resources/static/assets/index-e5abaec0.js
|
||||||
src/main/resources/static/assets/index-45b24ee3.js
|
framework/src/main/resources/static/assets/index-e051e64c.js
|
||||||
src/main/resources/static/assets/index-58b7edbc.css
|
framework/src/main/resources/static/assets/index-f52936ec.js
|
||||||
src/main/resources/static/assets/index-97e2e5d7.js
|
framework/src/main/resources/static/assets/index1-5c7d9d99.js
|
||||||
src/main/resources/static/assets/index-336eb0cd.js
|
framework/src/main/resources/static/assets/index2-26043b81.js
|
||||||
src/main/resources/static/assets/index-1124a30a.js
|
framework/src/main/resources/static/assets/lbcz_xg-6b0694a6.js
|
||||||
src/main/resources/static/assets/index-5736aae9.js
|
framework/src/main/resources/static/assets/page.vue_vue_type_script_setup_true_lang-7a09a11a.js
|
||||||
src/main/resources/static/assets/index-23665d45.js
|
framework/src/main/resources/static/assets/personalCenter-a026f3ae.js
|
||||||
src/main/resources/static/assets/index-35744cd0.css
|
framework/src/main/resources/static/assets/PieChart-bffd7bcc.js
|
||||||
src/main/resources/static/assets/index-49408471.js
|
framework/src/main/resources/static/assets/RadarChart-e43ec971.js
|
||||||
src/main/resources/static/assets/index-a7bce641.css
|
framework/src/main/resources/static/assets/resize-24879ea2.js
|
||||||
src/main/resources/static/assets/index-adef366f.js
|
framework/src/main/resources/static/assets/sortable.esm-616533ae.js
|
||||||
src/main/resources/static/assets/index-dd0c8cf0.css
|
framework/src/main/resources/static/assets/tagsView-6df0ea3e.js
|
||||||
src/main/resources/static/assets/index-dd267244.js
|
framework/src/main/resources/static/assets/uploader-0562c8e7.js
|
||||||
src/main/resources/static/assets/index-de40e6e9.css
|
framework/src/main/resources/static/assets/uploader-4183de44.css
|
||||||
src/main/resources/static/assets/index-f9a887b2.css
|
|
||||||
src/main/resources/static/assets/index1-f104bedb.js
|
|
||||||
src/main/resources/static/assets/index2-8960589f.js
|
|
||||||
src/main/resources/static/assets/indicator-5b15d0d1.png
|
|
||||||
src/main/resources/static/assets/lbcz_sc-0ed76926.js
|
|
||||||
src/main/resources/static/assets/lbcz_td-b5984317.js
|
|
||||||
src/main/resources/static/assets/lbcz_xg-aaaefba0.js
|
|
||||||
src/main/resources/static/assets/logo-03d6d6da.png
|
|
||||||
src/main/resources/static/assets/page.vue_vue_type_script_setup_true_lang-b61c9f0c.js
|
|
||||||
src/main/resources/static/assets/personalCenter-035ae2fa.js
|
|
||||||
src/main/resources/static/assets/personalCenter-ad68cb91.css
|
|
||||||
src/main/resources/static/assets/PieChart-24d7f015.js
|
|
||||||
src/main/resources/static/assets/PieChart.vue_vue_type_script_setup_true_lang-d4bdc783.js
|
|
||||||
src/main/resources/static/assets/RadarChart-f3f7d950.js
|
|
||||||
src/main/resources/static/assets/RadarChart.vue_vue_type_script_setup_true_lang-c1ab7800.js
|
|
||||||
src/main/resources/static/assets/resize-76420810.js
|
|
||||||
src/main/resources/static/assets/rsaEncrypt-96cab0ea.js
|
|
||||||
src/main/resources/static/assets/sortable.esm-be94e56d.js
|
|
||||||
src/main/resources/static/assets/tagsView-23de2998.js
|
|
||||||
src/main/resources/static/assets/top_tx-3cab94c6.png
|
|
||||||
src/main/resources/static/assets/u287-9a3328bc.gif
|
|
||||||
src/main/resources/static/assets/uploader-769f4f98.js
|
|
||||||
src/main/resources/static/assets/uploader-ccfd78f9.css
|
|
||||||
|
|||||||
139
framework/docs/Java框架项目技术文档.md
Normal file
139
framework/docs/Java框架项目技术文档.md
Normal file
@ -0,0 +1,139 @@
|
|||||||
|
# 项目技术文档（framework 模块）
|
||||||
|
|
||||||
|
> 运行环境：Windows，Java 21（兼容 17+），Spring Boot 3.3.x
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
- 平台型后端服务，采用 `Spring Boot 3.3.x`，区分 `dev` / `server` 两种运行配置。
|
||||||
|
- 数据访问：`MyBatis-Plus 3.5.6` + `MyBatis 3.5.16`；连接池：`Druid`。
|
||||||
|
- 任务调度：`Quartz 2.3.2`；API 文档：`springdoc-openapi`（Swagger UI）。
|
||||||
|
- 缓存与基础设施：`Redis`、`WebSocket`、`Actuator`、验证码（`easy-captcha`）、加密（`jasypt`）、`ip2region`、`hutool` 等。
|
||||||
|
- 打包方式：可执行 `JAR`（已启用 `spring-boot-maven-plugin` 的 `repackage`）。默认开发端口 `8093`（`server` 可使用 `8090`）。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
- 仓库根（当前工作目录）：`D:\JavaProjectSpace\framework`
|
||||||
|
- 主要结构：
|
||||||
|
```
|
||||||
|
framework/
|
||||||
|
├── Dockerfile
|
||||||
|
├── frontend/ # 前端源码（Vite + TypeScript + Tailwind）
|
||||||
|
├── pom.xml # Maven 构建管理
|
||||||
|
└── src/
|
||||||
|
├── main/
|
||||||
|
│ ├── java/ # 业务代码（入口类在 com.yfd.platform.*）
|
||||||
|
│ └── resources/ # 配置与静态资源（static、配置 YAML、日志）
|
||||||
|
└── test/
|
||||||
|
└── java/ # 测试代码
|
||||||
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
- 前置要求：
|
||||||
|
- 安装 `JDK 21`（兼容 17+）、`Maven 3.9+`、`Git`、`Node.js 18+`（前端构建）。
|
||||||
|
- Windows 终端建议执行 `chcp 65001`，确保 UTF-8 编码输出。
|
||||||
|
- 构建后端：
|
||||||
|
- `mvn clean package -DskipTests`
|
||||||
|
- 本地运行（dev）：
|
||||||
|
- `java -jar target/platform-1.0.jar --spring.profiles.active=dev`
|
||||||
|
- 运行（server）：
|
||||||
|
- `java -jar target/platform-1.0.jar --spring.profiles.active=server`
|
||||||
|
- API 文档：
|
||||||
|
- 访问 `http://localhost:8093/swagger-ui/index.html`（以实际配置为准）
|
||||||
|
|
||||||
|
## 前端集成
|
||||||
|
- 自动构建：Maven 在 `generate-resources` 阶段调用 `npm install` 与 `npm run build:mvn`，产物输出到 `frontend/dist`。
|
||||||
|
- 静态资源复制：可通过 `maven-resources-plugin` 将 `frontend/dist` 复制至 `src/main/resources/static`，如需开启请将 POM 中该插件的 `<skip>` 设置为 `false` 或按需配置 Profile。
|
||||||
|
- 单独构建：在 `framework/frontend` 目录手动执行 `npm install && npm run build`，然后复制 `dist/` 到后端静态目录。
|
||||||
|
|
||||||
|
## 配置说明
|
||||||
|
- Profile 切换：通过 `--spring.profiles.active=<dev|server>` 激活环境。
|
||||||
|
- 关键属性：
|
||||||
|
- `file-space.system`：文件根路径，需在激活的 profile 中配置。
|
||||||
|
- `spring.datasource.druid.*`：数据库连接与池化参数。
|
||||||
|
- `server.port`：端口（`dev` 默认 8093，`server` 可使用 8090）。
|
||||||
|
- 编码与 JVM 参数：
|
||||||
|
- 统一 JVM 编码：`-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8`（POM 已配置）。
|
||||||
|
- PowerShell 输出建议设为 UTF-8：`chcp 65001`。
|
||||||
|
|
||||||
|
## 依赖与版本
|
||||||
|
- Spring：`spring-boot-starter-web`、`security`、`cache`、`websocket`、`actuator`。
|
||||||
|
- 数据访问：`mybatis-spring-boot-starter`、`mybatis-plus-boot-starter`、`druid-spring-boot-starter`、`mysql-connector-j`、`sqlite-jdbc`。
|
||||||
|
- 工具与增强：`hutool-all`、`poi` / `poi-ooxml`、`fastjson`、`freemarker`、`jsoup`、`jasypt`、`ip2region`、`easy-captcha`、`UserAgentUtils`、`nashorn-core`。
|
||||||
|
- 文档：`springdoc-openapi-starter-webmvc-ui`（Swagger UI）。
|
||||||
|
- 构建管控：`maven-enforcer-plugin`（JDK≥17、Maven≥3.6.3）。
|
||||||
|
|
||||||
|
## 数据库配置示例
|
||||||
|
- MySQL 连接：
|
||||||
|
```yaml
|
||||||
|
spring:
|
||||||
|
datasource:
|
||||||
|
druid:
|
||||||
|
master:
|
||||||
|
url: jdbc:mysql://<host>:3306/<db>?useUnicode=true&characterEncoding=UTF8&rewriteBatchedStatements=true&useSSL=false&allowPublicKeyRetrieval=true
|
||||||
|
username: <user>
|
||||||
|
password: <password>
|
||||||
|
```
|
||||||
|
- 授权建议：
|
||||||
|
```sql
|
||||||
|
CREATE USER 'appuser'@'%' IDENTIFIED BY 'StrongPassword!';
|
||||||
|
GRANT ALL PRIVILEGES ON <db>.* TO 'appuser'@'%';
|
||||||
|
FLUSH PRIVILEGES;
|
||||||
|
```
|
||||||
|
- Druid 健壮性：
|
||||||
|
```yaml
|
||||||
|
spring:
|
||||||
|
datasource:
|
||||||
|
druid:
|
||||||
|
initial-size: 0
|
||||||
|
test-on-borrow: false
|
||||||
|
test-while-idle: true
|
||||||
|
validation-query: SELECT 1
|
||||||
|
```
|
||||||
|
|
||||||
|
## 日志与监控
|
||||||
|
- 日志：Logback（UTF-8 输出），推荐格式：`%d [%thread] %-5level %logger{50} - %msg%n`。
|
||||||
|
- 监控：启用 Actuator，健康检查路径：`/actuator/health`。
|
||||||
|
- 建议接入集中日志与指标采集（ELK / Vector），监控数据库与线程池（Druid / Quartz）。
|
||||||
|
|
||||||
|
## 定时任务
|
||||||
|
- 默认 `RAMJobStore`（非集群、内存存储）。
|
||||||
|
- 如需持久化与集群，改用 `JdbcJobStore` 并配置数据源与表结构。
|
||||||
|
|
||||||
|
## 安全与鉴权
|
||||||
|
- 采用 JWT 进行鉴权（如 `jwtAuthenticationTokenFilter`，按实际代码启用）。
|
||||||
|
- 敏感配置（`jwt.secret`、数据库密码）通过环境变量或外部密钥管理。
|
||||||
|
- 生产环境建议启用 HTTPS 并使用强密钥。
|
||||||
|
|
||||||
|
## Docker 部署
|
||||||
|
- 端口：默认暴露 `8093`（dev）；可在 `server` profile 使用 `8090`。
|
||||||
|
- 基本流程：
|
||||||
|
- 构建镜像：`docker build -t projectframework-app:latest .`
|
||||||
|
- 运行（开发环境）：`docker run -d --name platform-app -p 8093:8093 -e SPRING_PROFILES_ACTIVE=dev projectframework-app:latest`
|
||||||
|
- 运行（服务器环境）：`docker run -d --name platform-app -p 8090:8090 -e SPRING_PROFILES_ACTIVE=server projectframework-app:latest`
|
||||||
|
- 文件空间挂载示例：`-v D:/data/file-space:/data/file-space -e FILE_SPACE_SYSTEM=/data/file-space`
|
||||||
|
|
||||||
|
## Git 使用（框架分支）
|
||||||
|
- 远程仓库：根据实际仓库地址配置（示例：`http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git`）。
|
||||||
|
- 分支建议：`main-framework`（稳定分支）、`develop-framework`（开发分支）。
|
||||||
|
- 常用命令：`git pull`、`git add .`、`git commit -m "<message>"`、`git push`。
|
||||||
|
- 提交署名：`git config user.name "<Your Name>"`，`git config user.email "<your@email>"`。
|
||||||
|
|
||||||
|
## CI/CD 建议
|
||||||
|
- CI 阶段：`mvn -B -DskipTests clean package`，配合单元测试与安全扫描（依赖检查、代码质量）。
|
||||||
|
- CD 阶段：推送镜像到私有仓库，使用环境变量注入敏感信息。
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
- 中文乱码：执行 `chcp 65001`，确保 `logback-spring.xml` 使用 UTF-8。
|
||||||
|
- `NoSuchMethodError`（MyBatis）：升级到 `MyBatis 3.5.16+` 并与 MP 版本匹配。
|
||||||
|
- 数据库 `Access denied`：校验账户密码与远程授权；必要时新建业务账户并放开 `3306`。
|
||||||
|
- 端口占用/启动失败：检查 `server.port` 与冲突端口；查看应用日志定位根因。
|
||||||
|
- 前端构建问题：如遇 npm 依赖警告或复制冲突，可先独立构建并手动复制 `dist/`。
|
||||||
|
|
||||||
|
## 变更日志（模板）
|
||||||
|
- `feat:` 新增功能说明
|
||||||
|
- `fix:` 缺陷修复说明
|
||||||
|
- `docs:` 文档更新说明
|
||||||
|
- `refactor:` 重构说明
|
||||||
|
- `perf:` 性能优化说明
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
如需扩展专题文档（接口规范、部署拓扑、参数字典等），请在 `docs/` 目录继续维护并与版本管理同步。
|
||||||
@ -1,52 +0,0 @@
|
|||||||
# 前后端一体化构建与打包说明
|
|
||||||
|
|
||||||
本文档说明如何在 Maven 构建流程中，先编译前端（pnpm），再编译后端（Java），并在 `package` 阶段将两者一起打包，使生成的可运行 `jar/war` 直接可以访问前端首页 `index.html`。
|
|
||||||
|
|
||||||
## 前置要求
|
|
||||||
- 已安装 JDK（推荐 17+）和 Maven（3.6.3+）。
|
|
||||||
- 已安装 Node.js（推荐 18+）与 pnpm（全局）：`npm i -g pnpm`。
|
|
||||||
- 当前项目结构：
|
|
||||||
- 后端（Spring Boot）：`app/pom.xml`，源码在 `app/src/main/java` 与资源在 `app/src/main/resources`。
|
|
||||||
- 前端（Vite/Vue）：位于 `app/frontend`，构建输出目录默认是 `app/frontend/dist`。
|
|
||||||
|
|
||||||
## 构建流程概览
|
|
||||||
在 `pom.xml` 中集成了以下步骤：
|
|
||||||
1. `generate-resources` 阶段：进入 `frontend` 目录，执行 `pnpm install --frozen-lockfile` 与 `pnpm run build`。
|
|
||||||
2. `process-resources` 阶段：将前端构建产物从 `frontend/dist` 复制到后端资源目录 `src/main/resources/static`。
|
|
||||||
3. 随后执行后端 Java 编译与打包，最终产出可运行的 `jar/war`。
|
|
||||||
|
|
||||||
这样在运行后端时，Spring Boot 会从类路径的 `static` 目录自动提供 `index.html` 作为欢迎页入口（访问根路径 `/` 即可看到前端页面）。
|
|
||||||
|
|
||||||
## 关键 POM 配置（摘要）
|
|
||||||
已经在 `app/pom.xml` 的 `<build><plugins>` 中加入：
|
|
||||||
- `exec-maven-plugin`：在 Java 编译前执行 pnpm 安装与构建。
|
|
||||||
- `maven-resources-plugin`：复制前端构建产物到 `src/main/resources/static`。
|
|
||||||
|
|
||||||
无需手动改动目录，只需按下述命令执行即可。
|
|
||||||
|
|
||||||
## 常用命令
|
|
||||||
- 开发运行（跳过测试）：`mvn -DskipTests spring-boot:run`
|
|
||||||
- 如需指定开发配置：`mvn -DskipTests -Dspring-boot.run.profiles=dev spring-boot:run`
|
|
||||||
- 构建打包（跳过测试）：`mvn -DskipTests package`
|
|
||||||
- 构建过程中会自动执行前端构建并拷贝到后端资源。
|
|
||||||
|
|
||||||
## 运行与访问
|
|
||||||
- 运行可执行包（以 `war` 为例，`artifactId=platform`，`version=1.0`）：
|
|
||||||
- 默认运行：`java -jar target/platform-1.0.war`
|
|
||||||
- 指定 dev 配置：`java -Dspring.profiles.active=dev -jar target/platform-1.0.war`
|
|
||||||
- 访问：
|
|
||||||
- 若启用 `dev` 配置并端口为 `8093`：`http://localhost:8093/`
|
|
||||||
- 若使用默认端口（例如 `18080`）：`http://localhost:18080/`
|
|
||||||
|
|
||||||
> 说明：Spring Boot 会自动将 `classpath:/static/index.html` 作为欢迎页，访问根路径即可进入前端入口页面。
|
|
||||||
|
|
||||||
## 注意事项
|
|
||||||
- 请确保 `pnpm` 可在构建机/开发机的环境变量中直接调用。
|
|
||||||
- 若前端构建输出目录（`dist`）有自定义，请同步更新 POM 中的复制路径。
|
|
||||||
- 如前端使用路由的 `history` 模式并期望后端兜底到 `index.html`，可按需添加后端控制器或使用前端服务器侧配置（当前方案以静态欢迎页为主）。
|
|
||||||
|
|
||||||
## 故障排查
|
|
||||||
- 构建失败（找不到 `pnpm`）：确认已安装并可在命令行执行 `pnpm -v`。
|
|
||||||
- 页面乱码：已在 POM 配置统一 JVM 编码为 `UTF-8`；在 Windows PowerShell 终端也应设置为 `UTF-8`。
|
|
||||||
|
|
||||||
完成上述配置后，只需使用 Maven 的标准命令，即可实现前后端一体化构建和打包运行。
|
|
||||||
@ -1,161 +0,0 @@
|
|||||||
# 项目技术文档
|
|
||||||
|
|
||||||
> 项目：ProjectFrameWork2025（模块：`app` / Java 后端）
|
|
||||||
> 运行环境：Windows，Java 21（兼容 17+），Spring Boot 3.x
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
- 平台型后端服务，采用 `Spring Boot 3.x`，区分 `dev` / `server` 两种运行配置。
|
|
||||||
- 数据访问使用 `MyBatis-Plus 3.5.6` 与 `MyBatis 3.5.16`，连接池为 `Druid`。
|
|
||||||
- 任务调度使用 `Quartz 2.3.2`；API 文档采用 `springdoc-openapi` / Swagger UI。
|
|
||||||
- 支持 WAR 包运行，亦可容器化部署；默认开发端口 `8093`（`server` 可使用 `8090`）。
|
|
||||||
|
|
||||||
## 目录结构
|
|
||||||
- 仓库根（当前工作目录）：`D:\Trae_space\ProjectFrameWork2025\app`
|
|
||||||
- 主要结构：
|
|
||||||
```
|
|
||||||
app/
|
|
||||||
├── .gitignore
|
|
||||||
├── Dockerfile
|
|
||||||
├── frontend/ # 前端说明或资源
|
|
||||||
│ └── readme.md
|
|
||||||
├── pom.xml # Maven 构建管理
|
|
||||||
└── src/
|
|
||||||
├── main/
|
|
||||||
│ ├── java/ # 业务代码（入口类在 com.yfd.platform.*）
|
|
||||||
│ └── resources/ # 配置与静态资源
|
|
||||||
└── test/
|
|
||||||
└── java/ # 测试代码
|
|
||||||
```
|
|
||||||
|
|
||||||
## 快速开始
|
|
||||||
- 前置要求：
|
|
||||||
- 安装 `JDK 21`（兼容 17+），`Maven 3.9+`，`Git`。
|
|
||||||
- Windows 终端执行 `chcp 65001`，确保 UTF-8 编码输出。
|
|
||||||
- 构建后端：
|
|
||||||
- `mvn clean package -DskipTests`
|
|
||||||
- 本地运行（dev）：
|
|
||||||
- `java -jar target/platform-1.0.war --spring.profiles.active=dev`
|
|
||||||
- 运行（server）：
|
|
||||||
- `java -jar target/platform-1.0.war --spring.profiles.active=server`
|
|
||||||
- API 文档：
|
|
||||||
- 默认访问 `http://localhost:8093/swagger-ui/index.html`（以实际配置为准）
|
|
||||||
|
|
||||||
## 配置说明
|
|
||||||
- Profile 切换：
|
|
||||||
- 通过 `--spring.profiles.active=<dev|server>` 激活环境。
|
|
||||||
- 关键属性：
|
|
||||||
- `file-space.system`：文件根路径，需在激活的 profile 中配置。
|
|
||||||
- `spring.datasource.druid.*`：数据库连接参数与池化配置。
|
|
||||||
- `server.port`：端口（`dev` 默认 8093，`server` 可使用 8090）。
|
|
||||||
- VS Code/终端编码建议：
|
|
||||||
- 启动参数加入 `-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8`。
|
|
||||||
- 终端执行 `chcp 65001`，PowerShell 输出设置为 UTF-8。
|
|
||||||
|
|
||||||
## 依赖与版本
|
|
||||||
- `Spring Boot 3.x`
|
|
||||||
- `MyBatis-Plus 3.5.6`（依赖 `MyBatis 3.5.16+`，需有 `Configuration.parsePendingResultMaps(boolean)`）
|
|
||||||
- `Druid` 数据源
|
|
||||||
- `Quartz 2.3.2`
|
|
||||||
- `springdoc-openapi` / Swagger UI
|
|
||||||
- 日志：`Logback`（UTF-8 输出，`logback-spring.xml`）
|
|
||||||
|
|
||||||
## 数据库配置
|
|
||||||
- MySQL 连接示例：
|
|
||||||
```yaml
|
|
||||||
spring:
|
|
||||||
datasource:
|
|
||||||
druid:
|
|
||||||
master:
|
|
||||||
url: jdbc:mysql://<host>:3306/<db>?useUnicode=true&characterEncoding=UTF8&rewriteBatchedStatements=true&useSSL=false&allowPublicKeyRetrieval=true
|
|
||||||
username: <user>
|
|
||||||
password: <password>
|
|
||||||
```
|
|
||||||
- 远程授权建议：
|
|
||||||
```sql
|
|
||||||
CREATE USER 'appuser'@'%' IDENTIFIED BY 'StrongPassword!';
|
|
||||||
GRANT ALL PRIVILEGES ON <db>.* TO 'appuser'@'%';
|
|
||||||
FLUSH PRIVILEGES;
|
|
||||||
```
|
|
||||||
- Druid 健壮性：
|
|
||||||
```yaml
|
|
||||||
spring:
|
|
||||||
datasource:
|
|
||||||
druid:
|
|
||||||
initial-size: 0
|
|
||||||
test-on-borrow: false
|
|
||||||
test-while-idle: true
|
|
||||||
validation-query: SELECT 1
|
|
||||||
```
|
|
||||||
|
|
||||||
## 日志
|
|
||||||
- 控制台与文件统一 UTF-8 输出：
|
|
||||||
- 控制台 `ConsoleAppender`，文件 `RollingFileAppender`（按日滚动，保留 30 天）。
|
|
||||||
- 推荐日志格式：`%d [%thread] %-5level %logger{50} - %msg%n`。
|
|
||||||
|
|
||||||
## 定时任务
|
|
||||||
- 默认 `RAMJobStore`（非集群、内存存储）。
|
|
||||||
- 如需持久化与集群，改用 `JdbcJobStore` 并配置数据源与表结构。
|
|
||||||
|
|
||||||
## 安全与鉴权
|
|
||||||
- 使用 `JWT` 过滤器进行鉴权（如 `jwtAuthenticationTokenFilter`）。
|
|
||||||
- 敏感配置（`jwt.secret`、数据库密码）建议通过环境变量或外部密钥管理。
|
|
||||||
- 生产环境必须启用 HTTPS 并使用强密钥。
|
|
||||||
|
|
||||||
## API 文档
|
|
||||||
- 启用 `swagger-ui.enabled: true`。
|
|
||||||
- 访问路径通常为 `http://<host>:<port>/swagger-ui/index.html`。
|
|
||||||
|
|
||||||
## Docker 部署
|
|
||||||
- `Dockerfile` 已暴露端口 `8093`：
|
|
||||||
- 构建镜像：`docker build -t projectframework2025-app:latest .`
|
|
||||||
- 运行（开发环境）：
|
|
||||||
- `docker run -d --name platform-app -p 8093:8093 -e SPRING_PROFILES_ACTIVE=dev projectframework2025-app:latest`
|
|
||||||
- 运行（服务器环境）：
|
|
||||||
- `docker run -d --name platform-app -p 8090:8090 -e SPRING_PROFILES_ACTIVE=server projectframework2025-app:latest`
|
|
||||||
- 如需挂载文件空间：
|
|
||||||
- `-v D:/data/file-space:/data/file-space -e FILE_SPACE_SYSTEM=/data/file-space`
|
|
||||||
|
|
||||||
## 前端
|
|
||||||
- 前端说明见 `frontend/readme.md`。如需联调，请统一跨域与鉴权策略。
|
|
||||||
|
|
||||||
## Git 使用
|
|
||||||
- 远程仓库：`http://121.37.111.42:3000/ThbTech/ProjectFrameWork2025.git`
|
|
||||||
- 主分支：`main`
|
|
||||||
- 常用命令：
|
|
||||||
- `git pull`、`git add .`、`git commit -m "<message>"`、`git push`
|
|
||||||
- 提交署名：
|
|
||||||
- `git config user.name "<Your Name>"`
|
|
||||||
- `git config user.email "<your@email>"`
|
|
||||||
|
|
||||||
## 常见问题
|
|
||||||
- 中文乱码：
|
|
||||||
- 执行 `chcp 65001`，确保 `logback-spring.xml` 使用 UTF-8。
|
|
||||||
- `NoSuchMethodError`（MyBatis）：
|
|
||||||
- 升级 `MyBatis` 至 `3.5.16+` 并与 MP 版本匹配。
|
|
||||||
- 数据库 `Access denied`：
|
|
||||||
- 校验账户密码与远程授权；必要时新建业务账户并放开 `3306`。
|
|
||||||
- 端口占用/启动失败：
|
|
||||||
- 检查 `server.port` 与冲突端口；查看应用日志定位根因。
|
|
||||||
|
|
||||||
## 运维与监控
|
|
||||||
- 建议接入 `Spring Boot Actuator`：`/actuator/health`。
|
|
||||||
- 配合日志轮转与集中采集（ELK/Vector），区分环境日志路径。
|
|
||||||
- 监控数据库与线程池指标（Druid/Quartz）。
|
|
||||||
|
|
||||||
## CI/CD 建议
|
|
||||||
- 在 CI 阶段执行：
|
|
||||||
- `mvn -B -DskipTests clean package`
|
|
||||||
- 单元测试与安全扫描（依赖检查、代码质量）
|
|
||||||
- 在 CD 阶段：
|
|
||||||
- 推送镜像到私有仓库，环境变量注入敏感信息。
|
|
||||||
|
|
||||||
## 变更日志（示例模板）
|
|
||||||
- `feat:` 新增功能说明
|
|
||||||
- `fix:` 缺陷修复说明
|
|
||||||
- `docs:` 文档更新说明
|
|
||||||
- `refactor:` 重构说明
|
|
||||||
- `perf:` 性能优化说明
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
如需扩展专题文档（接口规范、部署拓扑、参数字典等），建议在 `docs/` 目录继续维护并与版本管理同步。
|
|
||||||
@ -11,7 +11,7 @@
|
|||||||
<groupId>com.yfd</groupId>
|
<groupId>com.yfd</groupId>
|
||||||
<artifactId>platform</artifactId>
|
<artifactId>platform</artifactId>
|
||||||
<version>1.0</version>
|
<version>1.0</version>
|
||||||
<packaging>war</packaging>
|
<packaging>jar</packaging>
|
||||||
<name>platform</name>
|
<name>platform</name>
|
||||||
<description>springboot 项目基础框架3.0</description>
|
<description>springboot 项目基础框架3.0</description>
|
||||||
<properties>
|
<properties>
|
||||||
@ -111,12 +111,7 @@
|
|||||||
<version>${guava.version}</version>
|
<version>${guava.version}</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
|
|
||||||
<!-- spring-内置Tomcat-->
|
<!-- 对于 jar 包，spring-boot-starter-web 已包含嵌入式 Tomcat，无需显式 provided -->
|
||||||
<dependency>
|
|
||||||
<groupId>org.springframework.boot</groupId>
|
|
||||||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
|
||||||
<scope>provided</scope>
|
|
||||||
</dependency>
|
|
||||||
|
|
||||||
<!-- spring-quartz任务-->
|
<!-- spring-quartz任务-->
|
||||||
<dependency>
|
<dependency>
|
||||||
@ -367,6 +362,9 @@
|
|||||||
<goal>copy-resources</goal>
|
<goal>copy-resources</goal>
|
||||||
</goals>
|
</goals>
|
||||||
<configuration>
|
<configuration>
|
||||||
|
<skip>true</skip>
|
||||||
|
<overwrite>true</overwrite>
|
||||||
|
<failOnError>false</failOnError>
|
||||||
<outputDirectory>${project.basedir}/src/main/resources/static</outputDirectory>
|
<outputDirectory>${project.basedir}/src/main/resources/static</outputDirectory>
|
||||||
<resources>
|
<resources>
|
||||||
<resource>
|
<resource>
|
||||||
@ -390,6 +388,7 @@
|
|||||||
<goal>process-asciidoc</goal>
|
<goal>process-asciidoc</goal>
|
||||||
</goals>
|
</goals>
|
||||||
<configuration>
|
<configuration>
|
||||||
|
<skip>true</skip>
|
||||||
<backend>html</backend>
|
<backend>html</backend>
|
||||||
<doctype>book</doctype>
|
<doctype>book</doctype>
|
||||||
</configuration>
|
</configuration>
|
||||||
@ -411,6 +410,13 @@
|
|||||||
</exclude>
|
</exclude>
|
||||||
</excludes>
|
</excludes>
|
||||||
</configuration>
|
</configuration>
|
||||||
|
<executions>
|
||||||
|
<execution>
|
||||||
|
<goals>
|
||||||
|
<goal>repackage</goal>
|
||||||
|
</goals>
|
||||||
|
</execution>
|
||||||
|
</executions>
|
||||||
</plugin>
|
</plugin>
|
||||||
<!-- 固化构建规则：Maven Enforcer -->
|
<!-- 固化构建规则：Maven Enforcer -->
|
||||||
<plugin>
|
<plugin>
|
||||||
@ -439,12 +445,7 @@
|
|||||||
</execution>
|
</execution>
|
||||||
</executions>
|
</executions>
|
||||||
</plugin>
|
</plugin>
|
||||||
</plugins>
|
|
||||||
</build>
|
|
||||||
|
|
||||||
<!-- 额外生成 classes JAR，便于其他业务工程作为依赖引用 -->
|
<!-- 额外生成 classes JAR，便于其他业务工程作为依赖引用 -->
|
||||||
<build>
|
|
||||||
<plugins>
|
|
||||||
<plugin>
|
<plugin>
|
||||||
<groupId>org.apache.maven.plugins</groupId>
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
<artifactId>maven-jar-plugin</artifactId>
|
<artifactId>maven-jar-plugin</artifactId>
|
||||||
@ -455,6 +456,9 @@
|
|||||||
<goals>
|
<goals>
|
||||||
<goal>jar</goal>
|
<goal>jar</goal>
|
||||||
</goals>
|
</goals>
|
||||||
|
<configuration>
|
||||||
|
<classifier>plain</classifier>
|
||||||
|
</configuration>
|
||||||
</execution>
|
</execution>
|
||||||
</executions>
|
</executions>
|
||||||
</plugin>
|
</plugin>
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user