root
7de982d150
feat: add Actuator/Micrometer Prometheus and Springdoc defaults build(app): fix MyBatis dependency convergence; relax enforcer for Maven 3.6.3 chore: add quartz.properties example and Dockerfile; remove duplicate websocket dep
143 lines
6.1 KiB
Markdown
143 lines
6.1 KiB
Markdown
# 项目技术方案说明
|
||
|
||
> 项目：ProjectFrameWork2025（模块：`java/platform`）
|
||
> 运行环境：Windows，Java 21（兼容 17+），Spring Boot 3.x
|
||
|
||
## 1. 项目概述
|
||
- 平台型后端服务，基于 Spring Boot 构建，采用分环境配置（`dev`/`server`）。
|
||
- 数据访问使用 MyBatis-Plus + Druid 连接池，计划支持 Redis、定时任务（Quartz），并暴露 Swagger UI 便于接口联调。
|
||
- 支持 WAR 包运行（内嵌 Tomcat 或外部容器）。
|
||
|
||
## 2. 技术栈与版本
|
||
- 核心框架：`Spring Boot 3.x`
|
||
- ORM：`MyBatis-Plus 3.5.6`
|
||
- MyBatis 核心：`3.5.16`（与 MP 3.5.6 兼容，解决 `parsePendingResultMaps(boolean)` 缺失）
|
||
- 数据源：`Druid`
|
||
- 任务调度：`Quartz 2.3.2`
|
||
- API 文档：`springdoc-openapi` 或 `Swagger UI`（YAML 中 `swagger-ui.enabled: true`）
|
||
- 日志：`Logback`（`logback-spring.xml`，统一 UTF-8 编码）
|
||
- 语言与 JDK：推荐 `Java 17+`，当前运行 `Java 21.0.5`
|
||
|
||
## 3. 模块与目录结构
|
||
```
|
||
ProjectFrameWork2025/
|
||
├── .vscode/launch.json # VS Code 启动配置（UTF-8 调试）
|
||
└── java/
|
||
├── pom.xml # Maven 构建与依赖管理
|
||
├── src/main/java # 业务代码（入口：com.yfd.platform.PlatformApplication）
|
||
├── src/main/resources # 配置与静态资源
|
||
│ ├── application.yml # 通用配置（激活 profile）
|
||
│ ├── application-dev.yml # 开发环境配置
|
||
│ ├── application-server.yml # 服务器环境配置
|
||
│ └── logback-spring.xml # 统一日志编码与输出格式
|
||
└── target/platform-1.0.war # 打包产物（可直接运行）
|
||
```
|
||
|
||
## 4. 配置管理策略
|
||
- Profile：通过 `--spring.profiles.active=<dev|server>` 切换。
|
||
- 关键属性：
|
||
- `file-space.system`：文件空间根路径，必须在激活的 profile 中配置（已补充到 `application-server.yml`）。
|
||
- `spring.datasource.druid.*`：数据库连接池配置（URL/用户名/密码）。
|
||
- `server.port`：端口（`dev` 默认 8093，`server` 默认 8090）。
|
||
- VS Code 与终端编码：
|
||
- 在 `.vscode/launch.json` 中设置：
|
||
- `vmArgs: -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8`
|
||
- `env.JAVA_TOOL_OPTIONS` 与 `env.JDK_JAVA_OPTIONS` 设为 UTF-8
|
||
- `console: integratedTerminal`
|
||
- 终端运行前执行：`chcp 65001`，并确保 PowerShell 输出编码为 UTF-8
|
||
|
||
## 5. 数据库与数据源
|
||
- 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;
|
||
```
|
||
- 确保 MySQL `bind-address` 放开远程，防火墙/安全组放行 `3306`。
|
||
- Druid 健壮性配置建议（数据库未就绪时减少报错）：
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
druid:
|
||
initial-size: 0
|
||
test-on-borrow: false
|
||
test-while-idle: true
|
||
validation-query: SELECT 1
|
||
```
|
||
|
||
## 6. ORM 与持久化
|
||
- DAO 层使用 MyBatis-Plus，简化 CRUD；Mapper XML 与注解可共存。
|
||
- 版本兼容性已确认：`MP 3.5.6` 依赖 `MyBatis 3.5.16+` 的 `Configuration.parsePendingResultMaps(boolean)`。
|
||
- 如遇 `NoSuchMethodError`，优先检查 `pom.xml` 中 MyBatis 版本与依赖冲突。
|
||
|
||
## 7. 日志方案
|
||
- 使用 `logback-spring.xml` 统一控制台与文件日志编码为 UTF-8：
|
||
- 控制台：`ConsoleAppender` + `PatternLayoutEncoder`（`charset: UTF-8`）
|
||
- 文件：`RollingFileAppender` 按日滚动，保留 30 天历史
|
||
- 日志格式：`%d [%thread] %-5level %logger{50} - %msg%n`
|
||
- 在 Windows 终端执行：`chcp 65001`，并设置 `JAVA_TOOL_OPTIONS` 保证 JVM 使用 UTF-8。
|
||
|
||
## 8. 定时任务
|
||
- Quartz 持久化策略当前为 `RAMJobStore`（非集群、内存存储）。
|
||
- 如需持久化与集群，可改为 `JdbcJobStore` 并配置数据源与表结构。
|
||
|
||
## 9. 安全与鉴权
|
||
- 采用 `JWT` 方案（存在 `jwtAuthenticationTokenFilter` 等 Bean），通过过滤器进行请求鉴权。
|
||
- 建议：
|
||
- 将敏感配置（`jwt.secret`、数据库密码）置于环境变量或外部密钥管理。
|
||
- 开发环境使用弱密钥仅限本地，生产需强密钥并开启 HTTPS。
|
||
|
||
## 10. API 文档与联调
|
||
- 启用 Swagger UI（`swagger-ui.enabled: true`）。
|
||
- 访问路径通常为：`/swagger-ui/index.html`（具体以 springdoc 配置为准）。
|
||
|
||
## 11. 构建与运行
|
||
- 构建：
|
||
```bash
|
||
mvn -f java/pom.xml clean package -DskipTests
|
||
```
|
||
- 启动（dev）：
|
||
```bash
|
||
java -jar java/target/platform-1.0.war --spring.profiles.active=dev
|
||
```
|
||
- 启动（server）：
|
||
```bash
|
||
java -jar java/target/platform-1.0.war --spring.profiles.active=server
|
||
```
|
||
- VS Code 调试：选择配置 `Spring Boot-PlatformApplication<platform>` 启动。
|
||
|
||
## 12. 常见问题与排错
|
||
- 控制台中文乱码：
|
||
- 终端执行 `chcp 65001`，VS Code 配置 UTF-8，`logback-spring.xml` 强制 UTF-8。
|
||
- MyBatis `NoSuchMethodError`：
|
||
- 升级 MyBatis 至 `3.5.16+` 与 MP 版本匹配。
|
||
- 数据库 `Access denied`：
|
||
- 校验账户密码与远程授权；必要时新建业务账户并放开 `3306`。
|
||
- 占用端口/启动失败：
|
||
- 检查 `server.port` 与端口冲突；查看应用日志根因。
|
||
|
||
## 13. 运维与监控建议
|
||
- 接入 Spring Boot Actuator 暴露健康检查端点（`/actuator/health`）。
|
||
- 结合日志轮转与集中采集（ELK/Vector），按环境区分日志路径。
|
||
- 数据库连接与线程池指标纳入监控（Druid/Quartz）。
|
||
|
||
## 14. 后续规划
|
||
- 增加 Redis 缓存与会话支持。
|
||
- Quartz 改为持久化存储以支持任务恢复与集群。
|
||
- 完善 CI/CD 流程，增加测试与安全检查。
|
||
- 引入统一配置中心（如 Nacos/Spring Cloud Config）管理多环境配置。
|
||
|
||
---
|
||
|
||
如需针对该方案进行扩展（例如新增模块、接口规范或部署拓扑图），可在 `docs/` 下继续补充专题文档。 |