停止编写Excel规格文档：企业级Java开发的Markdown先行方法

将设计规格从Excel转移到Markdown，利用AI生成Java代码，从而防止设计与代码脱节，并将开发时间缩短55%。

在企业级Java开发中，设计文档通常被困在诸如Excel或Word之类的二进制孤岛中，导致它们与实际代码渐行渐远。本文展示了一种模式，即通过使用结构化的Markdown和生成式AI，将设计文档视为源代码。

我们都经历过这种情况：架构团队向开发团队交付一份详细设计文档（[Detailed Design Document]DDD）。它是一个50页的Word文件，或者更糟，是一个包含多个标签页、用于定义Java类、字段和验证规则的大型Excel电子表格。

当你写下第一行代码时，这份文档就已经过时了。

二进制文件几乎无法进行版本控制，差异对比不切实际，并且将定义复制粘贴到Javadoc中非常繁琐。在企业级规模下，这种”代码漂移”（即实现与设计脱节）成为了技术债务的主要来源。

通过将设计文档转移到结构化的Markdown并利用生成式AI，我们可以将文档完全视为源代码。这在架构师的意图和开发人员的集成开发环境（IDE）之间架起了一座桥梁。

问题：二进制壁垒

在传统的瀑布模型或混合开发环境中，设计存在于Office文档（Word/Excel）中，而代码则以文本格式（Java/YAML）存在。由于格式不兼容，自动化流程中断。你无法轻易地将Excel表格”编译”成Java POJO，当然也无法对Word文档进行单元测试。

为了弥合这一差距，设计信息需要具备以下特点：

基于文本（以便于Git版本控制）。

结构化（以便于机器解析）。

人类可读（以便于审查和协作）。 解决方案就是使用结构化Markdown。

解决方案：将Markdown作为数据源

我们不应仅将Markdown视为编写README文件的方式，而应将其作为一种结构化的规格说明格式。通过标准化标题和布局，Markdown文件就成为一种一致且对机器友好的数据源，生成式AI工具（GitHub Copilot、ChatGPT等）可以解析它来生成样板代码、图表，甚至为利益相关者生成遗留的Excel报告。

1. 目录结构

为使此方法有效，设计文档必须与代码存放在一起，并镜像包结构，以便它们同步演进。

模式示例：

/project-root /src /main/java/com/app/backend/RegisteredUser.java /design-docs /backend RegisteredUser.md OrderService.md /diagrams architecture.mermaid

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

2. 结构化规格说明

关键在于将Markdown写成实际的规格说明，而不是博客文章。我们使用特定的标题（例如## Class Summary, ## Members）作为自动化工具的挂钩点。

示例：RegisteredUser.md

# RegisteredUser ## Class Summary Represents a user who has completed the registration process. Manages user credentials and validation status. ## Members | Name | Type | Description | | :--- | :--- | :--- | | userId | String | Unique identifier for the user. | | userPassword | String | Encrypted password string. | ## Methods + fn isValidUserId(): bool - Logic: Returns true if userId length >= 3. + fn isValidUserPassword(): bool - Logic: Returns true if password length >= 8.

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

实施：从文本到Java

一旦我们用结构化的Markdown表达了设计，生成式AI就可以弥合与Java代码之间的鸿沟。在富士通的案例研究中，他们利用一个VS Code扩展和OpenAI API来读取这些Markdown规格说明，并生成初始的类框架。

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

提示上下文示例：

“请阅读以下Markdown设计文档。根据’Methods’部分中的描述，生成一个包含Javadoc、字段和验证逻辑的Java类。”

生成输出示例：

package com.app.backend; /** * Represents a user who has completed the registration process. * Manages user credentials and validation status. */ public class RegisteredUser { private String userId; private String userPassword; public RegisteredUser(String userId, String userPassword) { this.userId = userId; this.userPassword = userPassword; } /** * Logic: Returns true if userId length >= 3. */ public boolean isValidUserId() { return this.userId != null && this.userId.length() >= 3; } /** * Logic: Returns true if password length >= 8. */ public boolean isValidUserPassword() { return this.userPassword != null && this.userPassword.length() >= 8; } }

AI不会猜测；它会严格按照书面描述实现指定的业务规则（>=3, >=8）。如果设计发生变更，你只需更新Markdown，然后重新生成代码。

可视化架构

当不再使用Excel、Visio或其他图表工具时，一个常见的担忧是失去了”绘制”系统的能力。但既然我们的设计现在存在于结构化的文本中，我们就可以将其编译成图表。

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

输入（Markdown标题）： Class: RegisteredUser depends on Class: UserProfile

#Mermaid Diagram classDiagram class RegisteredUser { +String userId +String userPassword +isValidUserId() } class UserProfile { +String email } RegisteredUser --> UserProfile

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

“Excel”需求

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

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

旧方式：主文件是Excel -> 开发人员手动编写Java。

新方式：主文件是Markdown -> 自动生成Java并为管理层自动生成Excel。

结果与投资回报率

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

开发速度加快55%：样板代码（类、测试）直接从Markdown规格说明生成。

减少沟通开销：AI辅助的Markdown转换比处理Excel单元格更快、更准确。

真正的差异对比能力：Git现在能准确显示谁在何时更改了业务规则（通过Git提交历史）。

结论

文档常常沦为事后的补救措施，因为我们用于设计的工具（Office套件）与我们用于开发的工具（IDE）格格不入。通过采用Markdown作为一种正式的规范语言，我们将设计工作直接拉入了DevOps流程。

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

【注】本文译自：Markdown-First Approach to Enterprise Java