如何访问服务器上的网站,厦门网站个人制作,h5在线编辑,知名跟单网站做信号提供方我们知道 80% 的工程师在 80% 的时间都在维护或迭代遗留项目。而绝大部分遗留项目的业务、产品和技术文档都是匮乏的。我遇到的第一个问题就是在文档匮乏的情况下从”Shit Mountain“代码中理清业务逻辑。
在客户端同学协助下#xff0c;我大概定位到新需求涉及的几个 API 接…我们知道 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
