9.1 KiB
9.1 KiB
系统代码结构框架规划
1. 目标与原则
1.1 业务目标
- framework 模块：沉淀系统级通用能力（安全、认证、权限、日志、任务调度、文件、缓存、监控、通用工具等），不依赖任何业务代码，可被 N 个业务模块复用
- business-css 模块：仅聚焦“临界事故情景分析”业务，零系统代码，所有共性能力通过 framework 提供
1.2 设计原则
| 原则 | 落地要求 |
|---|---|
| 高内聚低耦合 | 业务模块只依赖 framework，framework 绝不反向依赖业务 |
| DRY | 同一能力只在一个地方实现（framework），禁止业务模块重复造轮子 |
| 可演进 | 后续新增业务模块（business-xxx）零改动即可接入现有能力 |
| 可维护 | 通过 Maven 多模块 + 分层分包，让“修改点”收敛到最小范围 |
2. 多模块 Maven 结构（聚合工程）
d:\JavaProjectSpace (root pom, packaging=pom)
├── framework (com.yfd:platform:1.0)
│ ├── src/main/java
│ ├── src/main/resources
│ └── pom.xml
├── business-css (com.yfd:business-css:1.0-SNAPSHOT)
│ ├── src/main/java
│ ├── src/main/resources
│ └── pom.xml
└── pom.xml ← modules 声明
3. framework 模块职责与目录
3.1 职责矩阵
| 能力域 | 是否包含 | 说明 |
|---|---|---|
| 统一配置 | ✅ | 数据源、Redis、Jackson、MyBatis-Plus、Swagger、监控、日志、加解密等 |
| 安全 & 认证 | ✅ | Spring Security + JWT 过滤器、权限注解、匿名访问标记 |
| 系统级 API | ✅ | 用户/角色/菜单/部门/字典/日志/文件/消息/定时任务等 |
| 通用工具 | ✅ | RSA、Excel、IP 归属、验证码、异步线程池、缓存封装 |
| 前端静态 | ✅ | 仅提供全局通用静态（如 404、error、swagger-ui）；业务页面由业务模块提供 |
| 业务代码 | ❌ | 禁止出现任何与“临界事故”相关的类、表、API |
3.2 代码分层
src/main/java/com/yfd/platform
├── config # 自动配置类（DataSource、Security、Async、Redis、MyBatisPlus...）
│ ├── bean # @ConfigurationProperties 配置属性类
│ ├── thread # 线程池配置
│ └── ...
├── constant # 系统级常量
├── exception # 全局异常 + 自定义业务异常基类
├── annotation # 系统注解（@Log、@AnonymousAccess 等）
├── aspect # 系统级 AOP（操作日志、权限校验）
├── datasource # 动态数据源切换（若业务需要多库）
├── utils # 通用工具（RSA、Excel、IP、验证码、SpringContextHolder...）
├── system # 系统管理域（用户/角色/菜单/部门/字典/日志/文件/消息/任务）
│ ├── domain # PO / DTO / VO（注意：仅系统表）
│ ├── mapper # MyBatis-Plus Mapper
│ ├── service # Service 接口 + 实现
│ └── controller # REST API（/api/system/*）
└── component # 非业务组件（WebSocket、SSE、任务执行器）
3.3 资源目录
src/main/resources
├── mapper/system/*.xml # 仅系统表 SQL 映射
├── static # 全局通用静态（swagger、error、login 背景图等）
├── banner.txt / logback.xml # 统一启动 Banner & 日志
└── application*.yml # 框架级默认配置（数据源、redis、监控、线程池...）
注意：framework 绝不放业务 SQL、业务静态页面；业务资源全部下沉到业务模块。
4. business-css 模块职责与目录
4.1 职责矩阵
| 能力域 | 是否包含 | 说明 |
|---|---|---|
| 业务领域代码 | ✅ | 临界事故实体、服务、控制器、DTO、Mapper XML |
| 业务静态页面 | ✅ | 仅与“临界事故”相关的页面、图片、图标 |
| 系统能力 | ❌ | 通过依赖 framework 获得，禁止复制粘贴 |
| 系统表 SQL | ❌ | 系统表由 framework 提供，业务模块只写业务表 |
4.2 代码分层
src/main/java/com/yfd/business/css
├── model # 业务实体 / DTO / VO（仅业务表）
├── mapper # MyBatis-Plus Mapper 接口
├── service # 业务服务接口 + 实现
├── controller # REST API（/api/css/* 或 /api/simulation/*）
└── *Application.java
4.3 资源目录
src/main/resources
├── mapper/css/*.xml # 仅业务表 SQL 映射
├── static/css/* # 业务静态（页面、图片、图标）
└── application.yml # 业务个性化配置（端口、数据源 URL、业务开关）
5. 依赖关系与 Maven 坐标
| 模块 | 坐标 | 依赖 |
|---|---|---|
| framework | com.yfd:platform:1.0 | 无业务依赖，仅技术栈（Spring Boot、MyBatis-Plus、Security、Redis...） |
| business-css | com.yfd:business-css:1.0-SNAPSHOT | com.yfd:platform:1.0（plain classifier） |
plain classifier：framework 通过
maven-jar-plugin额外生成platform-1.0-plain.jar，仅含 classes & resources，不含 Spring-Boot 启动器，避免业务模块引入重复主类。
6. 配置隔离策略
| 配置项 | 放在哪里 | 示例 |
|---|---|---|
| 数据源、Redis、MyBatis、线程池、监控、日志 | framework | framework/src/main/resources/application.yml |
| 业务开关、业务参数、端口、上下文 | business-css | business-css/src/main/resources/application.yml |
| 环境差异化（dev/prod） | 各自模块 | application-dev.yml、application-prod.yml |
启动顺序：业务模块的
application.yml会覆盖 framework 的同名 key，实现“共性 + 个性”组合。
7. 静态资源隔离策略
| 资源类型 | 放在哪里 | 访问路径 | 说明 |
|---|---|---|---|
| 全局通用（swagger、error、login 背景） | framework | /error、/swagger-ui.html |
所有业务模块共用 |
| 业务页面（.html、.js、*.png） | business-css | /css/index.html |
仅当前业务使用 |
| 业务接口 | business-css | /api/simulation/* |
REST 无静态冲突 |
最佳实践：业务静态统一放在
/static/{业务简称}/目录，避免文件名冲突。
8. 数据库隔离策略
| 表归属 | 模块 | 说明 |
|---|---|---|
| 系统表（sys_user、sys_role、sys_menu...） | framework | 由 framework 提供 Mapper & XML，业务模块只读/调用 Service |
| 业务表（css_simulation、css_record...） | business-css | 由业务模块自行创建 Mapper & XML，禁止写入系统表 SQL |
多业务共享同一库：系统表前缀
sys_，业务表前缀css_、xxx_，物理共存但逻辑隔离。
9. 启动与部署
9.1 开发阶段
# 1. 安装 framework 到本地仓库
mvn -DskipTests clean install -pl framework
# 2. 启动业务模块（自动依赖 framework）
mvn -DskipTests spring-boot:run -pl business-css
9.2 交付阶段
# 一次性打包所有模块
mvn -DskipTests clean package
# 产物
framework/target/platform-1.0.jar # 系统后台服务（可选独立部署）
business-css/target/business-css-1.0-SNAPSHOT.jar # 业务服务（含内嵌 Tomcat）
部署方式：
- 轻量场景：只部署
business-css-1.0-SNAPSHOT.jar，内嵌 framework 能力- 分离场景：独立部署
platform-1.0.jar（提供统一后台），再部署多个业务 jar，网关统一路由
10. 横向扩展：新增业务模块（business-xxx）
- 新建 Maven 模块
business-xxx，parent 指向根 pom - 依赖
com.yfd:platform:1.0:plain - 包名
com.yfd.business.xxx - 表前缀
xxx_ - 静态资源
/static/xxx/ - API 前缀
/api/xxx/ - 端口
8083（避免与 css 冲突）
零改动接入：无需复制任何系统代码，仅需以上 7 步即可拥有完整的用户/权限/日志/文件/任务能力。
11. 常见误区与禁止项
| 误区 | 正确做法 |
|---|---|
| 把系统表 SQL 写在业务模块 | 系统 SQL 只能放在 framework/mapper/system |
| 把系统静态页面（login、404）复制到业务模块 | 全局静态统一收敛到 framework/static |
业务模块直接依赖 platform-1.0.jar（可执行） |
使用 platform-1.0-plain.jar（仅 classes） |
| framework 里出现“css”字样 | framework 必须业务无关，出现业务代码即重构 |
| 多个业务模块端口重复 | 每个业务模块独立端口（8082、8083...） |
12. 演进路线
| 阶段 | 动作 |
|---|---|
| 当前 | 单库多模块，Maven 聚合，静态/配置/表逻辑隔离 |
| 下一步 | 引入 Spring Cloud Gateway，统一路由 & 鉴权，业务模块只关注领域逻辑 |
| 未来 | 业务模块拆分为独立微服务（docker-compose/k8s），framework 作为共享 lib 或 sidecar |
一句话总结：framework 做“平台”，business-css 做“产品”；平台沉淀，产品迭代，互不污染，横向复制。