1. 我的平台
  2. 二开规范

金蝶云·星空二开规范手册

版本

修订

V1.2

2019-5-10
   
   

金蝶云星空aPaaS平台依托金蝶云星空动态领域模型，支持单据扩展、脚本及插件开发，但开发过程中因开发人员的熟悉程度以及对框架的理解不同，容易出现不合理的设计或不合规的代码实现。

为了保障产品的稳定性，向后兼容性，保障二开模块的质量与性能，维护客户信息系统安全，要求所有二次开发必须遵守以下规范。

1. 二次开发定义

金蝶云星空二次开发分为以下三个级别，依次为：配置级开发，插件级开发和通用级开发，三者关系如下图所示。

  • 配置级开发：

    • 配置级开发指扩展字段或新增一些额外单据的需求，这些单据逻辑简单，不需要辅助程序助插件（含脚本插件）。

  • 插件级开发：

    • 插件级开发指业务逻辑较为复杂，需要辅助程序插件或脚本插件才能实现相关功能，包含以下情景：

    • 表单插件(含列表插件)
    • 服务操作插件
    • 单据转换插件
    • 反写插件
    • 工作流插件
    • 报表取数插件
    • 直接SQL取数报表
    • 实体服务规则
    • 值更新事件
  • 通用级开发：

    • 通用级开发主要是对一些规模较大，开发了独立的服务或页面，并需要部署到站点运行。凡涉及以下情景的开发均视为通用级开发。

    • 发布Web API自定义服务
    • 发布页面资源文件
    • 配置文件或修改原有配置项
    • 部署程序访问外部系统
    • 部署计划任务插件
    • 程序或插件中有读写本地文件的操作

2. 项目组织规范

  • 实施、开发平台：
    • 所有公有云项目必须依托协同开发平台进行二次开发，包含但不限于单据扩展，单据新增。
    • 私有云项目（由机构分包的二次开发实施），也必须在协同开发平台进行二次开发。
    • 对并发许可及特殊环境的客户二次开发，需要开通二次开发的，必须提交申请，批准后才给予开通。
    • 在协同开发平台为特定客户的二次开发所建的应用名必须与该客户的正式名称相同。
  • 开发商代码规范：
    • 线下开发模式必须设置有效的开发商代码，所有开发商代码必须是由协同开发平台分配的开发商代码，不允许私自设置与系统不兼容的开发商代码。
    • 行业产品的开发必须选择企业开发商代码，项目交互的应用可以选择个人或企业的开发商代码。

3. 单据开发规范

  • 命名规范

    • 扩展或新增单据时(含转换规则、报表等动态领域模型)，其单据ID可以选择系统生成的唯一ID，如果需要自定义ID，则必须遵守以下规则：

    • 自定义的单据名（系统生成除外）必须以开发商代码加下划线排头（如：PAAB_xxxxx）
    • ID或Key长度不允许超过30字符，只能使用字母、下划线
    • 扩展的字段标识和属性必须以开发商代码加下划线排头（如：PAAB_xxxxx），字段名必须包含开发商代码（如：F_PAAB_xxxxx）
    • 扩展的任何元素，例如标签控件、页签控件、面板控件等，标识必须以开发商代码加下划线排头（如：PAAB_LableXXX，PAAB_TabXXX等）
  • 设计原则规范

    • 单据设计必须遵守以下规范：

    • 一个单据的字段总数原则上不要超过50个字段（含隐藏字段）
    • 框架布局下，停靠上，下，左，右的元素小于等于1个，中间停靠的等于1个，同时，停靠元素的同级上不允许存在绝对布局元素
    • 字段的一些默认出厂值需要按需设置，例如单据列表默认显示、支持引出、支持引入等需要
    • 网控必须配置，防止并发修改数据导致数据错误
    • 基础资料表单主键设计建议使用整型，否则不支持单据转换

4. 代码编写规范

  • 工程命名规范

    • 工程名称必须以下述标准进行命令，{开发商标识}.{项目}.{工程归类}，如果存在细分模块，可以使用四级命名空间，如：{开发商标识}.{项目}.{工程归类}.{模块名}。

    • 命名空间必须与工程名、生成的程序集名称一致；
    • 工程命名遵守大驼峰法则，除了用以分隔的‘.’外，仅允许使用26个大小字英文字母或辅助数字命名；
    • 表单插件工程命名规则：{开发商标识}.{项目}.BusinessPlugIn, (e.gPPAB. K3Cloud.BusinessPlugIn)
    • 服务操作插件工程命名规则：{开发商标识}.{项目}.BusinessPlugIn,如K3Cloud.BusinessPlugIn
  • 禁止使用的操作

    • 杜绝所有一切可能威害服务器运行安全的代码，代码标准平台会动态调整，当前已包含的规则：

    • 禁止任何使用进程的代码；
    • 禁止任何读取操作系统用户信息的操作；
    • 禁止使用本地文件操作（网络流操作,平台规定的临时目录除外）;
    • 禁止任何Socket侦听的代码;

5. 脚本编写规范

  • DDL规范

    • 关于所有表、字段、视图、主键、索引操作的必须遵守以下规则:

    • 表名视图名必须以开发商标识加下载线排头
    • 表必须有物理主键
    • 主键原则上使用整型（不允许用自增长主键）,数据量较小的表可以使用字符型
    • 禁止修改标准产品视图
    • 禁止删除物理表（临时表除外）
    • 不允许使用触发器
    • 不建议使用存储过程
    • 新建数据表时，必须拥有聚集索引
    • 主键和索引字段的值不允许为null
    • GUID字段不允许建立为聚集索引
    • 主从关系表，从表需要引用主表中某个字段，对应字段名称要求一致
    • 一般数量、金额类型：必须使用精确数值类型，如：Decimal，禁止为空，指定默认值为0；禁止使用Double、Float、Money等非精确类型，对这种类型固定为Dicemal(23,10)、Dicemal(19,6)
    • 在使用Dicemal数值类型时必须明确指定小数精度
    • 字符类型，统一使用nvarchar
    • Not null属性的字段，必须设置缺省值
    • 多语言字段单独放在一张表中
    • 使用ntext数据类型替代text数据类型
    • 临时表必须显式地创建，使用完毕后必须显式地删除
  • DML规范

    • 所有数据操作必须遵守以下规则

    • 任何查询都要带查询条件
    • 查询条件必须使用参数化查询
    • 保持事务简短并处于一个批处理中
    • 使用较低的隔离级别。如对于查询报表和序时簿等查询，设置较低的事务隔离级别，提高并发能力
    • 必须使用join语句进行表间连接,禁止使用where条件进行表连接
    • 预插数据Insert前必须按主键匹配删除再插入
    • 一次批量提交SQL的语句不应该超过500条，如果超过，需要分几次提交
    • 可以关联物理表实现的SQL语句，不要关联视图
    • SQL脚本中禁止使用外部联接运算符“*=”和 “=*”
    • ORDER BY 子句中的字段别名禁止使用表别名作为前缀。[SQL SERVER2005下执行中断]
    • 不要在 where 子句中的“=”左边进行函数、算术运算或其他表达式运算，否则系统将可能无法正确使用索引
    • 不要在where条件中使用函数,否则将不能利用索引
    • 在where条件中使用明确的字段类型值,避免由于隐式转换而不能正确使用索引
    • where 子句中不要使用case条件
    • 对于where条件中查询连续的数值,使用between替代in
    • 如果in子句中需要查询的值较多（大于30个），必须使用表函数方式实现
    • 不允许使用fid in（select fid from …），必须采用 exists(select 1 from …where v.fid=fid)的方式

6. 发布上线规范

  • 私有云上线规范

    • 建议通过安装包进行部署，原则上不要直接往生产服务器替换组件等操作。

  • 公有云部署上线规范

    • 公有云二开（插件级、通用级）都需要走二开上线流程，要求开发者通过协同开发平台提交上线申请，具体流程如下，参见《公有云二开上线流程》：

    • 开发人员在线构建应用
    • 开发人员提交上线申请
    • 客户IT管理员批准上线
    • 公有云运维审核
    • 发布到生产环境

7. 附录：

◊ 《金蝶KSQL规范》：https://open.kingdee.com/K3Cloud/WenKu/DocumentView.aspx?docId=110019

◊ 《公有云二开上线流程》：https://open.kingdee.com/K3Cloud/Open/HowToApplyOnline.aspx