Java 模块目录结构指南

文档定位

本文档约定的是 ineed-core 及同类 Java Maven 仓库中的“模块物理目录结构”。

它回答的是：

• 一个目标目录到底应该是聚合模块、BOM 模块、普通代码模块，还是业务聚合模块
• 什么类型的模块应该有 src
• 什么类型的模块只能有 pom.xml 和子模块目录，不能生成 src

如果你要创建的是业务聚合模块骨架，继续读 business-module-layout-guide.md。 如果你要确认当前仓库真实声明了哪些模块，继续读 module-inventory.md。

先判断模块类型，再决定目录结构

开发者、代码生成器或自动化工具在创建 Java 模块前，必须先判断目标属于哪一类。

当前至少区分四类：

额外说明：

• 业务聚合模块属于“特殊聚合模块”，目录结构继续按 business-module-layout-guide.md 处理
• 不允许在还没判断模块类型前，就机械地创建 src/main/java

根聚合模块

根聚合模块只负责：

• 声明顶级 <modules>
• 统一版本、插件和依赖管理
• 作为整个仓库入口

标准形态：

{repo-root}/
  pom.xml
  README.md
  docs/
  {child-module-a}/
  {child-module-b}/

规则：

• 根聚合模块本身不放 src/main/java
• 不在根聚合模块下直接放业务 Java 源码
• 新增顶层模块前，先确认是否真的需要进入根 pom.xml 的 <modules>

分组聚合模块

分组聚合模块本身是 packaging=pom 的父级目录，负责聚合一组同类型子模块。

例如：

• ineed-core-modules
• ineed-core-reactive-modules
• ineed-core-tests
• ineed-core-starters

标准形态：

{aggregate-module}/
  pom.xml
  {child-module-a}/
  {child-module-b}/
  {child-module-c}/

规则：

• 分组聚合模块自身不生成 src/main/java
• 分组聚合模块自身不直接承载 Java 源码、资源文件、测试代码
• 真正的源码只能放在其子模块里
• 子模块目录必须和 pom.xml 中 <modules> 声明保持一致

BOM 模块

BOM 模块只负责 dependencyManagement，不负责承载运行时代码。

例如：

• ineed-core-bom

标准形态：

{bom-module}/
  pom.xml

规则：

• BOM 模块不生成 src/main/java
• BOM 模块不生成 src/test/java
• BOM 模块不承载业务实现、配置类、测试类、样板代码
• 不要把 BOM 模块误当成普通代码模块去补目录骨架

普通代码模块

普通代码模块是实际承载 Java 源码、资源和测试的模块。

例如：

• ineed-core-base
• ineed-core-data-base
• ineed-rdb-metadata
• ineed-core-context
• ineed-core-engine
• ineed-core-webmvc
• ineed-core-data-core
• ineed-core-data-jpa
• ineed-core-data-jdbc
• ineed-core-data-mybatis-flex
• ineed-core-context-reactive
• ineed-core-engine-reactive
• ineed-core-webflux
• ineed-core-data-core-reactive
• ineed-core-data-r2dbc
• ineed-starter-druid
• ineed-core-test-webmvc
• ineed-core-test-webflux

标准物理目录模板：

{code-module}/
  pom.xml
  src/
    main/
      java/
        .gitkeep
      resources/
        .gitkeep
    test/
      java/
        .gitkeep
      resources/
        .gitkeep

规则：

• 所有普通代码模块都应统一具备 src/main/java、src/main/resources、src/test/java、src/test/resources
• 即使暂时没有源码，也应先保留四类目录；空目录通过 .gitkeep 入库
• 不允许只创建 src/main/java 而忽略测试目录
• 不允许把 entity、controller、service、repository 直接散落在模块根目录
• 如果同一代码模块中同时暴露阻塞式与响应式共享 service 契约，统一使用 service/ 与 service/reactive/ 分包
• .settings、target、IDE 文件、构建输出不属于需要生成或提交的目录骨架

业务聚合模块是特殊情况

业务聚合模块不是单个代码模块，而是“聚合目录 + 多个子模块”的组合。

标准形态继续按 business-module-layout-guide.md：

{business-aggregate}/
  pom.xml
  {business-aggregate}-core/
  {business-aggregate}-engine/
  {business-aggregate}-jpa/
  {business-aggregate}-jdbc/
  {business-aggregate}-mybatis-flex/
  {business-aggregate}-webmvc/
  {business-aggregate}-engine-reactive/
  {business-aggregate}-r2dbc/
  {business-aggregate}-webflux/

关键点：

• 业务聚合模块本身是聚合目录，不是直接写 Java 源码的地方
• 真正放源码的是各个业务子模块
• core 是共享契约层，不再单独创建 {module}-reactive-core

共享 service 契约的目录落点

如果业务聚合模块中的 core 子模块需要同时暴露阻塞式与响应式共享 service 契约，推荐物理落点如下：

{business-aggregate}-core/
  src/main/java/com/ineed/{domain}/{object}/service/
  src/main/java/com/ineed/{domain}/{object}/service/reactive/

{business-aggregate}-webmvc/
  src/main/java/com/ineed/{domain}/{object}/service/

{business-aggregate}-webflux/
  src/main/java/com/ineed/{domain}/{object}/service/reactive/

规则：

• core 子模块中的 service/ 与 service/reactive/ 放共享接口定义
• webmvc / webflux 子模块中的对应目录只放本线适配实现，不重复定义另一套共享契约
• 不要把跨模块复用的共享接口只放进某个 webmvc 或 webflux 实现模块

模块类型与目录结构的映射规则

创建新模块时，必须满足下面的映射：

常见错误点

下面这些都是错误生成方式：

• 把 packaging=pom 的聚合模块生成成带 src/main/java 的代码模块
• 在 ineed-core-modules/、ineed-core-reactive-modules/、ineed-core-tests/、ineed-core-starters/ 下面直接写源码
• 给 ineed-core-bom/ 生成 src 目录
• 把业务聚合目录当成单模块，在聚合目录根下直接放 controller、service、entity
• 忽略 src/test/java 和 src/test/resources
• 重复发明 {module}-reactive-core
• 把阻塞式与响应式共享契约混放在同一个 service 根包，或者不使用 service/reactive/
• 把跨模块共享接口只定义在 webmvc / webflux 实现模块中
• 没有先看 pom.xml 中 <modules> 和 <packaging>，就凭名字猜目录结构

创建前自检

创建任何 Java 模块前，至少先检查：

1. 目标目录是根聚合模块、分组聚合模块、BOM 模块、普通代码模块，还是业务聚合模块
2. 目标 pom.xml 是否是 packaging=pom
3. 如果是聚合/BOM 模块，是否错误地准备生成 src
4. 如果是普通代码模块，是否已补齐四类 src 目录
5. 如果是业务聚合模块，是否转去遵循 business-module-layout-guide.md
6. 子模块目录名是否与父级 <modules> 声明一致
7. 是否错误把 IDE / 构建输出目录当成应入库骨架

如果以上检查未完成，不应直接创建目录结构。

阅读建议

• 想确认当前仓库有哪些真实模块，读 module-inventory.md
• 想创建业务聚合模块，读 business-module-layout-guide.md
• 想约束业务代码生成，结合 development-contract.md 和 code-style-guide.md 一起使用本文档

最后更新：2026-05-15