# 《编码规则服务层开发规范》
云苍穹平台的编码规则是标准功能之一, 无需配置即可支持多种场景的编码生成.
但是也有很多场景覆盖不到, 需要业务或二开做再次开发, 这时就需要了解我们的编码规则服务层, 以及 **开发规范** .
具体的服务层使用方式可参考 [金蝶云生态门户](https://dev.kingdee.com/index/docsNew/12b50160-a080-499f-9026-a3502f9993fb) 上的接口文档内容, 有详细的 API 介绍. 这里主要规范几个开发过程中, 容易被忽视的问题.
## 1 注意区分 API 接口的功能
编码规则服务层中有两个重要接口, 如果没分清各自的场景就任意使用, 会造成编码重复的可能.
```java
// 读取编号 (多次读取都会是同一个编号)
static String readNumber(String entityId, DynamicObject dataInfo, String orgId);
```
```java
// 生成编号 (多次读取编号的流水号会自增)
static String getNumber(String entityId, DynamicObject dataInfo, String sorgId);
```
注意这里流水号的变化区别, `readNumber` 代表只读模式, `getNumber` 代表消费模式. 如果需要给每个单生成一个唯一编号, 应该使用 **消费模式**.
## 2 调用时入参的数据包信息要完整
可能你早就注意到了, API 接口中多数是需要传入 `DynamicObject` 这个动态对象数据包的.
为什么需要它? 因为编码规则的配置也是需要 **依赖单据上的数据**. 比如编码规则的配置中有配置 "业务对象字段" 或是 "业务对象日期" (如下图), 那就需要得到入参数据包的相关字段值, 才能拼装出正确的编号.
没有传递这些你配置相关的信息, 构建出来的编号就是不完整的, 需要注意这点.
## *3 开发表单插件时的通用规范
### 3.1 使用 SaveServiceHelper 的隐患
如果不需要自行编写调用编码规则服务层 API, 但是有些其他功能需要编写表单插件, 那么有个规范就要注意了!
在编写表单插件时, 如果自行使用 `SaveServiceHelper#save` 方法把单据直接保存入库, **会造成编码规则功能无法生成唯一编号**. 最后效果是可能这个单据用的 "只读模式" 的编号入库, 有 **重复生成编号的隐患**
为什么会有这个问题, 在表单插件调用 `SaveServiceHelper#save` 为什么会造成没有生成唯一编号 ?
关键点在于编码规则功能生成唯一编号的时机. 打开一张单据, 看到的自动生成的编号仅仅是 "只读模式" 下的预读编号, 相当于一个示例, 不具有唯一性. 真正点击 "保存" 或 "提交" 时才会生成唯一编号. **在这个生成时机之前, 如果把数据直接入库, 入库的编号自然是不具备唯一性的**.
用图形解释正常使用, 以及表单插件干预后的区别, 正常流程如下图:
插件干预后的效果如下图:
### 3.2 如何解决
使用 `kd.bos.servicehelper.operation.OperationServiceHelper#executeOperate` 调用保存操作, 这种方式会在保存入库的同时, 也调用操作相关的插件.
