适用范围：

目录

• 目录
• 摘要
• 数据创建
  • create
  • batchCreate
  • copyByRule
• 数据更新
  • update.increment
  • update.edit
  • update.byQuery
  • batchUpdate
  • editTeamMember
• 数据删除
  • directDelete
  • batchDelete
  • deleteTeamMember
  • bulkDelete
  • delete
• 数据查询
  • find
  • findOne
  • findById
  • findByIds
  • select.query
  • select.stream
  • findWithRelated
  • getTeamMember
• 数据校验
  • duplicateSearch
• 团队成员管理
  • replaceOutTeamMember
  • addTeamMember
  • addOutTeamMember
  • changeOwner
  • batchChangeOwner
• 数据锁定
  • lock
  • unlock
  • batchLock
  • batchUnlock
• 数据作废与恢复
  • remove
  • batchRemove
  • bulkRecover
• 数据聚合
  • aggregate.groupBy
  • aggregate.simple
• 对象描述查询
  • getOptionName
  • findDescribe
  • getOptionInfo
  • getMappingRule
  • getCascadeOption
• 其他功能
  • merge
• 参考类型
  • CreateAttribute
  • UpdateAttribute
  • ActionAttribute
  • RemoveAttribute
  • BatchUpdateAttribute
  • FindAttribute
  • SelectAttribute
  • FQLAttribute
  • OptionAttribute
  • TeamMemberAttribute
  • OutTeamMemberAttribute
  • QueryOperator
• 使用建议
  • 推荐优先使用
  • 高风险API
• 原文问题修复记录
• 版本记录
• 背景说明
• 适用场景
• 前置条件
• 操作步骤
• 注意事项

摘要

本文档的概要说明如下： 本文档介绍 Fx.object 的API定义、使用方式及相关说明。

• 作为 Fx.object 的主入口文档使用
• 优先解决原文中的结构混乱、签名不一致、导航困难问题
• 保留原文核心API信息，压缩冗长模板内容

说明：

• 原文部分方法摘要、正文和示例存在不一致。本文对明显冲突处做了统一整理。
• 个别签名按正文示例进行了归并整理，这属于基于原文上下文的推定。

数据创建

方法	说明	签名
create	主从对象同时入库	Fx.object.create(String apiName, Map objectData, Map details, CreateAttribute createAttribute)
batchCreate	批量创建，单批最多 500 行	Fx.object.batchCreate(String apiName, List objects, CreateAttribute attribute)
copyByRule	按映射规则复制创建数据	Fx.object.copyByRule(String sourceApiName, String sourceId, String ruleApiName, Map masterPlus, Map detailPlus)

create

主从对象同时入库。

Fx.object.create(String apiName, Map objectData, Map details, CreateAttribute createAttribute)

参数：

参数	类型	必填	说明
apiName	String	是	主对象 API Name
objectData	Map	是	主对象字段值
details	Map	是	从对象数据，键为从对象 API Name
createAttribute	CreateAttribute	是	创建控制参数

返回：

• isError/error: 是否异常
• data: 新建结果
• message: 提示信息

注意：

• details 传空表示不创建从对象
• 查重阻断也可能进入错误分支，需从 data 中取重复信息

最小示例：

Map masterData = ["name": "主从同时新建1", "owner": ["1000"]]
Map detailData = ["object_detail1__c": [["name": "张三1"]]]
def (Boolean error, Map data, String errorMessage) = Fx.object.create(
  "object_1yO4J__c",
  masterData,
  detailData,
  CreateAttribute.builder().build()
)

batchCreate

批量创建数据，单批最多支持 500 行。

Fx.object.batchCreate(String apiName, List objects, CreateAttribute attribute)

参数：

参数	类型	c必填	说明
apiName	String	是	对象 API Name
objects	List[Map]	是	每一项是一条对象数据
attribute	CreateAttribute	是	创建控制参数

返回：

• data: List[Map]

最小示例：

List objects = [
  ["name": "客户A", "owner": ["1000"]],
  ["name": "客户B", "owner": ["1000"]]
]
def (Boolean error, List<Map> data, String errorMessage) = Fx.object.batchCreate(
  "AccountObj",
  objects,
  CreateAttribute.builder().build()
)

copyByRule

按映射规则创建数据。

Fx.object.copyByRule(String sourceApiName, String sourceId, String ruleApiName, Map masterPlus, Map detailPlus)

适用场景：

• 根据映射规则把 A 对象复制为 B 对象
• 在映射基础上补充主对象或从对象字段值

注意：

• 原文明确说明该方法创建的数据可以触发审批流和工作流

最小示例：

Map masterPlus = ["field_wbYI0__c": "方法补充值"]
Map detailPlus = ["object_snpWU__c": [["field_a72ov__c": "明细补充值"]]]
def (Boolean error, Object result, String errorMessage) = Fx.object.copyByRule(
  "object_pbx98__c",
  "66d827e45c1ac90001ede05c",
  "map_y5iy4__c",
  masterPlus,
  detailPlus
)

数据更新

方法	说明	签名
update.increment	增量更新单条数据	Fx.object.update(String apiName, String objectId, Map updateFields, UpdateAttribute attribute)
update.edit	主从覆盖更新	Fx.object.update(String apiName, String objectId, Map updateFields, Map detailData, ActionAttribute actionAttribute)
update.byQuery	按条件批量更新	Fx.object.update(String apiName, QueryTemplate template, Map updateFields, UpdateAttribute attribute)
batchUpdate	底层批量字段更新	Fx.object.batchUpdate(String apiName, Map objects, List fields, BatchUpdateAttribute attribute)
editTeamMember	覆盖编辑内部团队成员	Fx.object.editTeamMember(String apiName, String dataId, List teamMembers, Boolean ignoreSendingRemind)

update.increment

增量更新单条数据。

Fx.object.update(String apiName, String objectId, Map updateFields, UpdateAttribute attribute)

特点：

• 不校验锁定状态
• 不触发编辑按钮前验证、后动作以及验证规则
• 更适合字段级修改

注意：

• 不支持直接更新负责人、公式字段、统计字段等
• 币种、汇率类字段不能被更新为空

最小示例：

Map updateFields = ["name": "新的名称"]
def (Boolean error, Map data, String errorMessage) = Fx.object.update(
  "object_s82CA__c",
  "64b1113e87ec1c0001bfc102",
  updateFields,
  UpdateAttribute.builder().triggerWorkflow(true).build()
)

update.edit

主从覆盖更新。

Fx.object.update(String apiName, String objectId, Map updateFields, Map detailData, ActionAttribute actionAttribute)

特点：

• 适合主从整体重写
• detailData 传空集合会清空从对象
• detailData 传 null 表示不更新从对象

注意：

• 无法更新锁定数据
• 如需锁定数据更新，优先评估 update.increment

最小示例：

Map updateFields = ["name": "主对象名称"]
Map detailData = [
  "object_detail__c": [
    ["name": "明细1"],
    ["name": "明细2"]
  ]
]
def (Boolean error, Map data, String errorMessage) = Fx.object.update(
  "object_qs2nb__c",
  "607d5e3dd02b9f00016507d8",
  updateFields,
  detailData,
  ActionAttribute.create()
)

update.byQuery

按查询条件批量更新。

Fx.object.update(String apiName, QueryTemplate template, Map updateFields, UpdateAttribute attribute)

特点：

• 默认最多更新 1000 条
• 若需更新超过 1000 条，需设置 isAllUpdate=true

注意：

• 原文标注为灰度能力
• 大批量更新耗时较高，原文给出 1000 条约 3 分钟
• 若设置 runBusiness=false 或类似绕过业务逻辑参数，应谨慎评估

最小示例：

QueryTemplate query = QueryTemplate.AND([
  "name": QueryOperator.EQ("主从同时新建1")
])
def (Boolean error, Object result, String errorMessage) = Fx.object.update(
  "object_1yO4J__c",
  query,
  ["field__c": "test"],
  UpdateAttribute.builder().build()
)

batchUpdate

批量更新指定字段。

Fx.object.batchUpdate(String apiName, Map objects, List fields, BatchUpdateAttribute attribute)

参数说明：

• objects 的 key 为数据 ID，value 为待更新字段 Map
• fields 决定本次实际写入的字段范围

高风险说明：

• 原文说明这是偏底层API，接近直接更新数据库
• fields 中出现但 objects 未提供值时，表示清空字段
• 不建议用于计算、统计、引用字段
• 自定义对象单批最多 500 条

推荐：

• 预制对象优先考虑 convert2SingleOperation=true
• 数据量少时，直接循环调用 update.increment 更可控

最小示例：

Map objects = [
  "60acc4a2d040a70001886739": ["field_bVch6__c": "test1"],
  "60acc482d040a70001886582": ["field_bVch6__c": "test2"]
]
List fields = ["field_bVch6__c"]
def (Boolean error, List result, String errorMessage) = Fx.object.batchUpdate(
  "object_8N0H2__c",
  objects,
  fields,
  BatchUpdateAttribute.builder().build()
)

editTeamMember

覆盖编辑内部相关团队。

Fx.object.editTeamMember(String apiName, String dataId, List teamMembers, Boolean ignoreSendingRemind)

团队成员结构：

字段	类型	说明
userId	String	团队成员 ID
permission	Integer	1 只读，2 读写
role	Integer	相关团队角色
type	Integer	成员类型

注意：

• 只能修改内部相关团队
• 原文的角色枚举与示例值不完全一致，实际取值以系统定义为准

最小示例：

List teamMembers = [
  ["userId": "1058", "role": 4, "permission": 1],
  ["userId": "1057", "role": 4, "permission": 2]
]
def result = Fx.object.editTeamMember(
  "AccountObj",
  "36fd270a986842529445bf3d252cca9b",
  teamMembers,
  false
).result() as Map

数据删除

方法	说明	签名
directDelete	直接删库，不可恢复	Fx.object.directDelete(String apiName, String dataId)
batchDelete	批量直接删除	Fx.object.batchDelete(String apiName, List objectIds)
deleteTeamMember	删除团队成员	Fx.object.deleteTeamMember(String apiName, List objectIds, List teamMembers, List outTeamMemberEmployee, Boolean ignoreSendingRemind)
bulkDelete	批量彻底删除已作废数据	Fx.object.bulkDelete(String apiName, List objectIds)
delete	彻底删除单条已作废数据	Fx.object.delete(String apiName, String objectId)

directDelete

直接删除数据库数据，不可恢复。

Fx.object.directDelete(String apiName, String dataId)

这是全篇最危险API之一，只适合确认无误的底层清理场景。

最小示例：

Fx.object.directDelete("object_kFc8w__c", "664dd6c2f7239000076e133f").result()

batchDelete

批量直接删除数据。

Fx.object.batchDelete(String apiName, List objectIds)

注意：

• 不区分对象是否作废
• 会直接彻底删除

最小示例：

Fx.object.batchDelete(
  "object_kFc8w__c",
  ["664dd6c2f7239000076e133f", "664dd6c2f7239000076e1340"]
).result()

deleteTeamMember

删除相关团队成员。

Fx.object.deleteTeamMember(String apiName, List objectIds, List teamMembers, List outTeamMemberEmployee, Boolean ignoreSendingRemind)

外部团队成员结构：

字段	类型	说明
userId	String	下游企业人员 ID
outTenantId	String	下游企业 ID

最小示例：

List objectIds = ["36fd270a986842529445bf3d252cca9b"]
List teamMembers = ["1058"]
List outTeamMemberEmployee = [["userId": "309175511", "outTenantId": "301185430"]]
Fx.object.deleteTeamMember(
  "AccountObj",
  objectIds,
  teamMembers,
  outTeamMemberEmployee,
  false
).result()

bulkDelete

批量彻底删除已作废数据。

Fx.object.bulkDelete(String apiName, List objectIds)

注意：

• 仅用于回收站中已作废数据
• 原文建议单次不要超过 20 条

最小示例：

Fx.object.bulkDelete("object_c6584__c", ["6707d19a8b6d28000716bb05"]).result()

delete

彻底删除单条已作废数据。

Fx.object.delete(String apiName, String objectId)

最小示例：

Fx.object.delete("object_c6584__c", "6707d19a8b6d28000716bb05").result()

数据查询

方法	说明	签名
find	FQL 查询多条	Fx.object.find(String apiName, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)
findOne	FQL 查询单条	Fx.object.findOne(String apiName, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)
findById	按 ID 查询单条	Fx.object.findById(String apiName, String id, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)
findByIds	按 ID 集合查询	Fx.object.findByIds(String apiName, List ids, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)
select.query	SQL 查询	Fx.object.select(String sql, SelectAttribute selectAttribute)
select.stream	大数据量 SQL 流式分页查询	Fx.object.select(String sql, SelectAttribute selectAttribute, Closure consumer)
findWithRelated	查找关联或主从联查	Fx.object.findWithRelated(String apiName, String relatedField, List criteria, Map orderBy, Integer limit, Integer skip, ActionAttribute attribute)
getTeamMember	获取团队成员	Fx.object.getTeamMember(String apiName, String dataId)

find

FQL 查询多条数据。

Fx.object.find(String apiName, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)

返回体重点：

字段	类型	说明
size	Integer	本次返回条数
total	Integer	总条数
dataList	List	数据列表

最小示例：

FQLAttribute fql = FQLAttribute.builder()
  .columns(["_id", "name"])
  .queryTemplate(QueryTemplate.AND(["name": QueryOperator.EQ("account1")]))
  .build()
SelectAttribute selectAttribute = SelectAttribute.builder().needInvalid(false).build()
def (Boolean error, QueryResult queryResult, String errorMessage) = Fx.object.find(
  "AccountObj",
  fql,
  selectAttribute
)

findOne

FQL 查询单条数据。

Fx.object.findOne(String apiName, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)

建议：

• 查单条优先使用该API，而不是 find + limit 1

最小示例：

FQLAttribute fql = FQLAttribute.builder()
  .columns(["_id", "name"])
  .queryTemplate(QueryTemplate.AND(["_id": QueryOperator.EQ("6177cde7a0cb410001930ad0")]))
  .build()
def (Boolean error, Map data, String errorMessage) = Fx.object.findOne(
  "AccountObj",
  fql,
  SelectAttribute.builder().build()
)

findById

按 ID 查询单条数据。

Fx.object.findById(String apiName, String id, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)

最小示例：

FQLAttribute fql = FQLAttribute.builder()
  .columns(["_id", "name"])
  .build()
def (Boolean error, Map data, String errorMessage) = Fx.object.findById(
  "AccountObj",
  "6177cde7a0cb410001930ad0",
  fql,
  SelectAttribute.builder().build()
)

findByIds

按 ID 集合查询。

Fx.object.findByIds(String apiName, List ids, FQLAttribute fqlAttribute, SelectAttribute selectAttribute)

最小示例：

FQLAttribute fql = FQLAttribute.builder()
  .columns(["_id", "name"])
  .build()
def (Boolean error, QueryResult result, String errorMessage) = Fx.object.findByIds(
  "AccountObj",
  ["6177cde7a0cb410001930ad0", "6177cde7a0cb410001930ad1"],
  fql,
  SelectAttribute.builder().build()
)

select.query

SQL 查询。

Fx.object.select(String sql, SelectAttribute selectAttribute)

注意：

• 原文说 selectAttribute 非必填，但摘要表中标成必填；本文按“可选”理解
• 返回结果可能是 QueryResult，也可能是聚合 List

最小示例：

String sql = "select _id, name from AccountObj where create_time > 0 limit 10 offset 0"
SelectAttribute attribute = SelectAttribute.builder().needInvalid(false).build()
def result = Fx.object.select(sql, attribute).result() as QueryResult

select.stream

大数据量 SQL 流式分页查询。

Fx.object.select(String sql, SelectAttribute selectAttribute, Closure consumer)

适用场景：

• 查全量数据
• 需要边查边处理

限制：

• 不支持 order by
• 不支持 limit

最小示例：

String sql = "select _id, name from object_227xW__c where field_rzv5M__c > 100"
Fx.object.select(sql, SelectAttribute.builder().build(), { list ->
  list.each { row ->
    log.info((row as Map)["name"])
  }
}).result()

findWithRelated

通过查找关联或主从关系做联查。

Fx.object.findWithRelated(String apiName, String relatedField, List criteria, Map orderBy, Integer limit, Integer skip, ActionAttribute attribute)

说明：

• 查找关联场景：apiName 传相关对象 API Name，relatedField 传查找关联字段
• 主从场景：apiName 传从对象 API Name，relatedField 传主从关系字段

最小示例：

def attribute = ActionAttribute.build {
  forceQueryFromDB = false
}
def (Boolean error, QueryResult result, String errorMessage) = Fx.object.findWithRelated(
  "object_0uyAd__c",
  "field_YjJ6d__c",
  [["_id": "60868215965b1900014c0d35"]],
  ["create_time": 1],
  10,
  0,
  attribute
)

getTeamMember

获取团队成员信息。

Fx.object.getTeamMember(String apiName, String dataId)

返回重点：

• teamMemberEmployee
• teamMemberRole
• teamMemberPermissionType
• teamMemberType
• outTenantId
• teamMemberName

最小示例：

def rst = Fx.object.getTeamMember("AccountObj", "83cf73d957924284a96e9c44ebb333ec").result() as List

数据校验

方法	说明	签名
duplicateSearch	获取查重结果	Fx.object.duplicateSearch(String apiName, String type, Map data, String relatedApiName, Integer pageNumber, Integer pageSize)

duplicateSearch

获取查重结果。

Fx.object.duplicateSearch(String apiName, String type, Map data, String relatedApiName, Integer pageNumber, Integer pageSize)

常见 type：

• NEW
• TOOL

结果重点：

• dataList
• matchType
• keepSave

最小示例：

Map data = ["object_describe_api_name": "object_zPSCw__c", "field_619D3__c": "123"]
def (Boolean error, Map result, String errorMessage) = Fx.object.duplicateSearch(
  "object_zPSCw__c",
  "NEW",
  data,
  null,
  1,
  20
)

团队成员管理

方法	说明	签名
replaceOutTeamMember	全量替换外部成员	Fx.object.replaceOutTeamMember(String apiName, String objectId, Object outTeamMembers, Boolean ignoreSendingRemind)
addTeamMember	添加内部团队成员	Fx.object.addTeamMember(String apiName, String objectId, Object teamMemberAttribute)
addOutTeamMember	添加外部团队成员	Fx.object.addOutTeamMember(String apiName, String objectId, Object outTeamMemberAttribute)
changeOwner	单条更换负责人	Fx.object.changeOwner(String apiName, String dataId, String ownerId, ActionAttribute attribute)
batchChangeOwner	批量更换负责人	Fx.object.batchChangeOwner(String apiName, List changeData, ActionAttribute attribute)

replaceOutTeamMember

全量替换所有外部成员。

Fx.object.replaceOutTeamMember(String apiName, String objectId, Object outTeamMembers, Boolean ignoreSendingRemind)

注意：

• 不可替换外部负责人

最小示例：

def member = TeamMemberEmployee.builder()
  .userId("309175511")
  .outTenantId("301185430")
  .build()
def outMembers = OutTeamMemberAttribute.createEmployMember(
  [member],
  TeamMemberEnum.Permission.READANDWRITE
)
def result = Fx.object.replaceOutTeamMember(
  "object_qep6N__c",
  "61848edfd9007e00019ee222",
  [outMembers],
  false
)

addTeamMember

添加内部团队成员。

Fx.object.addTeamMember(String apiName, String objectId, Object teamMemberAttribute)

支持添加：

• 人员
• 用户组
• 部门
• 角色

注意：

• 不能添加负责人
• 若成员已存在，则会更新原成员信息

最小示例：

def teamMember = TeamMemberAttribute.createEmployMember(
  ["1027"],
  TeamMemberEnum.Role.NORMAL_STAFF,
  TeamMemberEnum.Permission.READONLY
)
Fx.object.addTeamMember("object_qep6N__c", "61848edfd9007e00019ee222", teamMember).result()

addOutTeamMember

添加外部团队成员。

Fx.object.addOutTeamMember(String apiName, String objectId, Object outTeamMemberAttribute)

支持添加：

• 外部人员
• 下游企业
• 外部角色
• 下游企业组

最小示例：

def member = TeamMemberEmployee.builder()
  .userId("309175511")
  .outTenantId("301185430")
  .build()
def teamMember = OutTeamMemberAttribute.createEmployMember(
  [member],
  TeamMemberEnum.Permission.READANDWRITE
)
Fx.object.addOutTeamMember("object_qep6N__c", "61848edfd9007e00019ee222", teamMember).result()

changeOwner

单条更换负责人。

Fx.object.changeOwner(String apiName, String dataId, String ownerId, ActionAttribute attribute)

最小示例：

Fx.object.changeOwner(
  "AccountObj",
  "ed47841898054749a2ec9be9e6e5d728",
  "1001",
  ActionAttribute.create()
).result()

batchChangeOwner

批量更换负责人。

Fx.object.batchChangeOwner(String apiName, List changeData, ActionAttribute attribute)

说明：

• 原文签名写 changeData 结构为 dataId/userId
• 原文示例写成 objectId/ownerId
• 本文建议以实际运行时API定义为准，落地前先在测试环境确认字段名

最小示例：

List changeData = [
  ["objectId": "5f86b47b1bdac00001f2c300", "ownerId": ["-10000"]],
  ["objectId": "5f86b4a71bdac00001f2d232", "ownerId": ["-10000"]]
]
Fx.object.batchChangeOwner("object_i66LR__c", changeData, ActionAttribute.create()).result()

数据锁定

方法	说明	签名
lock	锁定数据	Fx.object.lock(String apiName, String dataId, Boolean cascadeDetail)
unlock	解锁数据	Fx.object.unlock(String apiName, String dataId, Boolean cascadeDetail)
batchLock	批量锁定	Fx.object.batchLock(String apiName, List objectIds, Boolean cascadeDetail)
batchUnlock	批量解锁	Fx.object.batchUnlock(String apiName, List objectIds, Boolean cascadeDetail)

lock

锁定数据。

Fx.object.lock(String apiName, String dataId, Boolean cascadeDetail)

最小示例：

Fx.object.lock("AccountObj", "e6a338ae8a944cdfb2bae737db1aa12f", true).result()

unlock

解锁数据。

Fx.object.unlock(String apiName, String dataId, Boolean cascadeDetail)

最小示例：

Fx.object.unlock("AccountObj", "e6a338ae8a944cdfb2bae737db1aa12f", true).result()

batchLock

批量锁定数据。

Fx.object.batchLock(String apiName, List objectIds, Boolean cascadeDetail)

最小示例：

Fx.object.batchLock("AccountObj", ["e6a338ae8a944cdfb2bae737db1aa12f"], true).result()

batchUnlock

批量解锁数据。

Fx.object.batchUnlock(String apiName, List objectIds, Boolean cascadeDetail)

最小示例：

Fx.object.batchUnlock("AccountObj", ["e6a338ae8a944cdfb2bae737db1aa12f"], true).result()

数据作废与恢复

方法	说明	签名
remove	作废单条数据	Fx.object.remove(String apiName, String id)
batchRemove	批量作废	Fx.object.batchRemove(String apiName, List objectIds, RemoveAttribute attribute)
bulkRecover	批量恢复已作废数据	Fx.object.bulkRecover(String apiName, List objectIds)

remove

作废单条数据，放入回收站。

Fx.object.remove(String apiName, String id)

最小示例：

def rst = Fx.object.remove("AccountObj", "ed47841898054749a2ec9be9e6e5d728").result() as Map

batchRemove

批量作废业务数据。

Fx.object.batchRemove(String apiName, List objectIds, RemoveAttribute attribute)

注意：

• 只有生命状态为正常的数据才能被作废
• 原文把 attribute 标成“可选参数”，但是否必填列写成“是”；本文按“建议传入”理解

最小示例：

RemoveAttribute attribute = RemoveAttribute.builder()
  .triggerApprovalFlow(false)
  .triggerWorkflow(false)
  .skipFunctionAction(true)
  .build()
def (Boolean error, Object data, String errorMessage) = Fx.object.batchRemove(
  "object_kFc8w__c",
  ["664dd6c2f7239000076e133f"],
  attribute
)

bulkRecover

批量恢复已作废数据。

Fx.object.bulkRecover(String apiName, List objectIds)

注意：

• 原文建议单次不要超过 20 条

最小示例：

def rst = Fx.object.bulkRecover("object_c6584__c", ["6707d19a8b6d28000716bb05"]).result() as Map

数据聚合

方法	说明	签名
aggregate.groupBy	按字段分组聚合	Fx.object.aggregate(String apiName, Aggregate type, List criteria, String groupByField, FindAttribute attribute)
aggregate.simple	条件聚合	Fx.object.aggregate(String apiName, Aggregate type, Integer decimalScale, List criteria, FindAttribute attribute)

aggregate.groupBy

按字段分组聚合。

Fx.object.aggregate(String apiName, Aggregate type, List criteria, String groupByField, FindAttribute attribute)

典型场景：

• 按某字段分组做 SUM/COUNT/MAX/MIN/AVG

最小示例：

def (Boolean error, List data, String errorMessage) = Fx.object.aggregate(
  "object_227xW__c",
  Aggregate.MAX("field_rzv5M__c"),
  [["field_rzv5M__c": Operator.GT(10)]],
  "field_qC2yp__c",
  FindAttribute.getDefaultFindAttribute()
)

aggregate.simple

按条件聚合。

Fx.object.aggregate(String apiName, Aggregate type, Integer decimalScale, List criteria, FindAttribute attribute)

说明：

• 原文 decimalScale 描述写错成“对象的 api 名称”，这里按字段含义整理为“小数精度”

注意：

• 默认从 ES 聚合
• 若对一致性要求高，优先使用 forceQueryFromDB=true

最小示例：

def (Boolean error, Object result, String errorMessage) = Fx.object.aggregate(
  "object_m4S5S__c",
  Aggregate.AVG("field_k2y2d__c"),
  2,
  [["field_Oo1K2__c": Operator.GT("200")]],
  FindAttribute.getDefaultFindAttribute()
)

对象描述查询

方法	说明	签名
getOptionName	根据 value 取选项名称	Fx.object.getOptionName(String objectApiName, String fieldApiName, String value)
findDescribe	查询对象描述	Fx.object.findDescribe(String apiName)
getOptionInfo	获取单选/多选/业务类型 value 映射	Fx.object.getOptionInfo(String apiName, String fieldApiName)
getMappingRule	获取映射规则描述	Fx.object.getMappingRule(String mappingRuleApiName)
getCascadeOption	获取单选级联配置	Fx.object.getCascadeOption(String apiName, String fieldApiName, String optionValue)
getCascadeOption.attribute	按属性对象获取单选级联配置	Fx.object.getCascadeOption(OptionAttribute optionAttribute)

getOptionName

获取单选、多选或业务类型的名称。

Fx.object.getOptionName(String objectApiName, String fieldApiName, String value)

说明：

• 原文字段名写成 filedAPIName，本文统一为 fieldApiName

最小示例：

def (Boolean error, Object data, String errorMessage) = Fx.object.getOptionName(
  "object_kFc8w__c",
  "mc_currency",
  "CNY"
)

findDescribe

查询对象描述信息，例如字段、单选信息等。

Fx.object.findDescribe(String apiName)

说明：

• 原文摘要写成无参
• 但正文示例实际传入了对象 API Name
• 本文按示例和语义统一为带 apiName

最小示例：

def rst = Fx.object.findDescribe("object_qep6N__c").result() as Map

getOptionInfo

查询单选、多选、业务类型对应的 value 映射。

Fx.object.getOptionInfo(String apiName, String fieldApiName)

返回特点：

• 会同时提供 label -> value 和 value -> label 的双向映射

最小示例：

def rst = Fx.object.getOptionInfo("EnterpriseInfoObj", "enterprise_type").result() as Map

getMappingRule

查询映射规则描述。

Fx.object.getMappingRule(String mappingRuleApiName)

返回重点：

• ruleList
• sourceApiName
• targetApiName
• fieldMapping

最小示例：

def rst = Fx.object.getMappingRule("map_ri5oc__c").result() as Map

getCascadeOption

获取单选级联关系配置。

推荐写法一：

Fx.object.getCascadeOption(String apiName, String fieldApiName, String optionValue)

推荐写法二：

Fx.object.getCascadeOption(OptionAttribute optionAttribute)

说明：

• 原文签名和示例不一致
• 本文保留两种写法，其中 OptionAttribute 写法与原文示例一致

最小示例：

def optionAttribute = OptionAttribute.builder()
  .apiName("object_qep6N__c")
  .fieldApiName("field_16Yl4__c")
  .optionValue("C3mG8ou09")
  .build()
def rst = Fx.object.getCascadeOption(optionAttribute).result() as Map

其他功能

方法	说明	签名
merge	合并客户或线索	Fx.object.merge(String apiName, String targetDataId, List sourceDataIds, Map objectData)

merge

对象合并，目前只支持客户和线索对象。

Fx.object.merge(String apiName, String targetDataId, List sourceDataIds, Map objectData)

说明：

• 原文摘要写成无参
• 原文示例明确给出了 4 个参数
• 本文按示例统一为四参签名

最小示例：

Map objectData = ["name": "测试合并10", "mobile": "1884***4501"]
Fx.object.merge(
  "LeadsObj",
  "61b9aed9a3c69e0001351a87",
  ["61b9af07a3c69e000135213f"],
  objectData
).result()

参考类型

CreateAttribute

字段说明

字段	类型	说明
calculateDefaultValue	boolean	是否计算默认值，默认为 false
fillOutOwner	boolean	是否填充外部负责人，业务逻辑接口使用，元数据接口不使用，默认否
designatedCreatedBy	boolean	是否指定创建人（包含所有从对象都是指定创建人），默认是系统，可以在参数 objectData 中指定 key: created_by (List<String>)，传入人员的 id 可以设置创建人
specifyTime	boolean	是否指定创建时间，一般使用当前时间，默认否
skipAfterFunction	boolean	是否跳过后动作函数，业务逻辑接口使用，元数据接口不使用，默认为 false
triggerWorkflow	boolean	是否触发工作流，默认触发
duplicateSearch	boolean	是否查重，元数据接口不使用该字段（元数据底层有实现查重），默认查重
enableRealTimeCalculateDataAuth	boolean	是否实时计算数据权限，默认为 false
skipFunctionAction	boolean	是否跳过前验证函数，默认为 false 不跳过
forceQueryFromDB	boolean	是否强制从数据库中查询，和老接口对齐，暂时不区分
triggerApprovalFlow	boolean	是否触发审批流，默认触发

最小示例

CreateAttribute attr = CreateAttribute.builder()
    .triggerWorkflow(true)
    .duplicateSearch(true)
    .build()

UpdateAttribute

字段说明

字段	类型	说明
isAllUpdate	boolean	是否更新所有数据，当为 false 的时候最多只更新 1000 条数据，为 true 的时候不做数量限制，默认为 false
triggerWorkflow	boolean	是否触发工作流，默认触发；不支持触发审批流
duplicateSearch	boolean	是否查重，默认查重
modifiedBySelf	boolean	是否指定当前用户为修改人；默认为 false 代表系统更新，更新人是系统；设置为 true 代表当前用户更新，更新人是当前用户；可能存在数据权限不足更新失败的情况；不是所有场景都可以获取到当前用户，此时也会默认系统
skipImmutableFieldValidate	boolean	是否跳过不可变字段验证，默认 false；主要应用于上游数据同步到下游时，下游是否可对锁定字段编辑
applyDataPrivilegeCheck	boolean	是否校验数据权限，默认不校验

最小示例

UpdateAttribute attr = UpdateAttribute.builder()
    .triggerWorkflow(true)
    .isAllUpdate(false)
    .build()

ActionAttribute

字段说明

字段	类型	说明
fillOutOwner	boolean	是否填充外部负责人，默认为 false
designatedCreatedBy	boolean	是否指定创建人（包含所有从对象都是指定创建人），默认是系统，可以在参数 objectData 中指定 key: created_by (List<String>)，传入人员的 id 可以设置创建人
specifyTime	boolean	是否指定创建时间，仅创建接口使用，默认为 false
skipAfterFunction	boolean	在 create、update 控制是否跳过后动作函数，默认为 false
triggerWorkflow	boolean	是否触发工作流，默认触发
duplicateSearch	boolean	是否查重，默认为 true
modifiedBySelf	boolean	是否指定当前用户为修改人，仅更新接口使用；默认为 false 代表系统更新，更新人是系统；设置为 true 代表当前用户更新，更新人是当前用户；可能存在数据权限不足更新失败的情况；不是所有场景都可以获取到当前用户，此时也会默认系统
skipFunctionAction	boolean	在 create、update 只控制是否跳过前验证函数，其他的如 bulkRemove、changeOwner、batchChangeOwner 同时控制跳过前后函数
skipImmutableFieldValidate	boolean	是否跳过不可变字段验证，默认 false；主要应用于上游数据同步到下游时，下游是否可对锁定字段编辑
forceQueryFromDB	boolean	是否强制从数据库中查询，默认为 false
triggerApprovalFlow	boolean	是否触发审批流，默认触发

快捷方法

• ActionAttribute.create() — 快速构造方式，所有属性都是默认值
• ActionAttribute.build { ... } — 构建器构造属性，在闭包中进行属性赋值

最小示例

// 使用 builder
ActionAttribute attr = ActionAttribute.builder()
    .triggerWorkflow(true)
    .forceQueryFromDB(false)
    .build()

// 使用快捷方法 create
ActionAttribute attr2 = ActionAttribute.create()

// 使用 build 闭包方式
ActionAttribute.build {
    forceQueryFromDB = false
}

RemoveAttribute

字段	类型	说明
triggerWorkflow	boolean	是否触发工作流
triggerApprovalFlow	boolean	是否触发审批流
skipFunctionAction	boolean	是否跳过前后动作方法
skipButtonConditions	boolean	是否跳过按钮显示条件校验
useCurrentIdentity	boolean	是否使用当前用户身份

最小示例：

RemoveAttribute attr = RemoveAttribute.builder()
    .triggerWorkflow(false)
    .skipFunctionAction(true)
    .build()

BatchUpdateAttribute

字段说明

字段	类型	说明
triggerWorkflow	boolean	是否触发工作流，默认触发
convert2SingleOperation	boolean	预制对象存在特殊业务逻辑不支持批量更新，可以通过设置参数为 true，转为循环单条更新来处理（速度会比较慢）；默认 false，不转为单条更新；仅预制对象可转为单条更新

最小示例

BatchUpdateAttribute attr = BatchUpdateAttribute.builder()
    .triggerWorkflow(true)
    .convert2SingleOperation(true)
    .build()

FindAttribute

字段	类型	说明
returnRelatedValue	Boolean	是否返回相关数据 value
extendFieldApiNames	List[String]	需要补充 __r 的字段
forceQueryFromDB	Boolean	是否从 DB 查询

最小示例：

// 使用默认配置
FindAttribute attr = FindAttribute.getDefaultFindAttribute()

// 自定义配置
FindAttribute attr = FindAttribute.builder()
    .forceQueryFromDB(true)
    .returnRelatedValue(true)
    .build()

SelectAttribute

字段说明

参数名称	object	描述
needRelevantTeam	java.lang.Boolean	是否需要相关团队，默认否
needQuote	java.lang.Boolean	是否实时计算引用字段，默认是
paginationOptimization	java.lang.Boolean	是否执行分页优化，默认否，当需要大量数据分页操作时可以设置为true
fillExtendInfo	java.lang.Boolean	是否需要自动填充__r字段，例如人员信息，默认不填充
needCount	java.lang.Boolean	是否返回匹配条件的数量总数，默认否
validateFilterField	java.lang.Boolean	是否校验筛选字段，7.6日前默认为false不校验(可手动改为true校验)，7.6后默认为true校验（修改为false不生效）；
calculateCount	java.lang.Boolean	是否实时计算统计字段，默认是
searchRichTextExtra	java.lang.Boolean	是否返回完整的富文本/协同富文本/长文本，默认否
filterByDataRight	java.lang.Boolean	是否根据数据权限过滤数据（默认false）
needCalculate	java.lang.Boolean	查询时是否执行计算字段，默认是
needInvalid	java.lang.Boolean	是否返回已作废的数据，默认否
needOptionLabel	java.lang.Boolean	是否返回选项名称，默认否，该参数为true会补充单选多选label 放到${字段apiName}__r中
convertQuoteForView	java.lang.Boolean	是否以页面展示的格式返回引用字段（默认false），该参数主要针对引用单选、多选、布尔、业务类型的字段，默认返回value，设置为true以后，返回的是label，并通过${字段apiName}__v返回value，以及${字段apiName}__o返回其他选项。

最小示例

SelectAttribute attr = SelectAttribute.builder()
    .needInvalid(false)
    .needCalculate(true)
    .needCount(true)
    .build()

FQLAttribute

字段说明

参数名称	object	描述
queryTemplate	com.fxiaoke.functions.model.QueryTemplate	WHERE [查询条件]，详见QueryTemplate说明
columns	java.util.List[java.lang.String]	SELECT [字段]
limit	java.lang.Integer	LIMIT [查询数量] 默认10，上限100
orderBy	java.util.Map	ORDER BY [排序字段] 例如 ["_id":1] 1升序 -1降序
skip	java.lang.Integer	SKIP [翻页条目]

最小示例

FQLAttribute fql = FQLAttribute.builder()
    .queryTemplate(QueryTemplate.AND(["name": QueryOperator.LIKE("%test%")]))
    .columns(["_id", "name", "owner"])
    .limit(20)
    .orderBy(["create_time": -1])
    .skip(0)
    .build()

OptionAttribute

字段说明

参数名称	object	描述
apiName	java.lang.String	对象apiName
optionValue	java.lang.String	父单选选项值
fieldApiName	java.lang.String	父单选字段apiName

最小示例

OptionAttribute attr = OptionAttribute.builder()
    .apiName("object_qep6N__c")
    .optionValue("option_id")
    .fieldApiName("field_16Yl4__c")
    .build()

TeamMemberAttribute

1. createEmployMember 添加内部成员

TeamMemberAttribute.createEmployMember()

Groovy 举例

def employTeamMember = TeamMemberAttribute.createEmployMember(["1027"], TeamMemberEnum.Role.NORMAL_STAFF, TeamMemberEnum.Permission.READONLY)
//employTeamMember.setIgnoreSendingRemind(true) // 可选参数，是否忽略发送CRM提醒。默认false
//employTeamMember.setRealtime(true) // 可选参数，是否实时生效。默认false
def employTeamResult = Fx.object.addTeamMember("object_qep6N__c","61848edfd9007e00019ee222", employTeamMember)
log.info(employTeamResult)

2. createGroupMember 添加用户组成员

TeamMemberAttribute.createGroupMember()

Groovy 举例

def groupTeamMember = TeamMemberAttribute.createGroupMember(["6152bd0de3e51c0001ec4de3"], TeamMemberEnum.Role.NORMAL_STAFF, TeamMemberEnum.Permission.READANDWRITE)
//groupTeamMember.setIgnoreSendingRemind(true) // 可选参数，是否忽略发送CRM提醒。默认false
//groupTeamMember.setRealtime(true) // 可选参数，是否实时生效。默认false
def groupTeamResult = Fx.object.addTeamMember("object_qep6N__c","61848edfd9007e00019ee222", groupTeamMember)
log.info(groupTeamResult)

3. createDepartmentMember 添加部门成员

TeamMemberAttribute.createDepartmentMember()

Groovy 举例

def deptTeamMember = TeamMemberAttribute.createDepartmentMember(["1008"], TeamMemberEnum.Role.NORMAL_STAFF, TeamMemberEnum.Permission.READONLY)
//deptTeamMember.setIgnoreSendingRemind(true) // 可选参数，是否忽略发送CRM提醒。默认false
//deptTeamMember.setRealtime(true) // 可选参数，是否实时生效。默认false
def deptTeamResult = Fx.object.addTeamMember("object_qep6N__c","61848edfd9007e00019ee222", deptTeamMember)
log.info(deptTeamResult)

4. createRoleMember 添加角色成员

TeamMemberAttribute.createRoleMember()

Groovy 举例

def roleTeamMember = TeamMemberAttribute.createRoleMember(["00000000000000000000000000000009"], TeamMemberEnum.Role.NORMAL_STAFF, TeamMemberEnum.Permission.READONLY)
//roleTeamMember.setIgnoreSendingRemind(true) // 可选参数，是否忽略发送CRM提醒。默认false
//roleTeamMember.setRealtime(true) // 可选参数，是否实时生效。默认false
def roleTeamResult = Fx.object.addTeamMember("object_qep6N__c","61848edfd9007e00019ee222", roleTeamMember)
log.info(roleTeamResult)

OutTeamMemberAttribute

1. createEmployMember 添加外部成员

OutTeamMemberAttribute.createEmployMember(<List teamMemberList>, <Permission permission>)

参数说明

入参格式

参数名称	类型	描述	是否必填
teamMemberList	List[object]	添加外部人员列表	是
permission	Permission	TeamMemberEnum.Permission.READONLY //只读 / TeamMemberEnum.Permission.READANDWRITE //读写 / TeamMemberEnum.Permission.NO_PERMISSION //无权限	是

出参格式

参数名称	类型	描述
outTeamMemberAttribute	OutTeamMemberAttribute

Groovy 举例

def teamMemberEmployee = TeamMemberEmployee.builder()
         .userId("309175511")
         .outTenantId("301185430")
         .build()
OutTeamMemberAttribute outEmployTeamMember = OutTeamMemberAttribute.createEmployMember([teamMemberEmployee], TeamMemberEnum.Permission.READANDWRITE)
def outEmployTeamResult = Fx.object.addOutTeamMember("object_qep6N__c","61848edfd9007e00019ee222", outEmployTeamMember)
log.info(outEmployTeamResult)

2. createOutTenantMember 添加下游企业

OutTeamMemberAttribute.createOutTenantMember()

Groovy 举例

def outTenant = TeamMemberEmployee.builder()
.userId("300012805")
.outTenantId("300012805")
.build()
OutTeamMemberAttribute outTenantTeamMember = OutTeamMemberAttribute.createOutTenantMember([outTenant], TeamMemberEnum.Permission.READANDWRITE)
def outTenantTeamResult = Fx.object.addOutTeamMember("object_qep6N__c","61848edfd9007e00019ee222", outTenantTeamMember)
log.info(outTenantTeamResult)

3. createRoleMember 添加外部角色

OutTeamMemberAttribute.createRoleMember()

Groovy 举例

OutTeamMemberAttribute outRoleTeamMember = OutTeamMemberAttribute.createRoleMember(["5d1f28eee4b0896efc933508"], TeamMemberEnum.Permission.READANDWRITE)
def outRoleTeamResult = Fx.object.addOutTeamMember("object_qep6N__c","61848edfd9007e00019ee222", outRoleTeamMember)
log.info(outRoleTeamResult)

4. createOutTenantGroupMember 添加下游企业组

OutTeamMemberAttribute.createOutTenantGroupMember()

Groovy 举例

OutTeamMemberAttribute outTenantGroupTeamMember = OutTeamMemberAttribute.createOutTenantGroupMember(["613880213ed24b000150a713"], TeamMemberEnum.Permission.READANDWRITE)
def outTenantGroupResult = Fx.object.addOutTeamMember("object_qep6N__c","61848edfd9007e00019ee222", outTenantGroupTeamMember)
log.info(outTenantGroupResult)

QueryOperator

1. EQ 查询与条件相等的数据

QueryOperator.EQ()

Groovy 举例

List criteria = [["name": Operator.EQ("测试")]]

2. NE 查询与条件不相等的数据

QueryOperator.NE()

Groovy 举例

List criteria = [["name": Operator.NE("测试")]]

3. GT 查询比条件大的数据

QueryOperator.GT()

Groovy 举例

List criteria = [["create_time": Operator.GT(1645427372658)]]

4. LT 查询比条件小的数据

QueryOperator.LT()

Groovy 举例

List criteria = [["create_time": Operator.LT(1645427372658)]]

5. GTE 查询大于等于条件的数据

QueryOperator.GTE()

Groovy 举例

List criteria = [["create_time": Operator.GTE(1645427372658)]]

6. LTE 查询小于等于条件的数据

QueryOperator.LTE()

Groovy 举例

List criteria = [["create_time": Operator.LTE(1645427372658)]]

7. LIKE 模糊匹配字符串内容

QueryOperator.LIKE()

Groovy 举例

List criteria = [["name": Operator.LIKE("易动纷享")]]

8. NLIKE 除模糊匹配字符串内容

QueryOperator.NLIKE()

Groovy 举例

List criteria = [["name": Operator.NLIKE("易动纷享")]]

9. IN 查询有交集的数据

如数据是[1,2,3]，查询条件是[1,4] 则返回（因为有1） 如数据是[1,2,3]，查询条件是[4,5] 则不返回

QueryOperator.IN()

Groovy 举例

List criteria = [["name": Operator.IN(["易动", "纷享"])]]

10. NIN 查询无交集的数据

QueryOperator.NIN()

Groovy 举例

List criteria = [["name": Operator.NIN(["易动", "纷享"])]]

11. CONTAINS 查询数据的数组字段匹配输入条件的子集

如数据是[1,2,3],查询条件是[1,2] 则返回 如数据是[1,2,3],查询条件是[3,4] 则不返回

QueryOperator.CONTAINS()

Groovy 举例

List criteria = [["name": Operator.CONTAINS(["易动", "纷享"])]]

12. NCONTAINS 查询数据的数组字段匹配输入条件的子集之外的数据

如数据是[1,2,3],查询条件是[1,2] 则不返回 如数据是[1,2,3],查询条件是[3,4] 则返回

QueryOperator.NCONTAINS()

Groovy 举例

List criteria = [["name": Operator.NCONTAINS(["易动", "纷享"])]]

13. HASANYOF 查询任何匹配数组任一内容的数据

QueryOperator.HASANYOF()

Groovy 举例

List criteria = [["name": Operator.HASANYOF(["易动", "纷享"])]]

14. NHASANYOF 查询都不在数组内的数据

QueryOperator.NHASANYOF()

Groovy 举例

List criteria = [["name": Operator.NHASANYOF(["易动", "纷享"])]]

15. EXISTS 查询数据字段（是/否）存在内容的数据

QueryOperator.EXISTS()

Groovy 举例

List criteria = [["name": Operator.EXISTS(true)]]

16. STARTWITH 查询以...为开始的数据

QueryOperator.STARTWITH()

Groovy 举例

List criteria = [["name": Operator.STARTWITH("易动")]]

17. ENDWITH 查询以...为结束的数据

QueryOperator.ENDWITH()

Groovy 举例

List criteria = [["name": Operator.ENDWITH("易动")]]

18. BETWEEN 查询在...范围内的数据

QueryOperator.BETWEEN()

Groovy 举例

List criteria = [["name": Operator.BETWEEN([154542372658, 1645427372658])]]

使用建议

推荐优先使用

• 查单条数据优先用 findOne
• 查大批量数据优先用 select.stream
• 普通字段修改优先用 update.increment
• 主从整体覆盖才使用 update.edit
• 预制对象批量改数时优先评估 batchUpdate.convert2SingleOperation

高风险API

• directDelete
• batchDelete
• bulkDelete
• batchUpdate
• update.byQuery

这些API要重点确认：

• 是否会绕过部分业务校验
• 是否会影响工作流、审批流、前后动作
• 是否会对大量数据生效
• 是否需要从 DB 实时查询或按当前用户权限执行

原文问题修复记录

本优化版已显式修复或规避以下问题：

• 将多个同名重载改为分场景展示，如 update.increment、update.edit、update.byQuery
• 统一 String/List/Map/Boolean 类型写法，不再混用 string/object
• 修正 findDescribe、getCascadeOption、merge 的签名展示冲突
• 将 filedAPIName 统一为 fieldApiName
• 删除原文中的坏链接、无意义引用和拼接损坏示例
• 将高风险API集中标记，便于评审和使用

版本记录

版本	日期	变更内容	负责人
v1.0	2026-05-19	初始版本

背景说明

本文档详细描述 Fx.object 的相关接口功能和使用方法，帮助开发者快速集成相关能力。

适用场景

具体适用场景由实际业务需求决定，开发者可根据需要选择相应的接口进行集成。

前置条件

• 已接入纷享销客开放平台
• 已完成应用授权与配置
• 了解相关业务领域基础知识

操作步骤

具体操作步骤请参考各接口的详细说明。

注意事项

• 调用接口前请确保满足前置条件
• 注意接口调用频率限制
• 异常情况请参考错误码说明进行处理

兼容性说明：当前版本暂无可用的废弃或兼容性说明。