Java模块化架构文档应以module-info.java为源头，用依赖图与能力表明确边界和依赖，按集成/扩展/升级场景组织API视图，并附javadoc生成指引。
在 Java 模块化系统（JPMS）中，架构文档不是代码的附属说明，而是模块契约的正式表达。可读性高的架构文档，核心在于让读者一眼看清“谁提供什么、依赖谁、边界在哪”。它不堆砌术语，而用结构、约束和可视化传递真实设计意图。
紧扣 module-info.java 写清模块职责与边界
每个模块的 module-info.java 是架构文档的源头。文档中必须逐模块对照其声明，明确写出：
-
模块名称与定位：例如
com.example.payment是支付网关适配层，不处理业务规则，只负责协议转换 -
exports 的包及其语义：不只是列出包名，要说明“为什么导出”——
exports com.example.payment.api是为外部提供统一支付发起接口；exports com.example.payment.dto仅用于跨模块数据传输，不含逻辑 -
requires 的模块及理由：写明
requires com.example.logging是为了统一埋点，而非仅因编译需要；若requires static java.desktop，需注明“仅测试时启用图形调试工具”
用依赖图+导出表替代文字描述依赖关系
纯文字罗列“模块 A 依赖模块 B”极易遗漏隐含耦合。应提供两样东西：
-
轻量级依赖图：用 Mermaid 或 PlantUML 绘制，节点为模块名，箭头标注依赖类型（
requires/requires static/uses），避免包含 JDK 内部模块（如java.base）以聚焦业务关系 -
模块能力对照表：表格横向为模块名，纵向为“导出包”“依赖模块”“是否含 SPI 实现”“是否发布独立 Javadoc”，一目了然。例如：
模块 导出包 依赖 SPI 实现 com.example.authcom.example.auth.apijava.base,com.example.crypto是（实现 Authenticator）com.example.cryptocom.example.crypto.api,com.example.crypto.spijava.base否（仅定义 SPI）
按场景组织 API 文档视图，而非按模块罗列
开发者不关心“模块有哪些类”，而关心“我要做支付回调，该看哪个 API”。文档应围绕典型使用场景组织：
立即学习“Java免费学习笔记（深入）”；
-
集成场景页：如“接入第三方支付”，列出所需模块（
com.example.payment+com.example.webhook）、必配 exports（com.example.payment.api必须导出）、关键配置项（PaymentConfig的 module-info 声明方式） -
扩展场景页：如“自定义加密算法”，说明如何编写
com.example.crypto.spi的实现类，并在自己模块的module-info.java中用provides ... with ...声明，附上最小可运行示例 -
升级兼容页：明确标注哪些导出包是稳定 API（带
@API(status = STABLE)），哪些是预览特性（@API(status = EXPERIMENTAL)），并说明模块版本升级时的 breaking change 判断依据（如 exports 包删减、requires 模块变更）
把 javadoc 生成命令和输出结构写进文档
可读性高，也意味着“能立刻上手验证”。文档末尾应附上标准操作指引：
- 生成单模块文档命令：
javadoc --module com.example.auth --module-path mods --output docs/auth，并说明输出目录下index.html和module-summary.html的用途差异 - 生成全系统集成文档命令：
javadoc --module-source-path src --modules com.example.auth,com.example.payment,com.example.crypto --output docs/api，强调--module-source-path必须指向各模块源码根目录，而非 jar 包 - 提示常见陷阱：如未在
module-info.java中exports的包，即使有完整 javadoc 注释，也不会出现在生成的文档中
