# CloudCC 自定义类分析说明 ## 1. 分析口径 本文用于回答以下问题： - 自定义类能干什么 - 自定义类的主要作用是什么 - 为什么要用自定义类 - 自定义类能解决哪些问题 - 在什么情况下使用 - 在什么业务场景下使用 ## 2. 自定义类是什么 自定义类是运行在 CloudCC 服务端的 Java 业务代码载体。 它的定位不是页面本身，也不是触发器本身，而是被页面、按钮、触发器、定时类、组件或其他类调用的后端能力单元。 可以把它理解成 CloudCC 中的“业务服务层”： - 页面和按钮负责发起动作 - 触发器和定时类负责触发时机 - 自定义类负责真正的业务处理 因此，自定义类更适合承载那些： - 逻辑复杂 - 需要复用 - 需要服务端执行 - 需要跨对象处理 - 需要和外部系统通信 的能力。 ## 3. 自定义类能干什么 结合全部非测试类的逐类阅读，自定义类主要具备以下能力。 ### 3.1 数据读写与对象联动 这是最基础的能力，也是最普遍的能力。 自定义类可以： - 查询对象数据 - 查询关联对象数据 - 执行复杂条件检索 - 新增、更新、删除记录 - 在多个对象之间做联动更新 - 在业务动作完成后回写状态、金额、标记和结果 这使它非常适合承载“单次操作影响多个对象”的场景。 ### 3.2 复杂规则计算 大量自定义类并不是简单搬运数据，而是在做规则计算、汇总和判断。 这类能力通常包括： - 根据多个条件计算结果 - 根据角色、状态、时间、区域、分类决定不同处理路径 - 汇总明细到主记录 - 对数据进行分摊、拆分、匹配、校验和回写 当业务规则超出页面公式、字段配置或简单脚本能稳定承载的范围时，自定义类就是主要落点。 ### 3.3 流程编排与状态流转 自定义类非常适合做流程中的服务端编排。 典型表现为： - 接收一个动作入口 - 校验当前状态是否合法 - 查询上下游数据 - 按规则推进下一步 - 同步相关对象状态 - 触发通知、共享或资料处理 - 返回执行结果 从项目现状看，一批体量较大的类本质上都在承担这一职责。 ### 3.4 外部系统集成 这是本项目自定义类非常鲜明的特征之一。 自定义类可以作为平台与外部系统之间的集成层，负责： - 拼装请求参数 - 调用接口 - 接收返回结果 - 处理鉴权、异常和容错 - 将外部结果转换为平台内部可用的数据结构 相比把这些逻辑散落在页面、触发器或多个入口中，统一放到自定义类里更稳定、更易维护。 ### 3.5 通知、提醒与协同动作 自定义类不仅处理数据，也经常承担业务协同动作： - 发送邮件 - 发起提醒 - 推送待办 - 创建事件或任务 - 在关键节点通知相关角色 这类能力通常和流程控制绑定出现，用于保证业务动作执行后，协同链路能被同步拉起。 ### 3.6 文件、附件与资料处理 从全量阅读结果看，文件与资料相关处理占比也比较高。 自定义类可以负责： - 附件读取 - 文件上传或转发 - 目录创建 - 文件关系维护 - 文件与业务记录的绑定 - 资料同步与归档 这说明自定义类不仅处理结构化数据，也承担了一部分资料流转和文档协同职责。 ### 3.7 权限、共享与角色控制 一部分自定义类会在服务端完成权限相关动作，例如： - 基于角色、简档、组织关系控制动作 - 自动写入共享关系 - 按负责人或部门分配数据 - 根据审批角色决定是否允许继续 这类能力放在服务端实现，通常比放在前端更可靠。 ## 4. 自定义类的主要作用是什么 综合来看，自定义类的主要作用可以概括为以下 5 点。 ### 4.1 承载复杂后端逻辑 把复杂的、需要服务端执行的业务逻辑从页面层、按钮层、触发层中抽离出来，放到独立的服务端类中处理。 ### 4.2 形成可复用能力 把相同能力沉淀为公共服务，让多个入口共享同一套实现，避免逻辑重复。 ### 4.3 作为流程编排中枢 把“校验、查询、计算、写回、通知、集成”串成一条完整链路，让一个复杂动作在服务端被稳定执行。 ### 4.4 隔离系统边界 把平台内部逻辑和外部系统调用隔离开，让页面、按钮、触发器只需要调用结果，而不需要关心接口细节。 ### 4.5 提升治理性 通过统一的日志、异常、时间、返回结构和复用方式，让系统更容易排查、更容易维护、更容易扩展。 ## 5. 为什么要用自定义类 ### 5.1 因为很多业务已经超出页面配置能力 如果只是简单展示、字段联动、轻量前端交互，标准页面和脚本就足够。 但当业务涉及： - 多对象联动 - 多步骤状态推进 - 复杂计算 - 外部系统调用 - 文件和资料流转 - 权限和共享处理 页面层通常无法优雅承载，这时就需要自定义类。 ### 5.2 因为关键规则必须放在服务端 关键校验、关键状态、关键金额、关键动作如果只放在前端或入口层，可靠性和一致性都不足。 自定义类让这些规则在服务端可信执行，避免绕过和分叉实现。 ### 5.3 因为同一能力需要跨入口复用 同一套业务处理常常会被： - 页面按钮调用 - 触发器调用 - 定时类调用 - 组件调用 - 其他类调用 如果没有自定义类，逻辑会在多个地方重复，后续维护成本会迅速上升。 ### 5.4 因为需要统一集成出口 外部系统对接如果没有统一出口，接口规则、异常处理和认证逻辑会散落在各处。 自定义类正好可以充当统一的集成边界层。 ### 5.5 因为需要长期可维护 随着业务增长，真正难的不是“先做出来”，而是“后面还能改、还能查、还能扩”。 自定义类的价值就在于把复杂逻辑集中起来，为后续维护留下结构基础。 ## 6. 自定义类能解决哪些问题 ### 6.1 解决数据一致性问题 - 一个动作影响多个对象，但平台默认能力难以统一处理 - 主记录和明细记录之间容易口径不一致 - 上下游对象状态需要同时同步 自定义类可以把这些联动统一放到服务端，减少口径分裂。 ### 6.2 解决复杂规则难落地的问题 - 条件过多 - 公式过长 - 分支过深 - 决策依赖多个维度 这些逻辑如果堆在页面、公式或触发器里，维护难度很快失控。自定义类更适合承载这类规则。 ### 6.3 解决流程动作分散的问题 - 一个动作不仅要改数据，还要发通知、写共享、建目录、推接口 - 业务动作涉及多个系统和多个后续步骤 自定义类能够把这些步骤编排为一条服务端流程，保证执行次序和结果完整性。 ### 6.4 解决集成混乱的问题 - 外部接口多 - 返回结构不统一 - 失败处理不一致 - 同一种接口能力被多处重复实现 通过自定义类统一集成出口，可以降低重复和耦合。 ### 6.5 解决通知协同不及时的问题 - 业务动作完成后需要自动提醒相关人 - 邮件、待办、事件、任务需要按规则自动触发 自定义类可以把“业务处理”和“协同动作”组合在同一服务端链路里。 ### 6.6 解决文件资料处理分散的问题 - 附件上传、同步、归档、目录维护容易分散到多个入口 - 文件和业务记录之间的关系处理容易缺乏统一规范 自定义类适合承担统一的资料处理逻辑。 ### 6.7 解决权限与共享难统一的问题 - 不同角色对动作权限不同 - 数据共享规则需要自动生成 - 负责人切换后共享关系要同步变化 这类逻辑放在自定义类中更容易统一控制。 ## 7. 在什么情况下使用自定义类 满足以下任一情况时，优先考虑自定义类： - 业务逻辑复杂，页面层无法稳定承载 - 同一能力需要被多个入口复用 - 涉及多对象联动或批量处理 - 需要服务端强校验 - 需要复杂规则计算 - 需要外部系统集成 - 需要文件、附件、目录等资料处理 - 需要自动通知、提醒、待办协同 - 需要统一权限、共享和角色控制 - 需要接入 AI 或智能分析能力 相反，以下场景通常不需要优先上自定义类： - 仅做简单展示 - 仅做轻量前端交互 - 仅做简单字段联动 - 完全可以由标准配置完成的场景 ## 8. 在什么业务场景下使用 从全部非测试类的整体结构看，自定义类适合以下业务场景。 ### 8.1 复杂流程型场景 特点： - 一次动作会牵引多个后续步骤 - 同时影响多类数据 - 需要统一控制前后状态 适合使用自定义类，因为这类场景最依赖服务端编排能力。 ### 8.2 规则密集型场景 特点： - 有大量条件判断 - 有汇总、分摊、计算、校验 - 结果需要回写并留痕 适合使用自定义类，因为这类场景需要稳定的规则承载层。 ### 8.3 集成协同型场景 特点： - 需要和外部系统对接 - 需要把内部动作同步到外部 - 需要将外部结果回填平台 适合使用自定义类，因为它天然适合做集成边界层。 ### 8.4 通知驱动型场景 特点： - 某个节点发生后必须提醒相关人 - 需要自动创建待办、任务或消息 - 通知内容依赖业务数据动态生成 适合使用自定义类，因为通知逻辑通常要和业务处理紧密耦合。 ### 8.5 文件资料型场景 特点： - 需要读写附件 - 需要目录维护 - 需要文件同步、上传、归档或转发 适合使用自定义类，因为文件流转需要统一的服务端处理能力。 ### 8.6 权限共享型场景 特点： - 不同角色处理路径不同 - 需要自动授权、共享或分配 - 动作是否允许执行取决于服务端判断 适合使用自定义类，因为权限控制必须具备服务端可信性。 ### 8.7 智能辅助型场景 特点： - 需要调用模型或分析服务 - 需要上传文件给智能服务处理 - 需要把分析结果转成平台中的业务动作 适合使用自定义类，因为它既能做调用入口，也能做结果落地层。 ## 9. 与其他能力的分工建议 - 自定义类：负责复杂逻辑、服务复用、流程编排、集成处理 - 触发器：负责触发时机 - 定时类：负责时间驱动的自动执行 - 页面和组件：负责界面展示与交互 - 按钮：负责动作入口 推荐模式是： - 页面、按钮、触发器、定时类做“薄入口” - 自定义类做“厚服务” 这样可以把复杂度集中在服务端可治理的地方。