Service API 文档

---

概述

本文档将系统阐述自动生成的Service中默认集成的标准API接口及其规范，帮助开发者快速理解其核心功能与调用方式。

---

一、数据操作方法

1. add(data, env)

功能：

• 添加新数据
  参数：
• data：要添加的数据对象（必填）
• env：环境参数（可选）

返回：

• 成功返回添加的 data 对象

异常：

• 数据验证失败时抛出 {"state": "err", "msg": "错误信息", "code": "错误码"}
• 对象已存在时抛出重复错误

触发事件：

• add_before/add_after

使用示例：

var data = {};
owl_xxxService.add(data);

2. get(id, includeDeleted)

功能：

• 获取数据对象
  参数：
• id：对象ID（必填）
• includeDeleted：是否包含已删除数据（默认 false）

返回：

• 对象或 null（未找到或被软删除且未指定 includeDeleted）

使用示例：

var data = owl_xxxService.get(id);

3. getUniqueObj(key, value)

功能：

• 根据被定义为unique:true的字段值获取数据对象

参数：

• key：字段名称
• value：字段值

返回：

• 对象或 null

使用示例：

//使用场景：比如用户表的mobile字段是必须唯一的，那么根据mobile获取数据对象的方法如下
var data = owl_xxxService.getUniqueObj("mobile", "13800138xx1");

4. getObjects(ids)

功能：

• 根据ids批量获取数据对象

参数：

• ids：数据id数组

返回：

• 对象列表（即使对象为空也会一一对应返回）

使用示例：

var ids = ["owl_mall_u_50001","owl_mall_u_50002"];
var dataList = owl_xxxService.getObjects(ids);
dataList.forEach(function (data) {
    //...
});

5. update(data, env)

功能：

• 更新数据
  参数：
• data：更新后的数据对象（需包含 id 和 _v 版本号）
• env：环境参数（可选）

返回：

• 更新后的 data 对象

异常：

• 版本冲突（_v 不匹配）抛出 {"code": "concurrentupdate", ...}
• 数据验证失败

触发事件：

• update_before/update_after

使用示例：

var data = owl_xxxService.get(id);
data.xxx = "";
owl_xxxService.update(data);

6. del(id, userId, ip, ua)

功能：

• 软删除数据
  参数：
• id：对象ID（必填）
• userId：操作用户ID
• ip：操作IP
• ua：用户代理

返回：

• 无

触发事件：

• delete_before/delete_after

使用示例：

owl_xxxService.del(id);

---

二、查询与索引方法

1. search(mfilters, searchArgs, keyword, from, pageSize, sort, dataSource, isRecycleBin, meta_fields)

功能：

• 复杂搜索

参数：

• mfilters：过滤条件
• searchArgs：键值对搜索条件（如 {"name": "test"}）
• keyword：全文搜索关键词
• from/pageSize：分页参数
• sort：排序规则（如 [{"owl_createTime": {order: "desc"}}]）
• dataSource：数据源（如指定ES索引）
• isRecycleBin：是否搜索回收站

返回：

• {state: 'ok', list: 数据列表, total: 总数}

使用示例：

var keyword = null;
var start = 0;
var page_size = 1;

var searchArgs = {}
searchArgs.state = "1";

var searchResult = owl_xxxService.search(null, searchArgs, keyword, start, page_size, null);
if (searchResult.state === 'ok') {
    var listData = searchResult.list;
    var total = searchResult.total.value;
    
    //...
}

2. count(mfilters, searchArgs, keyword, dataSource, isRecycleBin, meta_fields)

功能：

• 统计匹配记录数

参数：

• 同search方法

返回：

• 整数（匹配记录数）

使用示例：

var keyword = null;
var start = 0;
var page_size = 1;

var searchArgs = {}
searchArgs.state = "1";

var total = owl_xxxService.count(null, searchArgs, keyword, start, page_size, null);
//...

3. index(data)

功能：

• 将数据同步到索引

参数：

• data对象

返回：

• 无

特别说明：

• 一般情况下该方法无用，只有在特殊情况下使用。

使用示例：

var data = owl_xxxService.get(id);
owl_xxxService.index(data);

---

三、辅助方法

1. lock(key) / unlock(key)

功能：

• 分布式锁

参数：

• key：锁标识符

使用示例：

var lockId = "lock_" + id;
owl_xxxService.lock(lockId);
try {
    //...
} finally {
    owl_xxxService.unlock(lockId);
}