企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

search_instance_associations是蓝鲸智云配置平台（bk-cmdb）提供的通用模型实例关系（实例关联）查询接口，用于按条件检索任意两个模型实例之间已建立的关联关系记录。它允许调用方以bk_obj_id（如bk_switch）为入口，通过组合查询条件（AND/OR 嵌套）精准筛选出源实例与目标实例的关联明细，是构建拓扑视图、实例关联分析、资产对账等场景的基础能力。读完本文，你将掌握该接口的完整请求参数、组合查询规则、分页排序用法、返回数据结构，以及其在 topo_server 中的底层实现链路。

接口概述

• 接口名称：通用模型实例关系查询（Search Instance Associations）
• 适用版本：v3.10.1 及以上
• 所需权限：模型实例查询权限（源码中通过HasFindModelInstAuth完成鉴权，见 service/association.go）
• HTTP 方法 / 路径：POST /search/instance_associations/object/{bk_obj_id}

该接口的路由注册在 service_business_initfunc.go，与count/instance_associations/object/{bk_obj_id}（实例关联计数接口）相邻，二者共用同一套组合条件解析逻辑，区别仅在于前者返回明细、后者返回数量。

从调用链看，该接口由topo_server承接，经过 logics/inst/association.go 的业务逻辑层将条件转换为 MongoDB 查询，再下发给coreservice的ReadInstAssociation（见 apimachinery/coreservice/association/api.go）完成最终数据读取。

请求参数详解

通用参数（common_args_desc）

所有蓝鲸 CMDB API 请求都需携带蓝鲸智云开放平台通用鉴权参数，包括bk_app_code、bk_app_secret、bk_username/bk_token等，用于标识应用身份与操作用户。

接口专属参数

上述结构与源码中的CommonSearchFilter一一对应（见 common.go）：ObjectID对应bk_obj_id，Conditions对应conditions（*querybuilder.QueryFilter类型），Fields对应fields，Page对应page。其中还包含一个可选字段TimeCondition（time_condition，仅用于时间过滤且与conditions是“与”关系），供需要按时间维度筛选用。

conditions 组合条件结构

conditions由两层结构组成：

conditions

conditions.rules

rules数组中的每一条规则可以是原子规则（包含field、operator、value）或嵌套的组合规则（包含condition与rules），从而实现多级嵌套：

字段含义速查（对应源码InstAsst结构，见 association.go）：

• id：实例关联记录的自增序列 ID
• bk_inst_id：源模型实例 ID
• bk_obj_id：源模型（关联起点）的模型 ID
• bk_asst_inst_id：目标模型实例 ID
• bk_asst_obj_id：目标模型（关联终点）的模型 ID
• bk_obj_asst_id：自动生成的模型关联 ID（如bk_switch_connect_host）
• bk_asst_id：关联类型 ID（如connect、run）

page 分页参数

limit上限受BKMaxInstanceLimit约束，超过上限会返回分页超限错误（CCErrCommPageLimitIsExceeded），相关校验见 common.go。

组合查询规则（querybuilder）深度解析

conditions的组装规则由 bk-cmdb 内置的查询构建器（query builder）解析，详细设计可参考 src/common/querybuilder/README.md。该模块的作用是把前端/API 传入的类 jQuery-QueryBuilder 结构参数，转换为 MongoDB 过滤条件。

核心约束如下（均可在源码中验证）：

• 嵌套深度：组合条件最大深度为 3（即最多嵌套 2 层），常量MaxDeep = 3定义于 types.go，超出会返回exceed max query condition deepth错误；
• OR 条件规则数：单个 OR 组合内最多 20 条规则，常量DefaultMaxConditionOrRulesCount = 20（types.go）；
• 数组值上限：数组类型 value 最多 500 个元素，常量DefaultMaxSliceElementsCount = 500（types.go）；
• 类型一致性：数组元素类型需保持一致（校验选项NeedSameSliceElementType: true，见 common.go）。

querybuilder 支持的操作符分为以下几类：

需要特别说明：between/not_between这类区间操作符在 querybuilder 中不直接支持（见 README.md 与 jQuery-QueryBuilder 的差异说明），官方建议基于基本比较操作符（greater_or_equal+less_or_equal组合）自行实现区间过滤，使用前请确认当前版本的操作符可用范围。

完整请求示例

以下示例查询模型bk_switch（交换机）与主机host之间建立的bk_switch_connect_host关联，并附加条件：源实例 ID 属于[2, 4, 6]或关联类型 ID 等于3：

{ "bk_app_code":"code", "bk_app_secret":"secret", "bk_username": "xxx", "bk_token":"xxxx", "bk_obj_id":"bk_switch", "conditions":{ "condition": "AND", "rules": [ { "field": "bk_obj_asst_id", "operator": "equal", "value": "bk_switch_connect_host" }, { "condition": "OR", "rules": [ { "field": "bk_inst_id", "operator": "in", "value": [2,4,6] }, { "field": "bk_asst_id", "operator": "equal", "value": 3 } ] } ] }, "fields":[ "bk_inst_id", "bk_asst_inst_id", "bk_asst_obj_id", "bk_asst_id", "bk_obj_asst_id" ], "page":{ "start":0, "limit":500 } }

结构解读：

• 顶层condition: "AND"表示以下规则同时成立；
• 第一条规则限定关联类型为bk_switch_connect_host；
• 第二条是嵌套的OR组合（第 2 层），表示“源实例 ID 为 2/4/6”或“关联类型 ID 为 3”；
• fields按需指定返回字段，减少传输开销；
• page从第 0 条开始，每页 500 条。

返回结果解析

返回结果示例

{ "result": true, "code": 0, "message": "", "permission": null, "request_id": "e43da4ef221746868dc4c837d36f3807", "data": { "info": [ { "bk_inst_id": 2, "bk_asst_inst_id": 8, "bk_asst_obj_id": "host", "bk_asst_id": "connect", "bk_obj_asst_id": "bk_switch_connect_host" } ] } }

response 顶层字段

data.info 每条关联记录的字段

注意：返回记录还隐含携带bk_obj_id（源模型 ID）、id（记录自增 ID）、bk_supplier_account等字段（对应 InstAsst 的完整字段集），但只有当它们被fields显式要求时才会出现在输出中；bk_obj_id恒等于请求路径中的模型 ID。此外，服务端将查询结果以data.info数组形式封装（见 service/association.go），与通用响应结构保持一致。

源码实现剖析

1. 路由与入口

接口注册于 service_business_initfunc.go：

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/search/instance_associations/object/{bk_obj_id}", Handler: s.SearchInstanceAssociations})

处理函数 SearchInstanceAssociations 的执行流程：

1. 从路径参数取出bk_obj_id；
2. 将请求体解码为CommonSearchFilter并回填ObjectID；
3. 调用input.Validate()做参数校验（模型 ID 非空、分页 limit 上限、组合条件深度与规则数）；
4. 设置读偏好为SecondaryPreferredMode（优先从 MongoDB 从节点读取，降低主节点压力，允许轻微数据延迟）；
5. 通过HasFindModelInstAuth校验“模型实例查询”权限；
6. 调用业务逻辑层SearchInstanceAssociations执行查询。

2. 条件转换与数据读取

业务逻辑层 SearchInstanceAssociations 完成关键转换：

• 通过input.GetConditions()将querybuilder.QueryFilter组合条件转换为 MongoDB 过滤条件（Conditions.ToMgo()，见 common.go）；
• 组装InstAsstQueryCondition（含bk_obj_id、fields、condition、page，并关闭 count 计数DisableCounter: true以提升性能）；
• 最终调用CoreService().Association().ReadInstAssociation下发至 coreservice 读取实例关联集合（inst_asst数据表）。

3. 数据结构落点

每条实例关联记录对应结构体 InstAsst，核心字段的 bson/json 标签与接口返回字段完全对应：bk_inst_id（源实例）、bk_obj_id（源模型）、bk_asst_inst_id（目标实例）、bk_asst_obj_id（目标模型）、bk_obj_asst_id（模型关联 ID）、bk_asst_id（关联类型）、bk_supplier_account（开发商账号）、bk_biz_id（业务 ID）。

实战注意事项与最佳实践

1. 主线模型查询必须带bk_biz_id：当bk_obj_id指向主线模型（如业务、集群、模块、主机等拓扑主线上的模型）时，务必在请求中携带bk_biz_id，否则查询范围不准确。
2. fields按需返回：不指定fields会返回全部字段，实例关联量大时严重影响性能与网络开销，生产环境建议始终显式声明所需字段。
3. 控制分页与深度：limit默认 500 且受上限约束；组合条件最多 3 层、单个 OR 最多 20 条规则、数组 value 最多 500 个元素，超限请求会被校验逻辑直接拒绝，组装条件时应提前评估复杂度。
4. 区间查询用组合操作符：between/not_between在 querybuilder 中不受支持，区间过滤请用greater_or_equal与less_or_equal组合表达。
5. 权限前置：调用方需要具备对应模型的“实例查询”权限，鉴权失败将返回无权限响应（permission字段会携带权限申请信息）。
6. 关联查询的补充接口：若需要同时获取源/目标实例详情与关联记录，可参考同族接口find/instassociation/object/{bk_obj_id}/inst/detail（SearchInstAssociationAndInstDetail）与find/instassociation/related（SearchAssociationRelatedInst），它们分别用于返回带实例明细的关联信息与指定实例的全部关联（含作为源与目标两侧的记录）。

• 后端
• 企业应用
• 运维