我们知道 80% 的工程师在 80% 的时间都在维护或迭代遗留项目。而绝大部分遗留项目的业务、产品和技术文档都是匮乏的。我遇到的第一个问题就是在文档匮乏的情况下从”Shit Mountain“代码中理清业务逻辑。

在客户端同学协助下，我大概定位到新需求涉及的几个 API 接口，然后顺藤摸瓜从 API 接口声明到业务服务实现捋了一遍，勉强熟悉了这部分业务逻辑，然后如履薄冰地写代码，期间和产品经理多轮沟通，再和客户端同学联调，最后通过测试同学测试，总算顺利完成需求交付。

但经过这一轮折腾后，我想：有没有更好的方式让新接手的工程师可以更快熟悉并上手项目。最直观的想法是看文档，但众所周知文档有以下问题：

• 很少有项目会维护文档，或者维护完整的文档（绝大部分情况）
• 随着时间推移，项目文档很可能会过期，很少项目会持续迭代更新文档
• 项目的业务文档、产品文档和技术文档可能出现不一致甚至自相矛盾的情况（非结构化的文档很容易有这类问题）
• 项目文档如果没有很好地分门别类，检索、阅读费时费力

文档这条路不通，我想到 DDD（领域驱动设计）通过定义领域、子域、聚合根、实体、值对象、领域事件等概念为业务逻辑提供了一套清晰通用的描述语言。那是否可以借鉴 DDD 的思想，为整个软件制定一套描述性强的 DSL，最终为软件生成一份自描述的规格说明？答案是肯定的。调研发现有一个名叫 SysML 的 MBSE 建模语言，详细可以参考这篇文章 SysML 建模在系统开发生命周期的应用。SysML 包括九种图（包图、需求图、活动图、序列图、状态机图等），它是软件统一建模语言 UML 的一种扩展，用于表示系统开发中的所有活动。SysML 建模语言固然很好，但太重（早期 SOA 的理念也很好，但协议规范过于冗长、复杂最终鲜为人知）不便于在实际项目中照搬。至此，思路就很清晰了，设计一套 ** 简化版的 SysML DSL**，这套 DSL 的特点如下：

• 以自然语言编写，可读性强
• 只描述软件的关键功能、功能对应的用例、功能对应的页面、页面用到的接口、页面交互和接口流转。业务领域模型、内部系统 / 模块关系、数据模型、状态机等属于各端自己需要关注的，不需要在这套 DSL 中描述
• DSL 天然结构化，便于和开发框架集成

基于以上特点，在 ChatGPT 的帮助下，我编写了宠物商店 Petstore 的 DSL Demo，如下：

# 整体功能描述
系统 Petstore {描述 "Petstore是一个在线宠物商店系统，提供宠物管理和订单管理功能。用户可以查看所有宠物，添加新宠物，更新宠物信息。同时，用户可以查看订单历史，创建新订单，以及更新订单状态。"功能 宠物管理 {用例 查看所有宠物用例 添加新宠物用例 更新宠物信息}功能 订单管理 {用例 查看订单历史用例 创建新订单用例 更新订单状态}# 页面和接口描述页面 宠物列表 {使用用例 查看所有宠物使用接口 /api/pets 获取宠物列表}页面 新增宠物 {使用用例 添加新宠物使用接口 /api/pets/add 添加宠物}页面 订单历史 {使用用例 查看订单历史使用接口 /api/orders 获取订单历史}页面 创建订单 {使用用例 创建新订单使用接口 /api/orders/create 创建订单}# 页面交互和接口流转交互流转 {页面宠物列表 到 页面新增宠物 通过事件 选择宠物 -> 跳转 {接口流转 接口 /api/pets 获取宠物列表 到 接口 /api/pets/add 添加宠物 通过事件 完成添加 -> 更新宠物列表}页面新增宠物 到 页面宠物列表 通过事件 完成添加 -> 刷新列表 {接口流转 接口 /api/pets 获取宠物列表 -> 刷新列表}页面订单历史 到 页面创建订单 通过事件 创建新订单 -> 跳转 {接口流转 接口 /api/orders 获取订单历史 到 接口 /api/orders/create 创建订单 通过事件 完成创建 -> 更新订单历史}页面创建订单 到 页面订单历史 通过事件 完成创建 -> 刷新历史 {接口流转 接口 /api/orders 获取订单历史 -> 刷新历史}}
}

建议：

• 上面 DSL Demo 中的描述和功能和用例需要测试或开发同学手动维护，而页面和接口描述、页面交互和接口流转可以借助 SDK 自动生成
• 最好为这个 DSL 提供一个简单的管理后台，提供可视化及增删改等维护功能
• 公司如果有自研开发框架，可以基于这个 DSL 生成脚手架代码

END