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

更新 knowledge.md

Browse Source
This commit is contained in:
oyo
2025-10-20 14:01:45 +08:00
parent c50bb46f20
commit ba9318c2ba
1 changed files with 11 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
knowledge.md
View File

@@ -42,8 +42,8 @@
* **命名规则:** 类名以Enum结尾 * **命名规则:** 类名以Enum结尾
* **类路径:** 位于 <code>**.common.enums</code> 包下 * **类路径:** 位于 <code>**.common.enums</code> 包下
* **唯一标识符位置:** 类注解@AutoGenerated中指定，uuid规则: ${Enum的uuid}|ENUM|DEFINITION * **唯一标识符位置:** 类注解@AutoGenerated中指定，uuid规则: ${Enum的uuid}|ENUM|DEFINITION
- **生成代码:** 在common层生成Enum文件，如StatusEnum * **生成代码:** 在common层生成Enum文件，如StatusEnum
- **修改建议:** 不建议修改 * **禁止** 修改该类
#### **2.3 值对象 (EO)** #### **2.3 值对象 (EO)**
- **定义与用途：** EO是可复用的POJO数据结构，可跨模块使用，可作为实体字段类型。 - **定义与用途：** EO是可复用的POJO数据结构，可跨模块使用，可作为实体字段类型。
@@ -83,7 +83,7 @@
* **命名规则：** 类名以Eo结尾 * **命名规则：** 类名以Eo结尾
* **类路径：** 位于 `**.persist.eo` 包下 * **类路径：** 位于 `**.persist.eo` 包下
* **唯一标识符位置：** 类注解@AutoGenerated中指定，uuid规则：${Eo的uuid}|EO|DEFINITION * **唯一标识符位置：** 类注解@AutoGenerated中指定，uuid规则：${Eo的uuid}|EO|DEFINITION
- **修改建议：** 不建议修改 * **禁止** 修改该类
#### **2.4 实体关系 (ER / Entity)** #### **2.4 实体关系 (ER / Entity)**
- **定义与用途:** 实体对应数据库表，关系为实体间的外键依赖 - **定义与用途:** 实体对应数据库表，关系为实体间的外键依赖
@@ -95,6 +95,7 @@
* **职责:** 生成Mybatis-plus结构定义类文件 * **职责:** 生成Mybatis-plus结构定义类文件
* **类路径：** 位于 `**.persist.dos` 包下 * **类路径：** 位于 `**.persist.dos` 包下
* **唯一标识符位置：** 类注解@AutoGenerated中指定，uuid规则: ${Entity的uuid}|ENTITY|DEFINITION * **唯一标识符位置：** 类注解@AutoGenerated中指定，uuid规则: ${Entity的uuid}|ENTITY|DEFINITION
* **禁止** 修改该类
- Mapper - Mapper
* **生成产物**：persist层的Mybatis-plus Mapper类 * **生成产物**：persist层的Mybatis-plus Mapper类
* **职责:** 为Mybatis-plus框架提供Mapper * **职责:** 为Mybatis-plus框架提供Mapper
@@ -137,7 +138,7 @@
* **命名规则**：${entityName}BO * **命名规则**：${entityName}BO
* **类路径：** `**.manager.bo`包下 * **类路径：** `**.manager.bo`包下
* **唯一标识符位置：** 类注解@AutoGenerated中，uuid规则: ${Entity的uuid}|BO|DEFINITION * **唯一标识符位置：** 类注解@AutoGenerated中，uuid规则: ${Entity的uuid}|BO|DEFINITION
* **修改建议：** 建议修改BO中的validateAggregate或valid方法进行业务不变性校验。不建议修改校验方法以外的代码。 * **禁止** 修改该类
#### **2.6 数据传输对象 (DTO)** #### **2.6 数据传输对象 (DTO)**
- **定义与用途:** DTO基于某个Entity构建，通过外键关系关联多个Entity的数据结构。DTO隐含数据组装逻辑，符合外键关系。分为BaseDTO和普通DTO：BaseDTO直接派生自Entity，包含Entity所有字段，每个Entity只有一个BaseDTO；普通DTO基于BaseDTO创建，包含BaseDTO所有字段，可增加扩展字段或自定义字段。DTO不能作为接口参数，不能作为HTTP API返回值。 - **定义与用途:** DTO基于某个Entity构建，通过外键关系关联多个Entity的数据结构。DTO隐含数据组装逻辑，符合外键关系。分为BaseDTO和普通DTO：BaseDTO直接派生自Entity，包含Entity所有字段，每个Entity只有一个BaseDTO；普通DTO基于BaseDTO创建，包含BaseDTO所有字段，可增加扩展字段或自定义字段。DTO不能作为接口参数，不能作为HTTP API返回值。
@@ -280,6 +281,7 @@ meeting_with_room_dto无uuid，为待创建DTO。meeting_base_dto和meeting_room
* **禁止** 修改该类 * **禁止** 修改该类
* **类路径：** `**.manager.dto` 包路径下 * **类路径：** `**.manager.dto` 包路径下
* **唯一标识符位置：** 类注解@AutoGenerated中指定，uuid规则：${DTO在TOCO中的uuid}|DTO|DEFINITION * **唯一标识符位置：** 类注解@AutoGenerated中指定，uuid规则：${DTO在TOCO中的uuid}|DTO|DEFINITION
* **禁止** 修改该类
- **Manager** - **Manager**
* **生成产物:** Java接口及实现类 * **生成产物:** Java接口及实现类
* **命名规则:** 接口类名以Manager结尾、实现类名以ManagerImpl结尾(${DtoName}Manager)、基类名以ManagerBaseImpl结尾(${DtoName}ManagerImpl) * **命名规则:** 接口类名以Manager结尾、实现类名以ManagerImpl结尾(${DtoName}Manager)、基类名以ManagerBaseImpl结尾(${DtoName}ManagerImpl)
@@ -516,6 +518,7 @@ TOCO中判断使用方式的步骤：
* **职责:** 表达VO数据结构 * **职责:** 表达VO数据结构
* **类路径:** `**.entrance.web.vo` 包路径下 * **类路径:** `**.entrance.web.vo` 包路径下
* **唯一标识符位置:** 类注解@AutoGenerated中指定，uuid规则：${VO在TOCO中的uuid}|VO|DEFINITION * **唯一标识符位置:** 类注解@AutoGenerated中指定，uuid规则：${VO在TOCO中的uuid}|VO|DEFINITION
* **禁止** 修改该类
- **Converter** - **Converter**
* **生成产物:** controller层生成Java类（**有派生源**的VO才有Converter，无根VO没有Converter）和基类 * **生成产物:** controller层生成Java类（**有派生源**的VO才有Converter，无根VO没有Converter）和基类
* **命名规则:** 实现类名以Converter结尾(${VoName}Converter)，基类名以BaseConverter结尾(${VoName}BaseConverter) * **命名规则:** 实现类名以Converter结尾(${VoName}Converter)，基类名以BaseConverter结尾(${VoName}BaseConverter)
@@ -914,6 +917,7 @@ meeting_with_room_and_agenda_wo示例：
* **职责:** 读方案的查询参数结构，可作为API参数，直接透传给RPC调用 * **职责:** 读方案的查询参数结构，可作为API参数，直接透传给RPC调用
* **唯一标识符位置:** 类注解@AutoGenerated中指定，uuid规则: ${ReadPlan的uuid}|QTO|DEFINITION * **唯一标识符位置:** 类注解@AutoGenerated中指定，uuid规则: ${ReadPlan的uuid}|QTO|DEFINITION
* **内部结构:** QTO包含分页相关字段: * **内部结构:** QTO包含分页相关字段:
* **禁止** 修改该类
<code> <code>
private String scrollId; //瀑布流游标 private String scrollId; //瀑布流游标
private Integer size; //每页记录数 private Integer size; //每页记录数
@@ -979,6 +983,7 @@ meeting_with_room_and_agenda_wo示例：
- **如何创建/生成:** 创建读方案后，TOCO自动生成对应的QTO。无需单独创建 - **如何创建/生成:** 创建读方案后，TOCO自动生成对应的QTO。无需单独创建
- **关键配置:** 名称（${ReadPlanNameQto}，驼峰命名），查询字段列表（如idIs，nameLike，schoolNameLike等） - **关键配置:** 名称（${ReadPlanNameQto}，驼峰命名），查询字段列表（如idIs，nameLike，schoolNameLike等）
- **与API的关系:** QTO可作为API参数。API接收参数后直接透传给内部RPC调用。QTO只用于读操作参数，**禁止用于写参数结构** - **与API的关系:** QTO可作为API参数。API接收参数后直接透传给内部RPC调用。QTO只用于读操作参数，**禁止用于写参数结构**
- **禁止** 修改该类
#### **2.11 写方案 (WritePlan，单聚合操作)** #### **2.11 写方案 (WritePlan，单聚合操作)**
- **定义与用途：** 写方案是数据库写操作的唯一方式，每个写方案只能变更一个聚合的数据。写方案可以一次操作聚合内的多张表。例如：location(父对象/聚合根)和storey(子对象)是1:N关系，可创建写方案同时更新location信息和操作storey列表(新增/删除/修改)；也可创建写方案单独更新单个storey对象。 - **定义与用途：** 写方案是数据库写操作的唯一方式，每个写方案只能变更一个聚合的数据。写方案可以一次操作聚合内的多张表。例如：location(父对象/聚合根)和storey(子对象)是1:N关系，可创建写方案同时更新location信息和操作storey列表(新增/删除/修改)；也可创建写方案单独更新单个storey对象。
@@ -1307,7 +1312,7 @@ class CreateUserBto { //对应实体user
``` ```
关键字段：requestParams为请求参数列表，response为返回结构，参数和response结构相同，其中：name为参数名；type为参数类型，取值Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,Dto,Qto,Bto,List,PageResult,Void，参数不能为Void和PageResult，无返回值设为Void，分页查询结果设为PageResult且innerType必为Dto，对应VSQueryResult<XxxDto>；description为描述；typeUuid为类结构UUID，type为Enum、Eo、Dto时传入对象uuid，Qto时传入读方案uuid，Bto时传入写方案uuid；innerType为List内部类型，type为List或PageResult时包含；innerUuid为List内部类结构UUID，type为List或PageResult且innerType为Enum、Eo、Dto时传入对象uuid，innerType为Qto时传入读方案uuid，Bto时传入写方案uuid 关键字段：requestParams为请求参数列表，response为返回结构，参数和response结构相同，其中：name为参数名；type为参数类型，取值Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,Dto,Qto,Bto,List,PageResult,Void，参数不能为Void和PageResult，无返回值设为Void，分页查询结果设为PageResult且innerType必为Dto，对应VSQueryResult<XxxDto>；description为描述；typeUuid为类结构UUID，type为Enum、Eo、Dto时传入对象uuid，Qto时传入读方案uuid，Bto时传入写方案uuid；innerType为List内部类型，type为List或PageResult时包含；innerUuid为List内部类结构UUID，type为List或PageResult且innerType为Enum、Eo、Dto时传入对象uuid，innerType为Qto时传入读方案uuid，Bto时传入写方案uuid
- **生成代码:** RPC在service层生成类文件和实现函数，包含DTO自动生成的RPC如UserDtoService.getById、读写方案自动生成的RPC如UserDtoQueryService.queryByListQto、UserBOService.createUser、自定义RPC如UserCustomService.customMethod。公开RPC才能被其他模块使用，订阅后生成RpcAdapter适配器，其他模块通过RpcAdapter调用。RpcAdapter的命名方式严格遵守以下格式：${ClassName}In${ModuleName}RpcAdapter，以下为示例：Order模块订阅User模块的UserDtoService.getById，在Order模块生成UserDtoServiceInOrderRpcAdapter.getById方法，Order模块代码必须通过@Resource private UserDtoServiceInOrderRpcAdapter userDtoServiceInOrderRpcAdapter;注入适配器后调用。**必须注意**：变量命名必须是类名首字母小写，禁用其他变量名 - **生成代码:** RPC在service层生成类文件和实现函数，包含DTO自动生成的RPC如UserDtoService.getById、读写方案自动生成的RPC如UserDtoQueryService.queryByListQto、UserBOService.createUser、自定义RPC如UserCustomService.customMethod。公开RPC才能被其他模块使用，订阅后生成RpcAdapter适配器，其他模块通过RpcAdapter调用。RpcAdapter的命名方式严格遵守以下格式：${ClassName}In${ModuleName}RpcAdapter，以下为示例：Order模块订阅User模块的UserDtoService.getById，在Order模块生成UserDtoServiceInOrderRpcAdapter.getById方法，Order模块代码必须通过@Resource private UserDtoServiceInOrderRpcAdapter userDtoServiceInOrderRpcAdapter;注入适配器后调用。**必须注意**：变量命名必须是类名首字母小写，禁用其他变量名
- **修改建议:** 建议修改RPC方法，不建议修改RPC方法签名、适配器内容 - **修改建议：** 可修改RPC方法内容，**禁止** 修改方法签名，**禁止** RpcAdapter，如果不满足需求则必须通过修改TOCO设计元素并重新生成代码
#### **2.14 应用程序接口 (API)** #### **2.14 应用程序接口 (API)**
- **定义与用途:** API定义对外HTTP接口 - **定义与用途:** API定义对外HTTP接口
@@ -1346,7 +1351,7 @@ class CreateUserBto { //对应实体user
- **代码产物和修改建议** - **代码产物和修改建议**
- **生成代码:** entrance层生成Controller及对应API方法 - **生成代码:** entrance层生成Controller及对应API方法
- **修改建议:** 建议修改API方法实现内容，禁止直接修改API方法签名、URI。修改API定义需通过修改API设计元素实现 - **修改建议：** 可修改API方法实现，不可修改API方法签名、URI。由于TOCO生成的框架中已经使用了HandlerMethodReturnValueHandler对返回值进行统一包装处理，所以你**不能在Controller中使用@ResponseBody注解**，否则会导致包装失效！！！**禁止** 修改方法签名，如果不满足需求则必须通过修改TOCO设计元素并重新生成代码！
#### **2.15 流程服务（FunctionFlow)** #### **2.15 流程服务（FunctionFlow)**
- **定义与用途：** TOCO将复杂业务拆解为流程节点，基于业务逻辑内聚性合并功能，构建工作流式逻辑流程，提升代码可维护性。内嵌流程引擎执行生成代码。 - **定义与用途：** TOCO将复杂业务拆解为流程节点，基于业务逻辑内聚性合并功能，构建工作流式逻辑流程，提升代码可维护性。内嵌流程引擎执行生成代码。