feat: 简化技术描述语言（2.10~2.11）
This commit is contained in:
dayjoy
611
knowledge.md
611
knowledge.md
@@ -962,77 +962,80 @@ meeting_with_room_and_agenda_wo示例：
|
||||
* 根据用户名称查询用户列表返回UserDTO，生成UserNameQto、UserNameQtoService、UserNameQtoDao、UserNameQueryService; UserNameQueryService调用UserNameQtoService，UserNameQtoService调用UserNameQtoDao
|
||||
- **修改建议:**
|
||||
- 如有结果数据二次处理，建议在QueryService和QueryExecutor中扩展代码，不建议修改QTO文件
|
||||
|
||||
|
||||
#### **2.10 查询传输对象(QTO)**
|
||||
- **定义与用途:** 在TOCO中，QTO为读方案的查询参数结构，每个读方案会对应一个QTO，读方案调用方按照QTO的结构向读方案生成的RPC方法传入需要查询的实体字段值，完成对数据库的查询
|
||||
- **如何创建/生成:** 在创建读方案后，TOCO会自动生成QTO作为该读方案传入的查询参数结构，无需单独创建
|
||||
- **关键配置:** 名称（${ReadPlanNameQto}，驼峰展示），查询字段列表(如idIs，nameLike, schoolNameLike等)
|
||||
- **与API的关系:** QTO通常可作为API的参数，API接收到参数后可直接透传给内部的RPC进行调用，注意QTO只用作读操作的参数，**禁止用作写参数结构**
|
||||
- **定义与用途:** QTO是读方案的查询参数结构。每个读方案对应一个QTO。调用方使用QTO结构传入查询字段值，完成数据库查询
|
||||
- **如何创建/生成:** 创建读方案后，TOCO自动生成对应的QTO。无需单独创建
|
||||
- **关键配置:** 名称（${ReadPlanNameQto}，驼峰命名），查询字段列表（如idIs，nameLike，schoolNameLike等）
|
||||
- **与API的关系:** QTO可作为API参数。API接收参数后直接透传给内部RPC调用。QTO只用于读操作参数，**禁止用于写参数结构**
|
||||
|
||||
#### **2.11 写方案 (WritePlan，单聚合操作)**
|
||||
- **定义与用途:** TOCO针对写场景定义了一种写方案，所有对数据库的写操作都只能通过写方案实现（一个写方案只可以变更一个聚合的数据，无法同时操作多个聚合!）。写方案包含了对数据库表的写操作。每个写方案只能操作一个聚合内部的表，同时对一个聚合内表的操作尽量合并至一个写方案中（根据复用性、内聚性等方面具体情况具体分析）。注意写方案可以一次操作聚合内的多张表，如location和storey是同一个聚合，并且location和storey是**1:N**关系，location是父对象（聚合根），storey是子对象，那么我们可以创建一个写方案，同时更新单个聚合根location中的信息，以及操作其下的子表storey**列表**信息，如新增、删除、修改storey等；也可以创建一个写方案单独更新单个子表storey对象信息。
|
||||
- **关键配置:** 名称(小写字母+下划线，不要以write_plan结尾,全局唯一)，操作的聚合，聚合内的实体和字段，对每个实体的操作类型：CREATE（创建**单个**实体），UPDATE(更新**单个**实体), DELETE(删除**单个**实体), CREATE_ON_DUPLICATE_UPDATE(创建或者更新**单个**实体),FULL_MERGE( 批量更新**列表**数据，根据传入的列表数据，一条一条执行CREATE_ON_DUPLICATE_UPDATE的操作；并且删除掉老的列表中不在传入列表数据中的部分), PARTIAL_MERGE(批量更新**列表**数据，根据传入的列表数据，一条一条执行)
|
||||
- **与RPC的关系:** 对于每一个写方案，TOCO会自动生成一个RPC方法，其参数为写方案对应的BTO，返回值为本次操作的聚合根实体的主键值，内部只实现了对当前聚合的数据库操作
|
||||
- **生成的写方案RPC** 的使用： 写方案生成的RPC属于该写方案所属的模块，其他模块如果需要调用该写方案，需要先订阅该写方案RPC，在生成代码后使用adapter调用该读服务；当前模块则可以直接调用该写方案对应的Service
|
||||
- **与聚合的关系:** 每个聚合下可以定义多个写方案，但每个写方案只能操作一个聚合内的表，无法同时操作多个聚合内的表
|
||||
- **如何创建/生成:** 创建写方案时需要先选定对应的聚合，以及要操作的聚合内部的实体，然后确定对每个实体的具体操作类型
|
||||
- 提取需求中的更新部分需求，根据上下文信息构建出一个写更新方案
|
||||
- 上下文中输入了备选聚合对象的的定义，每个聚合对象定义了多个实体的嵌套关系
|
||||
- 先明确聚合内实体的父子关系层级
|
||||
- 根据需求提取出变更相关的名称
|
||||
- 根需求提取出变更相关的描述
|
||||
- 根据需求选择确定变更范围，选出一个最合适的聚合对象；注意: 最多只能选择一个聚合对象
|
||||
- 根据需求在选定的聚合对象按照对象的粒度，选出所需变更对象
|
||||
- 根据需求选定变更对象的字段；每个选定的对象至少需要选定一个字段，如果无法确定任何字段，默认选择全部字段， 字段必须明确指定名称，不能类似“所有字段”的模糊表达
|
||||
- 每个对象上可以设置对应的一个操作，操作包括：CREATE（创建），UPDATE(更新), DELETE(删除), CREATE_ON_DUPLICATE_UPDATE(创建或者更新),FULL_MERGE( 批量更新列表数据，根据传入的列表数据，一条一条执行CREATE_ON_DUPLICATE_UPDATE的操作；并且删除掉老的列表中不在传入列表数据中的部分), PARTIAL_MERGE(批量更新列表数据，根据传入的列表数据，一条一条执行CREATE_ON_DUPLICATE_UPDATE的操作)
|
||||
- 列表属性可以批量操作
|
||||
- 批量更新列表数据(FULL_MERGE或者PARTIAL_MERGE)，则操作方案需要包含它的父对象
|
||||
- 批量删除列表数据，则操作方案需要包含父对象，父对象的操作设置为UPDATE
|
||||
- 批量创建列表数据，则操作方案需要包含父对象，父对象的操作设置为UPDATE、或者是CREATE（当父对象也需要一起创建的时候）
|
||||
- 举例：meeting对象有List<meeting_agenda> agdendaList属性，如果需要批量创建agenda，则需要同时设置metting对象和meeting_agenda对象，并且对meeting_agenda设置create操作；这是会生成一个Bto参数，其中包含了 List<meeting_ageda> agendaList的属性，用于批量传递参数；反正，如果只设置了meeting_agenda的create操作，生成的Bto参数，只包含了meeting_agenda实体的属性，表示一次只能创建一条数据； 同理对于UPDATE、DELETE也是类似的规则
|
||||
- FULL_MERGE和PARTIAL_MERGE只能用在列表属性上, 单值属性请使用CREATE_ON_DUPLICATE_UPDATE
|
||||
- 操作是 UPDATE、DELETE、CREATE_ON_DUPLICATE_UPDATE、FULL_MERGE、PARTIAL_MERGE的时候必须且只能指定一个唯一键(unique_key)（包括主键）,用于确定对应的数据记录，主键对应的字段也要包含在fields字段中;
|
||||
- 唯一键(unique_key)的具体解释：在实体中，存在普通索引和唯一索引，这里的唯一键值的是唯一索引，由一个或多个字段组成
|
||||
- 选定的对象层级不能跳跃；如果发生不连续，去掉不连续的叶子对象
|
||||
- 注意父对象和下一层子对象的操作类型有如下限制，必须严格检查以下规则
|
||||
- 如果父对象的操作是DELETE，则下一层子对象不能选择，也不能能设定任何操作
|
||||
- 如果父对象是的操作是CREATE，则下一层子对象只能选择CREATE
|
||||
- 如果父对象是CREATE_ON_DUPLICATE_UPDATE，子对象只能是CREATE或者CREATE_ON_DUPLICATE_UPDATE或者FULL_MERGE或者PARTIAL_MERGE
|
||||
- 如果父对象是FULL_MERGE，子对象只能是FULL_MERGE或者PARTIAL_MERGE或者是CREATE
|
||||
- 对于选定的字段列表中的字段，如果字段的类型是Long、BigDecimal、Float 、Integer 则可以设置为增量更新字段， 把值设置在incrFields属性中，和操作"UPDATE"、"CREATE_ON_DUPLICATE_UPDATE"、"PARTIAL_MERGE"或者"FULL_MERGE"搭配表示对该字段增量更新： 例如A实体的字段count类型是Long, 如果该字段被设置为增量跟新字段，最终的效果是A.count = A.count + ? ; 对于减少字段的值也用该方法表示，可以通过传入负值的入参达到减值的效果
|
||||
- **写方案设计元素的表达**:
|
||||
|
||||
以json格式表达，json schema 定义如下:
|
||||
- **定义与用途：** 写方案是数据库写操作的唯一方式，每个写方案只能变更一个聚合的数据。写方案可以一次操作聚合内的多张表。例如：location(父对象/聚合根)和storey(子对象)是1:N关系，可创建写方案同时更新location信息和操作storey列表(新增/删除/修改)；也可创建写方案单独更新单个storey对象。
|
||||
- **关键配置：** 名称(小写+下划线，不以write_plan结尾，全局唯一)，操作的聚合，聚合内的实体和字段，每个实体的操作类型：
|
||||
- CREATE：创建单个实体
|
||||
- UPDATE：更新单个实体
|
||||
- DELETE：删除单个实体
|
||||
- CREATE_ON_DUPLICATE_UPDATE：创建或更新单个实体
|
||||
- FULL_MERGE：批量更新列表数据，执行CREATE_ON_DUPLICATE_UPDATE操作，删除不在传入列表中的旧数据
|
||||
- PARTIAL_MERGE：批量更新列表数据，执行CREATE_ON_DUPLICATE_UPDATE操作
|
||||
- **与RPC关系：** 每个写方案自动生成一个RPC方法，参数为对应BTO，返回值为聚合根实体主键值，只实现当前聚合的数据库操作。
|
||||
- **生成RPC使用：** 写方案RPC属于所属模块，其他模块需先订阅该RPC，用adapter调用；当前模块直接调用对应Service。
|
||||
- **与聚合关系：** 每个聚合可定义多个写方案，但每个写方案只能操作一个聚合内的表。
|
||||
- **创建方式：** 先选定聚合和要操作的实体，再确定每个实体的操作类型
|
||||
- 提取需求中的更新需求，根据上下文构建写方案
|
||||
- 输入备选聚合对象定义，每个聚合定义多个实体的嵌套关系
|
||||
- 明确聚合内实体的父子层级关系
|
||||
- 提取需求相关的变更名称和描述
|
||||
- 选择最合适的聚合对象(最多只能选一个)
|
||||
- 按对象粒度选出需变更对象
|
||||
- 选定变更对象的字段(每个对象至少选一个字段，无法确定时默认选全部，字段必须明确指定名称)
|
||||
- 为每个对象设置操作类型
|
||||
- 列表属性可批量操作：
|
||||
- 批量更新列表(FULL_MERGE/PARTIAL_MERGE)：需包含父对象
|
||||
- 批量删除列表：需包含父对象，父对象设为UPDATE
|
||||
- 批量创建列表：需包含父对象，父对象设为UPDATE或CREATE
|
||||
- 示例：meeting对象有List<meeting_agenda> agendaList，批量创建agenda需同时设置meeting和meeting_agenda对象，meeting_agenda设为CREATE；只设置meeting_agenda的CREATE则一次只能创建一条数据
|
||||
- FULL_MERGE和PARTIAL_MERGE只用于列表属性，单值属性用CREATE_ON_DUPLICATE_UPDATE
|
||||
- UPDATE/DELETE/CREATE_ON_DUPLICATE_UPDATE/FULL_MERGE/PARTIAL_MERGE操作必须指定一个唯一键(包括主键)，用于确定数据记录，主键字段也要包含在fields中
|
||||
- 唯一键：实体中的唯一索引，由一个或多个字段组成
|
||||
- 选定对象层级不能跳跃，发生不连续时去掉不连续的叶子对象
|
||||
- 父对象和子对象操作类型限制：
|
||||
- 父对象DELETE：子对象不能选择任何操作
|
||||
- 父对象CREATE：子对象只能CREATE
|
||||
- 父对象CREATE_ON_DUPLICATE_UPDATE：子对象只能CREATE/CREATE_ON_DUPLICATE_UPDATE/FULL_MERGE/PARTIAL_MERGE
|
||||
- 父对象FULL_MERGE：子对象只能FULL_MERGE/PARTIAL_MERGE/CREATE
|
||||
- 增量更新字段：Long/BigDecimal/Float/Integer类型字段可设为增量更新，设置在incrFields中，配合UPDATE/CREATE_ON_DUPLICATE_UPDATE/PARTIAL_MERGE/FULL_MERGE使用。例如：A实体count字段设为增量更新，效果是A.count = A.count + ?，传入负值可减值
|
||||
- **写方案设计元素表达：**
|
||||
```json
|
||||
{
|
||||
"type":"object",
|
||||
"description":"写方案定义",
|
||||
"properties":{
|
||||
"uuid":{"type":"string","description":"写方案设计元素的唯一标识,在创建的时候不传；更新的时候必须传递"},
|
||||
"name":{"type":"string","description":"写方案名称，英语表示，单词之间使用下划线连接，长度限制在32个字符之内"},
|
||||
"description":{"type":"string","description":"写方案描述，长度限制在256个字符内"},
|
||||
"bo": {"type":"string","description":"聚合根的名称，确定了唯一聚合"},
|
||||
"uuid":{"type":"string","description":"写方案唯一标识，创建时不传，更新时必传"},
|
||||
"name":{"type":"string","description":"写方案名称，英文+下划线，32字符内"},
|
||||
"description":{"type":"string","description":"写方案描述，256字符内"},
|
||||
"bo": {"type":"string","description":"聚合根名称"},
|
||||
"operations": {
|
||||
"type":"array","description":"定义了对写方案涉及到的相关实体的操作，包括操作类型和相关字段",
|
||||
"type":"array","description":"实体操作定义，包括操作类型和字段",
|
||||
"items":{
|
||||
"type": "object", "description":"定义了对具体一个实体的操作，包括操作类型和相关字段",
|
||||
"type": "object", "description":"具体实体操作定义",
|
||||
"properties":{
|
||||
"bo":{"type":"string","description":"具体操作的实体"},
|
||||
"action":{"type":"string","description":"对具体实体的操作"},
|
||||
"bo":{"type":"string","description":"操作的实体"},
|
||||
"action":{"type":"string","description":"实体操作类型"},
|
||||
"uniqueKey": {
|
||||
"type":"array",
|
||||
"description":"唯一键包含的字段列表，该唯一键用于确定数据记录",
|
||||
"items":{"type":"string","description":"字段名称，组成唯一键的字段名称"}
|
||||
"description":"唯一键字段列表，用于确定数据记录",
|
||||
"items":{"type":"string","description":"字段名称"}
|
||||
},
|
||||
"fields":{
|
||||
"type":"array",
|
||||
"items":{"type":"string","description":"字段名称，必须来自bo对象"},
|
||||
"description":"对选定的Bo的操作的字段列表"
|
||||
"description":"操作字段列表"
|
||||
},
|
||||
"incrFields":{
|
||||
"type":"array",
|
||||
"items":{ "type":"string", "description":"增量字段名称"},
|
||||
"description":"选定的字段中进行增量操作的字段列表"
|
||||
"description":"增量操作字段列表"
|
||||
},
|
||||
"required":["bo","action","fields"]
|
||||
}
|
||||
@@ -1042,12 +1045,12 @@ meeting_with_room_and_agenda_wo示例：
|
||||
"required":["name","description","operations","bo"]
|
||||
}
|
||||
```
|
||||
- **例子**
|
||||
- **上下文:**
|
||||
<code>
|
||||
- **示例：**
|
||||
- **上下文：**
|
||||
```java
|
||||
public class meeting {//会议聚合
|
||||
//唯一键：(id)、(meeting_name)
|
||||
Long id; //主键id
|
||||
Long id; //主键
|
||||
String meeting_name; //会议名称
|
||||
Date start_time; //开始时间
|
||||
Date end_time;//结束时间
|
||||
@@ -1075,10 +1078,10 @@ meeting_with_room_and_agenda_wo示例：
|
||||
String nickname;//昵称
|
||||
Long friend_count;//好友数量
|
||||
}
|
||||
</code>
|
||||
- **需求:** 创建会议
|
||||
- 对应的写方案定义:
|
||||
<code>
|
||||
```
|
||||
- **需求：** 创建会议
|
||||
- **对应写方案定义：**
|
||||
```json
|
||||
{
|
||||
"name": "create_meeting",
|
||||
"description": "创建会议",
|
||||
@@ -1095,280 +1098,277 @@ meeting_with_room_and_agenda_wo示例：
|
||||
}
|
||||
]
|
||||
}
|
||||
</code>
|
||||
- **代码产物和修改建议**
|
||||
- **BOService:**
|
||||
* **生成产物:** 在对应的聚合服务BOService里生成一个函数
|
||||
* **函数命名规则:** 和写方案同名
|
||||
* **职责:** 按需对入参进行转换，调用BaseBOService里的函数完成对聚合对象的操作, 实现对数据库的写操作；
|
||||
* **返回值:** 操作的聚合根实体记录的主键字段的值
|
||||
* **BOService的类路径:** <code>**.service</code>
|
||||
* **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${WritePlan在TOCO中的uuid}
|
||||
- **BaseBOService**
|
||||
- **生成产物:** 在对应的聚合的BaseBOService里生成一系列函数，根据入参完成对聚合对象的变更
|
||||
- **职责** 增对每个实体的生成增删改的函数，并且根据参数的结构以及聚合的结构，构建嵌套的调用逻辑，完成对一个聚合对象的变更，记录并且返回对应的变更情况
|
||||
- **类路径:** <code>**.service.base</code>
|
||||
- **禁止** 修改该类
|
||||
- **BTO (业务变更传输对象)**
|
||||
* **生成产物:** 一个Java类，以内部类的方式表示层级结构, **注意** BTO只能由写方案生成，不能凭空创建
|
||||
* **命名规则:** 一个Bto结尾(${WritePlanName}Bto，驼峰展示)
|
||||
* **禁止** 修改该类
|
||||
* **类路径:** 位于<code>**.service.bto</code>包路径下
|
||||
* **职责:** 在**TOCO**中，BTO为写方案的参数结构，每个写方案会对应一个BTO，写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要查询的实体字段值，完成对数据库的变更
|
||||
* **唯一标识符位置:** 其对应的唯一标识符在类注解@AutoGenerated中指定, uuid规则: ${WritePlan在TOCO中的uuid}|BTO|DEFINITION
|
||||
- **例子：**
|
||||
- 创建用户以及用户设置的写方案create_user_and_setting，生成CreateUserAndSettingBto, 在用户的聚合(UserBO)对应的UserBOService中生成函数createUserAndSetting，该函数调用BaseUserBOService中生成的createUserAndSetting, 其中在BaseUserBOService中还生成了createUser和createSetting的函数, 一起完成了用户的创建和设置创建的逻辑。
|
||||
```
|
||||
|
||||
- **代码产物和修改建议：**
|
||||
- **BOService：**
|
||||
* **生成产物：** 在聚合服务BOService中生成一个函数
|
||||
* **函数命名：** 与写方案同名
|
||||
* **职责：** 转换入参，调用BaseBOService函数完成聚合对象操作，实现数据库写操作
|
||||
* **返回值：** 聚合根实体记录主键值
|
||||
* **类路径：** `**.service`
|
||||
* **唯一标识：** 函数注解@AutoGenerated中指定，uuid规则：${WritePlan的uuid}
|
||||
- **BaseBOService：**
|
||||
- **生成产物：** 在聚合BaseBOService中生成系列函数，根据入参完成聚合对象变更
|
||||
- **职责：** 为每个实体生成增删改函数，根据参数结构和聚合结构构建嵌套调用逻辑，完成聚合对象变更，记录并返回变更情况
|
||||
- **类路径：** `**.service.base`
|
||||
- **禁止：** 修改该类
|
||||
- **BTO (业务变更传输对象)：**
|
||||
* **生成产物：** Java类，以内部类方式表示层级结构，注意BTO只能由写方案生成，不能凭空创建
|
||||
* **命名规则：** 以Bto结尾(${WritePlanName}Bto，驼峰命名)
|
||||
* **禁止：** 修改该类
|
||||
* **类路径：** `**.service.bto`包下
|
||||
* **职责：** 写方案的参数结构，每个写方案对应一个BTO，调用方按BTO结构向写方案RPC方法传入实体字段值，完成数据库变更
|
||||
* **唯一标识：** 类注解@AutoGenerated中指定，uuid规则：${WritePlan的uuid}|BTO|DEFINITION
|
||||
- **示例：**
|
||||
- 创建用户及设置的写方案create_user_and_setting，生成CreateUserAndSettingBto，在UserBOService中生成函数createUserAndSetting，该函数调用BaseUserBOService中生成的createUserAndSetting，其中BaseUserBOService还生成createUser和createSetting函数，一起完成用户创建和设置创建逻辑。
|
||||
- **修改建议：**
|
||||
- 不能修改BaseBOService中的函数，不建议修改BTO文件。建议在BOService中进行手动代码扩展，处理可能被复用的修改前后的逻辑，如修改数据库的前后值对比、或常被复用的校验逻辑（业务不变性校验逻辑除外）、需要经常在一个事务内执行的其他写操作等。
|
||||
- 父类函数会返回一个BoResult类，此类记录了各个Bto和Bo实例的对应关系，以及各个Bto实例的操作结果, 可以通过以下接口获取。 例如：在创建用户的写方案中，BoService里的入参为CreateUserBto 例如：在创建用户的写方案中，BoService里的入参为CreateUserBto,用户id由数据库生成，如果需要返回创建用户id，那么通过boResult.getAddedResult(createUserBto).getBo().getId()可以返回新建的用户id
|
||||
<code>
|
||||
- 不能修改BaseBOService函数，不建议修改BTO文件。建议在BOService中扩展代码，处理可能被复用的前后逻辑，如数据库前后值对比、常被复用的校验逻辑(业务不变性校验除外)、需要在一个事务内执行的其他写操作等。
|
||||
- 父类函数返回BoResult类，记录各Bto和Bo实例对应关系及Bto实例操作结果，可通过以下接口获取。例如：创建用户的写方案中，BoService入参为CreateUserBto，用户id由数据库生成，需要返回创建用户id时，通过boResult.getAddedResult(createUserBto).getBo().getId()返回新建用户id
|
||||
```java
|
||||
/**
|
||||
* 获取更新成功的bto结果
|
||||
*
|
||||
* @return
|
||||
*/
|
||||
public UpdatedBto getUpdatedResult(final Object bto)
|
||||
|
||||
/**
|
||||
* 获取成功插入的Bto的结果
|
||||
* @param btoObj
|
||||
* @return
|
||||
* 获取成功插入的Bto结果
|
||||
*/
|
||||
public AddedBto getAddedResult(final Object btoObj)
|
||||
|
||||
/**
|
||||
* 获取Bto对应的删除结果
|
||||
*
|
||||
* @param btoObj
|
||||
* @return
|
||||
*/
|
||||
public DeletedBto getDeletedResult(final Object btoObj)
|
||||
</code>
|
||||
<code>
|
||||
```
|
||||
```java
|
||||
public class UpdatedBto<Bto,Entity,BO> {
|
||||
//Bto 入参
|
||||
private Bto bto;
|
||||
//Bto 对应的Entity，前项
|
||||
private Entity entity;
|
||||
//bo，后项
|
||||
private BO bo;
|
||||
}
|
||||
</code>
|
||||
<code>
|
||||
//记录删除记录的情况
|
||||
//Bto入参
|
||||
private Bto bto;
|
||||
//Bto对应的Entity，前项
|
||||
private Entity entity;
|
||||
//bo，后项
|
||||
private BO bo;
|
||||
}
|
||||
```
|
||||
```java
|
||||
//记录删除记录情况
|
||||
@Setter
|
||||
@Getter
|
||||
public class DeletedBto<Bto,Entity> {
|
||||
//Bto 入参
|
||||
private Bto bto;
|
||||
//Bto 对应的Entity，前项
|
||||
private Entity entity;
|
||||
//Bto入参
|
||||
private Bto bto;
|
||||
//Bto对应的Entity，前项
|
||||
private Entity entity;
|
||||
}
|
||||
</code>
|
||||
<code>
|
||||
```
|
||||
```java
|
||||
//记录Bto创建的前后值
|
||||
@Setter
|
||||
@Getter
|
||||
public class AddedBto<Bto,BO> {
|
||||
//Bto 入参
|
||||
private Bto bto;
|
||||
//bo 后项
|
||||
private BO bo;
|
||||
//Bto入参
|
||||
private Bto bto;
|
||||
//bo后项
|
||||
private BO bo;
|
||||
}
|
||||
</code>
|
||||
```
|
||||
|
||||
#### **2.12 业务变更传输对象(BTO)**
|
||||
- **定义与用途:** 在TOCO中，BTO为写方案自动生成的参数结构，每个写方案会生成一个BTO。BTO为写方案选定的操作实体根据关系形成的树形集合，最外层为聚合根。写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要操作的实体字段值，完成对数据库的写操作
|
||||
- **如何创建/生成:** BTO只能由写方案自动创建，不能单独新建任何BTO。在创建写方案后，TOCO会自动生成一个BTO作为该写方案传入的参数结构。
|
||||
- **关键配置:** 名称（${WritePlanName}Bto，驼峰展示），嵌套的树形实体和字段列表，BTO内部的字段全部都来自Entity。以下为一个示例：
|
||||
<code>
|
||||
class CreateUserBto { //对应实体user
|
||||
Long id; //来自于user.id
|
||||
String name; //来自于user.name
|
||||
List<PictureBto> pictureList;
|
||||
class PictureBto { //对应实体picture
|
||||
String url; //来自于picture.url
|
||||
#### **2.12 业务变更传输对象(BTO)**
|
||||
- **定义与用途:** 在TOCO中，BTO为写方案自动生成的参数结构，每个写方案会生成一个BTO。BTO为写方案选定的操作实体根据关系形成的树形集合，最外层为聚合根。写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要操作的实体字段值，完成对数据库的写操作
|
||||
- **如何创建/生成:** BTO只能由写方案自动创建，不能单独新建任何BTO。在创建写方案后，TOCO会自动生成一个BTO作为该写方案传入的参数结构。
|
||||
- **关键配置:** 名称（${WritePlanName}Bto，驼峰展示），嵌套的树形实体和字段列表，BTO内部的字段全部都来自Entity。以下为一个示例：
|
||||
<code>
|
||||
class CreateUserBto { //对应实体user
|
||||
Long id; //来自于user.id
|
||||
String name; //来自于user.name
|
||||
List<PictureBto> pictureList;
|
||||
class PictureBto { //对应实体picture
|
||||
String url; //来自于picture.url
|
||||
}
|
||||
}
|
||||
</code>
|
||||
- **与API的关系:** BTO通常可作为API的参数，API接收到参数后可直接透传给内部的RPC进行调用，注意BTO只用作写操作的参数，**禁止用作查询参数结构**
|
||||
- **复杂场景处理：** 对于涉及多个写方案的复杂API，可以：
|
||||
a. 如果接口有一个主要的写场景，则创建一个主要的写方案，让其自动生成的BTO作为API参数，然后再增加其他基本类型的参数或EO
|
||||
b. 使用基本类型参数或EO作为参数，在接口执行流程中将基本类型参数转换为各个写方案自动生成的BTO，再调用多个写方案
|
||||
c. 如果流程过于复杂，优先考虑使用基本类型参数或EO
|
||||
|
||||
#### **2.13 服务层方法 (RPC)**
|
||||
- **定义与用途:** 在TOCO中，RPC为服务层的方法。RPC按照可见性可以分为两种，一种是公开RPC，可以被其他模块订阅，订阅后可以通过RPC适配器进行调用；另一种是非公开RPC，只能被当前模块调用。非公开RPC可以被公开，从而被其他模块订阅并调用
|
||||
- **如何创建/生成:** RPC有4种创建方式：a.DTO创建后会自动创建RPC，RPC的公开性与DTO的公开性保持一致；b.返回DTO的读方案会根据分页情况、以及是否生成计数函数的配置自动生成非公开的RPC c.写方案创建后会自动生成非公开的RPC，返回值为操作的聚合根实体记录的主键字段的值 d.如果上述三种RPC无法满足需求，则可以通过TOCO创建自定义RPC完整指定功能，需指定具体的参数和返回值以及公开性等。
|
||||
- **优先复用：** 当用户需要创建一个RPC时，如果用户有明确要求创建的方式，则按照用户的要求来创建。如果没有明确要求，则通常先判断是否可以通过创建读方案、写方案、DTO来使TOCO自动创建出对应的RPC，最后再考虑通过TOCO创建自定义RPC
|
||||
- **自定义RPC和代码中手写方法的关系：** 二者都可以通过手动的方式实现一个服务层的方法，应用场景的区别在于：如果一个方法需要被其他模块订阅，则通常使用自定义RPC；如果一个方法只是某个API私有调用，不需要给外部模块开放，则可以使用代码手写方法
|
||||
- **关键配置:** 类名(驼峰，首字母大写，以Service结尾)、是否公开、方法名(驼峰，首字母小写)、请求参数、返回值。注意如果一个RPC是分页查询且参数为Qto类型，则Qto中已经包含了分页所需的from、size、scrollId等属性，无需额外为RPC增加类似参数。
|
||||
- **TOCO中RPC的存储:** 注意RPC在TOCO中只存储了方法签名，不存储内部的执行流程逻辑，如果需要了解其内部的实现逻辑，则需要通过阅读RPC对应的代码。
|
||||
- **参数类型:** RPC的参数**只能**为QTO、BTO、Enum、基本类型，可为单值或列表。注意如果是对象类型，则优先使用QTO、BTO作为参数，**禁止使用**VO和自定义结构如Object
|
||||
- **返回值类型:** RPC的返回值**只能**为DTO、Enum、基本类型,可为单值或列表，**禁止使用**VO、QTO、BTO、自定义结构如Object作为返回值。注意如果是对象类型，则优先使用DTO作为返回值
|
||||
- **TOCO中json结构描述:** 在TOCO中，DTO使用一个json结构表示，示例如下：
|
||||
```json
|
||||
{
|
||||
"methodName": "saveUsers",
|
||||
"className": "UserSaveService",
|
||||
"requestParams":[
|
||||
{
|
||||
"name": "saveUserBtoList",
|
||||
"description": "批量保存用户参数",
|
||||
"type": "List",
|
||||
"innerType": "Bto",
|
||||
"innerUuid": "dbvvc4d4-0063-442f-abd7-vrfded656988"
|
||||
}
|
||||
],
|
||||
"response": {
|
||||
"type": "Boolean"
|
||||
}
|
||||
}
|
||||
```
|
||||
结构中一些关键字段描述如下：
|
||||
requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,Dto,Qto,Bto,List,PageResult,Void，其中参数不能为Void和PageResult，如果不需要返回值则type设置为Void，如果返回值为分页查询的结果则type设置为PageResult，且innerType必为Dto，对应代码中的VSQueryResult<XxxDto>；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Dto时传入该对象的uuid，当type为Qto时传入对应读方案的uuid、当type为Bto时传入对应写方案的uuid；innerType为List内部类型，当type为List或PageResult时包含该字段；innerUuid为List内部类结构的UUID，当type为List或PageResult且innerType为Enum、Eo、Dto时传入该对象的uuid，当innerType为Qto时传入对应读方案的uuid、当innerType为Bto时传入对应写方案的uuid。
|
||||
- **生成代码：** RPC会在service层中生成类文件及实现函数，包含DTO自动生成的RPC如UserDtoService.getById(主键为id)或StaffBaseDtoService.getByStaffId(主键为staff_id)、读写方案自动生成的RPC如UserDtoQueryService.queryByListQto、UserBOService.createUser、自定义RPC如UserCustomService.customMethod。特别注意公开的RPC才可被其他模块使用，RPC被订阅后会生成RpcAdapter适配器，其他模块通过RpcAdapter才可调用该方法。如Order模块订阅了User模块的UserDtoService.getById，则会在Order模块中生成UserDtoServiceInOrderRpcAdapter.getById方法，Order模块中的代码必须通过@Resource private UserDtoServiceInOrderRpcAdapter userDtoServiceInOrderRpcAdapter;注入适配器后才可进行方法调用。这里**必须要注意**：变量的命名必须是类名的首字母小写，禁止使用其他变量名。
|
||||
- **修改建议：** 建议修改RPC方法，不建议修改RPC方法签名、适配器中的内容
|
||||
|
||||
#### **2.14 应用程序接口 (API)**
|
||||
- **定义与用途:** 在TOCO中，API用于定义对外暴露的HTTP接口
|
||||
- **如何创建/生成:** API一般为通过TOCO创建，需指定具体的参数和返回值等。
|
||||
- **TOCO中API的存储:** 注意API在TOCO中只存储了其URI和方法签名，不存储内部的执行流程逻辑，如果需要了解其内部的实现逻辑，则需要通过阅读API对应的代码。
|
||||
- **关键配置:** uri(加粗展示，一般为/api/${moduleName}/xxx，如/api/user/create,全局唯一。如果用户有特殊命名规则的话以用户要求为准)、类名(以Controller结尾)、方法名(驼峰，首字母小写)、请求参数、返回值。注意如果一个API是分页查询且参数为Qto类型，则Qto中已经包含了分页所需的from、size、scrollId等属性，无需额外为API增加类似参数。
|
||||
- **参数类型:** API的参数**只能**为读方案自动生成的QTO、写方案自动生成的BTO、EO、Enum、基本类型，可为单值或列表。注意如果是对象类型，则优先使用读方案自动生成的QTO、写方案自动生成的BTO作为参数。**禁止使用**DTO和自定义结构如Object作为参数
|
||||
- **返回值类型:** TOCO的API运行在自己的Java脚手架中，脚手架会自动对API的返回值做一层对象包装（code、message、data）。所以在TOCO中，API的返回值无需考虑返回码和错误信息，只需考虑返回的数据本身。TOCO中API的返回值**只能**为VO、Enum、基本类型,可为单值或列表，**禁止使用**DTO、QTO、BTO、自定义结构如Object作为返回值。注意如果是对象类型，则优先使用VO作为返回值。
|
||||
- **TOCO中json结构描述:** 在TOCO中，API使用一个json结构表示，示例如下：
|
||||
```json
|
||||
{
|
||||
"methodName": "getUserMeetingList",
|
||||
"className": "MeetingQueryController",
|
||||
"usageScenario": "xxx",
|
||||
"requestParams":[
|
||||
{
|
||||
"name": "getMeetingListByUserId74Qto",
|
||||
"description": "查询参数",
|
||||
"type": "Qto",
|
||||
"uuid": "6351a4d4-0063-442f-abd7-a2df6d656988"
|
||||
},
|
||||
{
|
||||
"name": "test",
|
||||
"description": "是否为测试请求",
|
||||
"type": "Boolean"
|
||||
}
|
||||
],
|
||||
"response": {
|
||||
"type": "List",
|
||||
"innerType": "Vo",
|
||||
"innerUuid": "1d58352b-5333-4509-aec2-1abc3fac9122"
|
||||
}
|
||||
}
|
||||
```
|
||||
结构中一些关键字段描述如下：
|
||||
requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,PageResult,Vo,Qto,Bto,Void，其中参数不能为Void和PageResult，如果不需要返回值则type设置为Void，如果返回值为分页查询的结果则type设置为PageResult，且innerType必为Vo，对应代码中的VSQueryResult<XxxVo>；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Vo时传入该对象的uuid，当type为Qto时传入对应读方案的uuid、当type为Bto时传入对应写方案的uuid；innerType为List内部类型，当type为List时包含该字段；innerUuid为List或PageResult内部类结构的UUID，当type为List或PageResult且innerType为Enum、Eo、Vo时传入该对象的uuid，当innerType为Qto时传入对应读方案的uuid、当innerType为Bto时传入对应写方案的uuid。
|
||||
- **代码产物和修改建议**
|
||||
- **生成代码：** API会在entrance层生成Controller以及对应的API方法
|
||||
- **修改建议：** 建议修改API方法的实现内容，禁止直接修改API方法签名、URI，**注意**：如需修改API定义（名称、出入参数、URL）需要通过修改API设计元素实现
|
||||
|
||||
#### **2.15 流程服务（FunctionFlow)**
|
||||
- **定义与用途:** TOCO针对复杂业务拆解，定义了流程服务，把一个复杂的业务过程，根据业务逻辑的内聚性，合并逻辑功能，把流程分解成流程节点，最终构造出一个类似工作流的逻辑流程；最终实现复杂业务流程分解，提升代码的可维护性。TOCO内嵌了流程引擎，在Function_Flow生成代码后，可以在流程引擎中执行
|
||||
- **何时使用:**
|
||||
- 如果一个API/RPC中涉及的写服务超过3个，则**必须**使用流程服务
|
||||
- 当用户要求使用流程服务
|
||||
- **节点的封装:**
|
||||
- 因为TOCO是一个面向数据处理的系统，所以数据内聚为首要考虑因素；一个节点通常围绕一个核心写服务，包括取数的读服务，为写服务的入参进行数据处理和转换，以及该写服务完成后的一些附属功能, 除了条件节点，入参校验，最终数据返回节点，每个节点至少包括一个写服务。
|
||||
- **关键配置:** 名称(小写字母+下划线)，拆解复杂业务逻辑，如果业务流程比较简单，则不需要使用流程服务
|
||||
- **如何创建/生成:**
|
||||
- 流程不是逻辑的伪代码，不需要表达全部逻辑细节，相关有内聚性，相似性的功能逻辑需要被封装到一个流程节点内；例如用户注册：创建用户需要，需要创建账号信息，需要创建用户信息，并且发送一个通知消息，这几个功能都属于创建用户相关信息，而且没有逻辑分叉，因此可以内聚在一个逻辑节点内。
|
||||
- 流程节点之间的参数和返回值的传递通过一个统一的上下文Context传递（在写代码的时候按需修改Context文件，添加所需的字段）
|
||||
- 定义了JSON结构，用于表达逻辑流。流程节点分为 “顺序节点”、“条件节点”，“选择节点”，"开始节点“ ，节点之间通过有向边连接，表示逻辑的执行方向；从开始节点开始，可达各个节点。
|
||||
- 节点的边的定义如下：顺序节点可以有多条入边，可以有多条出边（一个出边表示下一个执行的节点，多条出边表示几个分支并发执行）；条件节点可由多条入边，可以有2条出边，表示条件为True和False两种逻辑分支；选择节点可以有多条入边，可以有多条出边，每条出边表示一种选择路径；开始节点只能有一条出边，不能有入边;
|
||||
- ”条件节点“只封装条件判断逻辑，返回TRUE或者FALSE；”循环节点“只封装条件判断逻辑，返回TRUE或者FALSE；”选择节点“只封装分支选择逻辑，返回下游分支节点的名称；
|
||||
- 终止流程：直接抛出异常
|
||||
- 一般校验逻辑放在一个“顺序节点"中，如果校验失败，以异常的方式抛出
|
||||
- 节点可以复用，同样的功能可以抽取出来封装到一个节点中
|
||||
- **流程服务设计元素的表达：**
|
||||
- 以Json表达，Json Schema 定义如下：
|
||||
```json
|
||||
{
|
||||
"type": "object","description": "流程服务设计元素", "required": [ "description","name","nodes","edges"],
|
||||
"properties":
|
||||
{
|
||||
"name": { "type": "string", "description": "流程名称，英语描述，单词之间使用下划线分割，总称不超过32个字符" },
|
||||
"moduleName": {"type": "string", "description": "模块名称，创建流程时传入，指定流程服务所属的模块"},
|
||||
"uuid": {"type": "string", "description": "流程服务设计元素的uuid，创建流程不传入，在更新的时候必须传入"},
|
||||
"description": {"type": "string", "description": "流程服务描述, 总长度控制在200个字符内"},
|
||||
"nodes": {
|
||||
"type": "array", "description": "流程服务的节点列表",
|
||||
"items": {
|
||||
"type": "object","description": "流程服务节点对象", "required": ["name", "type", "description"],
|
||||
"properties": {
|
||||
"name": {"type": "string", "description": "节点名称, 英语描述，单词之间使用下划线分割，总称不超过32个字符"},
|
||||
"type": {"type": "string", "description": "节点 类型，可以是 PROCESS_NODE(顺序节点）、SWITCH_NODE(选择节点)、CONDITION_NODE(条件节点）,START_NODE(开始节点)"},
|
||||
"description": {"type": "string", "description": "描述节点的功能, 英语描述，单词之间使用下划线分割，总称不超过200个字符" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"edges": {
|
||||
"type": "array", "description": "流程服务的边列表",
|
||||
"items": {
|
||||
"type": "object","description": "流程服务的边", "required": ["fromNode", "toNode"],
|
||||
"properties": {
|
||||
"fromNode": {"type": "string", "description": "边的开始节点名称"},
|
||||
"toNode": {"type": "string", "description": "边的结束节点名称"},
|
||||
"value": {"type": "boolean", "description": "可选，作为条件节点的出边，true值表示条件匹配的分支,false表示条件不匹配的分支; 作为循环节点的出边，true值表示进入循环，false值表示退出循环"}
|
||||
}
|
||||
</code>
|
||||
- **与API的关系:** BTO通常可作为API的参数，API接收到参数后可直接透传给内部的RPC进行调用，注意BTO只用作写操作的参数，**禁止用作查询参数结构**
|
||||
- **复杂场景处理：** 对于涉及多个写方案的复杂API，可以：
|
||||
a. 如果接口有一个主要的写场景，则创建一个主要的写方案，让其自动生成的BTO作为API参数，然后再增加其他基本类型的参数或EO
|
||||
b. 使用基本类型参数或EO作为参数，在接口执行流程中将基本类型参数转换为各个写方案自动生成的BTO，再调用多个写方案
|
||||
c. 如果流程过于复杂，优先考虑使用基本类型参数或EO
|
||||
#### **2.13 服务层方法 (RPC)**
|
||||
- **定义与用途:** 在TOCO中，RPC为服务层的方法。RPC按照可见性可以分为两种，一种是公开RPC，可以被其他模块订阅，订阅后可以通过RPC适配器进行调用；另一种是非公开RPC，只能被当前模块调用。非公开RPC可以被公开，从而被其他模块订阅并调用
|
||||
- **如何创建/生成:** RPC有4种创建方式：a.DTO创建后会自动创建RPC，RPC的公开性与DTO的公开性保持一致；b.返回DTO的读方案会根据分页情况、以及是否生成计数函数的配置自动生成非公开的RPC c.写方案创建后会自动生成非公开的RPC，返回值为操作的聚合根实体记录的主键字段的值 d.如果上述三种RPC无法满足需求，则可以通过TOCO创建自定义RPC完整指定功能，需指定具体的参数和返回值以及公开性等。
|
||||
- **优先复用：** 当用户需要创建一个RPC时，如果用户有明确要求创建的方式，则按照用户的要求来创建。如果没有明确要求，则通常先判断是否可以通过创建读方案、写方案、DTO来使TOCO自动创建出对应的RPC，最后再考虑通过TOCO创建自定义RPC
|
||||
- **自定义RPC和代码中手写方法的关系：** 二者都可以通过手动的方式实现一个服务层的方法，应用场景的区别在于：如果一个方法需要被其他模块订阅，则通常使用自定义RPC；如果一个方法只是某个API私有调用，不需要给外部模块开放，则可以使用代码手写方法
|
||||
- **关键配置:** 类名(驼峰，首字母大写，以Service结尾)、是否公开、方法名(驼峰，首字母小写)、请求参数、返回值。注意如果一个RPC是分页查询且参数为Qto类型，则Qto中已经包含了分页所需的from、size、scrollId等属性，无需额外为RPC增加类似参数。
|
||||
- **TOCO中RPC的存储:** 注意RPC在TOCO中只存储了方法签名，不存储内部的执行流程逻辑，如果需要了解其内部的实现逻辑，则需要通过阅读RPC对应的代码。
|
||||
- **参数类型:** RPC的参数**只能**为QTO、BTO、Enum、基本类型，可为单值或列表。注意如果是对象类型，则优先使用QTO、BTO作为参数，**禁止使用**VO和自定义结构如Object
|
||||
- **返回值类型:** RPC的返回值**只能**为DTO、Enum、基本类型,可为单值或列表，**禁止使用**VO、QTO、BTO、自定义结构如Object作为返回值。注意如果是对象类型，则优先使用DTO作为返回值
|
||||
- **TOCO中json结构描述:** 在TOCO中，DTO使用一个json结构表示，示例如下：
|
||||
```json
|
||||
{
|
||||
"methodName": "saveUsers",
|
||||
"className": "UserSaveService",
|
||||
"requestParams":[
|
||||
{
|
||||
"name": "saveUserBtoList",
|
||||
"description": "批量保存用户参数",
|
||||
"type": "List",
|
||||
"innerType": "Bto",
|
||||
"innerUuid": "dbvvc4d4-0063-442f-abd7-vrfded656988"
|
||||
}
|
||||
],
|
||||
"response": {
|
||||
"type": "Boolean"
|
||||
}
|
||||
}
|
||||
```
|
||||
结构中一些关键字段描述如下：
|
||||
requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,Dto,Qto,Bto,List,PageResult,Void，其中参数不能为Void和PageResult，如果不需要返回值则type设置为Void，如果返回值为分页查询的结果则type设置为PageResult，且innerType必为Dto，对应代码中的VSQueryResult<XxxDto>；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Dto时传入该对象的uuid，当type为Qto时传入对应读方案的uuid、当type为Bto时传入对应写方案的uuid；innerType为List内部类型，当type为List或PageResult时包含该字段；innerUuid为List内部类结构的UUID，当type为List或PageResult且innerType为Enum、Eo、Dto时传入该对象的uuid，当innerType为Qto时传入对应读方案的uuid、当innerType为Bto时传入对应写方案的uuid。
|
||||
- **生成代码：** RPC会在service层中生成类文件及实现函数，包含DTO自动生成的RPC如UserDtoService.getById(主键为id)或StaffBaseDtoService.getByStaffId(主键为staff_id)、读写方案自动生成的RPC如UserDtoQueryService.queryByListQto、UserBOService.createUser、自定义RPC如UserCustomService.customMethod。特别注意公开的RPC才可被其他模块使用，RPC被订阅后会生成RpcAdapter适配器，其他模块通过RpcAdapter才可调用该方法。如Order模块订阅了User模块的UserDtoService.getById，则会在Order模块中生成UserDtoServiceInOrderRpcAdapter.getById方法，Order模块中的代码必须通过@Resource private UserDtoServiceInOrderRpcAdapter userDtoServiceInOrderRpcAdapter;注入适配器后才可进行方法调用。这里**必须要注意**：变量的命名必须是类名的首字母小写，禁止使用其他变量名。
|
||||
- **修改建议：** 建议修改RPC方法，不建议修改RPC方法签名、适配器中的内容
|
||||
#### **2.14 应用程序接口 (API)**
|
||||
- **定义与用途:** 在TOCO中，API用于定义对外暴露的HTTP接口
|
||||
- **如何创建/生成:** API一般为通过TOCO创建，需指定具体的参数和返回值等。
|
||||
- **TOCO中API的存储:** 注意API在TOCO中只存储了其URI和方法签名，不存储内部的执行流程逻辑，如果需要了解其内部的实现逻辑，则需要通过阅读API对应的代码。
|
||||
- **关键配置:** uri(加粗展示，一般为/api/${moduleName}/xxx，如/api/user/create,全局唯一。如果用户有特殊命名规则的话以用户要求为准)、类名(以Controller结尾)、方法名(驼峰，首字母小写)、请求参数、返回值。注意如果一个API是分页查询且参数为Qto类型，则Qto中已经包含了分页所需的from、size、scrollId等属性，无需额外为API增加类似参数。
|
||||
- **参数类型:** API的参数**只能**为读方案自动生成的QTO、写方案自动生成的BTO、EO、Enum、基本类型，可为单值或列表。注意如果是对象类型，则优先使用读方案自动生成的QTO、写方案自动生成的BTO作为参数。**禁止使用**DTO和自定义结构如Object作为参数
|
||||
- **返回值类型:** TOCO的API运行在自己的Java脚手架中，脚手架会自动对API的返回值做一层对象包装（code、message、data）。所以在TOCO中，API的返回值无需考虑返回码和错误信息，只需考虑返回的数据本身。TOCO中API的返回值**只能**为VO、Enum、基本类型,可为单值或列表，**禁止使用**DTO、QTO、BTO、自定义结构如Object作为返回值。注意如果是对象类型，则优先使用VO作为返回值。
|
||||
- **TOCO中json结构描述:** 在TOCO中，API使用一个json结构表示，示例如下：
|
||||
```json
|
||||
{
|
||||
"methodName": "getUserMeetingList",
|
||||
"className": "MeetingQueryController",
|
||||
"usageScenario": "xxx",
|
||||
"requestParams":[
|
||||
{
|
||||
"name": "getMeetingListByUserId74Qto",
|
||||
"description": "查询参数",
|
||||
"type": "Qto",
|
||||
"uuid": "6351a4d4-0063-442f-abd7-a2df6d656988"
|
||||
},
|
||||
{
|
||||
"name": "test",
|
||||
"description": "是否为测试请求",
|
||||
"type": "Boolean"
|
||||
}
|
||||
],
|
||||
"response": {
|
||||
"type": "List",
|
||||
"innerType": "Vo",
|
||||
"innerUuid": "1d58352b-5333-4509-aec2-1abc3fac9122"
|
||||
}
|
||||
}
|
||||
```
|
||||
结构中一些关键字段描述如下：
|
||||
requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,PageResult,Vo,Qto,Bto,Void，其中参数不能为Void和PageResult，如果不需要返回值则type设置为Void，如果返回值为分页查询的结果则type设置为PageResult，且innerType必为Vo，对应代码中的VSQueryResult<XxxVo>；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Vo时传入该对象的uuid，当type为Qto时传入对应读方案的uuid、当type为Bto时传入对应写方案的uuid；innerType为List内部类型，当type为List时包含该字段；innerUuid为List或PageResult内部类结构的UUID，当type为List或PageResult且innerType为Enum、Eo、Vo时传入该对象的uuid，当innerType为Qto时传入对应读方案的uuid、当innerType为Bto时传入对应写方案的uuid。
|
||||
- **代码产物和修改建议**
|
||||
- **生成代码：** API会在entrance层生成Controller以及对应的API方法
|
||||
- **修改建议：** 建议修改API方法的实现内容，禁止直接修改API方法签名、URI，**注意**：如需修改API定义（名称、出入参数、URL）需要通过修改API设计元素实现
|
||||
#### **2.15 流程服务（FunctionFlow)**
|
||||
- **定义与用途:** TOCO针对复杂业务拆解，定义了流程服务，把一个复杂的业务过程，根据业务逻辑的内聚性，合并逻辑功能，把流程分解成流程节点，最终构造出一个类似工作流的逻辑流程；最终实现复杂业务流程分解，提升代码的可维护性。TOCO内嵌了流程引擎，在Function_Flow生成代码后，可以在流程引擎中执行
|
||||
- **何时使用:**
|
||||
- 如果一个API/RPC中涉及的写服务超过3个，则**必须**使用流程服务
|
||||
- 当用户要求使用流程服务
|
||||
- **节点的封装:**
|
||||
- 因为TOCO是一个面向数据处理的系统，所以数据内聚为首要考虑因素；一个节点通常围绕一个核心写服务，包括取数的读服务，为写服务的入参进行数据处理和转换，以及该写服务完成后的一些附属功能, 除了条件节点，入参校验，最终数据返回节点，每个节点至少包括一个写服务。
|
||||
- **关键配置:** 名称(小写字母+下划线)，拆解复杂业务逻辑，如果业务流程比较简单，则不需要使用流程服务
|
||||
- **如何创建/生成:**
|
||||
- 流程不是逻辑的伪代码，不需要表达全部逻辑细节，相关有内聚性，相似性的功能逻辑需要被封装到一个流程节点内；例如用户注册：创建用户需要，需要创建账号信息，需要创建用户信息，并且发送一个通知消息，这几个功能都属于创建用户相关信息，而且没有逻辑分叉，因此可以内聚在一个逻辑节点内。
|
||||
- 流程节点之间的参数和返回值的传递通过一个统一的上下文Context传递（在写代码的时候按需修改Context文件，添加所需的字段）
|
||||
- 定义了JSON结构，用于表达逻辑流。流程节点分为 “顺序节点”、“条件节点”，“选择节点”，"开始节点“ ，节点之间通过有向边连接，表示逻辑的执行方向；从开始节点开始，可达各个节点。
|
||||
- 节点的边的定义如下：顺序节点可以有多条入边，可以有多条出边（一个出边表示下一个执行的节点，多条出边表示几个分支并发执行）；条件节点可由多条入边，可以有2条出边，表示条件为True和False两种逻辑分支；选择节点可以有多条入边，可以有多条出边，每条出边表示一种选择路径；开始节点只能有一条出边，不能有入边;
|
||||
- ”条件节点“只封装条件判断逻辑，返回TRUE或者FALSE；”循环节点“只封装条件判断逻辑，返回TRUE或者FALSE；”选择节点“只封装分支选择逻辑，返回下游分支节点的名称；
|
||||
- 终止流程：直接抛出异常
|
||||
- 一般校验逻辑放在一个“顺序节点"中，如果校验失败，以异常的方式抛出
|
||||
- 节点可以复用，同样的功能可以抽取出来封装到一个节点中
|
||||
- **流程服务设计元素的表达：**
|
||||
- 以Json表达，Json Schema 定义如下：
|
||||
```json
|
||||
{
|
||||
"type": "object","description": "流程服务设计元素", "required": [ "description","name","nodes","edges"],
|
||||
"properties":
|
||||
{
|
||||
"name": { "type": "string", "description": "流程名称，英语描述，单词之间使用下划线分割，总称不超过32个字符" },
|
||||
"moduleName": {"type": "string", "description": "模块名称，创建流程时传入，指定流程服务所属的模块"},
|
||||
"uuid": {"type": "string", "description": "流程服务设计元素的uuid，创建流程不传入，在更新的时候必须传入"},
|
||||
"description": {"type": "string", "description": "流程服务描述, 总长度控制在200个字符内"},
|
||||
"nodes": {
|
||||
"type": "array", "description": "流程服务的节点列表",
|
||||
"items": {
|
||||
"type": "object","description": "流程服务节点对象", "required": ["name", "type", "description"],
|
||||
"properties": {
|
||||
"name": {"type": "string", "description": "节点名称, 英语描述，单词之间使用下划线分割，总称不超过32个字符"},
|
||||
"type": {"type": "string", "description": "节点 类型，可以是 PROCESS_NODE(顺序节点）、SWITCH_NODE(选择节点)、CONDITION_NODE(条件节点）,START_NODE(开始节点)"},
|
||||
"description": {"type": "string", "description": "描述节点的功能, 英语描述，单词之间使用下划线分割，总称不超过200个字符" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"edges": {
|
||||
"type": "array", "description": "流程服务的边列表",
|
||||
"items": {
|
||||
"type": "object","description": "流程服务的边", "required": ["fromNode", "toNode"],
|
||||
"properties": {
|
||||
"fromNode": {"type": "string", "description": "边的开始节点名称"},
|
||||
"toNode": {"type": "string", "description": "边的结束节点名称"},
|
||||
"value": {"type": "boolean", "description": "可选，作为条件节点的出边，true值表示条件匹配的分支,false表示条件不匹配的分支; 作为循环节点的出边，true值表示进入循环，false值表示退出循环"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
- 例子：用户注册流程
|
||||
<code>
|
||||
{
|
||||
"moduleName":"user",//该流程所属的模块
|
||||
"name":"user_register",//定义该流程的功能
|
||||
"description":"注册用户",//描述该流程的详细功能
|
||||
"nodes":[ // 定义该流程包含的节点
|
||||
{
|
||||
"name":"start",
|
||||
"type":"START_NODE",
|
||||
"description": "起始节点"
|
||||
},
|
||||
{
|
||||
"name":"check_user_registed",
|
||||
"type":"CONDITION_NODE",
|
||||
"description":"校验入参合法性；判断昵称是否重名；判断用户是否已注册"
|
||||
},
|
||||
{
|
||||
"name": "create_user",
|
||||
"descripiton":"创建用户，发送'用户创建'消息, 给用户发送欢迎通知",
|
||||
"type": "PROCESS_NODE"
|
||||
},
|
||||
{
|
||||
"name":"return_user_info",
|
||||
"descripiton":"返回用户信息，返回推荐给用户可能感兴趣的好友",
|
||||
"type":"PROCESS_NODE"
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"fromNode": "start",
|
||||
"toNode":"check_user_registed"
|
||||
},
|
||||
{
|
||||
"fromNode":"check_user_registed",
|
||||
"toNode":"create_user",
|
||||
"value":false
|
||||
},
|
||||
{
|
||||
"fromNode":"check_user_registed"
|
||||
"toNode":"return_user_info",
|
||||
"value":true
|
||||
},
|
||||
{
|
||||
"fromNode":"create_user",
|
||||
"toNode":"return_user_info"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
</code>
|
||||
```
|
||||
- 例子：用户注册流程
|
||||
<code>
|
||||
{
|
||||
"moduleName":"user",//该流程所属的模块
|
||||
"name":"user_register",//定义该流程的功能
|
||||
"description":"注册用户",//描述该流程的详细功能
|
||||
"nodes": [ // 定义该流程包含的节点
|
||||
{
|
||||
"name":"start",
|
||||
"type":"START_NODE",
|
||||
"description": "起始节点"
|
||||
},
|
||||
{
|
||||
"name":"check_user_registed",
|
||||
"type":"CONDITION_NODE",
|
||||
"description":"校验入参合法性；判断昵称是否重名；判断用户是否已注册"
|
||||
},
|
||||
{
|
||||
"name": "create_user",
|
||||
"descripiton":"创建用户，发送'用户创建'消息, 给用户发送欢迎通知",
|
||||
"type": "PROCESS_NODE"
|
||||
},
|
||||
{
|
||||
"name":"return_user_info",
|
||||
"descripiton":"返回用户信息，返回推荐给用户可能感兴趣的好友",
|
||||
"type":"PROCESS_NODE"
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"fromNode": "start",
|
||||
"toNode":"check_user_registed"
|
||||
},
|
||||
{
|
||||
"fromNode":"check_user_registed",
|
||||
"toNode":"create_user",
|
||||
"value":false
|
||||
},
|
||||
{
|
||||
"fromNode":"check_user_registed"
|
||||
"toNode":"return_user_info",
|
||||
"value":true
|
||||
},
|
||||
{
|
||||
"fromNode":"create_user",
|
||||
"toNode":"return_user_info"
|
||||
}
|
||||
]
|
||||
}
|
||||
</code>
|
||||
- **代码产物和修改建议**
|
||||
- **FlowConfig**
|
||||
* **生成产物:** 每个模块在service层的生成一个Java类，负责注册模块下的所有流程到执行器
|
||||
@@ -1396,8 +1396,7 @@ meeting_with_room_and_agenda_wo示例：
|
||||
- 用户登录，在UserFlowService中生成一个函数invokeLoginFlow，该函数通过流程框架根据流程定义调用LoginNode，LoginNode中封装了用户登录的逻辑，LoginFlowContext中封装了用户登录的参数和结果。
|
||||
- **修改建议：** 不修改 service 中的函数, 不修改FlowConfig, 可以修改FlowContext, 添加/修改出入参数， 修改FlowNode中的具体业务逻辑。
|
||||
|
||||
|
||||
#### **2.12 自定义查询**
|
||||
#### **2.16 自定义查询**
|
||||
- 在读方案无法满足需求的情况下，可以使用自定义查询
|
||||
- 自定查询使用复杂的sql实现业务功能
|
||||
- 自定义查询的数据访问层使用MyBatis、MyBatisPlus实现
|
||||
|
||||
Reference in New Issue
Block a user