更新 knowledge-design.md
This commit is contained in:
@@ -198,7 +198,7 @@ DateTime endTime; //结束时间
|
||||
|
||||
meeting_with_room_dto无uuid，为待创建DTO。meeting_base_dto和meeting_room_with_meetings_dto为已存在DTO，带uuid。
|
||||
|
||||
- **预定义方法:** 每个DTO基于根Entity的唯一索引自动生成预定义RPC方法及实现，预定义方法获取根Entity数据，通过RPC自动获取所有扩展字段数据并拼装。如实体user有唯一索引username，则为UserDto生成UserDto UserDtoService.getByUserName(String userName)和List<UserDto> UserDtoService.getByUserNames(List<String> userNames)。预定义方法内部基于外键关系自动生成复杂DTO数据的递归、Join拼装能力，直接返回DTO内部所有继承字段和扩展字段数据。自定义字段数据获取不自动生成，需在对应convert方法中编写代码。
|
||||
- **预定义方法:** 每个DTO基于根Entity的唯一索引自动生成预定义RPC方法及实现，预定义方法获取根Entity数据，通过RPC自动获取所有扩展字段数据并拼装。如实体user有唯一索引username，则为UserDto生成UserDto UserDtoService.getByUserName(String userName)和List<UserDto> UserDtoService.getByUserNames(List<String> userNames)。预定义方法内部基于外键关系自动生成复杂DTO数据的递归、Join拼装能力，直接返回DTO内部所有继承字段和扩展字段数据。
|
||||
- **公开性:** DTO可设置公开性，DTO为公开时生成的预定义RPC方法也为公开RPC，可被其他模块订阅调用；DTO为非公开时生成的预定义RPC方法也为非公开RPC，其他模块不可见。
|
||||
- **跨模块依赖:** 如DTO内引用其他模块DTO，需订阅其他模块RPC方法（getBy${PrimaryKey}、getBy${PrimaryKey}s、getBy${foreignKey}等），用于获取对应DTO。
|
||||
- **复杂嵌套DTO获取流程:** 获取DTO有2种方式，都可直接获取复杂嵌套DTO数据：
|
||||
@@ -209,7 +209,7 @@ meeting_with_room_dto无uuid，为待创建DTO。meeting_base_dto和meeting_room
|
||||
- a. 查询DTO条件为主键或唯一索引的值或列表，使用第1种方式
|
||||
- b. 通过其他复杂查询条件，采用第2种方式
|
||||
|
||||
判断使用方式时，只能根据查询条件判断是否使用读方案，禁止使用返回值是否需要数据拼装来判断！如现实代码和TOCO定义有冲突，只能使用TOCO定义！
|
||||
判断使用方式时，只能根据查询条件判断是否使用读方案，禁止使用返回值是否需要数据拼装来判断！
|
||||
|
||||
#### **2.7 视图对象 (VO)**
|
||||
- **定义与用途:** VO基于BaseDTO（或指定的其他DTO）派生，通过外键关系关联多个BaseDTO的数据结构。用于视图层与前端数据传输，作为HTTP API返回值或读方案返回值。不能作为接口参数或RPC返回值。
|
||||
@@ -402,8 +402,8 @@ meeting_with_room_dto无uuid，为待创建DTO。meeting_base_dto和meeting_room
|
||||
meeting_with_room_vo为根VO，无uuid，为待创建根VO。meeting_room_with_meetings_vo和meeting_base_vo为meeting_with_room_vo的子VO，无法被其他根VO引用，无uuid。注意：metting_with_room_vo的extendFieldList中create_user结构含vo，因为派生源meeting_detail_dto中create_user字段为user_base_dto类型，所以metting_with_room_vo中该继承字段类型需变为由user_base_dto派生出的VO结构，注意metting_with_room_vo中create_user对应的user_base_vo**必须派生自**DTO字段的user_base_dto类型。
|
||||
|
||||
- **派生源默认使用BaseDTO:** 除非用户指定VO的派生源DTO，否则创建VO时只可用**BaseDTO**为派生源。
|
||||
- **与DTO的转换关系:** 创建**有派生源**的VO后，TOCO生成代码时自动生成2种convert方法：1.基础convert方法，从DTO转换为VO，仅转换结构及基本类型字段的get/set，方法命名为convertTo${VoName}、convertTo${VoName}List、convertTo${VoName}Map，其中**Map转换方法**为底层批量方法，通常是自定义字段逻辑编写位置（复用性好，被其他convert方法调用），单个和列表convert方法都通过**调用Map方法**实现；2.带数据拼装逻辑的convert方法，内部**自动**调用基础convert方法从DTO转换为VO并设置基本类型字段数据，然后根据外键**自动**获取**扩展字段**数据拼装最终数据，方法命名为convertAndAssembleData、convertAndAssembleDataList，即这两个方法已**自动**获取所有**继承字段**和**扩展字段**数据。这2种方法代码生成在VO对应Converter类中。
|
||||
- **字段数据获取:** 继承自DTO的字段及扩展字段，TOCO在convert方法中自动生成数据获取代码，无需手动实现获取和拼装逻辑。自定义字段则**必须**在最底层convertTo${VoName}Map方法中实现对应获取和拼装逻辑，便于其他convert方法**复用**这段逻辑。**禁止**在其他convert方法中实现自定义字段逻辑，会导致某些场景下数据拼装不完整。
|
||||
- **与DTO的转换关系:** 创建**有派生源**的VO后，TOCO生成代码时自动生成2种convert方法：1.基础convert方法，从DTO转换为VO，仅转换结构及基本类型字段的get/set，方法命名为convertTo${VoName}、convertTo${VoName}List、convertTo${VoName}Map，其中**Map转换方法**为底层批量方法，通常是自定义字段逻辑编写位置（复用性好，被其他convert方法调用），单个和列表convert方法都通过**调用Map方法**实现；2.带数据拼装逻辑的convert方法，内部**自动**调用基础convert方法从DTO转换为VO并设置基本类型字段数据，然后根据外键**自动**获取**扩展字段**数据拼装最终数据，方法命名为convertAndAssembleData、convertAndAssembleDataList，即这两个方法已**自动**获取所有**继承字段**和**扩展字段**数据。
|
||||
- **字段数据获取:** 继承自DTO的字段及扩展字段，TOCO在convert方法中会自动组装数据，无需手动实现获取和拼装逻辑。自定义字段则需要在coding阶段实现对应获取和拼装逻辑，便于其他convert方法**复用**这段逻辑。**禁止**在其他convert方法中实现自定义字段逻辑，会导致某些场景下数据拼装不完整。
|
||||
- **跨模块依赖:** VO内存在由其他模块DTO派生出的子VO，需订阅其他模块RPC(getBy${PrimaryKey},getBy${PrimaryKey}s,getBy${ForeignKey}s等)方法，获取对应DTO，再转换为子VO。
|
||||
- **复杂嵌套VO获取流程:** 获取VO通常有3种方式，3种方式都可直接获取复杂嵌套VO数据：
|
||||
- 第1种：先通过预定义方法获取VO派生源BaseDTO，再通过convertAndAssembleData或convertAndAssembleDataList方法转换成VO
|
||||
@@ -415,7 +415,7 @@ TOCO中判断使用方式的步骤：
|
||||
- b. 通过其他复杂查询条件，可采用第2种或第3种方式
|
||||
- c. 用户上下文中有指定返回DTO的读方案符合条件，使用第2种，否则使用第3种
|
||||
|
||||
注意判断使用方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！**现实代码编写方式和TOCO步骤冲突时，只能使用TOCO定义！**
|
||||
注意判断使用方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！
|
||||
|
||||
#### **2.8 查询对象(WO)**
|
||||
- **定义与用途:** WO基于Entity通过外键关系关联多个Entity的数据结构。WO表达数据取数拼装逻辑，符合外键关系。WO作为ReadPlan查询上下文，创建ReadPlan前需先创建WO对象。理解ReadPlan语义时需要WO作为上下文。
|
||||
@@ -579,7 +579,7 @@ meeting_with_room_and_agenda_wo示例：
|
||||
- 需求超出读方案能力时，必须使用自定义查询
|
||||
- **特别注意** 根据主键获取单个或批量DTO/VO且不需过滤列表字段数据的需求，必须使用DTO自动生成的预定义方法，禁止使用读方案
|
||||
- **关键配置:** 名称(小写字母+下划线，不以read_plan结尾，全局唯一)、返回结构(DTO/VO，一个读方案只能返回一种类型)、查询条件自然语言描述、是否生成计数方法、排序字段、过滤字段及过滤条件
|
||||
- **与RPC、代码的关系:** 返回DTO的读方案自动生成RPC方法，参数为QTO，返回值为DTO列表；返回VO的读方案自动生成Java方法，参数为QTO，返回值为VO列表，方法内部逻辑由TOCO完全实现
|
||||
- **与RPC的关系:** 返回DTO的读方案自动生成RPC方法，参数为QTO，返回值为DTO列表；返回VO的读方案自动生成Java方法，参数为QTO，返回值为VO列表，方法内部逻辑由TOCO完全实现
|
||||
- **生成的读方案RPC使用:** 读方案RPC属于对应模块，其他模块需先订阅该RPC，用adapter调用；当前模块直接调用对应Service
|
||||
- **创建方式:** 先创建或选择一种DTO或VO作为返回值类型，然后定义查询条件自然语言描述、分页方式、是否生成计数方法、排序字段等
|
||||
- **排序** 支持两种方式：
|
||||
@@ -959,7 +959,7 @@ class CreateUserBto { //对应实体user
|
||||
- **优先复用:** 用户需要创建RPC时，有明确要求按要求创建。无明确要求时先判断能否通过读方案、写方案、DTO自动创建RPC，最后考虑自定义RPC
|
||||
- **自定义RPC和手写方法关系:** 两者都可手动实现服务层方法。区别：需要被其他模块订阅用自定义RPC；只是API私有调用不需要外部开放用手写方法
|
||||
- **关键配置:** 类名(驼峰，首字母大写，以Service结尾)、是否公开、方法名(驼峰，首字母小写)、请求参数、返回值。分页查询参数为Qto类型时，Qto已包含from、size、scrollId属性，无需额外参数
|
||||
- **TOCO中RPC存储:** RPC在TOCO中只存储方法签名，不存储执行逻辑。了解实现逻辑需阅读RPC对应代码
|
||||
- **TOCO中RPC存储:** RPC在TOCO中只存储方法签名，不存储执行逻辑。
|
||||
- **参数类型:** RPC参数**只能**为QTO、BTO、Enum、基本类型，可为单值或列表。对象类型优先用QTO、BTO，**禁用**VO和自定义结构如Object
|
||||
- **返回值类型:** RPC返回值**只能**为DTO、Enum、基本类型，可为单值或列表，**禁用**VO、QTO、BTO、自定义结构如Object。对象类型优先用DTO
|
||||
- **TOCO中json结构:** TOCO中DTO用json表示，示例：
|
||||
@@ -986,7 +986,7 @@ class CreateUserBto { //对应实体user
|
||||
#### **2.14 应用程序接口 (API)**
|
||||
- **定义与用途:** API定义对外HTTP接口
|
||||
- **创建方式:** 通过TOCO创建，需指定参数和返回值
|
||||
- **存储特点:** TOCO只存储URI和方法签名，不存储执行逻辑。了解实现需阅读对应代码
|
||||
- **存储特点:** TOCO只存储URI和方法签名，不存储执行逻辑。
|
||||
- **关键配置:** uri(/api/${moduleName}/xxx，如/api/user/create，全局唯一)、类名(以Controller结尾)、方法名(驼峰小写)、请求参数、返回值。分页查询参数为Qto时，已包含from、size、scrollId属性，无需额外参数
|
||||
- **参数类型:** 只能为QTO、BTO、EO、Enum、基本类型，可为单值或列表。对象类型优先用QTO、BTO。禁用DTO和自定义结构
|
||||
- **返回值类型:** 脚手架自动包装返回值(code、message、data)。只能为VO、Enum、基本类型，可为单值或列表。禁用DTO、QTO、BTO、自定义结构。对象类型优先用VO
|
||||
@@ -1019,7 +1019,7 @@ class CreateUserBto { //对应实体user
|
||||
关键字段：requestParams为请求参数列表，response为返回结构。参数和response结构相同：name为参数名；type为参数类型(Boolean,String,Integer,Long,Float,Double,BigDecimal,Date,ByteArray,Enum,Eo,List,PageResult,Vo,Qto,Bto,Void，参数不能为Void和PageResult，无返回值设为Void，分页结果设为PageResult且innerType必为Vo，对应VSQueryResult<XxxVo>)；description为描述；typeUuid为类结构UUID(type为Enum、Eo、Vo时传入对象uuid，Qto时传入读方案uuid，Bto时传入写方案uuid)；innerType为List内部类型(type为List时包含)；innerUuid为List或PageResult内部类结构UUID(type为List或PageResult且innerType为Enum、Eo、Vo时传入对象uuid，innerType为Qto时传入读方案uuid，Bto时传入写方案uuid)
|
||||
|
||||
#### **2.15 流程服务（FunctionFlow)**
|
||||
- **定义与用途：** TOCO将复杂业务拆解为流程节点，基于业务逻辑内聚性合并功能，构建工作流式逻辑流程，提升代码可维护性。内嵌流程引擎执行生成代码。
|
||||
- **定义与用途：** TOCO将复杂业务拆解为流程节点，基于业务逻辑内聚性合并功能，构建工作流式逻辑流程，提升可维护性。
|
||||
- **使用场景：**
|
||||
- API/RPC涉及写服务超过3个时**必须**使用
|
||||
- 用户要求使用时
|
||||
@@ -1126,7 +1126,7 @@ class CreateUserBto { //对应实体user
|
||||
- 读方案无法满足需求时，使用自定义查询
|
||||
- 自定义查询使用复杂sql实现业务功能
|
||||
- 数据访问层使用MyBatis、MyBatisPlus实现
|
||||
- 自定义查询时框架不自动生成代码(需要手动编写全部代码)
|
||||
- 自定义查询时框架不自动生成代码(需要在coding阶段手动编写)
|
||||
|
||||
### 3. TOCO 最佳实践
|
||||
|
||||
|
||||
Reference in New Issue
Block a user