Skip to content

Latest commit

 

History

History
168 lines (118 loc) · 6.58 KB

ReverseModelingGuide.md

File metadata and controls

168 lines (118 loc) · 6.58 KB
Raw

DSL标注代码教程

软件架构的终极⽬标，是⽤最⼩的⼈⼒成本来满⾜构建和维护该系统的需求 ─ 《架构整洁之道》

没有领域模型设计的软件，工程师往往会过多的关注到技术问题上，而忽视了产品设计和业务的目标。

领域建模对于商业软件来说是非常重要的一环，也是工程师消化行业领域知识的重要方法。

Annotation your code with DSL --> DDDplus maven plugin --> Your visualized business model
            |                             |                           |
        meta model                   parse AST                  domain knowledge

一、用dddplus-maven-plugin跑一遍代码

mvn io.github.dddplus:dddplus-maven-plugin:model \
    -DrootDir=${冒号分隔的源代码目录名称} \
    -DplantUml=${业务模型输出到哪一个文件, svg格式} \
    -DtextModel=${业务模型输出到哪一个文件, txt格式}

例如：

mvn io.github.dddplus:dddplus-maven-plugin:model \
    -DrootDir=application:domain:web \
    -DrawClassSimilarity=true \
    -DsimilarityThreshold=88 \
    -DplantUml=doc/myapp.svg \
    -DtextModel=doc/myapp.txt

执行后，就可以在doc目录下看到一些自动生成的报告。例如，在doc/myapp.txt文件，会看到：

  • DSL标注覆盖率
  • 代码规模：多少个类，多少个方法，多少个属性，多少条语句
  • 规模最大的方法 top 10
  • 相似度超过88%的相似类

但此时由于还未标注，生成的业务模型doc/myapp.svg只有基础的汇总信息，看不到模型，call graph也是空的。

二、开始DSL标注

2.1 引入pom依赖

在需要标注的代码模块都需要引入dddplus-spec依赖：可以放心使用，它不会引入任何间接依赖。

所有的DSL注解的有效范围都是RetentionPolicy.SOURCE，不会污染被标注代码。

<dependency>
    <groupId>io.github.dddplus</groupId>
    <artifactId>dddplus-spec</artifactId>
</dependency>

2.2 开始DSL标注

请参考DSL参考手册。

2.2.1 从 @Aggregate 开始标注

逆向建模自动生成的业务模型，是以Aggregate为边界进行组织的。

Aggregate
  ├── KeyEvent
  ├── KeyUsecase
  └── KeyModel
      ├── KeyBehavior
      ├── KeyElement
      ├── KeyFlow
      ├── KeyRelation
      ├── KeyRule
      └── KeyUsecase

Aggregate与DDD里的聚合概念一致，是业务边界；非DDD项目可以理解为模块。

具体地，在某个package下创建package-info.java，例如：

@Aggregate(name = "复核报差异")
package ddd.plus.showcase.wms.domain.diff;

2.2.2 标注核心实体类

请参考我们提供的Carton示例。

这涉及到的DSL包括：

  • KeyElement 关键业务字段
  • KeyRelation 业务实体间重要关系
  • KeyBehavior 该实体的关键业务行为
  • KeyRule 该实体的关键业务规则

2.2.3 标注服务与流程片段类

贫血模型往往把业务逻辑写到各个Service/Worker/Utils/Validator/Processor等类里，这不符合面向对象思想。

通过@KeyFlow可以把行为职责重新分配到业务实体上，提升模型可理解性，例如：

public class FooService {

    @KeyFlow(actor = Order.class) // actor是行为主体的意思
    public void doSth(Order order) {
    }
}

有时候，目前代码里并不存在一个恰当的业务概念抽象，在逆向过程中发现了它，但重构工作量太大不敢做，这时候可以先让这个业务概念仅存在于逆向模型里。

具体办法是为该业务概念创建一个类，实现IVirtualModel接口，相关的行为职责通过KeyFlow#actor赋予到这个类上。

2.2.4 标注业务入口

业务入口，通常位于RPC接口/MQ Consumer/Controller等类，在这些类的关键方法上标注@KeyUsecase，例如：

public class CheckingController {
    // 提交复核任务
    @KeyUsecase
    public ApiResponse<String> submitTask(@Valid SubmitTaskDto dto) { }
}

2.2.5 标注业务事件

通过@KeyEvent标注在业务事件类上，例如：

@KeyEvent
public class OrderShippedEvent {
}

2.2.6 标注建议

Since the recovered diagrams are intended to be inspected by a human, the presentation modes should take into account the cognitive limitations of humans explicitly.

  • 标注过程，不要一次性做全，可以做一点看一点，试探性摸索，熟悉后再做彻底标注
  • 图形有效的前提是不能有太多元素，不要追求大而全，请主动忽略非关键细节，人为降噪，以避免范围失控丢失焦点
    • 好的模型能尽可能简单的情况下较好的拟合事物

三、DSL标注后执行dddplus-maven-plugin

在标注过程中，可以随时执行dddplus-maven-plugin，以观察逆向业务模型的变化。

四、最佳实践

为了与日常开发、设计评审、代码评审等结合起来，建议把逆向生成的模型文件纳入版本控制，从而完整追溯业务模型的演进过程。

五、模型思维

用一个较为简单的东西来代表另一个东西，这个简单的东西被叫做模型。─ 维基百科

业务设计上往往没有建立起特定的领域模型，这是我们架构腐化和软件开发困难的关键原因。业务领域建立好的模型，并指导代码实践，这就是 “编程思维”。

通过模型思维来看待软件开发，我们会发现，软件从设计到开发的过程就是各种模型的转换。

模型分为形式化和非形式化两种。形式化的模型是精确描述的模型，而非形式化的模型是一些非精确描述的模型，主要用来做商业、业务探索。

对于应用开发的软件工程师来说，核心的问题并非如何编写代码，而是如何将非形式化的业务输入(模型)进行合理抽象、设计，并转换为形式化的过程。

某种程度上来说，通过高级语言编写的代码也是一种模型。在多年以前，计算机科学家们认为编写 Java 代码 的人不算程序员，可以由业务人员直接编写业务软件。由于软件工程中非形式化和形式化之间存在巨大鸿沟，编程就是模型的形式化过程，从这个角度看能深刻分析业务并获得良好抽象结果的程序员具有竞争力，并不会被 AI 编程所代替。