JavaProjectRepo/docs/TECHNICAL_PLAN.md

项目技术方案说明

项目：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 连接示例：

  spring:
    datasource:
      druid:
        master:
          url: jdbc:mysql://<host>:3306/<db>?useUnicode=true&characterEncoding=UTF8&rewriteBatchedStatements=true&useSSL=false&allowPublicKeyRetrieval=true
          username: <user>
          password: <password>
  

• 远程访问与授权建议：
  • 为应用账户授权外部访问：

    CREATE USER 'appuser'@'%' IDENTIFIED BY 'StrongPassword!';
    GRANT ALL PRIVILEGES ON <db>.* TO 'appuser'@'%';
    FLUSH PRIVILEGES;
    

  • 确保 MySQL bind-address 放开远程，防火墙/安全组放行 3306。
• Druid 健壮性配置建议（数据库未就绪时减少报错）：

  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. 构建与运行

• 构建：

  mvn -f java/pom.xml clean package -DskipTests
  

• 启动（dev）：

  java -jar java/target/platform-1.0.war --spring.profiles.active=dev
  

• 启动（server）：

  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/ 下继续补充专题文档。