金蝶苍穹-数据服务接口

2024-08-21后端6 分钟498 次阅读
AI 摘要salmon-ai

本文详细解析了金蝶苍穹数据服务接口的ORM基础与常用用法,介绍了QFilter链、主实体模型与动态对象的作用,以及BusinessDataServiceHelper、QuerySer

笔记来源:https://vip.kingdee.com/school/detail/182501577989651456?productLineId=29&lang=zh-CN

一、ORM 原理概述

什么是ORM

对象关系映射(Object Relation Mapping)的简称,把实体模型映射到数据库中,提供对象的操作,在数据库中则体现为CRUD。

常见的开源框架:

  • Hibernate
  • Mybatis
  • JPA

为什么需要ORM

image.png

苍穹元数据模型

image.png

ORM查询原理

image.png

ORM查询示例

OQL查询

image.png

Qfilter

image.png

过滤条件QFilter

QFilter作为ORM的过滤条件参数,最终被翻译为SQL的where部分。
一个QFilter对象,可以与多个QFilter进行and、or关联,最终组成一个QFilter链,依旧用一个QFilter对象表示。
设计成嵌套链原因:链可以表示条件之间的and、or关系,嵌套可表示条件组合(优先级),用一个对象封装,便于传参。

java 复制代码
QFilter f1 = …
QFilter f2 = …
QFilter f3 = …
QFilter f = f1.and(f2).or(f3);
// 注意:在构造一个QFilter链里,不可存在跨对象的属性的or过滤关系,否则可能无法正确拆分sql进行查询。

ORM映射对象

主实体模型(MainEntityType):this.getModel().getDataEntityType()

  • 表单运行时的元数据对象,其中包含:
    • 子实体:EntityType,对应单据体、子单据体等
    • 属性:DynamicProperty,对应字段
  • 作用:获取对象的实体标识、实体名称、表名等等,获取所有字段属性
  • DynamicObjectType的作用同MainEntityType

动态对象(DynamicObject):this.getModel().getDataEntity()

  • 基于主实体模型构建的数据字典,存储单据体、字段的值,是弱类型对象。
  • 作用:主要用来后台接收查询结果以及构造保存的数据对象
    java 复制代码
    DynamicObject object = BusinessDataServiceHelper.newDynamicObject(“实体标识”));
    DynamicObject object = BusinessDataServiceHelper.loadSingle(pk,“实体标识”);

二、ORM 接口详解

接口的作用与区别

接口名称 作用/区别1 作用/区别2
1、业务对象服务接口 BusinessDataServiceHelper 查缓存数据/数据库数据 创建新数据
2、数据查询接口 QueryServiceHelper 单一功能:查出平铺对象
3、数据保存接口 SaveServiceHelper Save:只保存数据
saveOperate:触发操作插件、校验规则、编码规则等
Save:会保存所有的变量、增量和删量,比如新增分录行,Update方法只会保存变量
4、数据删除接口 DeleteServiceHelper 直接删除、删除前校验

业务操作接口-BusinessDataServiceHelper

java 复制代码
// 创建新的 DynamicObject 实例
public static DynamicObject newDynamicObject(String entityName)

// 从数据库中加载单个对象 loadSingle
public static DynamicObject loadSingle(Object pk, DynamicObjectType type)
public static DynamicObject loadSingle(Object pk, String entityName)
public static DynamicObject loadSingle(Object pk, String entityName, String selectProperties)
public static DynamicObject loadSingle(String entityName, String selectProperties, QFilter[] filters)

// 从缓存中加载单个对象 loadSingleFromCache (只有基础资料才从缓存中获取)
public static DynamicObject loadSingleFromCache(Object pk, String entityName)
public static DynamicObject loadSingleFromCache(String entityName, QFilter[] filters)
public static DynamicObject loadSingleFromCache(Object pk, String entityName, String selectProperties)
public static DynamicObject loadSingleFromCache(String entityName, String selectProperties, QFilter[] filters)
public static DynamicObject loadSingleFromCache(Object pk, DynamicObjectType type)

// 从数据库加载多个对象 load
public static Object[] load(Object[] pkArray, IDataEntityType type)
public static DynamicObject[] load(Object[] pkArray, DynamicObjectType type)
public static DynamicObject[] load(String entityName, String selectProperties, QFilter[] filters)
public static DynamicObject[] load(String entityName, String selectProperties, QFilter[] filters, String orderBy)
public static DynamicObject[] load(String entityName, String selectProperties, QFilter[] filters, String orderBy, int top)
public static DynamicObject[] load(String entityName, String selectProperties, QFilter[] filters, String orderBy, int pageIndex, int pageSize)

// 从缓存中加载多个对象 loadFromCache
public static Map<Object, DynamicObject> loadFromCache(Object[] pkArray, DynamicObjectType type)
public static Map<Object, DynamicObject> loadFromCache(Object[] pkArray, String entityName)
public static Map<Object, DynamicObject> loadFromCache(String entityName, String selectProperties, QFilter[] filters)
public static Map<Object, DynamicObject> loadFromCache(String entityName, String selectProperties, QFilter[] filters, String orderBy)
public static Map<Object, DynamicObject> loadFromCache(String entityName, QFilter[] filters)
public static Map<Object, DynamicObject> loadFromCache(DynamicObjectType type, QFilter[] filters)

注意:目前loadFromCache只支持基础资料数据缓存的查询
image.png

数据查询接口-QueryServiceHelper

java 复制代码
// 查询平铺对象
public static DynamicObjectCollection query(String entityName, String selectFields, QFilter[] filters)
public static DynamicObjectCollection query(String entityName, String selectFields, QFilter[] filters, String orderBys)
public static DynamicObjectCollection query(String entityName, String selectFields, QFilter[] filters, String orderBys, int top)
public static DynamicObjectCollection query(String algoKey, String entityName, String selectFields, QFilter[] filters, String orderBys)
public static DynamicObjectCollection query(String algoKey, String entityName, String selectFields, QFilter[] filters, String orderBys, int top)

// 示例代码
BillList list = this.getControl("billistap");
String entityName = list.getEntityType().getName();
QFilter filter = QFilter.of("billno", QCP.equals, "1569136331894");
DynamicObjectCollection cols = QueryServiceHelper.query(entityName, "id,billno,entryentity.price as price", filter.toArray());
this.getView().showMessage(cols.get(0).getString("price"));

// 查询单个对象
public static DynamicObject queryOne(String entityName, String selectFields, QFilter[] filters)

// 查询数据集(类似 JDBC ResultSet)
public static DataSet queryDataSet(String algoKey, String entityName, String selectFields, QFilter[] filters, String orderBys)
public static DataSet queryDataSet(String algoKey, String entityName, String selectFields, QFilter[] filters, String orderBys, int top)

// 查询主键
public static List<Object> queryPrimaryKeys(String entityName, QFilter[] filters, String orderBys, int top)
public static List<Object> queryPrimaryKeys(String algoKey, String entityName, QFilter[] filters, String orderBys, int top)

// 查询是否存在
public static boolean exists(String entityName, Object pkId)
public static boolean exists(String entityName, QFilter[] qFilters)

// 通过全文索引查询单据编码(要求业务对象必须有 BillNo 字段)
public static List<BillNoDto> getAllBillNo(String searchKey, int top)

什么是平铺对象?
我们的单据是这样的:
image.png
那么平铺对象如下:
image.png

数据保存&删除接口

数据保存-SaveServiceHelper

java 复制代码
// 保存对象到数据库
public static Object[] save(IDataEntityType type, Object[] dataEntities)
public static Object[] save(DynamicObject[] dataEntities)

// 调用业务对象的保存操作,会触发操作校验、操作插件等服务
public static OperationResult saveOperate(String entityNumber, DynamicObject[] dataEntities)
public static OperationResult saveOperate(String entityNumber, DynamicObject[] dataEntities, OperateOption option)
public static OperationResult saveOperate(String operationKey, String entityNumber, DynamicObject[] dataEntities)
public static OperationResult saveOperate(String operationKey, String entityNumber, DynamicObject[] dataEntities, OperateOption option)

数据删除-DeleteServiceHelper

java 复制代码
// 直接从数据库删除
public static void delete(IDataEntityType type, Object pks)
public static int delete(String entityName, QFilter qFilters)

// 调用业务对象的删除操作,会触发删除校验,插件等服务
public OperationResult deleteOperate(String operationKey, String entityName, Object pks)
public OperationResult deleteOperate(String operationKey, String entityName, Object pks, OperateOption option)
public OperationResult deleteOperate(String entityName, Object pks)
public OperationResult deleteOperate(String entityName, Object[] pks, OperateOption option)

三、案例演示——新增

演示如何创建一个数据包,并且给数据包赋值,最后保存到数据库中。

  • 应用场景:
    新增&保存:列表页面,点击按钮a时,后台新增一条数据。
java 复制代码
private void addNewDemo() {
    // 创建一个采购申请单的表单标识的空数据包
    DynamicObject doj = BusinessDataServiceHelper.newDynamicObject("kdec_reqbill");
    
    // 设置表单的字段值
    doj.set("billstatus", "A");  // 设置单据状态为 'A'
    doj.set("kdec_notes", "addnewdemo备注");  // 设置备注
    doj.set("kdec_requser", UserServiceHelper.getCurrentUserId());  // 设置当前用户的ID为申请人

    // 添加两行分录数据
    DynamicObjectCollection entrys = doj.getDynamicObjectCollection("kdec_reqentryentity");

    // 新增一条空的分录行
    DynamicObject entry = entrys.addNew();
    entry.set("kdec_qty", 10);  // 设置数量为 10

    // 保存操作:参数为表单标识、待保存的数据包和操作选项
    OperationResult result = SaveServiceHelper.saveOperate("kdec_reqbill", new DynamicObject[]{doj}, OperateOption.create());

    // 判断保存结果是否成功
    if (result.isSuccess()) {
        // 显示成功通知
        this.getView().showSuccessNotification("新增采购数据成功");
        // 调用刷新操作刷新表单
        this.getView().invokeOperation("refresh");
    }
}
image.png

四、案例演示——仅查询

仅查询场景,演示如何实现:点击按钮查询出数据并显示。

  • 应用场景:
    仅查询:点击按钮b时,查出编码等于"xxx”的单据数据,并显示
java 复制代码
private void queryDemo() {
    // 创建类似 SQL 语句中的 WHERE 条件
    QFilter billnoQFilter = new QFilter("billno", QCP.equals, "REQ-20240119-0003");

    // 执行查询,获取符合条件的记录
    DynamicObjectCollection reqObj = QueryServiceHelper.query(
        "kdec_reqbill",
        "id,billno,kdec_requser,kdec_reqentryentity.kdec_qty",
        new QFilter[] { billnoQFilter }
    );

    // 遍历查询结果
    for (DynamicObject obj : reqObj) {
        // 获取分录中的数量和申请人
        Object qty = obj.get("kdec_reqentryentity.kdec_qty");
        Object kdecRequser = obj.get("kdec_requser");

        // 你可以在这里根据需要处理这些数据
    }

    // 显示查询到的数据行数
    this.getView().showMessage(
        "编号 REQ-20240119-0003 的数据查询结果行数:" + String.valueOf(reqObj.size())
    );
}
image.png

五、案例演示——查询-修改-保存

演示如何实现:在列表中点击按钮时,查出已选择行的数据,修改后保存。

  • 应用场景:
    查询&修改&保存:列表页面,列表中点击按钮c时,查出已选择行的数据,修改后保存
java 复制代码
private void editDemo() {
    // 获取列表选中行数据,"billlistap" 是标准单据列表控件的固定标识
    BillList billListap = getView().getControl("billlistap");
    ListSelectedRowCollection selectedRows = billListap.getSelectedRows();

    // 存储选中行的主键
    ArrayList<Object> ids = new ArrayList<>();
    String entityName = "kdec_reqbill";

    // 获取选中行的主键值并添加到 ids 列表中
    for (ListSelectedRow row : selectedRows) {
        Object primaryKeyValue = row.getPrimaryKeyValue();
        ids.add(primaryKeyValue);
    }

    // 构建过滤条件,根据选中行的主键值进行筛选
    QFilter idQFilter = new QFilter("id", QCP.in, ids);

    // 查询用户 "张三" 的信息
    DynamicObject userObj = BusinessDataServiceHelper.loadSingle(
        "bos_user", 
        "id,number", 
        new QFilter[] { new QFilter("name", QCP.equals, "张三") }
    );

    // 根据筛选条件加载单据数据
    DynamicObject[] dojs = BusinessDataServiceHelper.load(
        entityName,
        "id,kdec_requser,kdec_reqentryentity.kdec_qty", 
        new QFilter[] { idQFilter }
    );

    // 更新每条单据的数据
    for (DynamicObject doj : dojs) {
        // 设置用户信息
        doj.set("kdec_requser", userObj);

        // 获取并更新分录行数据
        DynamicObjectCollection entrys = doj.getDynamicObjectCollection("kdec_reqentryentity");
        for (DynamicObject entry : entrys) {
            // 将申请数量在原来的基础上加 10
            entry.set("kdec_qty", entry.getInt("kdec_qty") + 10);
        }
    }

    // 保存更新后的单据数据
    OperationResult result = SaveServiceHelper.saveOperate("kdec_reqbill", dojs, OperateOption.create());

    // 如果保存成功,显示成功通知
    if (result.isSuccess()) {
        this.getView().showSuccessNotification("编辑数据成功");
    }
}
image.png

六、案例演示——删除

演示如何实现:列表中点击按钮时,删除数据。

  • 应用场景:
    列表中点击按钮d时,删除前面的数据
java 复制代码
private void deleteDemo() {
    // 获取列表选中行数据,"billlistap" 是标准单据列表控件的固定标识
    BillList billListap = getView().getControl("billlistap");
    ListSelectedRowCollection selectedRows = billListap.getSelectedRows();

    // 存储选中行的主键
    ArrayList<Object> ids = new ArrayList<>();
    String entityName = "kdec_reqbill";

    // 获取选中行的主键值并添加到 ids 列表中
    for (ListSelectedRow row : selectedRows) {
        Object primaryKeyValue = row.getPrimaryKeyValue();
        ids.add(primaryKeyValue);
    }

    // 构建过滤条件(如果需要)
    QFilter idQFilter = new QFilter("id", QCP.in, ids);

    // 调用删除服务进行删除操作
    DeleteServiceHelper deleteServiceHelper = new DeleteServiceHelper();
    OperationResult result = deleteServiceHelper.deleteOperate(
        entityName, 
        ids.toArray(new Object[ids.size()])
    );

    // 如果删除成功,显示成功通知
    if (result.isSuccess()) {
        this.getView().showSuccessNotification("删除成功");
    }
}
image.png
觉得有用就点个赞,不用登录也能读

评论

0 条
登录 之后才能评论
—
还没有评论,来说第一句