简简单单 Online zuozuo ：本心、输入输出、结果

停止编写Excel规范：企业Java的Markdown优先方法

---

编辑 | 简简单单 Online zuozuo
地址 | https://blog.csdn.net/qq_15071263

---

如果觉得本文对你有帮助，欢迎关注、点赞、收藏、评论，谢谢

前言

企业Java中的设计文档经常被困在Excel或Word等二进制文件中，导致它们与实际代码逐渐偏离。本文介绍了一种模式，展示如何将设计文档视为源代码，通过采用结构化Markdown和生成式AI，我们可以像对待源代码一样对待文档。

我们都有过这样的经历：架构团队向开发团队交付一份详细设计文档（DDD）。这是一个50页的Word文件，甚至更糟糕的是，一个包含多个标签页定义的大型Excel电子表格。当你编写第一行代码时，文档就已经过时了。

二进制文件几乎无法进行版本控制，差异比较不切实际，将定义复制粘贴到Javadoc中也很繁琐。在企业规模下，这种"代码漂移"现象——即实现与规范逐渐偏离——会导致维护成本高昂、测试覆盖率低，以及技术债务的积累。

通过将设计文档转换为结构化Markdown并利用生成式AI，我们可以像对待源代码一样对待文档。这就在架构师的意图和开发者的实现之间架起了一座桥梁。

#Markdown #企业Java #设计文档 #生成式AI #代码生成 #软件开发流程 #文档管理

1、问题：二进制文件的壁垒

在传统的瀑布式或混合环境中，设计文档存在于Office文档（Word/Excel）中，而代码存在于文本格式（Java/YAML）中。由于格式不兼容，自动化被打破，文档和代码之间出现了不可逾越的鸿沟。

要弥合这一差距，设计信息需要满足以下要求：

• 基于文本（用于Git版本控制）
• 结构化（用于机器解析）
• 人类可读（用于审查和协作）

解决方案就是结构化Markdown。

2、解决方案：Markdown作为数据源

我们不仅仅将Markdown视为编写README文件的方式，而是将其视为结构化规范格式。通过标准化标题和布局，Markdown文件成为一种一致的、机器可解析的规范语言。

3、目录结构

要使这种方法发挥作用，设计文档必须与代码并存，镜像包结构，以便它们一起演进。

模式：

src/
  main/java/
    com/example/
      user/
        RegisteredUser.java
        RegisteredUser.md  ← 设计文档与代码并存
        UserProfile.java
        UserProfile.md

通过将.md文件保持在与.java文件相同的仓库结构中，我们在规范和实现之间建立了直接、可追溯的链接。

4、结构化规范

关键是将Markdown作为实际规范来编写，而不是作为博客文章。我们使用特定的标题（如## 类摘要、## 成员），这些标题作为自动化工具的钩子。

示例：RegisteredUser.md

## 类摘要
RegisteredUser表示已通过验证的用户账户。

## 成员
- `email: String` - 用户的电子邮件地址
- `tier: UserTier` - 用户层级（BASIC, PREMIUM, ENTERPRISE）

## 业务规则
- 如果tier为PREMIUM，则email必须包含至少3个字符
- 如果tier为ENTERPRISE，则email必须包含至少8个字符

这种格式对产品负责人来说是可读的，同时对LLM来说足够结构化，可以解释类型定义和逻辑约束。

5、实现：从文本到Java

一旦我们用结构化Markdown表达设计，生成式AI就可以弥合与Java代码之间的差距。在Fujitsu的案例研究中，他们利用VS Code扩展和OpenAI API来读取这些Markdown规范并生成相应的Java类。

你可以使用任何GenAI编码助手来复制这个工作流程。由于提示上下文包含严格、可预测的结构，幻觉率显著下降。

提示上下文示例：

根据以下Markdown规范生成Java类：

## 类摘要
RegisteredUser表示已通过验证的用户账户。

## 成员
- `email: String`
- `tier: UserTier`

## 业务规则
- 如果tier为PREMIUM，则email必须包含至少3个字符
- 如果tier为ENTERPRISE，则email必须包含至少8个字符

生成的输出：

AI不会猜测；它会完全按照编写的规范实现业务规则（>= 3, >= 8）。如果设计发生变化，你更新Markdown，然后重新生成代码。

6、可视化架构

当从Excel、Visio或其他图表工具迁移时，一个常见的担忧是失去"绘制"系统的能力。但现在我们的设计存在于结构化文本中，我们可以将其编译成图表。

使用标准化的Markdown标题，我们可以通过简单地扫描目录来自动生成Mermaid.js类图。

输入（Markdown标题）：类：RegisteredUser依赖于类：UserProfile

输出（自动生成的Mermaid图）：

这确保你的架构图始终反映设计文档的当前状态，而不是架构师三个月前绘制的内容。

7、"Excel"需求

许多企业仍然需要Excel文件用于正式签署或非技术利益相关者。

但现在真实来源是结构化文本（Markdown），生成Excel变得轻而易举。一个简单的脚本（甚至是一个AI提示）可以解析标题并自动填充CSV或XLSX模板。

• 旧方式：主文件是Excel -> 开发者手动编写Java。
• 新方式：主文件是Markdown -> 自动生成Java并为管理层自动生成Excel。

8、结果和投资回报率

转向Markdown优先方法不仅仅是整理你的仓库。在分析的案例研究中，团队看到了明显的生产力提升：

• 开发速度提高55%：样板代码（类、测试）直接从Markdown规范生成。
• 减少沟通开销：AI辅助的Markdown翻译比处理Excel单元格更快、更准确。
• 真正的差异比较能力：Git现在可以准确显示谁在何时更改了业务规则，在git提交历史中。

9、结论

文档往往成为事后考虑的事情，因为我们用于设计的工具（Office）与我们用于开发的工具（IDE）相互对立。通过采用Markdown作为正式规范语言，我们消除了这种工具之间的鸿沟。

所以下次当你被要求编写详细设计时，跳过电子表格。打开一个.md文件，定义清晰的结构，然后让代码从那里流动。

---

生如逆旅，一苇以航
欢迎关注、欢迎联系交流、欢迎沟通想法、欢迎交换意见、欢迎合作咨询

感谢亲的关注、点赞、收藏、评论，一键三连支持，谢谢