# 1 简介
本文主要介绍编码规则的接口，开发者可以调用这些接口获取到相应编码规则的信息，比如生成新的编码、获取编码规则信息、导出编码规则等。
## 2 接口
## 2.1 获取编码规则
### 2.1.1获取指定实体的全部启用状态的编码规则
**接口名：getAllCodeRuleByEntity**
这个接口会根据实体编码获取可用的编码规则（存在多个可用的编码规则，是因为不同受控组织、不同适用条件下，可以使用不同的编码规则）
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| -------- | -------- | ---- | -------- |
| entityId | String | 是 | 实体编码 |
**返回值**
返回值是CodeRuleInfo对象的集合，CodeRuleInfo对象记录的是编码规则详细信息
**代码示例**
```java
List<CodeRuleInfo> codeRuleInfoList = CodeRuleServiceHelper.getAllCodeRuleByEntity(entityId);
```
### 2.2.2 获取可用的编码规则
**接口名：getCodeRule**
这个接口会根据实体编码、动态对象和组织，获取组织在受控组织下，以及符合适用条件的编码规则
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| entityId | String | 是 | 实体编码 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
| orgId | String | 否 | 受控组织id，为空时默认取动态对象的主业务组织，主业务组织为空时默认取当前用户的组织 |
**返回值**
返回值是CodeRuleInfo对象，记录的是编码规则详细信息
**代码示例**
```java
CodeRuleInfo codeRuleInfo = CodeRuleServiceHelper.getCodeRule(entityId, dataInfo, orgId);
```
## 2.2 生成编号
### 2.2.1 预读编号（预读一个即将使用的编码，但不消耗流水号或断号）
**接口名：readNumber**
这个接口会根据指定实体，动态对象信息和受控组织ID，生成编号。调用后最大号不变，断号记录也不会被消耗。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| --------- | ------------- | ---- | ---------------------------------------------------------- |
| entityNum | String | 是 | 指定实体编码 |
| dataInfo | DynamicObject | 是 | 需要生成编码的实体对象（对象上需要具有生成编码的所需信息） |
| orgId | String | 否 | 指定受控组织ID，如果没有配置受控组织，传null即可 |
**返回值**
返回值是编号，类型为String
**代码示例**
```java
String number = CodeRuleServiceHelper.readNumber(entityId, dataInfo, orgId);
```
### 2.2.2 预读编号（预读一个即将使用的编码，但不消耗流水号或断号）
**接口名：readNumber**
这个接口会根据指定实体，动态对象信息和受控组织ID，生成编号。调用后最大号不变，断号记录也不会被消耗。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| ------------ | ------------- | ---- | ------------------------------------------------------------ |
| codeRuleInfo | CodeRuleInfo | 是 | 编码规则实体 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
**返回值**
返回值是编号，类型为String
**代码示例**
```java
String number = (String)CodeRuleServiceHelper.readNumber(codeRuleInfo, dataInfo);
```
### 2.1.3 生成编号（会消耗流水号或者消耗断号）
**接口名：getNumber**
这个接口会根据指定实体，动态对象信息和受控组织ID，生成编号。调用后最大号会加1，或者消耗断号记录（当前编码规则流水号段开启“断号补偿”时，才会消耗断号表的记录）
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| entityId | String | 是 | 实体编码 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
| orgId | String | 否 | 受控组织id，为空时默认取动态对象的主业务组织，主业务组织为空时默认取当前用户的组织 |
**返回值**
返回值是编号，类型为String
**代码示例**
```java
String number = (String)CodeRuleServiceHelper.getNumber(entityId, dataInfo, orgId);
```
### 2.2.4 生成编号（会消耗流水号或者消耗断号）
**接口名：getNumber**
这个接口会根据指定编码规则和动态对象信息，生成编号。调用后最大号会加1，或者消耗断号记录（当前编码规则流水号段开启“断号补偿”时，才会消耗断号表的记录）
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| ------------ | ------------- | ---- | ------------------------------------------------------------ |
| codeRuleInfo | CodeRuleInfo | 是 | 编码规则实体 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
**返回值**
返回值是编号，类型为String
**代码示例**
```java
String number = CodeRuleServiceHelper.getNumber(codeRuleInfo, dataInfo);
```
### 2.2.5 批量生成编号（生成多个编号，会消耗流水号或者消耗断号）
**接口名：getBatchNumber**
这个接口会一次批量生成指定数量的编号，如果当前编码规则流水号段开启“断号补偿”，会优先消耗断号，然后再消耗流水号，否则只消耗流水号。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| entityId | String | 是 | 实体编码 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
| orgId | String | 否 | 受控组织id，为空时默认取动态对象的主业务组织，主业务组织为空时默认取当前用户的组织 |
| count | int | 是 | 生成的编号数量 |
**返回值**
返回值是String[]，每一个元素就是一个新生成的编号
**代码示例**
```java
String[] numbers = CodeRuleServiceHelper.getBatchNumber(entityId, dataInfo, orgId, count);
```
### 2.2.6 批量生成编号（生成多个编号，会消耗流水号或者消耗断号）
**接口名：getNumbers**
这个接口会批量生成编号, 根据动态对象集合，顺序返回对应的编号，如果当前编码规则流水号段开启“断号补偿”，会优先消耗断号，然后再消耗流水号，否则只消耗流水号。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| --------- | ------------------- | ---- | ------------------------------------------------------------ |
| entityId | String | 是 | 实体编码 |
| dataInfos | List<DynamicObject> | 是 | 动态对象集合（单据或基础资料，对象上需要具有生成编码的所需信息） |
**返回值**
返回值是List<String>，每一个元素就是一个新生成的编号，未匹配到的动态对象也会在返回集合中占用一个位置，值为null
**代码示例**
```java
List<String> numbers = CodeRuleServiceHelper.getNumbers(entityId, dataInfos);
```
## 2.3 回收编号
### 2.3.1 回收指定的编号
**接口名：recycleNumber**
这个接口会根据指定的指定实体、动态对象信息、受控组织id，回收指定的编号。回收编号会记录到断号表中，下次生成编号时会优先消耗回收的编号。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| entityId | String | 是 | 实体编码 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
| orgId | String | 否 | 受控组织id，为空时默认取动态对象的主业务组织，主业务组织为空时默认取当前用户的组织 |
| number | String | 是 | 指定回收的编号 |
**返回值**
返回值是boolean，如果回收成功，返回true，否则为false
**代码示例**
```java
boolean isRecycleNumber = CodeRuleServiceHelper.recycleNumber(entityId, dataInfo, orgId, number);
```
### 2.3.2 回收指定的编号
**接口名：recycleNumber**
这个接口会根据指定的指定实体、动态对象信息、受控组织id，回收指定的编号。回收编号中的流水号会记录到断号表中，下次生成编号时会优先消耗回收的断号。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| ------------ | ------------- | ---- | ------------------------------------------------------------ |
| codeRuleInfo | CodeRuleInfo | 是 | 编码规则实体 |
| dataInfo | DynamicObject | 是 | 动态对象（单据或基础资料，对象上需要具有生成编码的所需信息） |
| number | String | 是 | 指定回收的编号 |
**返回值**
返回值是boolean，如果回收成功，返回true，否则为false
**代码示例**
```java
boolean isRecycleNumber = CodeRuleServiceHelper.recycleNumber(codeRuleInfo, dataInfo, number);
```
### 2.3.3 批量回收编号
**接口名：recycleBatchNumber**
这个接口会根据指定的指定实体、动态对象信息、受控组织id，回收指定的编号。回收编号中的流水号会记录到断号表中，下次生成编号时会优先消耗回收的断号。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| --------- | --------------- | ---- | ------------------------------------------------------------ |
| entityId | String | 是 | 实体编码 |
| dataInfos | DynamicObject[] | 是 | 动态对象集合（单据或基础资料，对象上需要具有生成编码的所需信息） |
| orgId | String | 否 | 受控组织id，为空时默认取动态对象的主业务组织，主业务组织为空时默认取当前用户的组织 |
| numbers | String[] | 是 | 指定回收的编号集合 |
**返回值**
返回值是boolean[]，如果回收成功，返回true，否则为false
**代码示例**
```java
boolean[] isRecycleNumber = CodeRuleServiceHelper.recycleBatchNumber(entityId, dataInfos, orgId, numbers);
```
### 2.3.4 预读断号(预读指定数量的断号，不消耗断号)
**接口名：readIntermitNumber**
这个接口会根据指定的编码规则、编码规则依据和断号数量，预读指定数量的断号，不会消耗断号
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| ------------- | ------------ | ---- | -------------------------- |
| codeRuleInfo | CodeRuleInfo | 是 | 编码规则实体 |
| sortItemValue | String | 是 | 编码规则依据 |
| intermitNum | int | 是 | 断号数量 ( 传-1 获取所有 ) |
**返回值**
返回值是List，预读的断号集合(如果传入的数量比目前数据中断号的数量还多，集合中也仅有已存在的数据，不会补足空值对象)
**代码示例**
```java
List<Integer> intermitNumbers = CodeRuleServiceHelper.readIntermitNumber(codeRuleInfo, sortItemValue, intermitNum);
```
### 2.3.5 消费断号(消耗指定数量的断号)
**接口名：consumeIntermitNumber**
这个接口会根据指定的编码规则、编码规则依据和断号数量，消耗指定数量的断号
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| ------------- | ------------ | ---- | -------------------------- |
| codeRuleInfo | CodeRuleInfo | 是 | 编码规则实体 |
| sortItemValue | String | 是 | 编码规则依据 |
| intermitNum | int | 是 | 断号数量 ( 传-1 获取所有 ) |
**返回值**
返回值是List，消耗的断号集合(如果传入的数量比目前数据中断号的数量还多，集合中也仅有已存在的数据，不会补足空值对象)
**代码示例**
```java
List<Integer> intermitNumbers = CodeRuleServiceHelper.consumeIntermitNumber(codeRuleInfo, sortItemValue, intermitNum);
```
## 2.4 导出编码规则
### 2.4.1 根据实体标识导出编码规则
**接口名：exportCodeRuleByEntityID**
这个接口会根据指定实体集合，导出编码规则的信息。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| ------------ | -------- | ---- | ---------------------------------- |
| entityIdList | List | 是 | 指定的要导出编码规则的实体编码列表 |
**返回值**
返回值是List，每一个CoderuleFile对象中有sql脚本，即用于预置编码规则的SQL
**代码示例**
```java
List<CoderuleFile> codeRuleFiles = CodeRuleServiceHelper.exportCodeRuleByEntityID(entityIdList);
```
### 2.4.2 根据应用id导出编码规则
**接口名：exportCodeRuleByAppID**
这个接口会根据指定应用ID列表，导出编码规则的信息。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| --------- | -------- | ---- | -------------------------------- |
| appIdList | List | 是 | 指定的要导出编码规则的应用ID列表 |
**返回值**
返回值是List，每一个CoderuleFile对象中有sql脚本，即用于预置编码规则的SQL
**代码示例**
```java
List<CoderuleFile> codeRuleFiles = CodeRuleServiceHelper.exportCodeRuleByAppID(appIdList);
```
### 2.4.3 根据编码id导出编码规则
**接口名：exportCodeRuleByCoderuleID**
这个接口会根据指定编码规则ID列表，导出编码规则的信息。
**参数说明**
| 参数名称 | 数据类型 | 必选 | 说明 |
| -------------- | -------- | ---- | ---------------------------- |
| coderuleIdList | List | 是 | 指定的要导出编码规则的ID列表 |
**返回值**
返回值是List，每一个CoderuleFile对象中有sql脚本，即用于预置编码规则的SQL
**代码示例**
```java
List<CoderuleFile> codeRuleFiles = CodeRuleServiceHelper.exportCodeRuleByCoderuleID(coderuleIdList);
```
