当前位置： 首页 > news >正文

OneCode 3.0 @APIEventAnnotation 注解速查手册

news 2025/7/24 2:18:08

一、注解概述与基本信息

​

1.1 注解定义与核心功能

@APIEventAnnotation 是 OneCode 3.0 框架中用于声明 API 事件的核心注解，主要用于将前端 UI 事件与后端 API 服务进行绑定，实现 “事件驱动、数据绑定、响应处理” 的全链路交互机制。该注解通过元数据配置替代传统的命令式编程，大幅减少了前端 JavaScript 代码量，提高了开发效率和代码可维护性。

该注解的完整定义如下：

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface APIEventAnnotation {// 配置属性...
}

该注解主要应用于 Controller 类的方法上，用于定义该方法处理的 API 事件。

1.2 注解元数据信息

元数据项值说明
作用目标方法只能应用于 Controller 类的方法
生命周期运行时保留注解信息在运行时可用
继承性不继承子类不会继承父类的注解配置
核心功能事件绑定、数据映射、请求配置、响应处理实现前后端交互的全链路管理

二、属性详解与使用示例

2.1 基础配置属性

1. queryAsync
  • 类型：boolean
  • 默认值：true
  • 说明：设置是否异步执行 API 请求
  • 适用场景：
    • 需要保持 UI 响应性的场景（如表单提交、数据加载）
    • 非阻塞式操作（大多数情况推荐使用异步）
    • 当需要同步执行多个 API 请求时设置为 false

示例代码：

@APIEventAnnotation(queryAsync = false, // 同步执行请求// 其他配置...
)
public ResultModel handleSyncRequest() {// 业务逻辑
}
2. autoRun
  • 类型：boolean
  • 默认值：false
  • 说明：设置是否在页面加载完成后自动执行 API 请求
  • 适用场景：
    • 页面初始化时需要加载数据的场景
    • 不需要用户触发即可执行的初始化操作
    • 避免重复编写页面加载后的初始化代码

示例代码：

@APIEventAnnotation(autoRun = true, // 页面加载后自动执行// 其他配置...
)
public ResultModel loadInitialData() {// 加载初始数据的业务逻辑
}
3. autoDisplay
  • 类型：boolean
  • 默认值：false
  • 说明：设置是否自动显示 API 调用结果
  • 适用场景：
    • 简单数据展示场景（如单一值、简短文本）
    • 不需要复杂处理的 API 响应结果
    • 减少手动编写结果展示代码的工作量

示例代码：

@APIEventAnnotation(autoDisplay = true, // 自动显示结果// 其他配置...
)
public ResultModel showSimpleResult() {// 返回简单结果的业务逻辑
}
4. isAllform
  • 类型：boolean
  • 默认值：false
  • 说明：设置是否将表单所有字段作为请求参数
  • 适用场景：
    • 表单提交场景（特别是包含多个字段的表单）
    • 需要提交表单全部数据的情况
    • 减少逐个配置表单字段的工作量

示例代码：

@APIEventAnnotation(isAllform = true, // 提交表单所有字段// 其他配置...
)
public ResultModel submitFullFormData() {// 处理表单全部数据的业务逻辑
}
5. index
  • 类型：int
  • 默认值：-1
  • 说明：设置 API 事件的执行顺序（数值越小优先级越高）
  • 适用场景：
    • 多个 API 事件需要按特定顺序执行的场景
    • 需要控制事件执行顺序的复杂业务流程
    • 确保某些关键操作在其他操作之前或之后执行

示例代码：

@APIEventAnnotation(index = 10, // 执行顺序为第10位// 其他配置...
)
public ResultModel executeWithPriority() {// 具有特定执行顺序的业务逻辑
}

2.2 事件绑定属性

6. bindMenu
  • 类型：CustomMenuItem[]
  • 默认值：{}
  • 说明：绑定菜单项事件
  • 适用场景：
    • 菜单驱动的业务操作（如文件菜单中的 “保存”、“打开” 等）
    • 需要将菜单操作与特定 API 事件关联的场景
    • 实现菜单驱动的复杂业务流程

示例代码：

@APIEventAnnotation(bindMenu = {CustomMenuItem.SAVE, // 绑定"保存"菜单项CustomMenuItem.EXPORT // 绑定"导出"菜单项},// 其他配置...
)
public ResultModel handleMenuEvents() {// 处理菜单事件的业务逻辑
}
7. bindAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：绑定自定义动作事件
  • 适用场景：
    • 自定义按钮或操作触发的事件
    • 需要执行特定动作的业务场景
    • 实现自定义操作的灵活处理

示例代码：

@APIEventAnnotation(bindAction = {CustomAction.PREVIEW, // 绑定"预览"动作CustomAction.EDIT // 绑定"编辑"动作},// 其他配置...
)
public ResultModel handleCustomActions() {// 处理自定义动作的业务逻辑
}
8. enumClass
  • 类型：Class<? extends Enum>
  • 默认值：Enum.class
  • 说明：指定事件枚举类
  • 适用场景：
    • 自定义事件枚举类型
    • 需要使用特定枚举类的场景
    • 实现自定义事件类型的扩展

示例代码：

@APIEventAnnotation(enumClass = CustomEventType.class, // 指定自定义事件枚举类// 其他配置...
)
public ResultModel handleCustomEvents() {// 处理自定义事件的业务逻辑
}
9. bindFieldEvent
  • 类型：CustomFieldEvent[]
  • 默认值：{}
  • 说明：绑定表单字段事件
  • 适用场景：
    • 表单字段值变化触发的事件（如输入框内容变化）
    • 需要实时验证或处理字段值的场景
    • 实现表单字段级别的精细化控制

示例代码：

@APIEventAnnotation(bindFieldEvent = {CustomFieldEvent.CHANGE, // 绑定"变化"事件CustomFieldEvent.BLUR // 绑定"失去焦点"事件},// 其他配置...
)
public ResultModel handleFieldEvents() {// 处理表单字段事件的业务逻辑
}
10. bindGalleryEvent
  • 类型：CustomGalleryEvent[]
  • 默认值：{}
  • 说明：绑定图片画廊事件
  • 适用场景：
    • 图片画廊操作触发的事件（如选择图片、查看详情）
    • 需要处理图片相关操作的场景
    • 实现图片画廊的自定义交互

示例代码：

@APIEventAnnotation(bindGalleryEvent = {CustomGalleryEvent.SELECT_ITEM, // 绑定"选择项目"事件CustomGalleryEvent.VIEW_DETAIL // 绑定"查看详情"事件},// 其他配置...
)
public ResultModel handleGalleryEvents() {// 处理图片画廊事件的业务逻辑
}
11. bindTitleBlockEvent
  • 类型：CustomTitleBlockEvent[]
  • 默认值：{}
  • 说明：绑定标题块事件
  • 适用场景：
    • 标题块操作触发的事件（如全屏、折叠）
    • 需要处理标题块相关操作的场景
    • 实现标题块的自定义交互

示例代码：

@APIEventAnnotation(bindTitleBlockEvent = {CustomTitleBlockEvent.FULLSCREEN, // 绑定"全屏"事件CustomTitleBlockEvent.COLLAPSE // 绑定"折叠"事件},// 其他配置...
)
public ResultModel handleTitleBlockEvents() {// 处理标题块事件的业务逻辑
}
12. bindContentBlockEvent
  • 类型：CustomContentBlockEvent[]
  • 默认值：{}
  • 说明：绑定内容块事件
  • 适用场景：
    • 内容块操作触发的事件（如刷新、加载更多）
    • 需要处理内容块相关操作的场景
    • 实现内容块的自定义交互

示例代码：

@APIEventAnnotation(bindContentBlockEvent = {CustomContentBlockEvent.REFRESH, // 绑定"刷新"事件CustomContentBlockEvent.LOAD_MORE // 绑定"加载更多"事件},// 其他配置...
)
public ResultModel handleContentBlockEvents() {// 处理内容块事件的业务逻辑
}
13. bindGridEvent
  • 类型：CustomGridEvent[]
  • 默认值：{}
  • 说明：绑定表格事件
  • 适用场景：
    • 表格操作触发的事件（如加载、刷新、导出）
    • 需要处理表格相关操作的场景
    • 实现表格的自定义交互

示例代码：

@APIEventAnnotation(    bindGridEvent = {        CustomGridEvent.LOAD, // 绑定"加载"事件        CustomGridEvent.REFRESH, // 绑定"刷新"事件        CustomGridEvent.EXPORT // 绑定"导出"事件    },    // 其他配置...)public ResultModel handleGridEvents() {    // 处理表格事件的业务逻辑}
14. bindMGridEvent
  • 类型：CustomMGridEvent[]
  • 默认值：{}
  • 说明：绑定复杂表格事件
  • 适用场景：
    • 复杂表格操作触发的事件（如合并单元格、分组行）
    • 需要处理复杂表格相关操作的场景
    • 实现复杂表格的自定义交互

示例代码：

@APIEventAnnotation(bindMGridEvent = {CustomMGridEvent.MERGE_CELL, // 绑定"合并单元格"事件CustomMGridEvent.GROUP_ROW // 绑定"分组行"事件},// 其他配置...
)
public ResultModel handleMGridEvents() {// 处理复杂表格事件的业务逻辑
}
15. bindTreeEvent
  • 类型：CustomTreeEvent[]
  • 默认值：{}
  • 说明：绑定树形组件事件
  • 适用场景：
    • 树形组件操作触发的事件（如展开、选中、检查）
    • 需要处理树形结构相关操作的场景
    • 实现树形组件的自定义交互

示例代码：

@APIEventAnnotation(bindTreeEvent = {CustomTreeEvent.EXPAND, // 绑定"展开"事件CustomTreeEvent.SELECT, // 绑定"选择"事件CustomTreeEvent.CHECK // 绑定"检查"事件},// 其他配置...
)
public ResultModel handleTreeEvents() {// 处理树形组件事件的业务逻辑
}
16. bindFormEvent
  • 类型：CustomFormEvent[]
  • 默认值：{}
  • 说明：绑定表单事件
  • 适用场景：
    • 表单操作触发的事件（如保存、重置、搜索）
    • 需要处理表单相关操作的场景
    • 实现表单的自定义交互

示例代码：

@APIEventAnnotation(bindFormEvent = {CustomFormEvent.SAVE, // 绑定"保存"事件CustomFormEvent.RESET, // 绑定"重置"事件CustomFormEvent.SEARCH // 绑定"搜索"事件},// 其他配置...
)
public ResultModel handleFormEvents() {// 处理表单事件的业务逻辑
}
17. bindMFormEvent
  • 类型：CustomMFormEvent[]
  • 默认值：{}
  • 说明：绑定多表表单事件
  • 适用场景：
    • 多表表单操作触发的事件（如添加行、删除行）
    • 需要处理多表表单相关操作的场景
    • 实现多表表单的自定义交互

示例代码：

@APIEventAnnotation(bindMFormEvent = {CustomMFormEvent.ADD_ROW, // 绑定"添加行"事件CustomMFormEvent.DELETE_ROW // 绑定"删除行"事件},// 其他配置...
)
public ResultModel handleMFormEvents() {// 处理多表表单事件的业务逻辑
}
18. bindTabsEvent
  • 类型：CustomTabsEvent[]
  • 默认值：{}
  • 说明：绑定标签页事件
  • 适用场景：
    • 标签页操作触发的事件（如切换、关闭）
    • 需要处理标签页相关操作的场景
    • 实现标签页的自定义交互

示例代码：

@APIEventAnnotation(bindTabsEvent = {CustomTabsEvent.SWITCH, // 绑定"切换"事件CustomTabsEvent.CLOSE // 绑定"关闭"事件},// 其他配置...
)
public ResultModel handleTabsEvents() {// 处理标签页事件的业务逻辑
}
19. bindHotKeyEvent
  • 类型：CustomHotKeyEvent[]
  • 默认值：{}
  • 说明：绑定快捷键事件
  • 适用场景：
    • 快捷键操作触发的事件（如 Ctrl+S、ESC）
    • 需要处理快捷键相关操作的场景
    • 实现全局快捷键的自定义交互

示例代码：

@APIEventAnnotation(bindHotKeyEvent = {CustomHotKeyEvent.CTRL_S, // 绑定"Ctrl+S"快捷键CustomHotKeyEvent.ESC // 绑定"ESC"键},// 其他配置...
)
public ResultModel handleHotKeyEvents() {// 处理快捷键事件的业务逻辑
}

2.3 数据映射属性

20. requestDataSource
  • 类型：RequestPathAnnotation[]
  • 默认值：{}
  • 说明：配置请求数据源
  • 适用场景：
    • 需要从特定数据源获取请求参数的场景
    • 实现表单数据、组件数据到请求参数的映射
    • 减少手动编写数据提取代码的工作量

示例代码：

@APIEventAnnotation(requestDataSource = {@RequestPathAnnotation(type = "form", name = "userForm", path = "id"), // 从表单获取ID@RequestPathAnnotation(type = "component", name = "deptTree", path = "selectedId") // 从组件获取选中ID},// 其他配置...
)
public ResultModel handleDataSources() {// 处理数据源的业务逻辑
}
21. responseDataTarget
  • 类型：ResponsePathAnnotation[]
  • 默认值：{}
  • 说明：配置响应数据目标
  • 适用场景：
    • 需要将响应数据映射到特定目标的场景
    • 实现响应数据到表单、组件的自动填充
    • 减少手动编写数据填充代码的工作量

示例代码：

@APIEventAnnotation(responseDataTarget = {@ResponsePathAnnotation(type = "form", name = "userForm", path = "lastUpdateTime") // 将响应数据映射到表单的lastUpdateTime字段},// 其他配置...
)
public ResultModel handleResponseTargets() {// 处理响应目标的业务逻辑
}
22. responseCallback
  • 类型：CallBackPathAnnotation[]
  • 默认值：{}
  • 说明：配置回调路径
  • 适用场景：
    • 需要在 API 调用完成后执行回调的场景
    • 实现复杂的回调逻辑（如更新多个组件状态）
    • 减少手动编写回调代码的工作量

示例代码：

@APIEventAnnotation(responseCallback = {@CallBackPathAnnotation(name = "updateStatus", params = {"{{response.status}}") // 回调函数，参数为响应中的status},// 其他配置...
)
public ResultModel handleCallbacks() {// 处理回调的业务逻辑
}
23. customRequestData
  • 类型：RequestPathEnum[]
  • 默认值：{}
  • 说明：配置常用请求数据
  • 适用场景：
    • 需要使用常用请求数据的场景
    • 实现预定义的请求数据映射（如表单 ID、全局用户信息）
    • 减少重复配置的工作量

示例代码：

@APIEventAnnotation(customRequestData = {RequestPathEnum.FORM_ID, // 表单IDRequestPathEnum.GLOBAL_USER_INFO // 全局用户信息},// 其他配置...
)
public ResultModel handleCustomRequests() {// 处理自定义请求数据的业务逻辑
}
24. customResponseData
  • 类型：ResponsePathEnum[]
  • 默认值：{}
  • 说明：配置常用响应数据
  • 适用场景：
    • 需要使用常用响应数据的场景
    • 实现预定义的响应数据映射（如表单重置、消息提示）
    • 减少重复配置的工作量

示例代码：

@APIEventAnnotation(customResponseData = {ResponsePathEnum.FORM_RESET, // 表单重置ResponsePathEnum.MESSAGE_TIP // 消息提示},// 其他配置...
)
public ResultModel handleCustomResponses() {// 处理自定义响应数据的业务逻辑
}
25. customResponseCallback
  • 类型：CallBackPathEnum[]
  • 默认值：{}
  • 说明：配置常用回调路径
  • 适用场景：
    • 需要使用常用回调路径的场景
    • 实现预定义的回调路径映射
    • 减少重复配置的工作量

示例代码：

@APIEventAnnotation(customResponseCallback = {CallBackPathEnum.UPDATE_STATUS // 更新状态回调},// 其他配置...
)
public ResultModel handleCustomCallbacks() {// 处理自定义回调的业务逻辑
}

2.4 生命周期回调属性

26. beforeData
  • 类型：CustomBeforData[]
  • 默认值：{}
  • 说明：数据准备前的回调
  • 适用场景：
    • 需要在准备请求数据前执行的操作
    • 实现数据预处理逻辑（如数据校验、格式转换）
    • 确保请求数据符合要求

示例代码：

@APIEventAnnotation(beforeData = {CustomBeforData.MESSAGE // 数据准备前的提示},// 其他配置...
)
public ResultModel handleBeforeData() {// 处理数据准备前逻辑的业务逻辑
}
27. beforeDataAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：数据准备前的动作
  • 适用场景：
    • 需要在数据准备前执行特定动作的场景
    • 实现复杂的数据准备逻辑（如多个步骤的预处理）
    • 减少重复编写预处理代码的工作量

示例代码：

@APIEventAnnotation(beforeDataAction = {@CustomAction(name = "validateForm") // 表单验证动作},// 其他配置...
)
public ResultModel handleBeforeDataActions() {// 处理数据准备前动作的业务逻辑
}@APIEventAnnotation(beforeInvoke = {@CustomBeforInvoke(message = "正在发送请求...") // 请求发送前的提示},// 其他配置...
)
public ResultModel handleBeforeInvoke() {// 处理请求发送前逻辑的业务逻辑
}
28. beforeInvoke
  • 类型：CustomBeforInvoke[]
  • 默认值：{}
  • 说明：请求发送前的回调
  • 适用场景：
    • 需要在发送请求前执行的操作
    • 实现请求前的最后检查（如权限验证）
    • 确保请求符合要求

示例代码：

@APIEventAnnotation(beforeInvoke = {CustomBeforInvoke.MESSAGE // 请求发送前的提示},// 其他配置...
)
public ResultModel handleBeforeInvoke() {// 处理请求发送前逻辑的业务逻辑
}
29. beforeInvokeAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：请求发送前的动作
  • 适用场景：
    • 需要在请求发送前执行特定动作的场景
    • 实现复杂的请求前逻辑（如显示加载动画）
    • 减少重复编写请求前代码的工作量

示例代码：

@APIEventAnnotation(beforeInvokeAction = {CustomBeforInvoke.BUSY // 增加遮罩},// 其他配置...
)
public ResultModel handleBeforeInvokeActions() {// 处理请求发送前动作的业务逻辑
}
30. callback
  • 类型：CustomCallBack[]
  • 默认值：{}
  • 说明：响应处理后的回调
  • 适用场景：
    • 需要在响应处理后执行的操作
    • 实现响应后的通用处理逻辑（如关闭对话框）
    • 减少重复编写响应处理代码的工作量

示例代码：

@APIEventAnnotation(callback = {@CustomCallBack(message = "响应处理完成") // 响应处理后的提示},// 其他配置...
)
public ResultModel handleCallbacks() {// 处理响应回调的业务逻辑
}
31. callbackAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：响应处理后的动作
  • 适用场景：
    • 需要在响应处理后执行特定动作的场景
    • 实现复杂的响应后逻辑（如刷新表格、重置表单）
    • 减少重复编写响应后代码的工作量

示例代码：

@APIEventAnnotation(callbackAction = {@CustomAction(name = "refreshGrid"), // 刷新表格动作@CustomAction(name = "resetForm") // 重置表单动作},// 其他配置...
)
public ResultModel handleCallbackActions() {// 处理响应后动作的业务逻辑
}
32. afterInvok
  • 类型：CustomCallBack[]
  • 默认值：{}
  • 说明：请求完成后的回调
  • 适用场景：
    • 需要在请求完成后执行的操作
    • 实现请求完成后的最终处理（如释放资源）
    • 确保无论成功与否都执行的逻辑

示例代码：

@APIEventAnnotation(afterInvok = {CustomCallBack.FREE // 解除遮罩},// 其他配置...
)
public ResultModel handleAfterInvok() {// 处理请求完成后逻辑的业务逻辑
}
33. afterInvokAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：请求完成后的动作
  • 适用场景：
    • 需要在请求完成后执行特定动作的场景
    • 实现复杂的请求完成后逻辑（如清理临时数据）
    • 减少重复编写请求完成后代码的工作量

示例代码：

@APIEventAnnotation(afterInvokAction = {@CustomAction(name = "cleanup") // 清理动作},// 其他配置...
)
public ResultModel handleAfterInvokActions() {// 处理请求完成后动作的业务逻辑
}
34. onError
  • 类型：CustomOnError[]
  • 默认值：{}
  • 说明：请求出错时的回调
  • 适用场景：
    • 需要处理请求错误的场景
    • 实现错误处理逻辑（如显示错误信息）
    • 确保错误情况得到妥善处理

示例代码：

@APIEventAnnotation(onError = {CustomOnError.MESSAGE// 请求出错时的提示},// 其他配置...
)
public ResultModel handleOnError() {// 处理请求错误逻辑的业务逻辑
}
35. onErrorAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：请求出错时的动作
  • 适用场景：
    • 需要在请求出错时执行特定动作的场景
    • 实现复杂的错误处理逻辑（如隐藏加载动画、显示错误信息）
    • 减少重复编写错误处理代码的工作量

示例代码：

@APIEventAnnotation(onErrorAction = {@CustomAction(name = "hideLoading"), // 隐藏加载动画动作@CustomAction(name = "showError") // 显示错误信息动作},// 其他配置...
)
public ResultModel handleOnErrorActions() {// 处理请求出错动作的业务逻辑
}
36. onData
  • 类型：CustomOnData[]
  • 默认值：{}
  • 说明：接收到数据时的回调
  • 适用场景：
    • 需要在接收到数据时执行的操作
    • 实现数据处理逻辑（如数据转换、过滤）
    • 确保数据在处理前符合要求

示例代码：

@APIEventAnnotation(onData = {CustomOnData.RELOAD// 接收到数据时的提示},// 其他配置...
)
public ResultModel handleOnData() {// 处理接收到数据逻辑的业务逻辑
}
37. onDataAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：接收到数据时的动作
  • 适用场景：
    • 需要在接收到数据时执行特定动作的场景
    • 实现复杂的数据处理逻辑（如数据格式化、存储）
    • 减少重复编写数据处理代码的工作量

示例代码：

@APIEventAnnotation(onDataAction = {@CustomAction(name = "processData") // 处理数据动作},// 其他配置...
)
public ResultModel handleOnDataActions() {// 处理接收到数据动作的业务逻辑
}
38. onExecuteSuccess
  • 类型：CustomOnExecueSuccess[]
  • 默认值：{}
  • 说明：请求执行成功时的回调
  • 适用场景：
    • 需要处理请求成功的场景
    • 实现成功处理逻辑（如显示成功信息）
    • 确保成功情况得到妥善处理

示例代码：

@APIEventAnnotation(onExecuteSuccess = {CustomOnExecueSuccess.MSG// 请求成功时的提示},// 其他配置...
)
public ResultModel handleOnExecuteSuccess() {// 处理请求成功逻辑的业务逻辑
}
39. onExecuteSuccessAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：请求执行成功时的动作
  • 适用场景：
    • 需要在请求成功时执行特定动作的场景
    • 实现复杂的成功处理逻辑（如刷新页面、跳转页面）
    • 减少重复编写成功处理代码的工作量

示例代码：

@APIEventAnnotation(onExecuteSuccessAction = {@CustomAction(name = "refreshPage"), // 刷新页面动作@CustomAction(name = "redirectToSuccessPage") // 跳转到成功页面动作},// 其他配置...
)
public ResultModel handleOnExecuteSuccessActions() {// 处理请求成功动作的业务逻辑
}
40. onExecuteError
  • 类型：CustomOnExecueError[]
  • 默认值：{}
  • 说明：请求执行失败时的回调
  • 适用场景：
    • 需要处理请求失败的场景
    • 实现失败处理逻辑（如显示失败原因）
    • 确保失败情况得到妥善处理

示例代码：

@APIEventAnnotation(onExecuteError = {CustomOnExecueError.FREE // 解除遮罩},// 其他配置...
)
public ResultModel handleOnExecuteError() {// 处理请求失败逻辑的业务逻辑
}
41. onExecuteErrorAction
  • 类型：CustomAction[]
  • 默认值：{}
  • 说明：请求执行失败时的动作
  • 适用场景：
    • 需要在请求失败时执行特定动作的场景
    • 实现复杂的失败处理逻辑（如记录错误日志、重试请求）
    • 减少重复编写失败处理代码的工作量

示例代码：

@APIEventAnnotation(onExecuteError = {@CustomAction(name = "reloadPage", method = "call", type = ActionTypeEnum.other, target = "callback", args = {"{SPA.reloadPage()}"}),},// 其他配置...
)
public ResultModel handleOnExecuteError() {// 处理请求失败逻辑的业务逻辑
}

三、核心事件枚举详解

3.1 表单相关事件

表单事件（CustomFormEvent）
事件名称描述触发时机
SAVE保存事件用户点击保存按钮或执行保存操作时触发
RESET重置事件用户点击重置按钮或执行重置操作时触发
SEARCH搜索事件用户点击搜索按钮或执行搜索操作时触发
CANCEL取消事件用户点击取消按钮或执行取消操作时触发
SUBMIT提交事件用户提交表单时触发
VALIDATE验证事件表单验证时触发

示例代码：

@APIEventAnnotation(bindFormEvent = {CustomFormEvent.SAVE, // 绑定保存事件CustomFormEvent.SEARCH // 绑定搜索事件},// 其他配置...
)
public ResultModel handleFormEvents() {// 处理表单事件的业务逻辑
}
多表表单事件（CustomMFormEvent）
事件名称描述触发时机
ADD_ROW添加行事件用户点击添加行按钮或执行添加行操作时触发
DELETE_ROW删除行事件用户点击删除行按钮或执行删除行操作时触发
EDIT_ROW编辑行事件用户点击编辑行按钮或执行编辑行操作时触发
BATCH_PROCESS批量处理事件用户执行批量处理操作时触发

示例代码：

@APIEventAnnotation(bindMFormEvent = {CustomMFormEvent.ADD_ROW, // 绑定添加行事件CustomMFormEvent.DELETE_ROW // 绑定删除行事件},// 其他配置...
)
public ResultModel handleMFormEvents() {// 处理多表表单事件的业务逻辑
}
字段事件（CustomFieldEvent）
事件名称描述触发时机
CHANGE变化事件字段值发生变化时触发
BLUR失去焦点事件字段失去焦点时触发
FOCUS获得焦点事件字段获得焦点时触发
VALIDATE验证事件字段验证时触发

示例代码：

@APIEventAnnotation(bindFieldEvent = {CustomFieldEvent.CHANGE, // 绑定变化事件CustomFieldEvent.BLUR // 绑定失去焦点事件},// 其他配置...
)
public ResultModel handleFieldEvents() {// 处理字段事件的业务逻辑
}

3.2 数据展示相关事件

表格事件（CustomGridEvent）
事件名称描述触发时机
LOAD加载事件表格加载数据时触发
REFRESH刷新事件表格刷新数据时触发
EXPORT导出事件用户点击导出按钮或执行导出操作时触发
SELECT选择事件用户选择表格行时触发
DESELECT取消选择事件用户取消选择表格行时触发
PAGE_CHANGE分页变化事件表格分页变化时触发

示例代码：

@APIEventAnnotation(bindGridEvent = {CustomGridEvent.LOAD, // 绑定加载事件CustomGridEvent.REFRESH // 绑定刷新事件},// 其他配置...
)
public ResultModel handleGridEvents() {// 处理表格事件的业务逻辑
}
复杂表格事件（CustomMGridEvent）
事件名称描述触发时机
MERGE_CELL合并单元格事件合并表格单元格时触发
GROUP_ROW分组行事件分组表格行时触发
UNGROUP_ROW取消分组行事件取消分组表格行时触发
SORT排序事件表格排序时触发
FILTER过滤事件表格过滤时触发

示例代码：

@APIEventAnnotation(bindTreeEvent = {CustomTreeEvent.EXPAND, // 绑定展开事件CustomTreeEvent.SELECT // 绑定选择事件},// 其他配置...
)
public ResultModel handleTreeEvents() {// 处理树形组件事件的业务逻辑
}
树形组件事件（CustomTreeEvent）
事件名称描述触发时机
EXPAND展开事件树形节点展开时触发
COLLAPSE折叠事件树形节点折叠时触发
SELECT选择事件用户选择树形节点时触发
DESELECT取消选择事件用户取消选择树形节点时触发
CHECK选中事件用户选中树形节点时触发
UNCHECK取消选中事件用户取消选中树形节点时触发

示例代码：

@APIEventAnnotation(bindTreeEvent = {CustomTreeEvent.EXPAND, // 绑定展开事件CustomTreeEvent.SELECT // 绑定选择事件},// 其他配置...
)
public ResultModel handleTreeEvents() {// 处理树形组件事件的业务逻辑
}
标签页事件（CustomTabsEvent）
事件名称描述触发时机
SWITCH切换事件标签页切换时触发
CLOSE关闭事件标签页关闭时触发
ADD添加事件添加新标签页时触发
REMOVE删除事件删除标签页时触发

示例代码：

@APIEventAnnotation(bindTabsEvent = {CustomTabsEvent.SWITCH, // 绑定切换事件CustomTabsEvent.CLOSE // 绑定关闭事件},// 其他配置...
)
public ResultModel handleTabsEvents() {// 处理标签页事件的业务逻辑
}

3.3 其他常用事件

快捷键事件（CustomHotKeyEvent）
事件名称描述触发时机
CTRL_SCtrl+S 事件用户按下 Ctrl+S 组合键时触发
CTRL_OCtrl+O 事件用户按下 Ctrl+O 组合键时触发
CTRL_PCtrl+P 事件用户按下 Ctrl+P 组合键时触发
ESCESC 事件用户按下 ESC 键时触发
ENTEREnter 事件用户按下 Enter 键时触发

示例代码：

@APIEventAnnotation(bindHotKeyEvent = {CustomHotKeyEvent.CTRL_S, // 绑定Ctrl+S事件CustomHotKeyEvent.ESC // 绑定ESC事件},// 其他配置...
)
public ResultModel handleHotKeyEvents() {// 处理快捷键事件的业务逻辑
}
标题块事件（CustomTitleBlockEvent）
事件名称描述触发时机
FULLSCREEN全屏事件用户点击全屏按钮或执行全屏操作时触发
COLLAPSE折叠事件用户点击折叠按钮或执行折叠操作时触发
EXPAND展开事件用户点击展开按钮或执行展开操作时触发
CLOSE关闭事件用户点击关闭按钮或执行关闭操作时触发

示例代码：

@APIEventAnnotation(bindTitleBlockEvent = {CustomTitleBlockEvent.FULLSCREEN, // 绑定全屏事件CustomTitleBlockEvent.COLLAPSE // 绑定折叠事件},// 其他配置...
)
public ResultModel handleTitleBlockEvents() {// 处理标题块事件的业务逻辑
}
内容块事件（CustomContentBlockEvent）
事件名称描述触发时机
REFRESH刷新事件用户点击刷新按钮或执行刷新操作时触发
LOAD_MORE加载更多事件用户点击加载更多按钮或执行加载更多操作时触发
COLLAPSE折叠事件用户点击折叠按钮或执行折叠操作时触发
EXPAND展开事件用户点击展开按钮或执行展开操作时触发

示例代码：

@APIEventAnnotation(bindContentBlockEvent = {CustomContentBlockEvent.REFRESH, // 绑定刷新事件CustomContentBlockEvent.LOAD_MORE // 绑定加载更多事件},// 其他配置...
)
public ResultModel handleContentBlockEvents() {// 处理内容块事件的业务逻辑
}

四、完整使用示例

4.1 表单提交场景示例

@Controller
@RequestMapping("/api/user")
public class UserController {@PostMapping("/save")@ResponseBody@APIEventAnnotation(// 事件绑定bindFormEvent = CustomFormEvent.SAVE, // 绑定表单保存事件bindHotKeyEvent = CustomHotKeyEvent.CTRL_S, // 绑定Ctrl+S快捷键// 请求数据源requestDataSource = {@RequestPathAnnotation(type = "form", name = "userForm", path = "id"), // 从表单获取ID@RequestPathAnnotation(type = "form", name = "userForm", path = "name"), // 从表单获取姓名@RequestPathAnnotation(type = "form", name = "userForm", path = "email") // 从表单获取邮箱},// 响应数据目标responseDataTarget = {@ResponsePathAnnotation(type = "form", name = "userForm", path = "lastUpdateTime") // 将响应数据映射到表单的lastUpdateTime字段},// 生命周期回调beforeInvoke = @CustomBeforInvoke.MESSAGE, // 请求发送前的提示onExecuteSuccess = @CustomOnExecueSuccess.MESSAGE, // 请求成功时的提示onExecuteError = @CustomOnExecueError.MESSAGE// 请求失败时的提示)public ResultModel<User> saveUser(@RequestBody User user) {// 业务逻辑实现User savedUser = userService.save(user);return ResultModel.success(savedUser);}
}

4.2 数据加载与分页场景示例

@Controller
@RequestMapping("/api/data")
public class DataController {@GetMapping("/list")@ResponseBody@APIEventAnnotation(// 事件绑定bindGridEvent = CustomGridEvent.LOAD, // 绑定表格加载事件autoRun = true, // 页面加载后自动执行// 请求数据源requestDataSource = {@RequestPathAnnotation(type = "component", name = "pageSize", path = "value"), // 从组件获取分页大小@RequestPathAnnotation(type = "component", name = "currentPage", path = "value") // 从组件获取当前页码},// 响应数据目标responseDataTarget = {@ResponsePathAnnotation(type = "grid", name = "dataGrid", path = "data") // 将响应数据映射到表格的数据字段},// 生命周期回调beforeInvoke = @CustomBeforInvoke.MESSAGE, // 请求发送前的提示onExecuteSuccess = @CustomOnExecueSuccess.MESSAGE, // 请求成功时的提示onExecuteError = @CustomOnExecueError.MESSAGE// 请求失败时的提示    )public ResultModel<Page<Data>> loadData(@RequestParam Integer pageSize, @RequestParam Integer currentPage) {// 业务逻辑实现Page<Data> dataPage = dataService.findPage(pageSize, currentPage);return ResultModel.success(dataPage);}
}

4.3 树形组件操作场景示例

@Controller
@RequestMapping("/api/tree")
public class TreeController {@GetMapping("/nodes")@ResponseBody@APIEventAnnotation(// 事件绑定bindTreeEvent = CustomTreeEvent.EXPAND, // 绑定树形节点展开事件// 请求数据源requestDataSource = {@RequestPathAnnotation(type = "tree", name = "treeComponent", path = "selectedId") // 从树形组件获取选中节点ID},// 响应数据目标responseDataTarget = {@ResponsePathAnnotation(type = "tree", name = "treeComponent", path = "children") // 将响应数据映射到树形组件的子节点字段},// 生命周期回调beforeInvoke = @CustomBeforInvoke.MESSAGE, // 请求发送前的提示onExecuteSuccess = @CustomOnExecueSuccess.MESSAGE, // 请求成功时的提示onExecuteError = @CustomOnExecueError.MESSAGE// 请求失败时的提示    ))public ResultModel<List<TreeNode>> loadTreeNodes(@RequestParam String parentId) {// 业务逻辑实现List<TreeNode> nodes = treeService.findChildren(parentId);return ResultModel.success(nodes);}
}

五、最佳实践与注意事项

5.1 事件绑定最佳实践

  1. 单一职责原则：每个 API 事件注解应专注于处理单一类型的事件或功能，避免绑定过多不相关的事件
  2. 合理选择事件类型：根据业务场景选择最合适的事件类型（如表单事件、表格事件等），避免使用通用事件代替特定事件
  3. 事件优先级设置：对于需要按特定顺序执行的多个 API 事件，通过index属性设置合理的执行顺序
  4. 事件解耦：避免在一个 API 事件中处理过多的业务逻辑，应将复杂业务逻辑分解为多个独立的 API 事件
  5. 事件命名规范：遵循统一的事件命名规范，提高代码可读性和可维护性

5.2 数据映射最佳实践

  1. 精简数据映射：只映射必要的数据字段，避免映射过多无关数据
  2. 数据验证前置：在数据映射前进行必要的验证，确保数据的有效性和完整性
  3. 数据转换处理：对于需要转换的数据（如日期格式转换），使用beforeData或onData回调进行处理
  4. 统一数据格式：保持前后端数据格式的一致性，减少数据转换的复杂度
  5. 敏感数据处理：对于敏感数据（如密码），应进行适当的加密或脱敏处理

5.3 生命周期回调最佳实践

  1. 清晰的回调逻辑：每个回调函数应具有明确的职责，避免逻辑混乱
  2. 错误处理全面：在onExecuteError和onError回调中处理所有可能的错误情况
  3. 资源清理：在afterInvok或afterInvokAction中释放所有占用的资源
  4. 用户反馈：在适当的回调中提供友好的用户反馈（如提示信息、加载状态）
  5. 避免阻塞操作：在回调函数中避免执行耗时的阻塞操作，以免影响用户体验

5.4 使用注意事项

  1. 注解作用域：@APIEventAnnotation 只能应用于 Controller 类的方法上，不能应用于类或其他类型的方法
  2. 事件重复绑定：避免在同一个方法上重复绑定相同的事件，否则可能导致不可预期的行为
  3. 数据映射冲突：注意避免数据映射路径冲突，确保每个数据字段有唯一的映射路径
  4. 异步执行注意事项：当queryAsync设置为true时，需注意异步执行可能带来的线程安全问题
  5. 异常处理：在 API 方法中必须处理所有可能抛出的异常，确保返回统一的 ResultModel 格式

5.5 常用动作枚举类

以下是一些常用的动作枚举类及其说明：

ActionTypeEnum
  • 描述：基本动作类型枚举
  • 核心值：
    • SAVE: 保存操作
    • DELETE: 删除操作
    • UPDATE: 更新操作
    • QUERY: 查询操作
    • EXPORT: 导出操作
ButtonActionEnum
  • 描述：按钮动作枚举
  • 核心值：
    • SUBMIT: 提交按钮
    • CANCEL: 取消按钮
    • RESET: 重置按钮
    • CONFIRM: 确认按钮
    • CLOSE: 关闭按钮
MenuActionEnum
  • 描述：菜单动作枚举
  • 核心值：
    • NEW: 新建菜单
    • OPEN: 打开菜单
    • SAVE: 保存菜单
    • DELETE: 删除菜单
    • EXPORT: 导出菜单
    • IMPORT: 导入菜单
TreeActionEnum
  • 描述：树形组件动作枚举
  • 核心值：
    • EXPAND_ALL: 全部展开
    • COLLAPSE_ALL: 全部折叠
    • ADD_NODE: 添加节点
    • DELETE_NODE: 删除节点
    • EDIT_NODE: 编辑节点
    • MOVE_NODE: 移动节点

这些动作枚举类可以与@APIEventAnnotation结合使用，实现更丰富的事件处理逻辑。例如：

@APIEventAnnotation(bindFormEvent = CustomFormEvent.SUBMIT,requestDataSource = "approvalDataSource",onExecuteSuccessAction = {@CustomAction(actionType = ActionTypeEnum.SAVE,params = {"status", "approved"})}
)
public class ApprovalSubmitEvent {// 事件处理逻辑
}

六、子注解详解

6.1 RequestPathAnnotation

  • 描述：请求路径注解，定义从前端组件到 API 参数的数据映射
  • 属性：
    • type: 组件类型（如 “form”, “grid”, “tree”）
    • name: 组件名称
    • path: 数据路径
    • paramName: 参数名称（可选，默认使用 path）
    • converter: 转换器类名（可选）
  • 示例：@RequestPathAnnotation(
    type = “form”,
    name = “mainForm”,
    path = “id”,
    converter = “EncryptConverter”
    )

6.2 ResponsePathAnnotation

  • 描述：响应路径注解，定义从 API 响应到前端组件的数据映射
  • 属性：
    • type: 组件类型
    • name: 组件名称
    • path: 数据路径
    • updateStrategy: 更新策略（如 UpdateStrategy.INCREMENT 增量更新）
  • 示例：@ResponsePathAnnotation(
    type = “grid”,
    name = “userGrid”,
    path = “rows”,
    updateStrategy = UpdateStrategy.INCREMENT
    )

6.3 AIGCAnnotation

  • 描述：AI 增强注解，配置 AI 辅助处理的相关参数
  • 属性：
    • prompt: AI 提示语
    • model: AI 模型名称
    • cacheable: 是否缓存结果
    • temperature: 生成温度
  • 示例：@AIGCAnnotation(
    prompt = “优化查询参数: {{requestParams}}”,
    model = “gpt-4”,
    cacheable = true
    )

6.4 CustomAction

  • 描述：自定义动作注解，定义要执行的动作
  • 属性：
    • name: 动作名称
    • params: 动作参数
    • async: 是否异步执行
  • 示例：@CustomAction(
    name = “refreshGrid”,
    params = {“{{response.data.gridId}}”},
    async = true
    )

七、总结

@APIEventAnnotation 是 OneCode 3.0 框架中实现前后端交互的核心注解，通过该注解可以轻松实现事件绑定、数据映射和请求生命周期管理等功能。本手册详细介绍了 @APIEventAnnotation 的所有属性、核心事件枚举以及使用示例，希望能帮助开发者更高效地使用 OneCode 3.0 框架进行企业级应用开发。

通过合理使用 @APIEventAnnotation，开发者可以将传统开发中大量的样板代码和配置工作简化为简洁的注解声明，从而更专注于业务逻辑的实现，提高开发效率和代码质量。在实际开发中，应根据具体业务场景选择合适的属性和事件，遵循最佳实践，以充分发挥 OneCode 3.0 框架的强大功能。

http://www.dtcms.com/a/291415.html

相关文章：

  • 从 Hi3861 平台到 WS63 星闪平台的程序移植全解析
  • 网络编程之 UDP：用户数据报协议详解与实战
  • 二分查找：区间内查询数字的频率
  • 网络协议（三）网络层 IPv4、CIDR（使用子网掩码进行网络划分）、NAT在私网划分中的应用
  • 大模型——上下文工程 (Context Engineering) – 现代 AI 系统的架构基础
  • c语言进阶 自定义类型 枚举，联合
  • 【LeetCode 热题 100】208. 实现 Trie (前缀树)
  • Linux下SPI设备驱动开发
  • 1.Java中的异常有哪些？异常处理机制呢？
  • C# 异常处理
  • 统计与大数据分析专业转型金融行业指南
  • makefile-- 其他函数
  • Linux PCI总线子系统
  • 网络基础DAY15-RSTP
  • OpenGL鼠标控制沿着指定轴旋转
  • linux --frp内网穿透
  • 低速信号设计之 RMII
  • 服务器系统时间不准确怎么办？
  • C++ 中的默认构造函数：非必要，不提供
  • 缓存数组，并遍历循环读取数组
  • springboot实战篇1
  • Windows VS2019 编译 Apache Thrift 0.15.0
  • DigitalOcean 云平台上线 AMD MI325X GPU Droplet 服务器
  • 如何编写假设和约束---SRS软件需求规格指南系列
  • accelerate 在Pycham中执行的设置方法
  • C语言字符串相关函数
  • 【网络编程】网络传输-protobuf
  • Prometheus+altermanager搭配钉钉报警
  • 【PTA数据结构 | C语言版】旅游规划
  • qwen 提示词