📚 课程目录第2章模块边界定义

2. 模块边界定义：什么是模块边界、高内聚低耦合原则在导出模块中的应用、边界划分的常见误区

2.1 什么是模块边界

模块边界是软件系统中一个模块对外提供的职责范围与交互契约。在报表导出场景中，模块边界定义了“导出模块负责什么、不负责什么”，以及它与其他模块（如数据查询、权限控制、存储服务）之间的通信协议。

  核心观点：模块边界不是物理文件的分割线，而是职责与依赖的契约。边界清晰时，导出模块可以独立开发、测试、部署和替换。

模块边界通常由以下三个维度构成：

维度	说明	导出模块示例
职责边界	模块必须完成的核心功能集合	模板渲染、参数注入、文件生成
依赖边界	模块对外部服务的依赖方向与方式	依赖数据查询接口，但不依赖具体数据库
通信边界	模块间交互的数据结构与调用协议	输入：报表配置DTO；输出：文件流或存储路径

2.2 高内聚低耦合原则在导出模块中的应用

高内聚指模块内部元素之间关联紧密，共同完成一个明确的职责。低耦合指模块之间的依赖关系简单、清晰、可替换。在报表导出模块中，这两个原则指导着每个子模块的划分方式。

实践口诀：“内聚做全、耦合做简”——模块内部把一件事做完整，模块之间只传递必要的数据，不传递实现细节。

2.2.1 高内聚：导出模块的职责聚合

导出模块内部应包含以下强关联的子模块，每个子模块只关注一个职责维度：

模板引擎适配器：负责模板加载、渲染、缓存，不关心数据来源
参数配置解析器：负责参数校验、默认值填充、参数注入，不关心文件格式
文件格式生成器：负责将渲染结果转为 PDF/Excel/CSV，不关心模板语法
导出状态管理器：负责进度跟踪、错误处理、回调通知，不关心文件内容

2.2.2 低耦合：模块间的依赖契约

导出模块对外部模块的依赖应通过接口抽象，避免直接依赖具体实现：

依赖方向	高耦合（反例）	低耦合（正例）
数据获取	直接调用 DAO 层 SQL 查询	调用 `ReportDataProvider` 接口
模板存储	硬编码本地文件路径	通过 `TemplateRepository` 抽象访问
权限校验	在导出模块内写权限逻辑	调用 `PermissionService` 接口
文件输出	直接写入 `/tmp/` 目录	通过 `FileStorage` 接口输出

2.3 边界划分的常见误区

在实际项目中，边界划分经常出现以下四类典型错误。识别并避免这些误区，是保证导出模块可维护性的关键。

误区类型	表现	后果	正确做法
职责过载	导出模块同时处理数据清洗、权限校验、日志审计	模块臃肿，修改一个功能影响其他功能	只负责“渲染+生成”，其他职责委托给专用模块
边界泄漏	导出模块直接访问数据库表或文件系统路径	数据库变更或存储迁移导致导出模块必须修改	通过接口抽象数据访问和文件存储
过度拆分	将模板加载、模板缓存、模板解析拆成三个独立模块	模块间通信成本高，调试困难	将强关联功能聚合为一个模块（如模板引擎适配器）
循环依赖	导出模块依赖配置模块，配置模块又依赖导出模块的状态	编译或启动失败，无法独立部署	引入事件机制或依赖倒置，打破循环

典型反例：某项目在导出模块中直接编写了“根据用户角色过滤报表数据”的逻辑。当权限模型从 RBAC 改为 ABAC 时，导出模块被迫修改，同时影响了 3 个导出功能。正确的做法是：导出模块只接收“已过滤的数据集”，权限过滤由独立的权限服务完成。

2.3.1 边界划分自检清单

在完成模块边界设计后，可以使用以下清单进行自检：

✅ 导出模块是否只做“模板渲染 + 参数注入 + 文件生成”三件事？
✅ 是否所有外部依赖都通过接口抽象，而不是直接引用具体类？
✅ 模块内部子模块是否职责单一，没有“顺便”功能？
✅ 是否存在循环依赖？能否通过事件或回调解耦？
✅ 如果替换模板引擎（如从 FreeMarker 换为 Thymeleaf），需要修改几个文件？

  边界设计黄金法则：一个模块的边界，应该让“最常见的变更”只影响该模块内部，而不扩散到其他模块。对于报表导出，最常见的变更是模板格式、参数规则和输出文件类型——这些都应该被封装在导出模块内部。