更新 knowledge.md

knowledge.md

@@ -1411,7 +1411,7 @@ class CreateUserBto {    //对应实体user
 - **定义与用途:** TOCO支持领域消息，通过创建和订阅领域消息，可以监听聚合对象的状态变化（创建、删除、更新)，TOCO会自动生成消息的发送逻辑
 - **关键配置:**  名称(小写字母+下划线), 由于消息是全局可见，所以TOCO限制了名称项目级别不能重复; **注意** 在监听状态变化的时候不要命名为某个字段的变更，比如 order_payed, 也不要按照业务语义命名，例如order_payed_complete,因为实际上是order表的任意变更都会受到消息，因此命名为order_changed或order_updated更准确的表达了消息的触发语义； 同理对于create事件，一般命名为 xxx_created；对于delete时间，一般命名为 xxx_deleted
 - **与聚合的关系:** 每个聚合下可以定义多个领域消息，每次可以监听聚合下面其中一个实体的状态变更
-- **如何创建/生成:** 创建领域消息，需要先去顶聚合，然后确定需要监听的实体以及监听的变更类型
+- **如何创建/生成:** 创建领域消息，需要先确定聚合，然后确定需要监听的实体以及监听的变更类型
 - **最佳实践** 如果只是字段区别，应该修改现有的领域消息，增加相应的字段即可，而不是新创建一个领域消息；
 - **领域消息的定义表达**
     - 以Json表达，Json Schema 定义如下：
@@ -1440,9 +1440,55 @@ class CreateUserBto {    //对应实体user
         - **唯一标识符位置:** 其对应的标识符在类注解@AutoGenerated中指定, uuid规则: ${DomainMessage在TOCO中的uuid}|DMO|DEFINITION
     - **例子**
       用户聚合，包含了user实体, 用户实体有 user_id， user_name 字段，那么创建一个领域消息，名称为user_created，描述为用户创建成功，聚合名称为user，实体名称为user，监听的变更类型为create，返回的字段为user_id，user_name。则会生一个类：<code> UserCreatedMo {Long userId;String userName;}</code>；特别的，对于update的监听，生成消息里会包含字段的前值，命名以old结尾, 例如：<code>UserUpdatedMo {String userName ; String userNameOld;}</code>
+#### **2.18 普通消息 （CommonMessage)**
+- **定义与用途:** TOCO支持普通消息，普通消息可以自由定义消息内容。定义消息后，TOCO可以生成消息体，以及消息的发送模板；只需调用这个发送函数，即可发送消息; 消息队列的创建配置等工作TOCO自动完成
+- **关键配置:**  名称(小写字母+下划线), 由于消息是全局可见，所以TOCO限制了名称项目级别不能重复; 
+- **领域消息的定义表达**
+    - 以Json表达，Json Schema 定义如下：
+  ```json
+  {
+      "type":"object",
+      "properties": {
+          "name":{ "type": "string", "description": "消息名称,单词之间使用下划线分割，总称不超过32个字符,一个模块的领域消息名称不能重复"},
+          "description": { "type": "string","description": "消息描述，不超过128个字符"},
+          "uuid":{ "type": "string", "description": "唯一标识符，创建时为空，更新时必填"},
+          "moduleName":{ "type": "string", "description": "所属模块，创建时必填，更新时可空"},
+          "delay": {"type": "boolean","description": "是否是延迟消息，如果是延时消息，在生成的的发送消息函数里添加延迟时间参数"},
+          "transactional": {"type": "boolean","description": "是否是事务消息，如果是事务消息，消息的发送和外层事务保持一致"},
+          "fieldList":{
+              "type":"array", "description": "消息属性列表",
+              "items":{
+                "type": "object",
+                "properties":{
+                    "name": { "type": "string","description": "字段名称，英文下划线分割，不超过32字符"},
+                    "uuid":{ "type": "string","description": "字段类型为Enum或Eo时必填，对应的Enum或Eo标识符" } ,
+                    "type":{ "type": "string","description": "字段类型：String,Integer,Long,Float,Double,Boolean,Date,Eo,Enum,BigDecimal,List" },
+                    "innerUuid":{"type": "string", "description": "当innerType为Eo或Enum时，对应的标识符"},
+                    "innerType": {  "type": "string", "description": "List元素类型：String,Integer,Long,Float,Double,Boolean,Date,Eo,Enum,BigDecimal"}
+                },
+                "required":[  "name","type"]
+              }
+          }
+       },
+      "required":["name","description"]
+  }
+  ```
+**代码产物和修改建议**
+  - **消息载体类:** 在manager层生成一个Java类，封装消息体
+    - **命名规则:** 类名为${commonMessageName}Mo
+    - **职责:**  消息内容载体
+    - **类路径:** ```**.manager.mo```
+    - **唯一标识符位置:** 其对应的标识符在类注解@AutoGenerated中指定, uuid规则: ${CommonMessage在TOCO中的uuid}|MO|DEFINITION
+  - **发送类** 在service层生成一个Java类，封装消息发送逻辑
+    - **命名规则:** 类型名为 ${commonMessageName}MoMessageSender
+    - **职责** 封装发送函数，作为消息发送的入口
+    - **类路径:** ```**.service.mq.producer``` 
+    - **唯一标识符位置:** 其对应的标识符在类注解@AutoGenerated中指定, uuid规则: ${CommonMessage在TOCO中的uuid}|MO|PRODUCER
+- **例子**
+  - 在用户注册成功后，需要给用户发一封邮件，可以定义个普通消息，名称为：user_registered, 包含了字段： long user_id, String nick_name， 生成代码后，会生成 类：<code> UserRegisteredMo {Long userId;String nickName;}</code> 和一个发送类 <code>UserRegisteredMoMessageSender {void send(UserRegisteredMo message);}</code>
 
-#### **2.18 订阅消息 (SubscribeMessage)**
+#### **2.19 订阅消息 (SubscribeMessage)**
-- **定义与用途:** TOCO支持订阅消息, 订阅消息后生成代码会生成消息消费的模板代码， 后续只需在对应的模板代码里填写业务逻辑，而无需关注如何订阅消息的代码逻辑 **注意**在TOCO中，消息订阅按照模块独立订阅：一个消息可以被多个模块订阅，同一个消息在一个模块中只能订阅一次
+- **定义与用途:** TOCO支持订阅消息（普通消息和领域消息）, 订阅消息后生成代码会生成消息消费的模板代码， 后续只需在对应的模板代码里填写业务逻辑，而无需关注如何订阅消息的代码逻辑 **注意**在TOCO中，消息订阅按照模块独立订阅：一个消息可以被多个模块订阅，同一个消息在一个模块中只能订阅一次
 - **订阅消息的定义表达**
     - 以Json表达，Json Schema 定义如下: 通过msgId或者msgName指定订阅的消息
   ```json