# 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，
