一、概述

适用范围

• 本规范适用于ISV开发的规范，YonBuilder标准版和专业版都适用。遵循规范开发会避免很多问题。

名词解释

• ISV：英文全称是Independent Software Vendors ，意为“独立软件开发商”，特指专门从事软件的开发、生产、销售和服务的企业。
• 商开环境：用于用户在一个隔离的区域进行自己的业务开发，与线上是独立分开的。
• 云市场：ISV用户将自己的产品发布到云市场进行销售给用户。

整体介绍

• 为了加快基于ISV和用友的快速开发和接入，避免开发的过程中出现一些比较奇怪的问题，加速开发过程，提高开发效率而制定的一部开发规范。

适用阅读对象

• 开发人员

• 产品经理

• 架构师

• 运营人员

文档修订摘要

二、系统对接方式

• 我们提供基于开放平台（OpenApi)的HTTPS的API接口操作现有单据、档案以及操作通过YonBuilder构建的单据和表单等，接口调用采用幂等方式调用

  • 幂等方式传送
  • 幂等方式初期用在保存/更新方式上，目前的幂等方式不能获取到ID, 需要通过查询接口查询一遍（未来会调整为直接返回幂等key和单据/档案ID）

• 一些基本单据、档案通过事件订阅的方式，可以接收到自己租户下的变化

三、基于YonBuider的应用同步方式

• 用户在沙箱环境进行开发的单据、表单、报表、智能分析以及基础档案的话可以通过“构建平台”- 传输包管理、传输包部署、传输包上载等方式将数据同步到其他租户
• 如果用户想用外部的数据源进行数据分析的话，需要购买“智能分析平台”模块

四、系统集成方式

• 基于YonBuilder方式构建的应用发布后只需要通过openApi进行调用，事件回调等进行集成
• 融合模式构建的应用可以通过SSO方式登录到YonSuite，事件回调等进行集成

五、用友云产品基于YonBuilder开发规范

1. 应用设计规范

• 有关联关系的功能需要放到一个应用中，禁止有关联关系的创建到多个应用，比如A应用引用了B应用发布参照功能

2. 编码规则

• ISV微服务编码规则

  • 第一段：p表示生态产品分类：ISV开发的应用
  • 第二段：领域云编码
  • 第三段：行业代码（如果不属于任何行业：默认i000）
  • 第四段：ISV代码，p开头，4位数前缀：p000-pzzz
  • 第五段：应用编码（不能包含特殊字符，长度不超过8，可以包含数字和_/-）
  • 举例：p-xx-i000-p001-cms01

• 行业微服务编码规则

  • 第一段：i表示行业产品分类：行业开发的微服务
  • 第二段：领域云编码
  • 第三段：行业代码（获取行业代码的时候取消行业代码中间的-例如：制药与医药流通 I-PMD 直接获取：ipmd）
  • 第四段：应用编码（不能包含特殊字符，长度不超过8，可以包含数字）
  • 举例：i-cpd-ifcc-wms

• 专业版自建应用编码

  • 专业版自建应用编码：${应用编码}${1位数字}，数字为应用服务的顺序编号

• 流水线编码

  • 流水线分为前端、后端、移动端，编码规则依次为 ：
  • yonbip-yisv-${领域云编码/行业代码}-${应用编码}-${env}-fe
  • yonbip-yisv-${领域云编码/行业代码}-${应用编码}-${env}-be
  • yonbip-yisv-${领域云编码/行业代码}-${应用编码}-${env}-mobile
  • ${领域云编码/行业代码}：如果行业代码为i000, 则为领域云编码，否则为行业代码
  • ${env}为环境变量, 开发-dev, 核心1-stage，生产-pro，核心3-core3
  • 流水线名称：生态-${商开|核心1|生产|核心3}-${项目名称}-${前端|后端|移动端}-${MDD版本}，如：生态-商开-GSP-后端-MDD540

旧规范

• 专业版自建应用编码(标准版系统自动创建）：I${两位ISV编码}${1位数字}，ISV编码，产品编码为数字、小写字母组合。
• 引擎编码：isv-${两位ISV编码}${1位数字}，必须以isv-开头，ISV编码，产品编码为数字、小写字母组合。后续将提前按规则提交微服务编码申请，通过后可以在创建引擎的时候选择该编码。
• 流水线编码分为前端、后端、移动端，编码规则依次为 ：
  • yonbip-yisv-i${两位ISV编码}${1位数字}-${env}-fe
  • yonbip-yisv-i${两位ISV编码}${1位数字}-${env}-be
  • yonbip-yisv-i${两位ISV编码}${1位数字}-${env}-mobile
  • ${env}为环境变量, 开发-dev, 核心1-stage，生产-pro，核心3-core3
• 流水线名称规范：生态-${商开|核心1|生产|核心3}-${项目名称}-${前端|后端|移动端}-${MDD版本}，如：生态-商开-GSP-后端-MDD540

---

• 数据库shema编码为：i{两位ISV编码}${1位数字}
• 交易类型编码: I${两位ISV编码}${1位数字}_${交易类型编码} 交易类型编码为数字、小写字母组合。

3. 域名使用规范

• ISV用户需要使用用友生态产品开发部创建的域名，域名命名规则为$env-$schema.yonisv.com
• 商开环境和生产环境需要不同的域名，$env目前有dev（商开）、stage（核心1）、pro（核心2）、core3（核心3）

4. 对象建模规范

• 业务对象编码：i${两位ISV编码}${1位数字}_${业务编码}，为数字、小写字母组合。例如条码项目，ISV编码为 tm， 需要创建的业务为条码打印:codeprint，则业务对象编码为：itm1_codeprint。
• 实体编码：主实体编码同业务对象编码
• 主、子表不用创建ID字段，系统会自动创建。子表实体不允许blob数据类型
• 数据库表名：同实体编码
• 实体-业务属性-编码：小驼峰式命名，如：merchantCode，原厂扩展业务属性加前缀extend,如：extendMerchantCode
• 实体-业务属性-表字段名：相应业务属性编码大写字母转为_小写字母，如：merchantCode -> merchant_code, extendMerchantCode -> extend_merchant_code
• 添加的字段一旦发布后不要删除， 因为需要一系列的原数据需要同步删除。
• 引用接口说明参考如下，如果需要的话可以沟选，不需要的话先不用沟通，不会产生多余的字段
  • 审批：支持审批流
  • 业务流：如果需要进行推单拉单的话，需要勾选业务流
  • 交易类型：根据该类型区分不同的单据，也是生成不同单据的标志
  • 树型结构：支持树型结构保存
  • 自动编码：支持业务单据按钮“编码规则”进行自动编码
  • 档案状态：支持启用、停用标志
  • 主组织： 该单据支持组织
• 枚举：isv${两位ISV编码}${1位数字}${N位编码}, 例如：isv_sy1_type
• 数据实体支持，单表、主子表、一主多子、主子孙表形式
• 数据类型支持大多数的数据类型，如文本、数值、图片等
• 表索引规范
  • 通过数据建模-唯一性校验和索引，建立索引（专业版从数据库直接创建）
  • 非唯一索引以 idx_字段1_字段2... 命名，索引名称全部小写
  • 唯一索引以 uniq_字段1_字段2... 命名，索引名称全部小写(专业版数据库自建)
  • 重要的查询相关必须被索引，比如：tenant_id, SELECT、UPDATE、DELETE语句的WHERE条件列,ORDER BY、GROUP BY、DISTINCT的字段
  • 在 varchar 字段上建立索引时，必须指定索引长度,没必要对全字段建立索引，根据实际文本区分度决定索引长度。 说明：索引的长度与区分度是一对矛盾体，一般对字符串类型数据，长度为 20 的索引，区分 度会高达 90%以上，可以使用 count(distinct left(列名, 索引长度))/count(*)的区分度来确定。
  • 建组合索引的时候，区分度最高的在最左边。 正例： 如果 where a=? and b=? ， 如果 a 列的几乎接近于唯一值，那么只需要单建 idx_a索引即可。 说明： 存在非等号和等号混合时，在建索引时，请把等号条件的列前置。如： where c>? and d=? 那么即使 c 的区分度更高，也必须把 d 放在索引的最前列， 即索引 idx_d_c。

5. 页面建模规范

• 页面修改之后需要重新进行发布，发布后需要重新刷新页面。
• 目前页面名称不允许重复，删除页面后数据暂时存储的，过一段时间会清理历史数据。
• 页面编码: 页面编码不可与应用编码相同，页面编码需要保持和业务对象编码一致。

6. 流程&自动化规范

• 函数编码同实体编码规则

• 函数分为前端、后端、API函数，针对不同的数据类型选择不同的函数

  • 前端函数针对前端进行编写，用于编写一些事件，需要遵循前端规范
  • 前端函数不能调用后端函数，只能调用后端API函数
  • 后端函数用于进行后端数据调用，比如查询某个数据。也可以进行http接口的访问等

• 尽量不调用OpenAPI，用YonQL（OpenAPI调用量大时会有限流）

7. 集成配置规范

• 通过应用构建的单据需要将API发布、授权后才可以进行外部调用
• 未经授权的API则不能通过外部调用

8. 发布规范

• 第一次发布应用前，要确认好应用所属领域和一级菜单，发布后无法修改
• 所有更新的页面需要重新进行发布
• 发布后的页面需要通过角色管理修改和授权才可以看到
• 在菜单结构-分组列表添加服务时，服务编码要见名知意（服务编码即serviceCode），方便查询调试

9. 其他规范

• 【单据】表头的“编码”，标题都应为【单据编号】，只有档案为【编码】

六、禁止条例

1. 应用构建禁令

• 开发阶段应用构建禁止使用自定义项、自定义档案、特征。
• 禁止直接在客户生产环境进行开发操作，开发、生产需分离。
• 禁止对象建模实体发布后删除字段。
• 禁止实体业务属性使用系统关键字。
• 实体发布后，字段不允许删除，因为需要一系列的元数据需要同步删除。
• 前端脚本禁止复杂循环及循环调用后端请求。
• 后端脚本和api脚本禁止循环操作（仅限DML语句）YonQL，使用YonQL批量操作。
• 后端脚本和api脚本调用开放平台或三方查询类接口必须实现分页，每页最大数量建议不超过100。
• 无论前端脚本、后端脚本还是api脚本、后端服务，一定不能写死循环。

2. 特征使用禁令

• 项目开发阶段，特征使用规范如下：
• 项目实施人员要求增补字段，子表等，如果是标准产品需求，通过标准产品扩展实体的方式实现，如果是新功能需求则修改业务对象的实体实现。
• 禁止通过添加特征来满足业务字段要求
• 如果业务需要物料特征组，这种情况可以使用特征，其他情况则禁止。

七、用友云产品基于脚手架规范

1. 脚手架的GIT推送代码注意事项

• 只允许推送一次git代码，再次推送将覆盖原有代码。注意、注意。

2. 专业版脚手架的代码开发规范

• 前端代码一写要写到脚手架，不允许写前、后端及API函数，要将这些函数全部写到脚手架里，方便维护。
• 确保前端脚手架package.json中的name属性值唯一，推荐使用 微服务编码 或 domainKey 或 引擎编码 作为name的值
• 在页面上不允许使用“页面规则”，所有的配置需要使用前端代码控制。
• 后端负责所有业务逻辑处理，不能将业务逻辑写到前端代码，定时任务也需要在后端编码，必要时结合“调度任务”。
• 规则链、公共函数需要写到后端控制。

2. 脚手架的前端说明

• 前端脚手架的结构，需要按以下的说明进行前端文档编写。

packages/mdf-app
├── docs
│   └── mdf-intro.md
├── manifest.development.json
├── manifest.production.json
├── package.json
├── pm2.json
├── src
│   │── business                    # 业务扩展脚本(JS)
│   │   └── common
│   ├── client
│   │   ├── index.jsx
│   │   └── styles            # 业务样式代码
│   │       └── default
│   ├── common
│   │   ├── extends             # 扩展UI元数据中的控件类型（React 组件方式)
│   │   │   ├── basic         # 基础控件扩展
│   │   │   ├── formatter     # 格式化
│   │   │   ├── home
│   │   │   ├── index.jsx
│   │   │   ├── meta          # 扩展容器组件
│   │   │   ├── modal         # 扩展模态框
│   │   │   ├── popover
│   │   │   ├── portal         # 扩展页面
│   │   │   └── toolbar
│   │   ├── config.env.js            # 全局环境变量配置
│   │   ├── config.comp.js       # 组件交互扩展入口registerMetaComp
│   │   ├── registerMetaComp.js # 注册扩展组件
│   │   ├── pages
│   │   │   └── demoRouter
│   │   └── redux
│   │       ├── Isomorph.jsx
│   │       ├── reducers.jsx
│   │       ├── routes.jsx
│   │       └── store
│   └── server                                  # Node Server 相关
│       ├── controllers
│       │   ├── amap.js
│       ├── env
│       │   └── index.jsx
│       ├── index.js
│       ├── middlewares
│       │   └── viewhook
│       └── router.js
├── static                                          # 无需编译的静态资源
│   ├── scripts
│   │   ├── font.js
│   │   ├── vendor.js
│   │   ├── vendor.js.map
│   │   ├── vendor.min.js
│   │   ├── vendor.min.js.map
│   │   └── yonyou-yyy.js
│   ├── styles
│   └── ueditor
│       
├── webpack.dev.config.js               # 基于Webpack的前端编译脚本
├── webpack.dll.config.js
├── webpack.package.config.js
└── webpack.prod.config.js

3. 脚后架的后端说明

• 后端脚手架工程结构如下
  • ${projectName}-be, 总模块，里边将所有模块汇总起来，新加的模块需要加到此工程的pom文件中
  • dev-${projectName}-bootstrap，该模块用于启动相关所需要的数据，一般我们自己建的module需要加入到依赖里边，才可以正常使用
  • dev-${projectName}-extend，该模块用于实现扩展模块，里边可以进行事件、后端函数、规则链定义，用于实现一些原厂的一些扩展功能
  • dev-${projectName}-isv, 用于给isv开放的个别功能，比如sso模块，规则的保存、提交、删除等
  • dev-${projectName}-mobile, 用于移动端的接口调用、token等方法
  • dev-${projectName}-app, 应用级模块处理，用于处理一些授权、cookie、流程等
• 后端代码规范
  • 如果自己创建的module，里边的类路径可以遵循用友的包创建规则，也可以使用自己创建的包命名规则，这个时候需要在包扫描类中加入到@ComponentScan注解中，类为com.yonyou.ucf.mdf.MDFApplication
  • 遵循一些基本的开发规范，比如不用在变量名中使用$或_，不能使用中英文混合含义变量，if语句里边处理的内容要用大括号括起来等避免一些基本的问题出现
  • 使用lambda表达式的时候一定要注意提前做空判断和处理，避免出现NPE错误
  • 如果涉及到跨域的情况，需要将ISVWebMvcConfigurer类的UCFCoreProperties类进行重写或重载，加入到自己需要的域名即可

4. 数据库字符集

• 数据库导出的脚本要自己指定一下字符集"utf8mb4"，然后再导入到数据库。为以后索引使用。