From 73ccf32447d367e76b3dcc8471182aef556464cb Mon Sep 17 00:00:00 2001 From: ycl Date: Thu, 14 Aug 2025 11:07:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20llms-full.txt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- llms-full.txt | 152 +++++++++++++++++++++++++------------------------- 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/llms-full.txt b/llms-full.txt index a99e16c..8840e98 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -38,7 +38,7 @@ * **生成产物**：在common模块中生成一个Java类 * **职责:** 表达Enum的数据结构 * **命名规则**：类名以Enum结尾 - * **类路径：** 位于 ```**.common.enums``` 包路径下 + * **类路径：** 位于 **.common.enums 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Enum在TOCO中的uuid}|ENUM|DEFINITION - **生成代码：** Enum会在common层生成Enum文件，如StatusEnum - **修改建议：** 不建议修改 @@ -78,7 +78,7 @@ * **生成产物**：在persist层生成结构定义类文，如AddressEo * **职责:** 表达POJO数据结构 * **命名规则**：类名以Eo结尾 - * **类路径：** 位于 ```**.persist.eo``` 包路径下 + * **类路径：** 位于 **.persist.eo 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Eo在TOCO中的uuid}|EO|DEFINITION - **修改建议：** 不建议修改 #### **2.4 实体关系 (ER / Entity)** @@ -89,25 +89,25 @@ - 结构定义 * **生成产物**：Java类，按照Mybatis-plus的要求生成 * **职责:** 按照Mybatis-plus的要求生成结构定义类文件 - * **类路径：** 位于 ```**.persist.dos``` 包路径下 + * **类路径：** 位于 **.persist.dos 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|DEFINITION - Mapper * **生成产物**：在persist层生成Mybatis-plus的Mapper类 * **职责:** 提供Mapper给Mybatis-plus框架 * **命名规则**：类名以Mapper结尾(${entityName}Mapper) - * **类路径：** 位于 ```**.persist.mapper.mybatis``` 包路径下 + * **类路径：** 位于 **.persist.mapper.mybatis 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Eo在TOCO中的uuid} - Dao接口 * **生成产物**：在persist层生成Dao接口 * **职责:** 提供Entity数据的查询接口，为service层提供数据访问入口 * **命名规则**：类名以Dao结尾(${entityName}Dao) - * **类路径：** 位于 ```**.persist.mapper``` 包路径下 + * **类路径：** 位于**.persist.mapper 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|IDAO - Dao实现 * **生成产物**：在persist层生成Dao接口的实现类文件 * **职责:** 通过调用Mapper实现实现Dao接口 * **命名规则**：类名以DaoImpl结尾(${entityName}DaoImpl) - * **类路径：** 位于 ```**.persist.mapper``` 包路径下 + * **类路径：** 位于 **.persist.mapper 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|ENTITY|DAO - **修改建议：** 不建议修改 #### **2.5 聚合对象 (BO/业务对象)** @@ -123,14 +123,14 @@ * **生成产物**：在Manager层生成聚合对象类文件，符合Hibernate的标准 * **职责:** 定义聚合对象，多个聚合对象组合成层级结构实现充血模型，支持写链路上的数据变更，监听数据变更，支持数据校验 * **命名规则**：类名以BO结尾(${entityName}BO) - * **类路径：** 位于 ```**.manager.bo``` 包路径下 + * **类路径：** 位于 **.manager.bo 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|BO|DEFINITION - **修改建议：** 建议修改BO中的validateAggregate或valid方法。不建议修改检验方法以外的其他代码，如果发现需求中有业务不变性校验，**注意** 上述的校验方法，在写方案内部由框架触发调用，而不是业务代码显式调用 - BaseBO * **生成产物**：对于存在子BO的聚合对象，封装不变的代码部分 * **职责:** 定义聚合对象，多个聚合对象组合成层级结构实现充血模型，支持写链路上的数据变更，监听数据变更，支持数据校验 * **命名规则**：类名以BO结尾(${entityName}BO) - * **类路径：** 位于 ```**.manager.bo``` 包路径下 + * **类路径：** 位于**.manager.bo 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定 ,uuid规则: ${Entity在TOCO中的uuid}|BO|DEFINITION - **修改建议：** 建议修改BO中的validateAggregate或valid方法，如果发现需求中有业务不变性校验;不建议修改检验方法以外的其他代码 #### **2.6 数据传输对象 (DTO)** @@ -139,7 +139,7 @@ - **关键配置:** 名称(BaseDTO以BaseDto结尾，其他DTO以Dto结尾,全局唯一)、根Entity、字段列表。DTO中的字段分为三种：a.继承Entity或BaseDTO的字段，和Entity及BaseDTO的字段类型一样；b.扩展字段，含正向替换和反向注入字段，类型为DTO或List;c.自定义字段，类型为基本类型、Eo、Enum、DTO类型。BaseDTO中一般包含Entity的全部字段,DTO中一般包含BaseDTO中的全部字段，不进行字段裁剪，可以根据外键关系扩展其他Entity(详见**字段扩展方式**)，在明确无法扩展外部Entity的情况下，可增加对应的自定义字段。 - **字段扩展方式:**TOCO定义了一个DTO组装方法，适用于DTO通过外键关系替换/注入对应Entity的信息，对象化表达有外键关系的Entity信息。只要存在外键关系且满足以下条件即可扩展：a.对于正向替换：当前实体存在指向其他实体的外键字段；b.对于反向注入：其他实体存在指向当前实体的外键字段。 例如：有两个Entity -``` + MeetingRoom{ //会议室 Long id;// 会议室id,主键 String name;// 会议室名称 @@ -152,12 +152,12 @@ String title; //会议标题 DateTime startTime； //会议开始时间 DateTime endTime； //会议结束时间 } -``` + 其中Meeting和MeetingRoom是n:1关系。即多个会议室会占用同一个会议室。 当组装对象以某Entity为根时，那么首先它将拥有和该Entity一样的数据结构，并将通过下面的“正向替换”，“反向注入”的行为，递归的将多个互相之间有外键关系的Entity的信息组装到该组装对象中。 定义“正向替换”这个行为，选定一个表，这张表存在到另外一张表的一个或多个外键。选择和需求相关的具体的外键属性，将该外键属性替换为另一张表为根的组装对象。这样就可以获取基于某些外键且包含另一张表更详细的属性数据。 例如：需要会议和其占用会议室时，将Meeting表中的roomid外键替换为以MeetingRoom为根的组装对象，而backupRoomid对应的候选会议室具体信息和本需求无关，不做任何替换。如下： -``` + MeetingWithRoomDto { Long id;// 会议id MeetingRoomDto room { //正向替换该会议用的会议室信息，是一个以会议室为根的对象 @@ -169,11 +169,11 @@ String title; //会议标题 DateTime startTime； //会议开始时间 DateTime endTime； //会议结束时间 } -``` + 又例如：需要会议和其候选会议室时，将Meeting表中的backupRoomid进行正向替换。 又例如：需要会议，且即需要其占用会议室，也需要候选会议室时，将Meeting表中的roomid，backupRoomid都进行正向替换。 同时TOCO还定义了“反向注入”这个行为，选定一个表，如果有另外的表到前表有外键，选择和需求相关的具体的外键属性在选定表中增加一个以另外表为根的组合对象(当外键关系是1:1时)或者组合对象的列表(当外键关系是n:1时)。需求是：“获取会议室，和占用它的会议信息”，需要选定MeetingRoom，那么基于另外的表Meeting中存在字段roomid，为到MeetingRoom的n:1关系外键。可以将List反向注入到MeetingRoom中，最终生成一个以Meeting为根的组装对象，生成： -``` + MeetingRoomWithMeetingDto { Long id;// 会议室id String name;// 会议室名称 @@ -184,11 +184,11 @@ DateTime startTime； //会议开始时间 DateTime endTime； //会议结束时间 } } -``` + 这种“正向替换”和“反向注入”可以按需递归调用，去将多个互相之间有外键关系的对象组装成最终对象。例如，还有另外一张表MeetingAgenda到Meeting有n:1的外键，和另外一张表AgendaAttendance到MeetingAgenda有n:1外键。那么如果我要去组装以Meeting开始，包含MeetingRoom, MeetingAgenda, AgendaAttendance的组装对象，首先发现MeetingRoom是可以正向扩展到Meeting的，反向注入MeetingAgenda，而AgendaAttendance需要先反向注入到MeetingAgenda中。 - **TOCO中DTO的json结构描述:** 在TOCO中，DTO使用一个json结构表示，该结构可用于理解DTO的含义，或作为创建、更新DTO工具的参数。部分字段的含义为：dto的uuid为唯一标识，如果需要创建DTO，则设置为null；如果需要复用，则填入其uuid。expandList为正向替换，reverseExpandList为反向注入，customFieldList为自定义字段。expandListList中，foreignKeyInThisEntity为正向替换对应的本表外键字段的名字，dtoFieldName为正向替换之后给该字段的起的新名字；reverseExpandList中，foreignKeyInOtherEntity为反向注入对应的他表外键字段的名字，dtoFieldName为反向注入之后给该字段的起的新名字；customFieldList中，uuid为自定义字段特有的UUID，创建DTO的时候不需要填入，因为TOCO会自动为其分配UUID，更新DTO的时候需要传入，用于定位需要更新的自定义字段；typeUuid参数对应类结构的UUID，当type为Enum、Eo时包含该字段；innerType为List内部类型，当type为List时包含该字段；innerUuid为List内部类结构的UUID，当type为List且innerType=Enum、Eo时包含该字段。示例如下： - meeting_with_room_dto -```json + { "dto": { "uuid": null, @@ -218,9 +218,9 @@ DateTime endTime； //会议结束时间 ] } } -``` + - meeting_room_with_meetings_dto -```json + { "dto": { "uuid": "d05c7b3d-1c92-45a1-2113-a01b245813c1", @@ -241,7 +241,7 @@ DateTime endTime； //会议结束时间 ] } } -``` + 示例中meeting_with_room_dto没有uuid，为待创建的DTO。meeting_base_dto和meeting_room_with_meetings_dto为已存在的DTO，带有uuid。 - **预定义方法:** 对于每一个DTO，TOCO会自动其根Entity的唯一索引生成一些预定义的RPC方法及实现，预定义方法不仅获取了根Entity的数据，还通过RPC调用的方式**自动**获取了**所有扩展字段**的数据，并对数据进行了拼装处理。如实体user有unique index(username)，则会针对UserDto生成UserDto UserDtoService.getByUserName(String userName)和List UserDtoService.getByUserNames(List userNames)。预定义方法内部根据外键关系自动生成了复杂DTO数据的递归、Join拼装的能力，会直接返回DTO内部的所有继承字段和扩展字段的数据。注意自定义字段的数据获取不会自动生成，需要在对应的convert方法中编写代码。 @@ -262,13 +262,13 @@ DateTime endTime； //会议结束时间 * **职责:** 表达DTO的数据结构 * **命名规则**：类名以Dto结尾 * **禁止** 修改该类 - * **类路径：** 位于 ```**.manager.dto``` 包路径下 + * **类路径：** 位于 **.manager.dto 包路径下 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|DEFINITION - **Manager** * **生成产物:** Java接口以及实现类 * **命名规则:** 接口类名以Manager结尾、实现类名以ManagerImpl结尾(${DtoName}Manager)、基类以名ManagerBaseImpl结尾(${DtoName}ManagerImpl) * **职责:** 提供了DTO数据的获取的接口，包括根据id单个、id列表批量获取、以及根据DTO对应的实体的数据库索引获取 - * **类路径：** 位于 ```**.manager``` 包路径下 + * **类路径：** 位于**.manager 包路径下 * **禁止** 删除该类中的任何系统自动生成的函数 * **唯一标识符位置：** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|MANAGER - **Converter** @@ -276,7 +276,7 @@ DateTime endTime； //会议结束时间 * **禁止** 删除该类中的任何系统自动生成的函数 * **命名规则:** 实现类名以Converter结尾(${DtoName}Converter)、基类名以BaseConverter结尾(${DtoName}BaseConverter) * **职责:** Entity转换到BaseDTO或则BaseDTO转化为普通DTO：从Entity转为BaseDTO的方法命名为convert${EntityName}To${DtoName}；从BaseDTO转换为DTO的方法命名为convert${BaseDtoName}To${DtoName} - * **类路径：** 位于 ```**.manager.converter``` 包路径下 + * **类路径：** 位于 **.manager.converter 包路径下 * **唯一标识符位置：** * 实现类Converter 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|CONVERTER * 基类BaseConverter 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${DTO在TOCO中的uuid}|DTO|BASE_CONVERTER @@ -294,7 +294,7 @@ DateTime endTime； //会议结束时间 - **根VO和子VO:**TOCO中的VO分为两种：1.根VO，指最外层的VO结构，需要经由TOCO创建，有uuid作为唯一标识，根VO可被其他根VO或子VO引用；2.子VO，某个根VO的内部嵌套VO，通过外键关系关联BaseDTO之后由TOCO自动创建，只附属于某个根VO，只能被这一个根VO引用，且没有uuid。所以在TOCO中，我们需要描述VO要的字段、扩展关系，并通过**创建根VO**的行为使TOCO**自动创建**其子VO，或引用其他根VO，即可完成一个复杂嵌套VO的创建过程，无需单独创建子VO。 - **字段扩展方式:**同DTO的字段扩展方式，可以通过任意**一个**派生源BaseDTO，即可经过外键扩展成为复杂嵌套VO。只要存在外键关系且满足以下条件即可扩展：对于正向替换：当前实体存在指向其他实体的外键字段；对于反向注入：其他实体存在指向当前实体的外键字段。 例如：有两个BaseDTO - ``` + MeetingRoomBaseDto{ //会议室 Long id;// 会议室id,主键 String name;// 会议室名称 @@ -307,10 +307,10 @@ DateTime endTime； //会议结束时间 DateTime startTime； //会议开始时间 DateTime endTime； //会议结束时间 } - ``` + 其中Meeting和MeetingRoom是n:1关系。即多个会议室会占用同一个会议室。 通过“正向替换”这个行为，可以组装出如下VO： - ``` + MeetingWithRoomVo { //根VO，需要通过TOCO创建 Long id;// 会议id MeetingRoomVo room { //正向替换该会议用的会议室信息，TOCO自动生成的内部VO，派生自MeetingRoomBaseDto @@ -322,9 +322,9 @@ DateTime endTime； //会议结束时间 DateTime startTime； //会议开始时间 DateTime endTime； //会议结束时间 } - ``` + 通过“反向注入”这个行为，可以生成： - ``` + MeetingRoomWithMeetingVo{ Long id;// 会议室id String name;// 会议室名称 @@ -335,11 +335,11 @@ DateTime endTime； //会议结束时间 DateTime endTime； //会议结束时间 } } - ``` + - **TOCO中VO的json结构描述:** 在TOCO中，VO使用一个json结构表示，该结构可用于理解VO的含义，或作为创建、更新VO工具的参数。部分字段的含义为：expandList为正向替换，reverseExpandList为反向注入，extendFieldList为来自派生源DTO的字段，customFieldList为自定义字段。expandListList中，foreignKeyInThisEntity为正向替换对应的本表外键字段的名字，voFieldName为正向替换之后给该字段的起的新名字；reverseExpandList中，foreignKeyInOtherEntity为反向注入对应的他表外键字段的名字，voFieldName为反向注入之后给该字段的起的新名字；customFieldList中，uuid为自定义字段特有的UUID，创建DTO的时候不需要填入，因为TOCO会自动为其分配UUID，更新DTO的时候需要传入，用于定位需要更新的自定义字段；typeUuid参数对应类结构的UUID，当type为List且innerType=Enum、Eo时会包含该字段；extendFieldList中，name为继承字段的名称，如果要继承的DTO字段不是DTO类型，则VO中的字段类型将与DTO字段一致，如果DTO中的字段为DTO或List类型，由于VO中的字段类型不能为DTO，**必须**将该DTO转换为VO才可作为VO字段使用，所以extendFieldList中会有**一个vo结构**，用来表示该字段DTO类型派生出的VO定义，注意：该VO字段中的VO类型必须派生自继承的DTO字段类型！ 示例如下： 系统中存在meeting_detail_dto -```json + { "uuid": "cd55c96b-aa67-bfb2-7614-70b503a8f8bf", "name": "meeting_detail_dto", @@ -358,9 +358,9 @@ DateTime endTime； //会议结束时间 } ] } -``` + - meeting_with_room_vo由meeting_detail_dto派生，并继承了id和create_user字段 -```json + { "vo": { "uuid": null, @@ -471,7 +471,7 @@ DateTime endTime； //会议结束时间 ] } } -``` + 示例中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类型。 @@ -496,12 +496,12 @@ DateTime endTime； //会议结束时间 * **生成产物:** 在controller层生成一个Java类 * **命名规则:** 类名以Vo结尾 * **职责:** 表达VO的数据结构 - * **类路径:** 位于 ```**.entrance.web.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``` 包路径下 + * **类路径:** 位于 **.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 @@ -567,7 +567,7 @@ DateTime endTime； //会议结束时间 - **关键配置:** Wo中的字段分为三种：a.继承Entity的字段，和Entity的字段类型一样；b.扩展字段，含正向替换和反向注入字段，类型为WO或List; - **字段扩展方式:** TOCO定义了一个WO组装方法，适用于WO通过外键关系替换/注入对应Entity的信息，对象化表达有外键关系的Entity信息。只要存在外键关系且满足以下条件即可扩展：a.对于正向替换：当前实体存在指向其他实体的外键字段；b.对于反向注入：其他实体存在指向当前实体的外键字段。 例如：有两个Entity - ``` + MeetingRoom{ //会议室 Long id;// 会议室id,主键 String name;// 会议室名称 @@ -580,12 +580,12 @@ DateTime endTime； //会议结束时间 DateTime startTime; //会议开始时间 DateTime endTime; //会议结束时间 } - ``` + 其中Meeting和MeetingRoom是n:1关系。即多个会议室会占用同一个会议室。 当组装对象以某Entity为根时，那么首先它将拥有和该Entity一样的数据结构，并将通过下面的“正向替换”，“反向注入”的行为，递归的将多个互相之间有外键关系的Entity的信息组装到该组装对象中。 定义“正向替换”这个行为，选定一个表，这张表存在到另外一张表的一个或多个外键。选择和需求相关的具体的外键属性，将该外键属性替换为另一张表为根的组装对象。这样就可以获取基于某些外键且包含另一张表更详细的属性数据。 例如：需要会议和其占用会议室时，将Meeting表中的roomid外键替换为以MeetingRoom为根的组装对象，而backupRoomid对应的候选会议室具体信息和本需求无关，不做任何替换。如下： - ``` + MeetingWithRoomWo { Long id;// 会议id MeetingRoomWo room { //正向替换该会议用的会议室信息，是一个以会议室为根的对象 @@ -597,11 +597,11 @@ DateTime endTime； //会议结束时间 DateTime startTime； //会议开始时间 DateTime endTime； //会议结束时间 } - ``` + 又例如：需要会议和其候选会议室时，将Meeting表中的backupRoomid进行正向替换。 又例如：需要会议，且即需要其占用会议室，也需要候选会议室时，将Meeting表中的roomid，backupRoomid都进行正向替换。 同时TOCO还定义了“反向注入”这个行为，选定一个表，如果有另外的表到前表有外键，选择和需求相关的具体的外键属性在选定表中增加一个以另外表为根的组合对象(当外键关系是1:1时)或者组合对象的列表(当外键关系是n:1时)。需求是：“获取会议室，和占用它的会议信息”，需要选定MeetingRoom，那么基于另外的表Meeting中存在字段roomid，为到MeetingRoom的n:1关系外键。可以将List反向注入到MeetingRoom中，最终生成一个以Meeting为根的组装对象，生成： - ``` + MeetingRoomWithMeetingWo { Long id;// 会议室id String name;// 会议室名称 @@ -612,10 +612,10 @@ DateTime endTime； //会议结束时间 DateTime endTime； //会议结束时间 } } - ``` + 这种“正向替换”和“反向注入”可以按需递归调用，去将多个互相之间有外键关系的对象组装成最终对象。例如，还有另外一张表MeetingAgenda到Meeting有n:1的外键,那么如果我要去组装以Meeting开始，包含MeetingRoom, MeetingAgenda的查询对象，首先发现MeetingRoom是可以正向扩展到Meeting的，并且可以反向注入MeetingAgenda - meeting_with_room_and_agenda_wo -```json + { "wo": { "uuid": null, @@ -647,7 +647,7 @@ DateTime endTime； //会议结束时间 ] } } -``` + #### **2.9 读方案 (ReadPlan)** - **定义与用途:** 在TOCO中，针对DTO和VO，读方案描述了如何基于查询对象从数据库获取DTO和VO列表数据，主要提供了两个能力 - 根据查询条件，返回符合条件的DTO或VO的id列表 @@ -690,7 +690,7 @@ DateTime endTime； //会议结束时间 - 禁止使用filter语法 - 禁止使用has语法 - 语法定义：使用 lezer 定义了如下语法 - ``` + @top Program { expression? } @skip { spaces | newline | LineComment } @precedence { @@ -761,7 +761,7 @@ DateTime endTime； //会议结束时间 "." } @detectDelim - ``` + - **读方案设计元素的表达** - 以json格式表达，json schema 定义如下 ```json @@ -858,7 +858,7 @@ DateTime endTime； //会议结束时间 - 用户需求 获取一段时间未被使用的会议室(包含当前会议已选择的会议室),并且根据会议名称会议信息，最后分页返回。 - 对应的读方案定义 - ```json + { "name": "get_unused_meeting_room_list", "description": "获取未使用的会议室(包含当前会议已选择的会议室)", @@ -876,24 +876,24 @@ DateTime endTime； //会议结束时间 } ] } - ``` + - **代码产物和修改建议** - **查询传输对象(QTO)** * **生成产物:** 在Service层生成一个Java类 * **命名规则:** 类名以Qto结尾(${ReadPlanName}Qto) - * **类路径:** 位于 ```**.persist.qto```包路径下 + * **类路径:** 位于**.persist.qto包路径下 * **职责:** 读方案的查询参数结构,通常可作为API的参数，API接收到参数后可直接透传给内部的RPC进行调用 * **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|DEFINITION * **内部结构:** QTO内部包含了如下分页相关的字段: - ``` + private String scrollId; //瀑布流分页时用作游标 private Integer size; //页码分页时用作每页记录的数量 private Integer from; //页码分页时用作开始的记录位置 - ``` + - **Dao** - **生成产物:** 在Dao层生成一个Java类 - **命名规则:** 类名以Dao结尾(${ReadPlanName}Dao) - - **类路径:** 位于 ```**.persist.mapper```包路径下 + - **类路径:** 位于 **.persist.mapper包路径下 - **职责:** 读方案对应的数据库查询方法 - **唯一标识符位置:** 其对应的唯一标志在类注解@AutoGenerated中指定,uuid规则: ${ReadPlan在TOCO中的uuid}|QTO|DAO - **QueryExecutor** @@ -903,7 +903,7 @@ DateTime endTime； //会议结束时间 - 瀑布流，会生成一个，**Waterfall函数，返回VSQueryResult - 查询数量， 会生成一个 **Count函数，返回Integer - **命名规则:** 类名以QueryExecutor结尾(${VoName}QueryExecutor) - - **类路径:** 位于 ```**.entrance.web.query.executor```包路径下 + - **类路径:** 位于**.entrance.web.query.executor包路径下 - **职责:** 提供针对VO的查询入口，把QtoService返回的id数据转化成目标**VO** - **QueryService** - **生成产物** 对于返回**DTO**的查询方案，在service层生成一个Java类,对于分页查询、不分页返回全量、瀑布流查询、计数都有后独立的函数实现 @@ -912,12 +912,12 @@ DateTime endTime； //会议结束时间 - 瀑布流，会生成一个，**Waterfall函数, 返回VSQueryResult - 查询数量， 会生成一个 **Count函数,返回Integer - **命名规则:** 类名以QueryService结尾(${DtoName}QueryService) - - **类路径:** 位于 ```**.service.index.entity```包路径下 + - **类路径:** 位于**.service.index.entity包路径下 - **职责:** 提供对DTO查询入口，把QtoService返回的id数据转化成目标**DTO**，或返回符合条件的记录数量 - **VSQueryResult说明：** - VSQueryResult为一个写死的类，全路径为com.vs.es.query.VSQueryResult，存在于jar中，可以直接使用，禁止再创建新的VSQueryResult类! - VSQueryResult代码结构如下： - ``` + package com.vs.es.query; import lombok.Data; @@ -934,7 +934,7 @@ DateTime endTime； //会议结束时间 private String scrollId; //瀑布流查询游标 private boolean hasMore; //瀑布流查询时表示是否有下一页 } - ``` + - **例子:** * 根据用户名称查询用户列表返回UserDTO，则生成UserNameQto、UserNameQtoService、UserNameQtoDao、UserNameQueryService; UserNameQueryService调用UserNameQtoService，UserNameQtoService调用UserNameQtoDao - **修改建议：** @@ -1050,10 +1050,10 @@ DateTime endTime； //会议结束时间 String nickname;//昵称 Long friend_count;//好友数量 } - ``` + - **需求:** 创建会议 - 对应的写方案定义: - ```json + { "name": "create_meeting", "description": "创建会议", @@ -1077,18 +1077,18 @@ DateTime endTime； //会议结束时间 * **函数命名规则:** 和写方案同名 * **职责:** 按需对入参进行转换，调用BaseBOService里的函数完成对聚合对象的操作, 实现对数据库的写操作； * **返回值:** 操作的聚合根实体记录的主键字段的值 - * **BOService的类路径:** ```**.service``` + * **BOService的类路径:** **.service * **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${WritePlan在TOCO中的uuid} - **BaseBOService** - **生成产物:** 在对应的聚合的BaseBOService里生成一系列函数，根据入参完成对聚合对象的变更 - **职责** 增对每个实体的生成增删改的函数，并且根据参数的结构以及聚合的结构，构建嵌套的调用逻辑，完成对一个聚合对象的变更，记录并且返回对应的变更情况 - - **类路径:** ```**.service.base``` + - **类路径:** **.service.base - **禁止** 修改该类 - **BTO (业务变更传输对象)** * **生成产物:** 一个Java类，以内部类的方式表示层级结构, **注意** BTO只能由写方案生成，不能凭空创建 * **命名规则:** 一个Bto结尾(${WritePlanName}Bto，驼峰展示) * **禁止** 修改该类 - * **类路径:** 位于```**.service.bto```包路径下 + * **类路径:** 位于**.service.bto包路径下 * **职责:** 在**TOCO**中，BTO为写方案的参数结构，每个写方案会对应一个BTO，写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要查询的实体字段值，完成对数据库的变更 * **唯一标识符位置:** 其对应的唯一标识符在类注解@AutoGenerated中指定, uuid规则: ${WritePlan在TOCO中的uuid}|BTO|DEFINITION - **例子：** @@ -1096,7 +1096,7 @@ DateTime endTime； //会议结束时间 - **修改建议：** - 不能修改BaseBOService中的函数，不建议修改BTO文件。建议在BOService中进行手动代码扩展，处理可能被复用的修改前后的逻辑，如修改数据库的前后值对比、或常被复用的校验逻辑（业务不变性校验逻辑除外）、需要经常在一个事务内执行的其他写操作等。 - 父类函数会返回一个BoResult类，此类记录了各个Bto和Bo实例的对应关系，以及各个Bto实例的操作结果, 可以通过以下接口获取。 例如：在创建用户的写方案中，BoService里的入参为CreateUserBto 例如：在创建用户的写方案中，BoService里的入参为CreateUserBto,用户id由数据库生成，如果需要返回创建用户id，那么通过boResult.getAddedResult(createUserBto).getBo().getId()可以返回新建的用户id - ``` + /** * 获取更新成功的bto结果 * @@ -1118,8 +1118,8 @@ DateTime endTime； //会议结束时间 * @return */ public DeletedBto getDeletedResult(final Object btoObj) - ``` - ``` + + public class UpdatedBto { //Bto 入参 private Bto bto; @@ -1128,8 +1128,8 @@ DateTime endTime； //会议结束时间 //bo，后项 private BO bo; } - ``` - ``` + + //记录删除记录的情况 @Setter @Getter @@ -1139,8 +1139,8 @@ DateTime endTime； //会议结束时间 //Bto 对应的Entity，前项 private Entity entity; } - ``` - ``` + + //记录Bto创建的前后值 @Setter @Getter @@ -1150,13 +1150,13 @@ DateTime endTime； //会议结束时间 //bo 后项 private BO bo; } - ``` + #### **2.12 业务变更传输对象(BTO)** - **定义与用途:** 在TOCO中，BTO为写方案自动生成的参数结构，每个写方案会生成一个BTO。BTO为写方案选定的操作实体根据关系形成的树形集合，最外层为聚合根。写方案调用方按照BTO的结构向写方案生成的RPC方法传入需要操作的实体字段值，完成对数据库的写操作 - **如何创建/生成:** BTO只能由写方案自动创建，不能单独新建任何BTO。在创建写方案后，TOCO会自动生成一个BTO作为该写方案传入的参数结构。 - **关键配置:** 名称（${WritePlanName}Bto，驼峰展示），嵌套的树形实体和字段列表，BTO内部的字段全部都来自Entity。以下为一个示例： -``` + class CreateUserBto { //对应实体user Long id; //来自于user.id String name; //来自于user.name @@ -1165,7 +1165,7 @@ DateTime endTime； //会议结束时间 String url; //来自于picture.url } } -``` + - **与API的关系:** BTO通常可作为API的参数，API接收到参数后可直接透传给内部的RPC进行调用，注意BTO只用作写操作的参数，**禁止用作查询参数结构** - **复杂场景处理：** 对于涉及多个写方案的复杂API，可以： a. 如果接口有一个主要的写场景，则创建一个主要的写方案，让其自动生成的BTO作为API参数，然后再增加其他基本类型的参数或EO @@ -1295,7 +1295,7 @@ requestParams为请求参数列表，response为返回结构，requestParams中 } ``` - 例子：用户注册流程 - ``` + { "moduleName":"user",//该流程所属的模块 "name":"user_register",//定义该流程的功能 @@ -1343,29 +1343,29 @@ requestParams为请求参数列表，response为返回结构，requestParams中 } ] } - ``` + - **代码产物和修改建议** - **FlowConfig** * **生成产物:** 每个模块在service层的生成一个Java类，负责注册模块下的所有流程到执行器 * **命名规则:** 类名为${moduleName}FlowConfig * **职责:** 在应用启动的时候注册模块内的所有的流程服务到执行器 - * **类路径:** ```**.service.flow``` + * **类路径:** **.service.flow - **Service** * **生成产物:** 在service层的以模块名为类名前缀的${moduleName}FlowService中生成一个流程的入口函数 * **函数命名规则:** 流程名为方法名为后缀：pubic void invoke${functionFlowName}(${functionFlowName}Context context) * **职责:** 在代码逻辑中，使用该流程需要以该函数作为调用入口 - * **类路径:** ```**.service``` + * **类路径:** **.service * **唯一标识符位置:** 其对应的标识符在函数的注解@AutoGenerated中指定, uuid规则: ${FunctionFlow在TOCO中的uuid}|FLOW|METHOD - **FlowNode** * **生成产物:** 在service层生成一个Java类， **注意** 每个FunctionFlow的开始节点(StartNode)不生成 * **类命名规则:** ${nodeName}Node * **入口函数命名:** pubic void process() * **职责:** 用于封装内聚性的业务逻辑 - * **类路径:** ```service.flow.node.${functionFlowName}``` + * **类路径:** service.flow.node.${functionFlowName} - **FlowContext** * **函数命名规则:** {nodeName}Node * **职责:** 作为流程节点之间的参数传递（包括出参和入参），在实现业务逻辑的时候，按需在这个上下文类中添加所需的字段 - * **类路径:** ```**.service.flow.context``` + * **类路径:** **.service.flow.context * **唯一标识符位置:** 其对应的标识符在类注解@AutoGenerated中指定, uuid规则: ${FunctionFlow在TOCO中的uuid}|FLOW|CONTEXT - **例子：** - 用户登录，在UserFlowService中生成一个函数invokeLoginFlow，该函数通过流程框架根据流程定义调用LoginNode，LoginNode中封装了用户登录的逻辑，LoginFlowContext中封装了用户登录的参数和结果。 @@ -1380,8 +1380,8 @@ requestParams为请求参数列表，response为返回结构，requestParams中 - **3.1 支持的语言/框架** Java、SpringBoot、MyBatis-plus(读)、Hibernate(写) - **3.2 项目结构与导航** - ``` TOCO生成的项目是一个多模块的SpringBoot项目,包括主模块和子模块，它的子模块位于根目录下的/modules目录中，**注意** 获取子模块代码文件路径的时候需要从根目录开始，所以必须从modules节点开始，例如：子模块module1下的的java类路径应该是`modules/module1/src/main/java...` + |──main_module │ ├── common # 项目级别公共的基础模块 │ │ ├──config/ # 中间件配置 @@ -1424,7 +1424,7 @@ requestParams为请求参数列表，response为返回结构，requestParams中 ├── query/ # 查询方案的service层入口，调用persist层的查询实现 └── base/ # 每个BOService对应的基类 在一个子模块的内，它的依赖层级为entrance -> service -> manager -> persist, 同时各个层都依赖 common - ``` + - **3.3 标准查找流程** 1. **API查找** → `modules/{模块名}/entrance/web/controller/` 2. **DTO查找** → `modules/{模块名}/manager/dto/`