# 金蝶云星空旗舰版 Java API 参考

## 核心服务类

### BusinessDataServiceHelper

业务数据服务助手，是最常用的数据访问类。

**常用方法：**

```java
// 加载单个数据实体
DynamicObject loadSingle(AppContext ctx, Object pkValue, String entityName)

// 加载多个数据实体
DynamicObject[] load(AppContext ctx, Object[] pkValues, String entityName)

// 按条件查询
DynamicObject[] load(AppContext ctx, String entityName, QFilter[] filters)

// 按条件查询指定字段
DynamicObject[] load(AppContext ctx, String entityName, String selectFields, QFilter[] filters)

// 加载基础资料
DynamicObject loadSingle(AppContext ctx, String entityName, Object pkValue, QFilter[] filters)
```

**使用示例：**

```java
// 加载采购订单
QFilter filter = new QFilter("billno", "=", "PO-001");
DynamicObject[] orders = BusinessDataServiceHelper.load(
    ctx, 
    "PUR_POOrder", 
    new QFilter[]{filter}
);

if (orders.length > 0) {
    DynamicObject order = orders[0];
    String billNo = order.getString("billno");
    BigDecimal totalAmount = order.getBigDecimal("totalamount");
}
```

### DBRoute

数据库路由，用于执行 SQL 查询。

**常用方法：**

```java
// 执行查询，返回 DataSet
DataSet queryDataSet(String routeName, String sql)

// 执行查询带参数
DataSet queryDataSet(String routeName, String sql, Object[] params)

// 执行更新
int execute(String routeName, String sql)

// 执行更新带参数
int execute(String routeName, String sql, Object[] params)
```

**使用示例：**

```java
// 查询采购订单
String sql = "SELECT FBILLNO, FDATE, FAMOUNT FROM T_PUR_POORDER WHERE FDOCUMENTSTATUS = 'C'";
DataSet ds = DBRoute.queryDataSet("default", sql);

while (ds.next()) {
    String billNo = ds.getString("FBILLNO");
    Date date = ds.getDate("FDATE");
    BigDecimal amount = ds.getBigDecimal("FAMOUNT");
}
```

### DataAccess

数据访问层，提供 ORM 功能。

**常用方法：**

```java
// 执行查询
DataSet executeDataSet(String sql)

// 执行更新
int executeUpdate(String sql)

// 批量插入
void insertBatch(String tableName, DataSet data)
```

---

## 插件基类

### AbstractBillPlugIn

表单插件基类，用于表单事件处理。

**常用事件：**

```java
// 表单加载后
public void afterLoadData(EventObject e)

// 字段值变更后
public void afterPropertyChanged(PropertyChangedArgs e)

// 保存前
public void beforeSave(BeforeSaveEventArgs e)

// 保存后
public void afterSave(EventObject e)

// 提交前
public void beforeSubmit(BeforeSubmitEventArgs e)

// 审核前
public void beforeAudit(BeforeAuditEventArgs e)
```

### AbstractOperatePlugin

操作插件基类，用于操作事件处理。

**常用事件：**

```java
// 操作执行前
public void beforeExecuteOperationTransaction(BeforeExecuteOperationTransactionArgs e)

// 操作执行后
public void afterExecuteOperationTransaction(AfterExecuteOperationTransactionArgs e)

// 校验操作
public void onGetValidateRules(GetValidateRulesEventArgs e)
```

### AbstractValidatePlugin

校验插件基类，用于数据校验。

**常用方法：**

```java
// 自定义校验规则
public void onGetValidateRules(GetValidateRulesEventArgs e)

// 校验数据
public void validate(ValidateEventArgs e)
```

---

## 常用工具类

### StringUtils

字符串处理工具。

```java
// 判断是否为空
boolean isEmpty(String str)

// 判断是否不为空
boolean isNotEmpty(String str)

// 去除空格
String trim(String str)
```

### NumberUtils

数字处理工具。

```java
// 判断是否为零
boolean isZero(BigDecimal value)

// 比较大小
int compareTo(BigDecimal v1, BigDecimal v2)

// 格式化数字
String formatNumber(BigDecimal value, int scale)
```

### DateUtils

日期处理工具。

```java
// 获取当前日期
Date getNow()

// 格式化日期
String formatDate(Date date, String pattern)

// 解析日期
Date parseDate(String dateStr, String pattern)
```

---

## 异常处理

### KDException

金蝶自定义异常。

```java
// 抛出异常
throw new KDException("错误编码", "错误信息");

// 带原因的异常
throw new KDException("错误编码", "错误信息", cause);
```

### 异常处理最佳实践

```java
try {
    // 业务逻辑
} catch (KDException e) {
    // 金蝶业务异常
    logger.error("业务处理失败: " + e.getMessage(), e);
    throw e;
} catch (Exception e) {
    // 其他异常
    logger.error("系统异常: " + e.getMessage(), e);
    throw new KDException("SYS001", "系统异常，请联系管理员", e);
}
```