toco/docs
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新 llms-full.txt

Browse Source
This commit is contained in:
ycl
2025-06-22 14:59:22 +08:00
parent 2f1c1c2498
commit 3cdc037fd9
1 changed files with 488 additions and 485 deletions
Download Patch File Download Diff File Expand all files Collapse all files

367
llms-full.txt
View File

@@ -9,6 +9,8 @@
- **定义与用途:** 在TOCO中，我们将系统领域细分为具体的模块，映射为Java工程中的module。这些模块代表了系统的叶子子域，每个模块负责特定的功能。模块划分有助于系统的可维护性和可扩展性，并能提高开发效率和代码质量 - **定义与用途:** 在TOCO中，我们将系统领域细分为具体的模块，映射为Java工程中的module。这些模块代表了系统的叶子子域，每个模块负责特定的功能。模块划分有助于系统的可维护性和可扩展性，并能提高开发效率和代码质量
- **关键配置:** 名称(小写英文字母+下划线，如meeting,user_detail,禁止加任何固定后缀)，描述 - **关键配置:** 名称(小写英文字母+下划线，如meeting,user_detail,禁止加任何固定后缀)，描述
- **与其他元素关系:** 下面的每种设计元素都属于一个模块 - **与其他元素关系:** 下面的每种设计元素都属于一个模块
- **代码产物：** 每个Module会单独生成一个Java Module：项目路径/modules/模块名，内部采用了entrance、service、manager、persist、common分层结构
#### **2.2 枚举 (Enum)** #### **2.2 枚举 (Enum)**
- **定义与用途:** Enum用来表达一些常量值的集合，可被其他模块使用，可被用来做为字段的类型 - **定义与用途:** Enum用来表达一些常量值的集合，可被其他模块使用，可被用来做为字段的类型
- **关键属性/配置:** 名称(以_enum结尾)，枚举值列表(全大写字母+下划线) - **关键属性/配置:** 名称(以_enum结尾)，枚举值列表(全大写字母+下划线)
@@ -31,6 +33,14 @@
"required":["name","description"] "required":["name","description"]
} }
``` ```
* **代码产物和修改建议**
* **生成产物**：在common模块中生成一个Java类
* **职责:** 表达Enum的数据结构
* **命名规则**：类名以Enum结尾
* **类路径：** 位于 ```**.common.enums``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Enum在TOCO中的uuid}|ENUM|DEFINITION
- **生成代码：** Enum会在common层生成Enum文件，如StatusEnum
- **修改建议：** 不建议修改
#### **2.3 值对象 (Eo)** #### **2.3 值对象 (Eo)**
- **定义与用途:** EO为一种POJO对象结构，可被其他模块使用，可被用来做为实体字段的类型。 - **定义与用途:** EO为一种POJO对象结构，可被其他模块使用，可被用来做为实体字段的类型。
- **关键属性/配置:** 名称(以_eo结尾)。EO的字段类型只能为基本类型（含List）、EO、Enum，其他类型不允许。 - **关键属性/配置:** 名称(以_eo结尾)。EO的字段类型只能为基本类型（含List）、EO、Enum，其他类型不允许。
@@ -63,15 +73,65 @@
"required":["name","description"] "required":["name","description"]
} }
``` ```
* **代码产物和修改建议**
* **生成产物**：在persist层生成结构定义类文，如AddressEo
* **职责:** 表达POJO数据结构
* **命名规则**：类名以Eo结尾
* **类路径：** 位于 ```**.persist.eo``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Eo在TOCO中的uuid}|EO|DEFINITION
- **修改建议：** 不建议修改
#### **2.4 实体关系 (ER / Entity)** #### **2.4 实体关系 (ER / Entity)**
- **定义与用途:** 实体及其关系。一个实体一般对应一个数据库表，关系为实体间的外键依赖关系 - **定义与用途:** 实体及其关系。一个实体一般对应一个数据库表，关系为实体间的外键依赖关系
- **关键属性/配置:** 实体中包含名称、字段、字段类型、主键、索引等，关系分为1:1和1:N关系 - **关键属性/配置:** 实体中包含名称、字段、字段类型、主键、索引等，关系分为1:1和1:N关系
- **与其他元素关系:** 实体关系是聚合的基础，也是DTO和VO的派生基础 - **与其他元素关系:** 实体关系是聚合的基础，也是DTO和VO的派生基础
- **代码产物和修改建议**
- 结构定义
* **生成产物**：Java类，按照Mybatis-plus的要求生成
* **职责:** 按照Mybatis-plus的要求生成结构定义类文件
* **类路径：** 位于 ```**.persist.dos``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|DEFINITION
- Mapper
* **生成产物**：在persist层生成Mybatis-plus的Mapper类
* **职责:** 提供Mapper给Mybatis-plus框架
* **命名规则**：类名以Mapper结尾(${entityName}Mapper)
* **类路径：** 位于 ```**.persist.mapper.mybatis``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Eo在TOCO中的uuid}
- Dao接口
* **生成产物**：在persist层生成Dao接口
* **职责:** 提供Entity数据的查询接口，为service层提供数据访问入口
* **命名规则**：类名以Dao结尾(${entityName}Dao)
* **类路径：** 位于 ```**.persist.mapper``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|IDAO
- Dao实现
* **生成产物**：在persist层生成Dao接口的实现类文件
* **职责:** 通过调用Mapper实现实现Dao接口
* **命名规则**：类名以DaoImpl结尾(${entityName}DaoImpl)
* **类路径：** 位于 ```**.persist.mapper``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|DAO
- **修改建议：** 不建议修改
#### **2.5 聚合对象 (BO/业务对象)** #### **2.5 聚合对象 (BO/业务对象)**
- **定义与用途:** 在TOCO中，聚合对象是对一组密切关联的实体的封装。聚合对象从单一实体开始，这个实体我们称为聚合根，通过实体间关系，不断的顺序将其他实体按层级关系组装进这个聚合对象。聚合对象可以按实体表达为树形结构。聚合对象提供了这组实体的内存一致性视图，提供数据操作入口。由于写操作的内聚性，聚合对象只能在单一模块中组合，而且一个实体只能属于一个对象。同样如果有实体不在任何一个聚合对象中，TOCO将无法提供与之相关的写方法。 - **定义与用途:** 在TOCO中，聚合对象是对一组密切关联的实体的封装。聚合对象从单一实体开始，这个实体我们称为聚合根，通过实体间关系，不断的顺序将其他实体按层级关系组装进这个聚合对象。聚合对象可以按实体表达为树形结构。聚合对象提供了这组实体的内存一致性视图，提供数据操作入口。由于写操作的内聚性，聚合对象只能在单一模块中组合，而且一个实体只能属于一个对象。同样如果有实体不在任何一个聚合对象中，TOCO将无法提供与之相关的写方法。
- **包含元素:** 聚合对象包括聚合根及其聚合下的其他子实体对象，例如，商品聚合ProductBO中，商品基本信息实体是ProductBO的聚合根，商品SKU实体、商品库存实体是ProductBO的子聚合对象。 - **包含元素:** 聚合对象包括聚合根及其聚合下的其他子实体对象，例如，商品聚合ProductBO中，商品基本信息实体是ProductBO的聚合根，商品SKU实体、商品库存实体是ProductBO的子聚合对象。
- **关键配置:** 名称(${EntityName驼峰}BO结尾，如StaffBO)，聚合根实体，聚合子对象实体。每个聚合必须包含一个聚合根 - **关键配置:** 名称(${EntityName驼峰}BO结尾，如StaffBO)，聚合根实体，聚合子对象实体。每个聚合必须包含一个聚合根
- **与其他元素关系:** 聚合是写方案的基础 - **与其他元素关系:** 聚合是写方案的基础
- **代码产物和修改建议**
- 综述
- 业务对象包含多个Entity，通过业务对象的嵌套组合表达了Entity之间的关系，如果一个业务对象包含了子对象，则会生成BO和BaseBO,BaseBO封装实体属性和关系，子类留给业务扩展逻辑；
如果是叶子节点（不存在子对象）的BO，则直接生成BO类文件，不生成BaseBO类文件
- BO
* **生成产物**：在Manager层生成聚合对象类文件，符合Hibernate的标准
* **职责:** 定义聚合对象，多个聚合对象组合成层级结构实现充血模型，支持写链路上的数据变更，监听数据变更，支持数据校验
* **命名规则**：类名以BO结尾(${entityName}BO)
* **类路径：** 位于 ```**.manager.bo``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|BO|DEFINITION
- **修改建议：** 建议修改BO中的validateAggregate或valid方法。不建议修改检验方法以外的其他代码，如果发现需求中有业务不变性校验，**注意** 上述的校验方法，在写方案内部由框架触发调用，而不是业务代码显式调用
- BaseBO
* **生成产物**：对于存在子BO的聚合对象，封装不变的代码部分
* **职责:** 定义聚合对象，多个聚合对象组合成层级结构实现充血模型，支持写链路上的数据变更，监听数据变更，支持数据校验
* **命名规则**：类名以BO结尾(${entityName}BO)
* **类路径：** 位于 ```**.manager.bo``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|BO|DEFINITION
- **修改建议：** 建议修改BO中的validateAggregate或valid方法，如果发现需求中有业务不变性校验;不建议修改检验方法以外的其他代码
#### **2.6 数据传输对象 (DTO)** #### **2.6 数据传输对象 (DTO)**
- **定义与用途:** 在TOCO中，DTO表达某个Entity为基本，通过外键关系不断关联多个Entity的数据结构。DTO还隐式表达了数据的取数拼装，这种拼装符合外键关系。往往被当做RPC的返回值、或读方案的返回值使用，不建议把DTO作为入参。注意DTO不能作为HTTP API的返回值。DTO分为BaseDTO和普通DTO，BaseDTO派生自Entity，包含Entity的所有字段，每个Entity有且仅有一个BaseDTO；普通DTO派生自BaseDTO，包含BaseDTO的所有字段，且可以增加扩展字段或自定义字段 - **定义与用途:** 在TOCO中，DTO表达某个Entity为基本，通过外键关系不断关联多个Entity的数据结构。DTO还隐式表达了数据的取数拼装，这种拼装符合外键关系。往往被当做RPC的返回值、或读方案的返回值使用，不建议把DTO作为入参。注意DTO不能作为HTTP API的返回值。DTO分为BaseDTO和普通DTO，BaseDTO派生自Entity，包含Entity的所有字段，每个Entity有且仅有一个BaseDTO；普通DTO派生自BaseDTO，包含BaseDTO的所有字段，且可以增加扩展字段或自定义字段
- **如何创建/生成:** 对于每个Entity，TOCO会自动生成一个BaseDTO，命名为${Entity名字}BaseDto，如UserBaseDto，该BaseDTO包含了Entity的全部字段。除了BaseDTO，其他的DTO均需要手动以BaseDTO为根来创建。在TOCO中，必须要先判断需要的DTO是否为BaseDTO，如果是BaseDTO，则可通过Entity名称获取BaseDTO；如果不是BaseDTO，则需要通过DTO要表达的信息来创建DTO，如：会议及其议程信息。 - **如何创建/生成:** 对于每个Entity，TOCO会自动生成一个BaseDTO，命名为${Entity名字}BaseDto，如UserBaseDto，该BaseDTO包含了Entity的全部字段。除了BaseDTO，其他的DTO均需要手动以BaseDTO为根来创建。在TOCO中，必须要先判断需要的DTO是否为BaseDTO，如果是BaseDTO，则可通过Entity名称获取BaseDTO；如果不是BaseDTO，则需要通过DTO要表达的信息来创建DTO，如：会议及其议程信息。
@@ -142,7 +202,7 @@ DateTime endTime； //会议结束时间
"uuid": null, "uuid": null,
"name": "meeting_room_with_meetings_dto", "name": "meeting_room_with_meetings_dto",
"fromEntity": "meeting_room", "fromEntity": "meeting_room",
"description": "会议室信息，包含会议列表", "description": "会议室信息，包含会议列表"
} }
} }
], ],
@@ -177,7 +237,7 @@ DateTime endTime； //会议结束时间
}, },
"fieldName": "meeting_list" "fieldName": "meeting_list"
} }
], ]
} }
} }
``` ```
@@ -195,6 +255,32 @@ DateTime endTime； //会议结束时间
- b. 如果通过其他复杂查询条件，则可以采用第2种方式 - b. 如果通过其他复杂查询条件，则可以采用第2种方式
注意判断使用哪种方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！**如果现实中的代码和TOCO中的步骤有冲突时，只能使用TOCO的定义！** 注意判断使用哪种方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！**如果现实中的代码和TOCO中的步骤有冲突时，只能使用TOCO的定义！**
- **代码产物和修改建议**
- 结构定义
* **生成产物**：一个Java类
* **职责:** 表达DTO的数据结构
* **命名规则**：类名以Dto结尾
* **类路径：** 位于 ```**.manager.dto``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|DEFINITION
- **Manager**
* **生成产物:** Java接口以及实现类
* **命名规则:** 接口类名以Manager结尾、实现类名以ManagerImpl结尾(${DtoName}Manager)、基类以名ManagerBaseImpl结尾(${DtoName}ManagerImpl)
* **职责:** 提供了DTO数据的获取的接口，包括根据id单个、id列表批量获取、以及根据DTO对应的实体的数据库索引获取
* **类路径：** 位于 ```**.manager``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|MANAGER
- **Converter**
* **生成产物:** Java实现类以及基类
* **命名规则:** 实现类名以Converter结尾(${DtoName}Converter)、基类名以BaseConverter结尾(${DtoName}BaseConverter)
* **职责:** Entity转换到BaseDTO或则BaseDTO转化为普通DTO：从Entity转为BaseDTO的方法命名为convert${EntityName}To${DtoName}；从BaseDTO转换为DTO的方法命名为convert${BaseDtoName}To${DtoName}
* **类路径：** 位于 ```**.manager.converter``` 包路径下
* **唯一标识符位置：**
* 实现类Converter 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|CONVERTER
* 基类BaseConverter 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|BASE_CONVERTER
- **例子:**
* 如UserDto、UserDtoManager、UserDtoConverter extends UserDtoBaseConverter、UserDtoService或（名称为${DtoName}Service，内部包含getById,getByIds等方法）。如果Dto为UserBaseDto，则生成的类名为UserBaseDtoService
- **修改建议：**
- 建议在Service与BaseConverter中进行代码扩展，不建议修改结构定义文件和Manager文件。其中DTO的**自定义字段**由于不直接派生自Entity，所以一般会对应取数逻辑代码。通常如果涉及到数据获取、计算和拼装，批量处理的性能最好，所以代码位置**必须**放在BaseConverter中已经自动生成的**列表**转换方法中，批量取数组装，如UserBaseDtoBaseConverter.convertUserToUserBaseDto(List<User>)或UserDtoBaseConverter.convertUserBaseDtoToUserDto(List<UserBaseDto>)
#### **2.7 视图对象 (VO)** #### **2.7 视图对象 (VO)**
- **定义与用途:** 在TOCO中，VO表达某个BaseDTO(如果用户指明派生源，也可使用其他DTO)为派生源，通过外键关系不断关联多个BaseDTO的数据结构。VO用于在视图层与前端之间进行数据传输，往往被当做HTTP API的返回值、或读方案的返回值使用，由服务端返回至前端。注意VO不能作为RPC的返回值。 - **定义与用途:** 在TOCO中，VO表达某个BaseDTO(如果用户指明派生源，也可使用其他DTO)为派生源，通过外键关系不断关联多个BaseDTO的数据结构。VO用于在视图层与前端之间进行数据传输，往往被当做HTTP API的返回值、或读方案的返回值使用，由服务端返回至前端。注意VO不能作为RPC的返回值。
- **关键配置:** 名称(以Vo结尾)、根Entity、派生源、字段列表。VO中的字段分为三种：a.继承DTO的字段，和DTO的字段类型一样；b.扩展字段，含正向替换和反向注入字段，类型为VO或List<VO>;c.自定义字段，类型为基本类型或VO类型。VO中的字段来源于DTO，可以根据页面需要将无用字段进行裁剪，可以根据外键关系扩展其他BaseDto(详见**字段扩展方式**)。如果在派生源中没有合适字段，且明确无法通过外键扩展外部BaseDto的情况下，可增加对应的自定义字段 - **关键配置:** 名称(以Vo结尾)、根Entity、派生源、字段列表。VO中的字段分为三种：a.继承DTO的字段，和DTO的字段类型一样；b.扩展字段，含正向替换和反向注入字段，类型为VO或List<VO>;c.自定义字段，类型为基本类型或VO类型。VO中的字段来源于DTO，可以根据页面需要将无用字段进行裁剪，可以根据外键关系扩展其他BaseDto(详见**字段扩展方式**)。如果在派生源中没有合适字段，且明确无法通过外键扩展外部BaseDto的情况下，可增加对应的自定义字段
@@ -357,6 +443,28 @@ DateTime endTime； //会议结束时间
- c. 如果用户上下文中有指定的返回DTO的读方案符合条件，则使用第2种，否则使用第3种 - c. 如果用户上下文中有指定的返回DTO的读方案符合条件，则使用第2种，否则使用第3种
注意判断使用哪种方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！**如果现实中的代码编写方式和TOCO中的步骤有冲突时，只能使用TOCO的定义！** 注意判断使用哪种方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！**如果现实中的代码编写方式和TOCO中的步骤有冲突时，只能使用TOCO的定义！**
- **代码产物和修改建议**
- **结构定义**
* **生成产物:** 在controller层生成一个Java类
* **命名规则:** 类名以Vo结尾
* **职责:** 表达VO的数据结构
* **类路径:** 位于 ```**.entrance.web.vo``` 包路径下
* **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${VO在TOCO中的uuid}|VO|DEFINITION
- **Converter**
* **生成产物:** 在controller层生成一个Java类(**有派生源**的VO才有Converter)和基类
* **命名规则:** 实现类名以Converter结尾(${VoName}Converter)，基类名以BaseConverter结尾(${VoName}BaseConverter)
* **类路径:** 位于 ```**.entrance.web.converter``` 包路径下
* **职责:** 把DTO转换成VO；Converter中包含2种convert方法：1.基础convert方法，从DTO转换为VO，仅转换结构，方法命名为convertTo${VoName}、convertTo${VoName}List、convertTo${VoName}Map，其中**Map转换方法**为底层批量方法，单个和列表convert方法都通过**调用Map方法**来实现;2.带数据拼装逻辑的convert方法，内部会调用基础convert方法从DTO转换为VO，然后再根据外键获取拼装最终数据，方法命名为convertAndAssembleData、convertAndAssembleDataList)
* **唯一标识符位置:**
* 实现类Converter其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${VO在TOCO中的uuid}|VO|CONVERTER
* 基类BaseConverter其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|BASE_CONVERTER
* **例子:**
* 如UserDetailVo、UserDetailVoConverter（包含convertToUserDetailVo、convertToUserDetailVoList、convertToUserDetailVoMap、convertAndAssembleData、convertAndAssembleDataList方法）
- **修改建议：**
- 建议在Converter中进行代码扩展，不建议修改结构定义文件。其中VO的**自定义字段**由于不直接派生自DTO，所以一般会对应取数逻辑代码。通常如果涉及到数据获取、计算和拼装，批量处理的性能最好，所以自定义字段对应的代码位置**必须**放在Converter的**Map**基础转换方法convertTo${VoName}Map中，批量取数组装，如UserVoConverter.convertToUserVoMap
#### **2.8 读方案 (ReadPlan)** #### **2.8 读方案 (ReadPlan)**
- **定义与用途:** 在TOCO中，读方案描述了一种数据库查询方案，查询条件为一个面向对象的查询语句，其中可以包含存在外键关系的多个实体的字段(如age=18 and name like #nameLike and school.name like #schoolNameLike，其中以#开头的是自定义参数，会自动生成一个QTO结构，由查询调用方动态传入),结果为符合查询条件的**一种**DTO或VO列表。读方案内部会将该面向对象的查询条件转化为复杂的join sql语句，来实现对数据库的查询，以及返回的复杂DTO和VO数据的组装。读方案可以指定其分页方式（不分页、页码分页、瀑布流分页），以及是否生成计数方法(用于返回符合条件的记录数量)。 - **定义与用途:** 在TOCO中，读方案描述了一种数据库查询方案，查询条件为一个面向对象的查询语句，其中可以包含存在外键关系的多个实体的字段(如age=18 and name like #nameLike and school.name like #schoolNameLike，其中以#开头的是自定义参数，会自动生成一个QTO结构，由查询调用方动态传入),结果为符合查询条件的**一种**DTO或VO列表。读方案内部会将该面向对象的查询条件转化为复杂的join sql语句，来实现对数据库的查询，以及返回的复杂DTO和VO数据的组装。读方案可以指定其分页方式（不分页、页码分页、瀑布流分页），以及是否生成计数方法(用于返回符合条件的记录数量)。
- **使用建议:** 如果查询条件只有主键，则建议使用预定义的getBy${PrimaryKey}或getBy${PrimaryKey}s方法来获取DTO（参照DTO的**预定义方法**）或VO（参照**复杂嵌套VO获取流程**），不建议使用读方案。非主键查询或多条件查询建议使用读方案。 - **使用建议:** 如果查询条件只有主键，则建议使用预定义的getBy${PrimaryKey}或getBy${PrimaryKey}s方法来获取DTO（参照DTO的**预定义方法**）或VO（参照**复杂嵌套VO获取流程**），不建议使用读方案。非主键查询或多条件查询建议使用读方案。
@@ -557,6 +665,39 @@ DateTime endTime； //会议结束时间
} }
} }
``` ```
- **代码产物和修改建议**
- **Service**
* **生成产物:** 在Service层生成一个Java类
* **命名规则:** 类名以QtoService结尾(${ReadPlanName}QtoService)
* **类路径:** 位于 ```**.service.index.entity```包路径下
* **职责:** 提供查询入口；返回符合查询条件的DTO或VO的id列表（分页、全部、或则瀑布流）,以及返回符合条件的总数。 在TOCO的读链路中，数据查询分2步骤，1. 获取符合查询条件的DTO或VO的id列表，2. 根据id列表组装DTO或VO列表。
* **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定，uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|SERVICE
- **查询传输对象(QTO)**
* **生成产物:** 在Service层生成一个Java类
* **命名规则:** 类名以Qto结尾(${ReadPlanName}Qto)
* **类路径:** 位于 ```**.persist.qto```包路径下
* **职责:** 读方案的查询参数结构
* **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|DEFINITION
- **Dao**
- **生成产物:** 在Dao层生成一个Java类
- **命名规则:** 类名以Dao结尾(${ReadPlanName}Dao)
- **类路径:** 位于 ```**.persist.mapper```包路径下
- **职责:** 读方案对应的数据库查询方法
- **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|DAO
- **QueryExecutor**
- **生成产物** 对于返回**VO**的查询方案，在controller层生成一个Java类
- **命名规则:** 类名以QueryExecutor结尾(${WritePlanName}QueryExecutor)
- **类路径:** 位于 ```**.entrance.web.query.executor```包路径下
- **职责:** 把QtoService返回的id数据转化成目标**VO**
- **QueryService**
- **生成产物** 对于返回**DTO**的查询方案，在service层生成一个Java类
- **命名规则:** 类名以QueryService结尾(${WritePlanName}QueryService)
- **类路径:** 位于 ```**.service.index.entity```包路径下
- **职责:** 把QtoService返回的id数据转化成目标**DTO**
- **例子:**
* 根据用户名称查询用户列表返回UserDTO，则生成UserNameQto、UserNameQtoService、UserNameQtoDao、UserNameQueryService; UserNameQueryService调用UserNameQtoService，UserNameQtoService调用UserNameQtoDao
- **修改建议：**
- 如果有对结果的数据二次处理，建议在QueryService和QueryExecutor中进行代码扩展，不建议修改QTO文件
#### **2.9 查询传输对象(QTO)** #### **2.9 查询传输对象(QTO)**
- **定义与用途:** 在TOCO中，QTO为读方案的查询参数结构，每个读方案会对应一个QTO，写方案调用方按照QTO的结构向读方案生成的RPC方法传入需要查询的实体字段值，完成对数据库的查询 - **定义与用途:** 在TOCO中，QTO为读方案的查询参数结构，每个读方案会对应一个QTO，写方案调用方按照QTO的结构向读方案生成的RPC方法传入需要查询的实体字段值，完成对数据库的查询
- **如何创建/生成:** 在创建读方案后，TOCO会自动生成QTO作为该读方案传入的查询参数结构，无需单独创建 - **如何创建/生成:** 在创建读方案后，TOCO会自动生成QTO作为该读方案传入的查询参数结构，无需单独创建
@@ -600,7 +741,7 @@ DateTime endTime； //会议结束时间
"operations": { "operations": {
"type":"array","description":"定义了对写方案涉及到的相关实体的操作，包括操作类型和相关字段", "type":"array","description":"定义了对写方案涉及到的相关实体的操作，包括操作类型和相关字段",
"items":{ "items":{
"type": "object", "description":"定义了对具体一个实体的操作，包括操作类型和相关字段" "type": "object", "description":"定义了对具体一个实体的操作，包括操作类型和相关字段",
"properties":{ "properties":{
"bo":{"type":"string","description":"具体操作的实体"}, "bo":{"type":"string","description":"具体操作的实体"},
"action":{"type":"string","description":"对具体实体的操作"}, "action":{"type":"string","description":"对具体实体的操作"},
@@ -681,6 +822,28 @@ DateTime endTime； //会议结束时间
] ]
} }
``` ```
- **代码产物和修改建议**
- **Service:**
* **生成产物:** 在对应的聚合服务BoService里生成一个函数
* **函数命名规则:** 和写方案同名
* **职责:** 按需对入参进行转换，调用BaseBOService里的函数完成对聚合对象的操作, 实现对数据库的写操作；
* **BoService的类路径:** ```**.service```
* **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${WritePlan在TOCO中的uuid}
- **BaseBoService**
- **生成产物:** 在对应的聚合的BaseBoService里生成一系列函数，根据入参完成对聚合对象的变更
- **职责** 增对每个实体的生成增删改的函数，并且根据参数的结构以及聚合的结构，构建嵌套的调用逻辑，完成对一个聚合对象的变更，记录并且返回对应的变更情况
- **类路径:** ```**.service.base```
- **BTO (业务变更传输对象)**
* **生成产物:** 一个Java类，以内部类的方式表示层级结构
* **命名规则:** 一个Bto结尾(${WritePlanName}Bto，驼峰展示)
* **类路径:** 位于```**.service.bto```包路径下
* **职责:** 在**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的函数, 一起完成了用户的创建和设置创建的逻辑。
- **修改建议：**
- 不能修改BaseBoService中的函数，不建议修改BTO文件。建议在BOService中进行手动代码扩展，处理可能被复用的修改前后的逻辑，如修改数据库的前后值对比、或常被复用的校验逻辑（业务不变性校验逻辑除外）、需要经常在一个事务内执行的其他写操作等。
#### **2.11 业务变更传输对象(BTO)** #### **2.11 业务变更传输对象(BTO)**
- **定义与用途:** 在TOCO中，BTO为写方案自动生成的参数结构，每个写方案会生成一个BTO。BTO为写方案选定的操作实体根据关系形成的树形集合，最外层为聚合根。写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要操作的实体字段值，完成对数据库的写操作 - **定义与用途:** 在TOCO中，BTO为写方案自动生成的参数结构，每个写方案会生成一个BTO。BTO为写方案选定的操作实体根据关系形成的树形集合，最外层为聚合根。写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要操作的实体字段值，完成对数据库的写操作
- **如何创建/生成:** 在创建写方案后，TOCO会自动生成一个BTO作为该写方案传入的参数结构，无需通过TOCO创建。 - **如何创建/生成:** 在创建写方案后，TOCO会自动生成一个BTO作为该写方案传入的参数结构，无需通过TOCO创建。
@@ -725,6 +888,9 @@ DateTime endTime； //会议结束时间
``` ```
结构中一些关键字段描述如下： 结构中一些关键字段描述如下：
requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,Dto,Qto,Bto,Void，其中参数不能为Void，如果不需要返回值，则type设置为Void；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Dto、Qto、Bto时包含该字段；innerType为List内部类型，当type为List时包含该字段；innerUuid为List内部类结构的UUID，当type为List且innerType为Enum、Eo、Dto、Qto、Bto时包含该字段。 requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,Dto,Qto,Bto,Void，其中参数不能为Void，如果不需要返回值，则type设置为Void；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Dto、Qto、Bto时包含该字段；innerType为List内部类型，当type为List时包含该字段；innerUuid为List内部类结构的UUID，当type为List且innerType为Enum、Eo、Dto、Qto、Bto时包含该字段。
- **代码产物和修改建议**
- **生成代码：** RPC会在service层中生成类文件及实现函数，包含DTO自动生成的RPC如UserDtoService.getById或UserBaseDtoService.getById、读写方案自动生成的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.13 应用程序接口 (API)** #### **2.13 应用程序接口 (API)**
- **定义与用途:** 在TOCO中，API用于定义对外暴露的HTTP接口 - **定义与用途:** 在TOCO中，API用于定义对外暴露的HTTP接口
- **如何创建/生成:** API一般为通过TOCO创建，需指定具体的参数和返回值等 - **如何创建/生成:** API一般为通过TOCO创建，需指定具体的参数和返回值等
@@ -758,7 +924,10 @@ requestParams为请求参数列表，response为返回结构，requestParams中
``` ```
结构中一些关键字段描述如下： 结构中一些关键字段描述如下：
requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,Vo,Qto,Bto,Void，其中参数不能为Void，如果不需要返回值，则type设置为Void；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Vo、Qto、Bto时包含该字段；innerType为List内部类型，当type为List时包含该字段；innerUuid为List内部类结构的UUID，当type为List且innerType为Enum、Eo、Vo、Qto、Bto时包含该字段。 requestParams为请求参数列表，response为返回结构，requestParams中每个参数和response的结构相同，其中：name为参数名;type为参数类型，参数类型取值范围为Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,Vo,Qto,Bto,Void，其中参数不能为Void，如果不需要返回值，则type设置为Void；description为描述；typeUuid为参数对应类结构的UUID，当type为Enum、Eo、Vo、Qto、Bto时包含该字段；innerType为List内部类型，当type为List时包含该字段；innerUuid为List内部类结构的UUID，当type为List且innerType为Enum、Eo、Vo、Qto、Bto时包含该字段。
#### **2.14 流程服务（Function_Flow)** - **代码产物和修改建议**
- **生成代码：** API会在entrance层生成Controller以及对应的API方法
- **修改建议：** 建议修改API方法的实现内容，不建议修改API方法签名、URI
#### **2.14 流程服务（FunctionFlow)**
- **定义与用途:** TOCO针对复杂业务拆解，定义了流程服务，把一个复杂的业务过程，根据业务逻辑的内聚性，合并逻辑功能，把流程分解成流程节点，最终构造出一个类似工作流的逻辑流程；最终实现复杂业务流程分解，提升代码的可维护性。TOCO内嵌了流程引擎，在Function_Flow生成代码后，可以在流程引擎中执行 - **定义与用途:** TOCO针对复杂业务拆解，定义了流程服务，把一个复杂的业务过程，根据业务逻辑的内聚性，合并逻辑功能，把流程分解成流程节点，最终构造出一个类似工作流的逻辑流程；最终实现复杂业务流程分解，提升代码的可维护性。TOCO内嵌了流程引擎，在Function_Flow生成代码后，可以在流程引擎中执行
- **何时使用:** - **何时使用:**
- 如果一个API/RPC中涉及的写服务超过3个，则推荐使用流程服务 - 如果一个API/RPC中涉及的写服务超过3个，则推荐使用流程服务
@@ -842,205 +1011,39 @@ requestParams为请求参数列表，response为返回结构，requestParams中
] ]
} }
``` ```
- **代码产物和修改建议**
### **3. TOCO 代码生成说明** - **FlowConfig**
#### **3.1 生成代码产物说明**
- **3.1.1 支持的语言/框架**
Java、SpringBoot、MyBatis-plus(读)、Hibernate(写)
- **3.1.2 特殊注解及含义**
TOC自动生成的类和方法会带有@AutoGenerated注解，注解中有2个属性:locked为boolean类型，如果locked=true，则代表该文件或方法不建议修改;uuid为String类型，表示该类或方法的唯一标识，如果uuid中包含|字符，则说明该uuid为特殊格式，由不同类型的数据拼装而成(见**[3.2 设计元素到代码的映射规则及修改建议]**中每种设计元素的代码说明）。
#### **3.2 设计元素到代码的映射规则及修改建议**
##### 3.2.1 Module
- **生成代码：** 每个Module会单独生成一个Java Module：项目路径/modules/模块名，内部采用了entrance、service、manager、persist、common分层结构
##### 3.2.2 Enum
* **生成产物**：在common模块中生成一个Java类
* **职责:** 表达Enum的数据结构
* **命名规则**：类名以Enum结尾
* **类路径：** 位于 ```**.common.enums``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Enum在TOCO中的uuid}|ENUM|DEFINITION
- **生成代码：** Enum会在common层生成Enum文件，如StatusEnum
- **修改建议：** 不建议修改
##### 3.2.3 EO
* **生成产物**：在persist层生成结构定义类文，如AddressEo
* **职责:** 表达POJO数据结构
* **命名规则**：类名以Eo结尾
* **类路径：** 位于 ```**.persist.eo``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Eo在TOCO中的uuid}|EO|DEFINITION
- **修改建议：** 不建议修改
##### 3.2.4 Entity
- 结构定义
* **生成产物**：Java类，按照Mybatis-plus的要求生成
* **职责:** 按照Mybatis-plus的要求生成结构定义类文件
* **类路径：** 位于 ```**.persist.dos``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|DEFINITION
- Mapper
* **生成产物**：在persist层生成Mybatis-plus的Mapper类
* **职责:** 提供Mapper给Mybatis-plus框架
* **命名规则**：类名以Mapper结尾(${entityName}Mapper)
* **类路径：** 位于 ```**.persist.mapper.mybatis``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Eo在TOCO中的uuid}
- Dao接口
* **生成产物**：在persist层生成Dao接口
* **职责:** 提供Entity数据的查询接口，为service层提供数据访问入口
* **命名规则**：类名以Dao结尾(${entityName}Dao)
* **类路径：** 位于 ```**.persist.mapper``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|IDAO
- Dao实现
* **生成产物**：在persist层生成Dao接口的实现类文件
* **职责:** 通过调用Mapper实现实现Dao接口
* **命名规则**：类名以DaoImpl结尾(${entityName}DaoImpl)
* **类路径：** 位于 ```**.persist.mapper``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|DAO
- **修改建议：** 不建议修改
##### 3.2.5 业务对象 (BO)
- 综述
- 业务对象包含多个Entity，通过业务对象的嵌套组合表达了Entity之间的关系，如果一个业务对象包含了子对象，则会生成BO和BaseBO,BaseBO封装实体属性和关系，子类留给业务扩展逻辑；
如果是叶子节点（不存在子对象）的BO，则直接生成BO类文件，不生成BaseBO类文件
- BO
* **生成产物**：在Manager层生成聚合对象类文件，符合Hibernate的标准
* **职责:** 定义聚合对象，多个聚合对象组合成层级结构实现充血模型，支持写链路上的数据变更，监听数据变更，支持数据校验
* **命名规则**：类名以BO结尾(${entityName}BO)
* **类路径：** 位于 ```**.manager.bo``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|BO|DEFINITION
- **修改建议：** 建议修改BO中的validateAggregate或valid方法。不建议修改检验方法以外的其他代码，如果发现需求中有业务不变性校验，**注意** 上述的校验方法，在写方案内部由框架触发调用，而不是业务代码显式调用
- BaseBO
* **生成产物**：对于存在子BO的聚合对象，封装不变的代码部分
* **职责:** 定义聚合对象，多个聚合对象组合成层级结构实现充血模型，支持写链路上的数据变更，监听数据变更，支持数据校验
* **命名规则**：类名以BO结尾(${entityName}BO)
* **类路径：** 位于 ```**.manager.bo``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|BO|DEFINITION
- **修改建议：** 建议修改BO中的validateAggregate或valid方法，如果发现需求中有业务不变性校验;不建议修改检验方法以外的其他代码
##### 3.2.6 数据传输对象 (DTO)
- 结构定义
* **生成产物**：一个Java类
* **职责:** 表达DTO的数据结构
* **命名规则**：类名以Dto结尾
* **类路径：** 位于 ```**.manager.dto``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|DEFINITION
- **Manager**
* **生成产物:** Java接口以及实现类
* **命名规则:** 接口类名以Manager结尾、实现类名以ManagerImpl结尾(${DtoName}Manager)、基类以名ManagerBaseImpl结尾(${DtoName}ManagerImpl)
* **职责:** 提供了DTO数据的获取的接口，包括根据id单个、id列表批量获取、以及根据DTO对应的实体的数据库索引获取
* **类路径：** 位于 ```**.manager``` 包路径下
* **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|MANAGER
- **Converter**
* **生成产物:** Java实现类以及基类
* **命名规则:** 实现类名以Converter结尾(${DtoName}Converter)、基类名以BaseConverter结尾(${DtoName}BaseConverter)
* **职责:** Entity转换到BaseDTO或则BaseDTO转化为普通DTO：从Entity转为BaseDTO的方法命名为convert${EntityName}To${DtoName}；从BaseDTO转换为DTO的方法命名为convert${BaseDtoName}To${DtoName}
* **类路径：** 位于 ```**.manager.converter``` 包路径下
* **唯一标识符位置：**
* 实现类Converter 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|CONVERTER
* 基类BaseConverter 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|BASE_CONVERTER
- **例子:**
* 如UserDto、UserDtoManager、UserDtoConverter extends UserDtoBaseConverter、UserDtoService或（名称为${DtoName}Service，内部包含getById,getByIds等方法）。如果Dto为UserBaseDto，则生成的类名为UserBaseDtoService
- **修改建议：**
- 建议在Service与BaseConverter中进行代码扩展，不建议修改结构定义文件和Manager文件。其中DTO的**自定义字段**由于不直接派生自Entity，所以一般会对应取数逻辑代码。通常如果涉及到数据获取、计算和拼装，批量处理的性能最好，所以代码位置**必须**放在BaseConverter中已经自动生成的**列表**转换方法中，批量取数组装，如UserBaseDtoBaseConverter.convertUserToUserBaseDto(List<User>)或UserDtoBaseConverter.convertUserBaseDtoToUserDto(List<UserBaseDto>)
##### 3.2.7 视图对象 (VO)
- **结构定义**
* **生成产物:** 在controller层生成一个Java类
* **命名规则:** 类名以Vo结尾
* **职责:** 表达VO的数据结构
* **类路径:** 位于 ```**.entrance.web.vo``` 包路径下
* **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${VO在TOCO中的uuid}|VO|DEFINITION
- **Converter**
* **生成产物:** 在controller层生成一个Java类(**有派生源**的VO才有Converter)和基类
* **命名规则:** 实现类名以Converter结尾(${VoName}Converter)，基类名以BaseConverter结尾(${VoName}BaseConverter)
* **类路径:** 位于 ```**.entrance.web.converter``` 包路径下
* **职责:** 把DTO转换成VO；Converter中包含2种convert方法：1.基础convert方法，从DTO转换为VO，仅转换结构，方法命名为convertTo${VoName}、convertTo${VoName}List、convertTo${VoName}Map，其中**Map转换方法**为底层批量方法，单个和列表convert方法都通过**调用Map方法**来实现;2.带数据拼装逻辑的convert方法，内部会调用基础convert方法从DTO转换为VO，然后再根据外键获取拼装最终数据，方法命名为convertAndAssembleData、convertAndAssembleDataList)
* **唯一标识符位置:**
* 实现类Converter其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${VO在TOCO中的uuid}|VO|CONVERTER
* 基类BaseConverter其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|BASE_CONVERTER
* **例子:**
* 如UserDetailVo、UserDetailVoConverter（包含convertToUserDetailVo、convertToUserDetailVoList、convertToUserDetailVoMap、convertAndAssembleData、convertAndAssembleDataList方法）
- **修改建议：**
- 建议在Converter中进行代码扩展，不建议修改结构定义文件。其中VO的**自定义字段**由于不直接派生自DTO，所以一般会对应取数逻辑代码。通常如果涉及到数据获取、计算和拼装，批量处理的性能最好，所以自定义字段对应的代码位置**必须**放在Converter的**Map**基础转换方法convertTo${VoName}Map中，批量取数组装，如UserVoConverter.convertToUserVoMap
##### 3.2.8 读方案 (ReadPlan)
- **Service**
* **生成产物:** 在Service层生成一个Java类
* **命名规则:** 类名以QtoService结尾(${ReadPlanName}QtoService)
* **类路径:** 位于 ```**.service.index.entity```包路径下
* **职责:** 提供查询入口；返回符合查询条件的DTO或VO的id列表（分页、全部、或则瀑布流）,以及返回符合条件的总数。 在TOCO的读链路中，数据查询分2步骤，1. 获取符合查询条件的DTO或VO的id列表，2. 根据id列表组装DTO或VO列表。
* **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定，uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|SERVICE
- **查询传输对象(QTO)**
* **生成产物:** 在Service层生成一个Java类
* **命名规则:** 类名以Qto结尾(${ReadPlanName}Qto)
* **类路径:** 位于 ```**.persist.qto```包路径下
* **职责:** 读方案的查询参数结构
* **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|DEFINITION
- **Dao**
- **生成产物:** 在Dao层生成一个Java类
- **命名规则:** 类名以Dao结尾(${ReadPlanName}Dao)
- **类路径:** 位于 ```**.persist.mapper```包路径下
- **职责:** 读方案对应的数据库查询方法
- **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|DAO
- **QueryExecutor**
- **生成产物** 对于返回**VO**的查询方案，在controller层生成一个Java类
- **命名规则:** 类名以QueryExecutor结尾(${WritePlanName}QueryExecutor)
- **类路径:** 位于 ```**.entrance.web.query.executor```包路径下
- **职责:** 把QtoService返回的id数据转化成目标**VO**
- **QueryService**
- **生成产物** 对于返回**DTO**的查询方案，在service层生成一个Java类
- **命名规则:** 类名以QueryService结尾(${WritePlanName}QueryService)
- **类路径:** 位于 ```**.service.index.entity```包路径下
- **职责:** 把QtoService返回的id数据转化成目标**DTO**
- **例子:**
* 根据用户名称查询用户列表返回UserDTO，则生成UserNameQto、UserNameQtoService、UserNameQtoDao、UserNameQueryService; UserNameQueryService调用UserNameQtoService，UserNameQtoService调用UserNameQtoDao
- **修改建议：**
- 如果有对结果的数据二次处理，建议在QueryService和QueryExecutor中进行代码扩展，不建议修改QTO文件
##### 3.2.9 写方案 (WritePlan)
- **Service:**
* **生成产物:** 在对应的聚合服务BoService里生成一个函数
* **函数命名规则:** 和写方案同名
* **职责:** 按需对入参进行转换，调用BaseBOService里的函数完成对聚合对象的操作, 实现对数据库的写操作；
* **BoService的类路径:** ```**.service```
* **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${WritePlan在TOCO中的uuid}
- **BaseBoService**
- **生成产物:** 在对应的聚合的BaseBoService里生成一系列函数，根据入参完成对聚合对象的变更
- **职责** 增对每个实体的生成增删改的函数，并且根据参数的结构以及聚合的结构，构建嵌套的调用逻辑，完成对一个聚合对象的变更，记录并且返回对应的变更情况
- **类路径:** ```**.service.base```
- **BTO (业务变更传输对象)**
* **生成产物:** 一个Java类，以内部类的方式表示层级结构
* **命名规则:** 一个Bto结尾(${WritePlanName}Bto，驼峰展示)
* **类路径:** 位于```**.service.bto```包路径下
* **职责:** 在**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的函数, 一起完成了用户的创建和设置创建的逻辑。
- **修改建议：**
- 不能修改BaseBoService中的函数，不建议修改BTO文件。建议在BOService中进行手动代码扩展，处理可能被复用的修改前后的逻辑，如修改数据库的前后值对比、或常被复用的校验逻辑（业务不变性校验逻辑除外）、需要经常在一个事务内执行的其他写操作等。
##### 3.2.10 RPC
- **生成代码：** RPC会在service层中生成类文件及实现函数，包含DTO自动生成的RPC如UserDtoService.getById或UserBaseDtoService.getById、读写方案自动生成的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方法签名、适配器中的内容
##### 3.2.11 API
- **生成代码：** API会在entrance层生成Controller以及对应的API方法
- **修改建议：** 建议修改API方法的实现内容，不建议修改API方法签名、URI
##### 3.2.12 流程服务(FunctionFlow)
- **FlowConfig**
* **生成产物:** 每个模块在service层的生成一个Java类，负责注册模块下的所有流程到执行器 * **生成产物:** 每个模块在service层的生成一个Java类，负责注册模块下的所有流程到执行器
* **命名规则:** 类名为${moduleName}FlowConfig * **命名规则:** 类名为${moduleName}FlowConfig
* **职责:** 在应用启动的时候注册模块内的所有的流程服务到执行器 * **职责:** 在应用启动的时候注册模块内的所有的流程服务到执行器
* **类路径:** ```**.service.flow``` * **类路径:** ```**.service.flow```
- **Service** - **Service**
* **生成产物:** 在service层的以模块名为类名前缀的${moduleName}FlowService中生成一个流程的入口函数 * **生成产物:** 在service层的以模块名为类名前缀的${moduleName}FlowService中生成一个流程的入口函数
* **函数命名规则:** 流程名为方法名为后缀：pubic void invoke${functionFlowName}(${functionFlowName}Context context) * **函数命名规则:** 流程名为方法名为后缀：pubic void invoke${functionFlowName}(${functionFlowName}Context context)
* **职责:** 在代码逻辑中，使用该流程需要以该函数作为调用入口 * **职责:** 在代码逻辑中，使用该流程需要以该函数作为调用入口
* **类路径:** ```**.service``` * **类路径:** ```**.service```
* **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${FunctionFlow在TOCO中的uuid}|FLOW|METHOD * **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${FunctionFlow在TOCO中的uuid}|FLOW|METHOD
- **FlowNode** - **FlowNode**
* **生成产物:** 在service层生成一个Java类， **注意** 每个FunctionFlow的开始节点(StartNode)不生成 * **生成产物:** 在service层生成一个Java类， **注意** 每个FunctionFlow的开始节点(StartNode)不生成
* **类命名规则:** ${nodeName}Node * **类命名规则:** ${nodeName}Node
* **入口函数命名:** pubic void process() * **入口函数命名:** pubic void process()
* **职责:** 用于封装内聚性的业务逻辑 * **职责:** 用于封装内聚性的业务逻辑
* **类路径:** ```service.flow.node.${functionFlowName}``` * **类路径:** ```service.flow.node.${functionFlowName}```
- **FlowContext** - **FlowContext**
* **函数命名规则:** {nodeName}Node * **函数命名规则:** {nodeName}Node
* **职责:** 作为流程节点之间的参数传递（包括出参和入参），在实现业务逻辑的时候，按需在这个上下文类中添加所需的字段 * **职责:** 作为流程节点之间的参数传递（包括出参和入参），在实现业务逻辑的时候，按需在这个上下文类中添加所需的字段
* **类路径:** ```**.service.flow.context``` * **类路径:** ```**.service.flow.context```
* **唯一标识符位置:** 其对应的标识符在类注解@AutoGenerated中指定, uuid规则: ${FunctionFlow在TOCO中的uuid}|FLOW|CONTEXT * **唯一标识符位置:** 其对应的标识符在类注解@AutoGenerated中指定, uuid规则: ${FunctionFlow在TOCO中的uuid}|FLOW|CONTEXT
- **例子：** - **例子：**
- 用户登录，在UserFlowService中生成一个函数invokeLoginFlow，该函数通过流程框架根据流程定义调用LoginNode，LoginNode中封装了用户登录的逻辑，LoginFlowContext中封装了用户登录的参数和结果。 - 用户登录，在UserFlowService中生成一个函数invokeLoginFlow，该函数通过流程框架根据流程定义调用LoginNode，LoginNode中封装了用户登录的逻辑，LoginFlowContext中封装了用户登录的参数和结果。
- **修改建议：** 不修改 service 中的函数, 不修改FlowConfig, 可以修改FlowContext, 添加/修改出入参数， 修改FlowNode中的具体业务逻辑。 - **修改建议：** 不修改 service 中的函数, 不修改FlowConfig, 可以修改FlowContext, 添加/修改出入参数， 修改FlowNode中的具体业务逻辑。
### **3 生成代码产物补充说明**
- **3.1.1 支持的语言/框架**
Java、SpringBoot、MyBatis-plus(读)、Hibernate(写)
- **3.1.2 特殊注解及含义**
TOC自动生成的类和方法会带有@AutoGenerated注解，注解中有2个属性:locked为boolean类型，如果locked=true，则代表该文件或方法不建议修改;uuid为String类型，表示该类或方法的唯一标识，如果uuid中包含|字符，则说明该uuid为特殊格式，由不同类型的数据拼装而成(见**[3.2 设计元素到代码的映射规则及修改建议]**中每种设计元素的代码说明）。
### 4. TOCO 最佳实践 ### 4. TOCO 最佳实践
#### 4.1 设计分析结果应用(Design analysis results application): #### 4.1 设计分析结果应用(Design analysis results application):
在TOCO中，设计分析(designAnalyze工具)的结果按照用户的要求或需求的复杂度分为2种，你需要分辨流程分析的结果类型，然后根据不同类型做出不同的后续工具调用规划: 在TOCO中，设计分析(designAnalyze工具)的结果按照用户的要求或需求的复杂度分为2种，你需要分辨流程分析的结果类型，然后根据不同类型做出不同的后续工具调用规划: