2025-08-20 13:57:42 +08:00
< TOCO知识库 >
-----------------------------------------------------------------------------
### **1. TOCO 平台概览:**
- **1.1 平台简介:** TOCO是软件设计和代码自动生成平台。基于DDD、分层架构、CQRS理论， ，
- **1.2 核心价值/目标用户:** 提供软件设计能力，设计成果直接生成标准代码，提高编码一致性和效率
- **1.3 主要特性概览:** 可视化设计、模型关联、多人协作、代码生成器
### **2. TOCO 设计元素:**
#### **2.1 模块 (Module)**
- **定义与用途:** 在TOCO中， ， ， ，
- **关键配置:** 名称(小写英文+下划线， ， ，
- **与其他元素关系:** 下列所有设计元素都属于某个模块
#### **2.2 枚举 (Enum)**
- **定义与用途:** 表示常量值集合，可跨模块使用，可作为字段类型
- **关键属性/配置:** 名称(以_enum结尾，
- **与其他元素关系:** 可作为Entity、Dto、Vo、Bto、Qto、Eo的字段类型
- **Enum设计元素的表达:**
- Json格式， ：
```json
{
"type": "object",
"properties": {
"name": { "type": "string","description": "名称,英语表达， ，
"uuid": { "type": "string","description": "唯一标识符，创建时为空，更新时必填"},
"description": { "type": "string", "description": "枚举含义和用途，
"moduleName": { "type": "string", "description": "所属模块，创建时必填，更新时可空"},
"values": {
"type": "array","description": "枚举值列表",
"items": {"type": "string","description": "枚举值， ， ，
}
},
"required":["name","description"]
}
```
#### **2.3 值对象 (EO)**
- **定义与用途：** EO是可复用的POJO数据结构， ，
- **关键属性/配置：** 名称以_eo结尾， ：
- **与其他元素关系：** 可作为Entity、Dto、Vo、Bto、Qto的字段类型，
- **EO设计元素的表达：
- 使用Json格式表达， ：
```json
{
"type":"object",
"properties": {
"name":{ "type": "string", "description": "名称， ，
"description": { "type": "string","description": "描述EO含义和用途，
"uuid":{ "type": "string", "description": "唯一标识符，创建时为空，更新时必填"},
"moduleName":{ "type": "string", "description": "所属模块，创建时必填，更新时可空"},
"fieldList":{
"type":"array", "description": "EO属性字段列表",
"items":{
"type": "object",
"properties":{
"name": { "type": "string","description": "字段名称， ，
"uuid":{ "type": "string","description": "字段类型为Enum或Eo时必填，
"type":{ "type": "string","description": "字段类型：
"innerUuid":{"type": "string", "description": "当innerType为Eo或Enum时，
"innerType": { "type": "string", "description": "List元素类型：
},
"required":[ "name","type"]
}
}
},
"required":["name","description"]
}
```
#### **2.4 实体关系 (ER / Entity)**
- **定义与用途:** 实体对应数据库表，关系为实体间的外键依赖
- **关键属性/配置:** 包含名称、字段、字段类型、主键、索引，
- **与其他元素关系:** 实体是聚合的基础，
#### **2.5 聚合对象 (BO/业务对象)**
- **定义与用途:** 聚合对象封装一组关联实体。从聚合根实体开始，按层级关系组装其他实体，形成树形结构。提供内存一致性视图和数据操作入口。一个实体只能属于一个聚合对象，聚合对象只能在单一模块中组合。
- **包含元素:** 聚合根实体 + 子实体对象。例如：
- **关键配置:** 名称(${EntityName驼峰}BO，
- **与其他元素关系:** 聚合是写方案的基础。
#### **2.6 数据传输对象 (DTO)**
- **定义与用途:** DTO基于某个Entity构建， ， ： ， ， ； ， ， ，
- **创建方式:** 每个Entity自动生成一个BaseDTO， ， ， ： ； ，
- **关键配置:** 名称（ ， ， ） ： ， ； ， ， < DTO > ； ， ， ， ， ，
- **字段扩展方式:** DTO通过外键关系替换/注入对应Entity信息。满足条件可扩展： ： ；
例如：
```
MeetingRoom{ //会议室
Long id;// 会议室id,主键
String name;// 会议室名称
}
Meeting { //会议
Long id;// 会议id,主键
Long roomid; //会议室id外键，
Long backupRoomid; //备用会议室id外键，
String title; //会议标题
DateTime startTime; //开始时间
DateTime endTime; //结束时间
}
```
Meeting和MeetingRoom是n:1关系。多个会议占用同一个会议室。
组装对象以某Entity为根时， ， ，
**正向替换：** 选定表存在到另一表的外键。选择相关的外键属性，将该外键替换为另一表为根的组装对象。获取基于外键且包含另一表详细属性的数据。
例如： ， ， ：
```
MeetingWithRoomDto {
Long id;// 会议id
MeetingRoomDto room { //正向替换会议室信息，以会议室为根的对象
Long id; //会议室ID
String name;// 会议室名称
}
Long backupRoomid; // 不变化
String title; //会议标题
DateTime startTime; //开始时间
DateTime endTime; //结束时间
}
```
**反向注入：** 选定表， ， （ ） （ ）
需求："获取会议室和占用它的会议信息"， ， < MeetingBaseDto > 反向注入到MeetingRoom中：
```
MeetingRoomWithMeetingDto {
Long id;// 会议室id
String name;// 会议室名称
List< MeetingBaseDto > meetingList { //反向注入使用该会议室的会议信息
Long id;// 会议id
String title; //会议标题
DateTime startTime; //开始时间
DateTime endTime; //结束时间
}
}
```
"正向替换"和"反向注入"可按需递归调用，组装多个有外键关系的对象。
- **JSON结构描述:** DTO用json结构表示， ： ， ， ， ， ， ， ； ， ， ； ， ， ， ； ， ； ， ； ，
示例：
- meeting_with_room_dto
```json
{
"dto": {
"uuid": null,
"name": "meeting_with_room_dto",
"description": "会议详情，包含会议室信息",
"fromEntity": "meeting",
"expandList": [
{
"foreignKeyInThisEntity": "room_id",
"dtoFieldName": "meeting_room",
"dto": {
"uuid": "d05c7b3d-1c92-45a1-2113-a01b245813c1",
"name": "meeting_room_with_meetings_dto",
"fromEntity": "meeting_room",
"description": "会议室信息，包含会议列表"
}
}
],
"customFieldList":[
{
"uuid": "自定义字段唯一标识，
"name": "status",
"type": "Enum",
"typeUuid": "对应Enum的uuid",
"description": "当前状态"
}
]
}
}
```
- meeting_room_with_meetings_dto
```json
{
"dto": {
"uuid": "d05c7b3d-1c92-45a1-2113-a01b245813c1",
"name": "meeting_room_with_meetings_dto",
"description": "会议室详情，包含会议信息",
"fromEntity": "meeting_room",
"reverseExpandList": [
{
"foreignKeyInOtherEntity": "room_id",
"dto": {
"uuid": "ffeec02d-2a32-1531-1ce1-b9bfc1993765",
"name": "meeting_base_dto",
"description": "会议基本信息",
"fromEntity": "meeting"
},
"dtoFieldName": "meeting_list"
}
]
}
}
```
meeting_with_room_dto无uuid， ，
2025-08-28 15:22:43 +08:00
- **预定义方法:** 每个DTO基于根Entity的唯一索引自动生成预定义RPC方法及实现， ， ， < UserDto > UserDtoService.getByUserNames(List< String > userNames)。预定义方法内部基于外键关系自动生成复杂DTO数据的递归、Join拼装能力，
2025-08-20 13:57:42 +08:00
- **公开性:** DTO可设置公开性， ， ； ，
- **跨模块依赖:** 如DTO内引用其他模块DTO， （ ） ，
- **复杂嵌套DTO获取流程:** 获取DTO有2种方式， ：
- 第1种：
- 第2种：
判断使用方式的步骤：
- a. 查询DTO条件为主键或唯一索引的值或列表，
- b. 通过其他复杂查询条件，
2025-08-28 15:22:43 +08:00
判断使用方式时，只能根据查询条件判断是否使用读方案，禁止使用返回值是否需要数据拼装来判断！
2025-08-20 13:57:42 +08:00
#### **2.7 视图对象 (VO)**
- **定义与用途:** VO基于BaseDTO（ ） ， ，
- **关键配置:** 名称（ ， ） ： （ ， ） ； （ ， < VO > ） ； （ ） ，
- **继承字段类型转换:** VO只与派生源VO有转换关系。当VO派生自某DTO， （ ） ， （ ） ，
- **与DTO的区别:** DTO用于服务层传输， ， ， ； ， ， ， ，
- **创建方式:** VO通常基于某个BaseDTO及外键关系派生， （ ， ）
- **根VO和子VO:** VO分两种： ： ， ， ， ； ： ， ， ， ，
- **字段扩展方式:** 同DTO字段扩展方式， ， ： （ ） ； （ ）
例如：
```
MeetingRoomBaseDto{ //会议室
Long id;// 会议室id,主键
String name;// 会议室名称
}
MeetingBaseDto { //会议
Long id;// 会议id,主键
Long roomid; //占用的会议室id， ，
Long backupRoomid; //备用的会议室id， ，
String title; //会议标题
DateTime startTime；
DateTime endTime；
}
```
Meeting和MeetingRoom是n:1关系。多个会议占用同一个会议室。
通过"正向替换"组装出：
```
MeetingWithRoomVo { //根VO，
Long id;// 会议id
MeetingRoomVo room { //正向替换会议室信息， ，
Long id; //会议室ID
String name;// 会议室名称
}
Long backupRoomid; // 不变
String title; //会议标题
DateTime startTime；
DateTime endTime；
}
```
通过"反向注入"生成：
```
MeetingRoomWithMeetingVo{
Long id;// 会议室id
String name;// 会议室名称
List< MeetingVo > meetingList{ //反向注入使用该会议室的会议信息， ，
Long id;// 会议id
String title; //会议标题
DateTime startTime；
DateTime endTime；
}
}
```
- **JSON结构描述:** VO用json结构表示， ： ， ， ， ， ， ； ， ， ； ， （ ， ） ； （ ） ； ， ， ， < DTO > 类型， ， ， ， ： ！
示例：
```
{
"uuid": "cd55c96b-aa67-bfb2-7614-70b503a8f8bf",
"name": "meeting_detail_dto",
"fromEntity": "meeting",
"description": "会议详情",
"expandList": [
{
"foreignKeyInThisEntity": "create_user_id",
"voFieldName": "create_user",
"dto": {
"uuid": "53bb59cf-1ed2-6fb3-9f61-895b638903d8",
"name": "user_base_dto",
"fromEntity": "user",
"description": "用户基本信息"
}
}
]
}
```
- meeting_with_room_vo由meeting_detail_dto派生，
```
{
"vo": {
"uuid": null,
"name": "metting_with_room_vo",
"description": "会议详情，包含会议室信息，以及会议室禁用列表",
"rootVo": "metting_with_room_vo",
"fromEntity": "meeting",
"fromDto": "meeting_detail_dto",
"fromDtoUuid": "cd55c96b-aa67-bfb2-7614-70b503a8f8bf",
"extendFieldList":[
{
"name": "id"
},
{
"name": "create_user",
"vo": {
"uuid": null,
"name": "user_base_vo",
"description": "用户信息",
"rootVo": "metting_with_room_vo",
"fromEntity": "user",
"fromDto": "user_base_dto",
"fromDtoUuid": "53bb59cf-1ed2-6fb3-9f61-895b638903d8",
"reverseExpandList": [],
"customFieldList":[],
"extendFieldList":[
{
"name": "name"
},
{
"name": "gender"
}
]
}
}
],
"expandList": [
{
"foreignKeyInThisEntity": "room_id",
"voFieldName": "meeting_room",
"vo": {
"name": "meeting_room_with_meetings_vo",
"description": "会议室信息，包含会议列表",
"rootVo": "metting_with_room_vo",
"fromEntity": "meeting_room",
"fromDto": "meeting_room_base_dto",
"fromDtoUuid": "88437212-6370-99a6-1e7a-fe1469082d08",
"reverseExpandList": [
{
"foreignKeyInOtherEntity": "room_id",
"vo": {
"uuid": null,
"name": "meeting_base_vo",
"description": "会议基本信息",
"rootVo": "metting_with_room_vo",
"fromEntity": "meeting",
"fromDto": "meeting_base_dto",
"fromDtoUuid": "1a768c5e-b449-db5d-fe55-9d572d64332a",
"extendFieldList":[
{
"name": "startTime"
},
{
"name": "endTime"
}
]
},
"voFieldName": "meeting_list"
}
],
"customFieldList":[
{
"uuid": "自定义字段的唯一标识，
"name": "occupied",
"type": "Boolean",
"description": "是否被占用"
},
{
"uuid": "自定义字段的唯一标识，
"name": "custom_eo",
"type": "Eo",
"typeUuid": "uuid of an eo"
},
{
"uuid": "自定义字段的唯一标识，
"name": "status_list",
"type": "List",
"innerType": "Enum",
"innerUuid": "uuid of an enum"
},
{
"uuid": "自定义字段的唯一标识，
"name": "custom_string_list",
"type": "List",
"innerType": "String"
}
],
"extendFieldList":[
{
"name": "id"
},
{
"name": "name"
}
]
}
}
]
}
}
```
meeting_with_room_vo为根VO， ， ， ， ： ， ， ，
- **派生源默认使用BaseDTO:** 除非用户指定VO的派生源DTO，
2025-08-28 15:22:43 +08:00
- **与DTO的转换关系:** 创建**有派生源**的VO后， ： ， ， ， ， ， （ ， ） ， ； ， ， ， ，
- **字段数据获取:** 继承自DTO的字段及扩展字段， ， ， ，
2025-08-20 13:57:42 +08:00
- **跨模块依赖:** VO内存在由其他模块DTO派生出的子VO， ， ，
- **复杂嵌套VO获取流程:** 获取VO通常有3种方式， ：
- 第1种： ，
- 第2种： ，
- 第3种：
TOCO中判断使用方式的步骤：
- a. 查询VO条件为主键或唯一索引的值或列表，
- b. 通过其他复杂查询条件，
- c. 用户上下文中有指定返回DTO的读方案符合条件， ，
2025-08-28 15:22:43 +08:00
注意判断使用方式时，只能根据查询条件判断是否使用读方案，绝对禁止使用返回值是否需要数据拼装来判断！
2025-08-20 13:57:42 +08:00
#### **2.8 查询对象(WO)**
- **定义与用途:** WO基于Entity通过外键关系关联多个Entity的数据结构。WO表达数据取数拼装逻辑， ，
当返回DTO|VO时需要对列表属性进行过滤， ， （ ） ：
查询DTO
```java
class MeetingDto {
String meetingId;
String meetingName;
List< MeetingAgenda > agendaList;
}
```
需求：根据会议名称查询会议列表，根据议程信息过滤部分议程。定义查询对象时需包含议程信息，扩展字段名定义为**agendaList**
- **查询对象设计元素表达**
以json格式表达， ：
```json
{
"type": "object","description": "查询对象定义", "required": ["dtoOrVoId","name","fromEntity"],
"properties": {
"name": {"type": "string", "description": "查询对象名称， ， ，
"uuid": {"type": "string", "description": "查询对象uuid， （ ） ，
"dtoOrVoId":{"type":"string","description":"返回数据对象(VO或DTO)的uuid， ，
"moduleName": {"type": "string", "description": "查询对象所属模块名称，创建时必传"},
"fromEntity": {"type": "string", "description": "查询对象对应的实体"},
"expandList": {
"type": "array", "description": "正向扩展列表",
"items": {
"type": "object","description": "正向扩展定义","required": ["field","wo","fieldName"],
"properties": {
"field": {"type": "string", "description": "fromEntity扩展字段，
"wo": {"$ref": "#"},
"fieldName": {"type": "string", "description": "扩展字段名称"}
}
}
},
"reverseExpandList": {
"type": "array", "description": "反向扩展列表",
"items": {
"type": "object","description": "反向扩展定义","required": ["field","wo","fieldName"],
"properties": {
"field": {"type": "string", "description": "fromEntity扩展字段，
"wo": {"$ref": "#"},
"fieldName": {"type": "string", "description": "扩展字段名称"}
}
}
}
}
}
```
- **创建/生成方式:**
- **创建思路** 按查询返回的DTO|VO结构， （ ） ， ：
- 去掉过滤和查询都不需要的扩展
- 补全查询或字段过滤需要的扩展
- **关键配置:** WO字段分三种： ， ； ， ， < WO >
- **字段扩展方式:** WO通过外键关系替换/注入对应Entity信息， ： ： ；
例如：
```java
MeetingRoom{ //会议室
Long id;// 会议室id,主键
String name;// 会议室名称
}
Meeting { //会议
Long id;// 会议id,主键
Long roomid; //占用会议室id， ，
Long backupRoomid; //备用会议室id， ，
String title; //会议标题
DateTime startTime; //会议开始时间
DateTime endTime; //会议结束时间
}
```
Meeting和MeetingRoom是n:1关系。多个会议占用同一个会议室。
组装对象以某Entity为根时， ， ，
**正向替换**：选定表，该表有到另一表的外键。选择需求相关的外键属性，将外键属性替换为另一表为根的组装对象。获取基于外键且包含另一表详细属性的数据。
例如： ， ， ：
```
MeetingWithRoomWo {
Long id;// 会议id
MeetingRoomWo room { //正向替换会议用的会议室信息，以会议室为根的对象
Long id; //会议室ID
String name;// 会议室名称
}
Long backupRoomid; // 不变化
String title; //会议标题
DateTime startTime; //会议开始时间
DateTime endTime; //会议结束时间
}
```
**反向注入**：选定表，其他表到该表有外键，选择需求相关的外键属性在选定表中增加以另一表为根的组合对象(1:1关系时)或组合对象列表(n:1关系时)。
需求："获取会议室和占用它的会议信息"， ， < MeetingBaseDto > 反向注入到MeetingRoom中：
```
MeetingRoomWithMeetingWo {
Long id;// 会议室id
String name;// 会议室名称
List< MeetingBaseWo > meetingList { //反向注入使用该会议室的会议信息，以会议为根的对象
Long id;// 会议id
String title; //会议标题
DateTime startTime; //会议开始时间
DateTime endTime; //会议结束时间
}
}
```
"正向替换"和"反向注入"可按需递归调用， ， ， ， ， ，
meeting_with_room_and_agenda_wo示例：
```json
{
"wo": {
"uuid": null,
"name": "meeting_with_room_and_agenda_wo",
"dtoOrVoId":"96eedc80-2c29-44ab-883f-031efdba43e8",
"description": "会议详情，包含会议室信息，以及其中的会议列表",
"fromEntity": "meeting",
"expandList": [
{
"field": "room_id",
"fieldName": "meeting_room",
"wo": {
"name": "meeting_room_wo",
"fromEntity": "meeting_room",
"description": "会议室信息"
}
}
],
"reverseExpandList": [
{
"field":"meeting_id",
"filedName": "meeting_agenda_list",
"wo": {
"fromEntity": "meeting_agenda",
"name": "meeting_agenda_wo",
"description": "会议议程信息"
}
}
]
}
}
```
#### **2.9 读方案 (ReadPlan)**
- **定义与用途:** 读方案描述如何从数据库获取DTO和VO列表数据， ：
- 根据查询条件返回符合条件的DTO或VO的id列表
- 根据查询条件返回符合条件的DTO或VO的id数量
- 根据字段过滤条件对DTO和VO的列表字段数据进行过滤
- **注意** 不派生自DTO的VO不能创建读方案
- **读方案能力边界**
- 支持sql的count、exists、left join、not、in、like、between、and、or、括号、order by、limit、offset
- 不支持group by、having语法，
- 1:N外键关系只能使用exists，
例如： ， ， ， `select * from t where exists (select * from t1 where t.id=t1.id)` 合法，`select * from t left join t1 on t.id=t1.id` 非法
- exists只能选择后表字段，
例如： ， ， `select * from t where exists (select * from t1 where t.id=t1.id and t.name like ?)` 非法，`select * from t left join t1 on t.id=t1.id and t1.name like ?` 合法
- 需求超出读方案能力时，必须使用自定义查询
- **特别注意** 根据主键获取单个或批量DTO/VO且不需过滤列表字段数据的需求， ，
- **关键配置:** 名称(小写字母+下划线， ， ，
2025-08-28 15:22:43 +08:00
- **与RPC的关系:** 返回DTO的读方案自动生成RPC方法， ， ； ， ， ，
2025-08-20 13:57:42 +08:00
- **生成的读方案RPC使用:** 读方案RPC属于对应模块， ， ；
- **创建方式:** 先创建或选择一种DTO或VO作为返回值类型，
- **排序** 支持两种方式：
- **默认排序**：指定默认排序字段(不需入参指定排序字段)
- **自定义排序**：指定排序字段(需入参指定排序字段)，满足列表头动态排序需求
- **排序字段来源**： ， ， ： ， ， ：
- 提取需求中的查询信息，以输入的查询对象作为上下文，构建查询语句
- 如有列表属性过滤需求：提取需求中的过滤信息，针对可过滤字段(列表属性)分别创建过滤条件。过滤条件不能使用列表属性作为查询条件属性(不能使用contains语法)。属性字段是从根节点属性到当前属性的路径
- **查询语法和过滤语法**
- 基本语法格式：属性名 操作符 变量或常量，变量格式为#变量名 ；枚举类型常量用单引号包围，例如：'MALE'
- 数值、时间类型属性操作符：!=, ==, >, < , < =, >=, in, notIn, isNullOrNot
- 文本类型属性操作符：
- isNullOrNot是三元操作符， ： #genderIsNullOrNot ， ，
- 对象属性或列表对象属性操作符：
- 对象属性可对其子属性进行上述查询
- 查询变量不能作为条件属性
- 查询条件间可用AND, OR连接
- 可插入括号()对条件分组
- 列表对象属性只能使用contains、isNull、isNotNull操作符： ， ；
- 通过and, or, not连接符拼装子查询完成查询。不要使用未提及的操作符号、连接符
- 查询条件中的入参可在运行时传入或不传入值， ； ，
- 使用点号(.)访问当前对象的单值对象类型子属性，可多个点号组合访问嵌套单值对象属性
- 查询条件中的属性必须是当前查询对象的属性或单值对象属性或单值对象子属性
- 禁止使用filter语法
- 禁止使用has语法
- 语法定义：使用 lezer 定义了如下语法
< code >
@top Program { expression? }
@skip { spaces | newline | LineComment }
@precedence {
member,
and @left ,
or @left
}
kw< term > { @specialize [@name ={term}]< identifier , term > }
boolean { @specialize [@name =Boolean]< identifier , " true " | " false " > }
@skip {} {
String[isolate] {
'"' (stringContentDouble | Escape)* ('"' | "\n") |
"'" (stringContentSingle | Escape)* ("'" | "\n")
}
}
commaSep< content > {
content ("," content)*
}
List {
"[" commaSep< Value > ~destructure "]"
}
Value { String | Number | List | boolean }
Field { identifier ~arrow }
Member { Field !member "." (Member | Field) }
Input { "#" identifier ~arrow }
expression {
TupleExpression | BinaryExpression | NotExpression | ParenthesizedExpression | ListExpression
}
TupleExpression { TwoTupleExpression | ThreeTupleExpression }
TwoTupleExpression { (Field | Member) TwoOperator }
ThreeTupleExpression { (Field | Member) ThreeOperator (Input | Value) }
ListExpression { (Field | Member) ListOperator ParenthesizedExpression }
BinaryExpression {
expression !and (kw< 'AND'> | kw< 'and'>) expression |
expression !or (kw< 'OR'> | kw< 'or'>) expression
}
NotExpression { (kw< 'NOT'> | kw< 'not'>) ParenthesizedExpression }
ParenthesizedExpression { "(" expression ")" }
@tokens {
spaces[@export ] { $[\u0009 \u000b\u00a0\u1680\u2000-\u200a\u202f\u205f\u3000\ufeff]+ }
newline[@export ] { $[\r\n\u2028\u2029] }
identifierChar { @asciiLetter | $[_$\u{a1}-\u{10ffff}] }
word { identifierChar (identifierChar | @digit )* }
identifier { word }
hex { @digit | $[a-fA-F] }
stringContentSingle { ![\\\n']+ }
stringContentDouble { ![\\\n"]+ }
@precedence { spaces, newline, identifier }
Escape {
"\\" ("x" hex hex | "u" ("{" hex+ "}" | hex hex hex hex) | ![xu])
}
Number {
(@digit ("_" | @digit )* ("." ("_" | @digit )*)? | "." @digit ("_" | @digit )*)
(("e" | "E") ("+" | "-")? ("_" | @digit )+)? |
@digit ("_" | @digit )* "n" |
"0x" (hex | "_")+ "n"? |
"0b" $[01_]+ "n"? |
"0o" $[0-7_]+ "n"?
}
@precedence { Number "." }
ThreeOperator { "in" | "notIn" | "!=" | "==" | ">" | ">=" | "< " | "< =" | "isNullOrNot" | "like" | "has" }
TwoOperator { "isNull" | "isNotNull" }
ListOperator { "contains" | "filter" }
LineComment[isolate] { "//" ![\n]* }
"(" ")"
"[" "]"
"."
}
@detectDelim
< / code >
- **读方案设计元素的表达**
- 以json格式表达，
```json
{
"type":"object","description":"读方案定义",
"properties":{
"qto": {
"type":"object",
"properties":{
"name": {"type":"string","description":"读方案名称， ； ， ，
"uuid": {"type":"string","description":"读服务设计元素的uuid， ，
"woId": {"type":"string","description":"查询对象的uuid， ， ，
"description": {"type":"string","description":"描述读方案的功能，
"generateCountApi": {"type":"boolean", "description":"是否需要生成计数接口"},
"supportPaginate": {"type":"boolean", "description":"是否需要分页"},
"supportUnPage":{"type":"boolean", "description":"如果不需要分页， ，
"supportWaterfall":{"type":"boolean","description":"是否需要瀑布流"},
"query":{"type":"string","description":"查询语句，符合前述语法定义"},
"voOrDtoId":{"type":"string","description":"返回数据对象(VO或DTO)的uuid,创建的时候必须指定，更新的时候不传递"},
"outOrder":{"type":"array","description":"入参排序方式定义",
"items":{"type":"object","description":"定义字段排序方式","required":["fieldPath", "direction"],
"properties":{"fieldPath": {"type":"string","description":"字段名路径"},"direction": {"type":"string","description":"排序方向，
},
"defaultOrder": {"type":"array","description":"默认排序方式定义",
"items": {"type":"object","description":"定义字段排序方式","required":["fieldPath", "direction"],
"properties":{"fieldPath": {"type":"string","description":"字段名"},"direction": {"type":"string","description":"排序方向，
},
"filters": {"type": "array", "description":"过滤条件定义",
"items": {"type":"object","description":"定义过滤条件","required":["fieldPath", "filter"],
"properties":{
"fieldPath": {"type":"string","description":"需要过滤的列表字段路径"},
"filter": {"type":"object","description":"过滤语法，符合前述的语法定义,不能使用contains语法"}
}
}
},
"required":["name","description","query"]
}
},
"required":["qto"]
}
}
```
- **举例**
- 上下文
< code >
public class meeting_room {
storey storey; // 楼层对象
String name; // 名称
room_type_enum room_type; // 会议室类型
List< equipment_enum > equipment; // 设备列表
Long id; // 主键
Long seat_number; // 座位数
String description; // 说明
Boolean enable_indicator; // 是否启用
String input_code; // 输入码
Long storey_id; // 楼层id
Long contact_staff_id; // 联系员工ID
List< meeting > meeting; // 会议列表，可添加过滤条件
class storey { // 楼层
location location; // 位置对象
String name; // 楼层名
Long id; // 主键
Long sort_number; // 排序号
Long location_id; // 位置id
}
class meeting {
Long id; // 主键
String title; // 标题
Date start_time; // 开始时间
Date end_time; // 结束时间
Long room_id; // 会议室id
String description; // 描述
Long create_user_id; // 创建人id
}
class location { // 位置，如楼栋
String name; // 名称
Long id; // 主键
String description; // 描述
Long sort_number; // 排序号
}
enum room_type_enum {
SMALL, //小会议室
MEDIUM, //中会议室
LARGE
}
enum equipment_enum {
TV, //电视
WHITEBOARD, //白板
PROJECTOR, //投影仪
VIDEO
}
}
< / code >
- 用户需求
获取一段时间未使用的会议室(包含当前会议已选择的会议室)，根据会议标题过滤会议信息，分页返回。
- 读方案定义
< code >
{
"name": "get_unused_meeting_room_list",
"description": "获取未使用的会议室(包含当前会议已选择的会议室)",
"woId":"759bedd4-4540-4de6-b65d-d44912fb0991",
"dtoOrVoId":"e50c02c3-f336-4dc6-88e1-24ffe3dea1e2",
"generateCountApi": true,
"supportPaginate": true,
"supportUnPage": false,
"supportWaterfall": false,
"query": "enable_indicator == true AND ( id == #idIs OR meeting isNull OR NOT ( meeting contains ( start_time < = #meetingEndTime AND end_time >= #meetingStartTime ) ) )",
"filters": [
{
"fieldPath": "meeting",
"filter": "title like #meetingTitleLike "
}
]
}
< / code >
#### **2.10 查询传输对象(QTO)**
- **定义与用途:** QTO是读方案的查询参数结构。每个读方案对应一个QTO。调用方使用QTO结构传入查询字段值，
- **如何创建/生成:** 创建读方案后，
- **关键配置:** 名称（${ReadPlanNameQto}， ） ， （ ， ， ）
- **与API的关系:** QTO可作为API参数。API接收参数后直接透传给内部RPC调用。QTO只用于读操作参数，
#### **2.11 写方案 (WritePlan，
- **定义与用途：** 写方案是数据库写操作的唯一方式， ： ， ；
- **关键配置：** 名称(小写+下划线， ，
- CREATE：
- UPDATE：
- DELETE：
- CREATE_ON_DUPLICATE_UPDATE：
- FULL_MERGE： ， ，
- PARTIAL_MERGE： ，
- **与RPC关系： ， ， ，
- **生成RPC使用： ， ， ；
- **与聚合关系：** 每个聚合可定义多个写方案，但每个写方案只能操作一个聚合内的表。
- **创建方式：** 先选定聚合和要操作的实体，再确定每个实体的操作类型
- 提取需求中的更新需求，根据上下文构建写方案
- 输入备选聚合对象定义，每个聚合定义多个实体的嵌套关系
- 明确聚合内实体的父子层级关系
- 提取需求相关的变更名称和描述
- 选择最合适的聚合对象(最多只能选一个)
- 按对象粒度选出需变更对象
- 选定变更对象的字段(每个对象至少选一个字段，无法确定时默认选全部，字段必须明确指定名称)
- 为每个对象设置操作类型
- 列表属性可批量操作：
- 批量更新列表(FULL_MERGE/PARTIAL_MERGE)：需包含父对象
- 批量删除列表： ，
- 批量创建列表： ，
- 示例： < meeting_agenda > agendaList， ， ；
- FULL_MERGE和PARTIAL_MERGE只用于列表属性，
- UPDATE/DELETE/CREATE_ON_DUPLICATE_UPDATE/FULL_MERGE/PARTIAL_MERGE操作必须指定一个唯一键(包括主键)， ，
- 唯一键：实体中的唯一索引，由一个或多个字段组成
- 选定对象层级不能跳跃，发生不连续时去掉不连续的叶子对象
- 父对象和子对象操作类型限制：
- 父对象DELETE：
- 父对象CREATE：
- 父对象CREATE_ON_DUPLICATE_UPDATE：
- 父对象FULL_MERGE：
- 增量更新字段： ， ， ： ，
- **写方案设计元素表达：**
```json
{
"type":"object",
"description":"写方案定义",
"properties":{
"uuid":{"type":"string","description":"写方案唯一标识，创建时不传，更新时必传"},
"name":{"type":"string","description":"写方案名称，英文+下划线，
"description":{"type":"string","description":"写方案描述，
"bo": {"type":"string","description":"聚合根名称"},
"operations": {
"type":"array","description":"实体操作定义，包括操作类型和字段",
"items":{
"type": "object", "description":"具体实体操作定义",
"properties":{
"bo":{"type":"string","description":"操作的实体"},
"action":{"type":"string","description":"实体操作类型"},
"uniqueKey": {
"type":"array",
"description":"唯一键字段列表，用于确定数据记录",
"items":{"type":"string","description":"字段名称"}
},
"fields":{
"type":"array",
"items":{"type":"string","description":"字段名称，
"description":"操作字段列表"
},
"incrFields":{
"type":"array",
"items":{ "type":"string", "description":"增量字段名称"},
"description":"增量操作字段列表"
},
"required":["bo","action","fields"]
}
}
}
},
"required":["name","description","operations","bo"]
}
```
- **示例：**
- **上下文：**
```java
public class meeting {//会议聚合
//唯一键：(id)、(meeting_name)
Long id; //主键
String meeting_name; //会议名称
Date start_time; //开始时间
Date end_time;//结束时间
List< meeting_agenda > meetingAgendaList;
class meeting_agenda {
Long id;//主键
Date start_time;//开始时间
Date end_time;//结束时间
String title;//议程名称
List< agenda_vs_user > agendaVsUserList;
}
class agenda_vs_user {
Long id; //主键
Long user_id; //用户id
Long agenda_id; //议程id
Date enroll_time; //注册时间
Long meeting_id;//会议id
}
}
public class user {//用户聚合
//唯一键：(id)、(name,gender)
Long id;//主键
String name;//名字
GenderEnum gender;//性别
String nickname;//昵称
Long friend_count;//好友数量
}
```
- **需求：** 创建会议
- **对应写方案定义：**
```json
{
"name": "create_meeting",
"description": "创建会议",
"bo": "meeting",
"operations": [
{
"bo": "meeting",
"action": "CREATE",
"fields": [
"meeting_name",
"start_time",
"end_time"
]
}
]
}
```
#### **2.12 业务变更传输对象(BTO)**
- **定义与用途:** BTO是写方案自动生成的参数结构， ， ，
- **创建方式:** BTO只能由写方案自动创建， ，
- **关键配置:** 名称（${WritePlanName}Bto， ） ， ， ：
```java
class CreateUserBto { //对应实体user
Long id; //来自user.id
String name; //来自user.name
List< PictureBto > pictureList;
class PictureBto { //对应实体picture
String url; //来自picture.url
}
}
```
- **与API关系:** BTO可作API参数， ，
- **复杂场景处理:** 涉及多个写方案的复杂API可以：
a. 有主要写场景时， ， ，
b. 用基本类型参数或EO作参数， ，
c. 流程过于复杂时，
#### **2.13 服务层方法 (RPC)**
- **定义与用途:** TOCO中RPC是服务层方法。分两种： ；
- **创建/生成方式:** RPC有4种创建方式： ， ； ； ， ； ，
- **优先复用:** 用户需要创建RPC时， ，
- **自定义RPC和手写方法关系:** 两者都可手动实现服务层方法。区别： ；
- **关键配置:** 类名(驼峰， ， ， ，
2025-08-28 15:22:43 +08:00
- **TOCO中RPC存储:** RPC在TOCO中只存储方法签名，
2025-08-20 13:57:42 +08:00
- **参数类型:** RPC参数**只能**为QTO、BTO、Enum、基本类型， ，
- **返回值类型:** RPC返回值**只能**为DTO、Enum、基本类型， ，
- **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"
}
}
```
关键字段： ， ， ， ： ； ， ， ， ， ， < XxxDto > ； ； ， ， ， ； ， ； ， ， ，
#### **2.14 应用程序接口 (API)**
- **定义与用途:** API定义对外HTTP接口
- **创建方式:** 通过TOCO创建，
2025-08-28 15:22:43 +08:00
- **存储特点:** TOCO只存储URI和方法签名，
2025-08-20 13:57:42 +08:00
- **关键配置:** uri(/api/${moduleName}/xxx， ， ， ，
- **参数类型:** 只能为QTO、BTO、EO、Enum、基本类型，
- **返回值类型:** 脚手架自动包装返回值(code、message、data)。只能为VO、Enum、基本类型，
- **json结构:** 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"
}
}
```
关键字段： ， ： ； ， ， ， ， < XxxVo > )； ； ， ， ； ； ， ，
#### **2.15 流程服务（
2025-08-28 15:22:43 +08:00
- **定义与用途：** TOCO将复杂业务拆解为流程节点， ， ，
2025-08-20 13:57:42 +08:00
- **使用场景：**
- API/RPC涉及写服务超过3个时**必须**使用
- 用户要求使用时
- **节点封装：**
- 以数据内聚为首要考虑，一个节点围绕一个核心写服务，包含读服务、数据处理转换、附属功能。除条件节点、入参校验、数据返回节点外，每节点至少包含一个写服务。
- **配置：** 名称(小写字母+下划线)，拆解复杂业务逻辑。简单业务流程无需使用。
- **创建方式：**
- 流程非逻辑伪代码，不表达全部细节。相关内聚、相似功能封装到一个节点内。如用户注册：创建账号、用户信息、发送通知属于创建用户相关信息，无逻辑分叉，可内聚在一个节点。
- 节点间参数和返回值通过统一上下文Context传递(编码时按需修改Context文件添加字段)。
- 用JSON表达逻辑流。节点类型： ，
- 边定义：顺序节点多条入边多条出边(一条出边为下个执行节点，多条为并发执行分支)；
- 条件节点只封装判断逻辑， ； ， ； ，
- 终止流程：直接抛异常。
- 校验逻辑放在顺序节点中，失败则抛异常。
- 节点可复用，相同功能可抽取封装到一个节点。
- **表达方式：**
- JSON表达， ：
```json
{
"type": "object","description": "流程服务设计元素", "required": [ "description","name","nodes","edges"],
"properties":
{
"name": { "type": "string", "description": "流程名称， ， ，
"moduleName": {"type": "string", "description": "模块名称，创建时传入，指定所属模块"},
"uuid": {"type": "string", "description": "uuid， ，
"description": {"type": "string", "description": "流程服务描述，
"nodes": {
"type": "array", "description": "节点列表",
"items": {
"type": "object","description": "节点对象", "required": ["name", "type", "description"],
"properties": {
"name": {"type": "string", "description": "节点名称， ， ，
"type": {"type": "string", "description": "节点类型：
"description": {"type": "string", "description": "节点功能描述， ， ，
}
}
},
"edges": {
"type": "array", "description": "边列表",
"items": {
"type": "object","description": "边", "required": ["fromNode", "toNode"],
"properties": {
"fromNode": {"type": "string", "description": "起始节点名称"},
"toNode": {"type": "string", "description": "结束节点名称"},
"value": {"type": "boolean", "description": "可选， ： ， ； ： ，
}
}
}
}
}
```
- 示例：用户注册流程
```json-with-comments
{
"moduleName":"user", // 该流程所属的模块
"name":"user_register", // 定义功能
"description":"注册用户", // 详细功能描述
"nodes": [ // 包含节点
{
"name":"start",
"type":"START_NODE",
"description": "起始节点"
},
{
"name":"check_user_registed",
"type":"CONDITION_NODE",
"description":"校验入参合法性；判断昵称是否重名；判断用户是否已注册"
},
{
"name": "create_user",
"description":"创建用户，发送'用户创建'消息, 给用户发送欢迎通知",
"type": "PROCESS_NODE"
},
{
"name":"return_user_info",
"description":"返回用户信息，返回推荐给用户可能感兴趣的好友",
"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"
}
]
}
```
#### **2.16 自定义查询**
- 读方案无法满足需求时，使用自定义查询
- 自定义查询使用复杂sql实现业务功能
- 数据访问层使用MyBatis、MyBatisPlus实现
2025-08-28 15:22:43 +08:00
- 自定义查询时框架不自动生成代码(需要在coding阶段手动编写)
2025-08-20 13:57:42 +08:00
### 3. TOCO 最佳实践
#### 3.1 接口参数类型和返回值选择:
设计TOCO接口(API、RPC)时， ， ； ， ： ；
**重要说明：**
- 本节描述参数选择的**优先级原则**，非绝对限制
- API参数绝对限制见2.14章节
- "优先使用QTO/BTO"指在满足规范前提下，根据场景选择最合适的参数类型
#### 3.2 并发数据保护最佳实践:
处理先读后更新场景时， ， ： ， ， `update account set balance = balance - amount where user_id = xxx and balance > amount` 的where条件保护； ， ： `if(userBo.getBalance() >= 0)` 或通过userBo业务不变性（ ） `balance>=0` 校验。
-----------------------------------------------------------------------------
< / TOCO知识库 >
