金蝶 K3 Cloud BOS 插件开发与 WebAPI 服务指南

本文梳理金蝶云星空 K3 Cloud 平台 BOS 插件开发体系，涵盖 Python 脚本插件常用工具类、C# WebAPI 自定义服务开发、凭证与现金流量数据查询服务的完整实践。

1. K3 Cloud 插件开发概述

金蝶云星空 (K3 Cloud) 的 BOS 插件开发体系支持两种语言：

开发语言	适用场景	运行方式
Python 脚本插件	表单插件、列表插件、轻量业务逻辑（无需编译部署）	在 BOS IDE 中直接编辑，注册到单据表单后即时执行
C# 二开插件	WebAPI 自定义服务、重量级业务扩展、复杂报表与性能敏感场景	编译为 DLL，部署至服务端 Website\Bin 目录

---

2. Python 脚本插件常用工具类

2.1 标准引用模块与命名空间导入

K3 Cloud Python 脚本插件基于 IronPython 运行时，需要通过 clr.AddReference 引入 .NET 程序集：

import clr
clr.AddReference('System')
clr.AddReference('System.Data')
clr.AddReference('Kingdee.BOS')
clr.AddReference('Kingdee.BOS.Core')
clr.AddReference('Kingdee.BOS.App')
clr.AddReference('Kingdee.BOS.Contracts')
clr.AddReference('Kingdee.BOS.ServiceHelper')
clr.AddReference('Newtonsoft.Json')

from Kingdee.BOS import *
from Kingdee.BOS.Core import *
from Kingdee.BOS.Core.Bill import *
from Kingdee.BOS.Core.Metadata import *
from Kingdee.BOS.Core.Metadata.FormElement import *
from Kingdee.BOS.Core.DynamicForm import *
from Kingdee.BOS.Core.DynamicForm.PlugIn import *
from Kingdee.BOS.Core.DynamicForm.PlugIn.Args import *
from Kingdee.BOS.Core.DynamicForm.PlugIn.ControlModel import *
from Kingdee.BOS.Core.DependencyRules import *
from Kingdee.BOS.Core.SqlBuilder import *
from Kingdee.BOS.Orm.DataEntity import *
from Kingdee.BOS.App.Data import *
from Kingdee.BOS.ServiceHelper import *
from System import *
from System.Data import *
from System.Collections.Generic import List
from Newtonsoft.Json import JsonConvert
from Newtonsoft.Json.Linq import *

2.2 创建单据视图 View（通用核心方法）

在 Python 脚本插件中，若要以编程方式新增或修改单据，需要先构建 BillView 视图对象：

def CreateBillView(ctx, formId, billId):
    """通过 formId 创建单据视图，billId 为 None 时新增，非 None 时编辑"""
    meta = MetaDataServiceHelper.Load(ctx, formId)
    form = meta.BusinessInfo.GetForm()
    # 创建 ImportBillView 实例（反射方式）
    tp = Type.GetType("Kingdee.BOS.Web.Import.ImportBillView,Kingdee.BOS.Web")
    billView = Activator.CreateInstance(tp)
    openParam = CreateOpenParameter(meta, ctx, billId)
    provider = form.GetFormServiceProvider()
    billView.Initialize(openParam, provider)
    return billView

def CreateOpenParameter(meta, ctx, billId):
    """构建单据打开参数"""
    form = meta.BusinessInfo.GetForm()
    openParam = BillOpenParameter(form.Id, meta.GetLayoutInfo().Id)
    openParam.Context = ctx
    openParam.ServiceName = form.FormServiceName
    openParam.PageId = Guid.NewGuid().ToString()
    openParam.FormMetaData = meta
    # billId 为空是新增 ADDNEW，非空是编辑 EDIT
    openParam.Status = OperationStatus.ADDNEW if billId is None else OperationStatus.EDIT
    if billId is not None:
        openParam.PkValue = billId
    openParam.CreateFrom = CreateFrom.Default
    openParam.DefaultBillTypeId = ""
    openParam.SetCustomParameter("ShowConfirmDialogWhenChangeOrg", False)
    plugs = form.CreateFormPlugIns()
    openParam.SetCustomParameter(FormConst.PlugIns, plugs)
    args = PreOpenFormEventArgs(ctx, openParam)
    for plug in plugs:
        plug.PreOpenForm(args)
    return openParam

---

3. C# WebAPI 自定义服务开发

当需要向外部系统暴露数据接口（如凭证查询、现金流量取数）时，需要基于 C# 开发 自定义 WebAPI 服务。

3.1 服务基类继承规范

所有自定义 WebAPI 服务类必须继承 AbstractWebApiBusinessService：

using Kingdee.BOS.WebApi.ServicesStub;
using Kingdee.BOS.ServiceFacade.KDServiceFx;

namespace EASK3
{
    public class VoucherService : AbstractWebApiBusinessService
    {
        public VoucherService(KDServiceContext context)
            : base(context) { }

        public string ExecuteService(string parameter)
        {
            JObject jo = (JObject)JsonConvert.DeserializeObject(parameter);
            string company = Convert.ToString(jo["company"]);
            string startDate = Convert.ToString(jo["startDate"]);
            string endDate = Convert.ToString(jo["endDate"]);
            
            // 参数校验
            if (string.IsNullOrEmpty(startDate))
                throw new Exception("开始日期不能为空");
            
            // 构建 SQL 查询凭证数据
            StringBuilder qrySql = new StringBuilder();
            qrySql.Append("/*dialect*/SELECT ... FROM T_GL_VOUCHERentry ...");
            
            // 执行查询并返回 JSON
            DataSet ds = DBServiceHelper.ExecuteDataSet(this.KDContext, qrySql.ToString());
            return JsonConvert.SerializeObject(ds.Tables[0]);
        }
    }
}

3.2 自定义服务部署流程

1. 在 Visual Studio 中编译项目，生成 DLL 文件。
2. 将编译产物（如 EASK3.dll）拷贝至 K3 Cloud 服务端安装目录：Website\Bin\。
3. 在 BOS IDE 中注册服务：WebAPI 服务 ➔ 新增 ➔ 绑定服务类名。
4. 外部系统可通过 K3 Cloud WebAPI 网关调用该自定义服务。

---

4. 常用数据操作 API 速查

API / 工具类	用途	使用示例
MetaDataServiceHelper.Load(ctx, formId)	加载表单元数据	获取业务信息与布局信息
BusinessDataServiceHelper.Load(ctx, ids, dynamicType)	按主键加载单据数据包	读取指定单据的完整数据
DBServiceHelper.ExecuteDataSet(ctx, sql)	执行原生 SQL 查询	返回 DataSet 结果集
DBServiceHelper.Execute(ctx, sql)	执行非查询 SQL (DML)	INSERT / UPDATE / DELETE
BusinessDataServiceHelper.Save(ctx, dataObjects)	保存单据数据包	新增或修改单据持久化
OperateServiceHelper.ExecuteOperate(ctx, ...)	执行单据操作（提交/审核等）	自动触发工作流