企业官网建设流程全解析

• 后端
• 企业应用
• 运维

count_instance_associations是蓝鲸配置平台（bk-cmdb）对外开放 API 中用于统计模型实例关联关系数量的接口，自 v3.10.1 起提供，适用于需要在不拉取明细的情况下快速获取关联规模、进行容量评估或触发阈值判断的场景。阅读本文后，你将完整掌握该接口的请求参数、conditions条件组装规则、响应结构，以及从 API 网关到 Mongo 底层计数的完整调用链路与校验逻辑。

接口概览

该接口在 API 网关资源配置文件 中登记，网关后端直连拓扑服务的/api/v3/count/instance_associations/object/{bk_obj_id}，并默认带有bk-rate-limit（默认每周期 100 token）限流插件，isPublic: false表示该资源不对外公开，需申请 API 权限后方可调用。

从调用链定位看，该路径属于拓扑（topo）系列接口，与查询实例关联明细的search_instance_associations互为姊妹接口：一个返回info明细列表，一个仅返回count数量。

请求参数详解

接口请求体为 JSON，包含三个字段：

注意：bk_obj_id同时也会出现在 URL 路径参数{bk_obj_id}中，两者含义一致。主链路模型（如业务、集群、模块等组织架构主线模型）的实例关联统计必须携带bk_biz_id，否则无法限定业务范围。

conditions 结构

conditions由condition与rules两个字段构成：

conditions.rules 字段说明

rules数组中的每个元素既可以是原子规则（原子过滤规则），也可以再次嵌套condition+rules形成组合规则：

各字段的实际含义与仓库中的字段常量一一对应（定义于 definitions.go）：

这些字段在实例关联记录表上均建有索引，见 src/common/index/association.go，因此按上述字段过滤可以命中 Mongo 索引。

操作符与 value 格式

conditions底层由src/common/querybuilder模块解析（模块说明见 src/common/querybuilder/README.md）。操作符常量定义在 src/common/querybuilder/types.go 的SupportOperators集合中，包括：

说明：接口文档操作符一栏示例中列出的between、not_between，在当前仓库的 querybuilder 实现中并未列入SupportOperators集合（README 明确注明"不支持 between 和 not_between 运算符，这类运算符可基于基本比较运算符组合实现"）。实际可用操作符以 types.go 中SupportOperators为准，区间过滤可改用greater_or_equal与less_or_equal组合表达。

限制边界（源码级校验）

conditions的合法性由CommonCountFilter.Validate把关（src/common/metadata/common.go），规则常量定义于 src/common/querybuilder/types.go：

若conditions为空（null或不传），校验直接通过，语义为"匹配全部关联记录"（见 common.go）。

请求示例

以下示例统计交换机模型（bk_switch）的实例关联数量：要求关联关系为bk_switch_connect_host，且满足"源实例 ID 属于 [2,4,6]或关联类型 ID 等于 3"：

{ "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 } ] } ] } }

外层condition为AND，连接"关联关系 ID 等于指定值"与内层OR组合；内层OR连接"源实例 ID 属于集合"与"关联类型等于 3"。整体语义等价于：

bk_obj_asst_id = 'bk_switch_connect_host' AND (bk_inst_id IN [2,4,6] OR bk_asst_id = 3)

查询主线模型（如biz、set、module）时，需在上述 JSON 中补充"bk_biz_id": <业务ID>字段。

响应示例与参数说明

{ "result": true, "code": 0, "message": "success", "permission": null, "data": { "count": 1 } }

响应参数：

data.count为 int 类型，即满足条件的实例关联记录数量。响应外层结构与CommonCountResp定义对应（src/common/metadata/common.go），data部分实际由metadata.CommonCountResult承载。

源码级调用链路剖析

从一次 HTTP 请求到最终计数，完整调用链如下：

① API 网关层：POST /api/v3/count/instance_associations/object/{bk_obj_id}在 apiserver 中按拓扑系列路径转发，该路径被列入topoPrefixes白名单（src/apiserver/service/url.go）。

② 权限解析层：apiserver 将请求转发到拓扑服务前，权限解析器会匹配正则^/api/v3/count/instance_associations/object/[^\s/]+/?$（src/ac/parser/topolatest.go），命中后标记为SkipAction跳过实例级鉴权（topolatest.go）。

③ 拓扑服务路由注册：拓扑服务通过utility.AddHandler注册该 POST 路由到CountInstanceAssociationshandler（service_business_initfunc.go）。

④ 拓扑服务 handler 处理：从路径取bk_obj_id，将请求体反序列化为metadata.CommonCountFilter，执行参数校验，并将读偏好设为SecondaryPreferredMode（从库优先读取，降低主库压力）（src/scene_server/topo_server/service/association.go）。

⑤ 逻辑层组装条件：CountInstanceAssociations逻辑将conditions通过GetConditions()转换为 Mongo 过滤条件，并强制注入bk_obj_id字段（src/scene_server/topo_server/logics/inst/association.go）：

cond, err := input.GetConditions() cond[common.BKObjIDField] = objID conditions := &metadata.Condition{Condition: cond}

⑥ coreservice 底层计数：拓扑服务调用 coreservice 的CountInstanceAssociations（src/source_controller/coreservice/core/association/instance.go），最终落到countInstanceAssociation：

asstTableName := common.GetObjectInstAsstTableName(objID, kit.SupplierAccount) return mongodb.Client().Table(asstTableName).Find(cond).Count(kit.Ctx)

即对实例关联记录表（表名由模型 ID 与租户标识动态生成）执行 MongoFind(...).Count(...)完成统计（instance.go）。由于关联记录表对bk_obj_id、bk_inst_id、bk_asst_obj_id、bk_asst_inst_id等字段建有复合索引（src/common/index/association.go），按这些字段过滤时计数查询效率有保障。

⑦ 条件转换细节：CommonCountFilter.GetConditions()将 QueryBuilder 的规则树通过ToMgo()转换为 Mongo 查询条件（src/common/metadata/common.go），原子规则与组合规则的定义可参见 src/common/querybuilder/types.go。

常见问题与注意事项

• 查询主线模型必须传bk_biz_id：不传时无法限定业务范围，结果可能与预期不符。
• conditions不传等于匹配全部：若希望统计某模型下所有关联记录，直接省略conditions即可，无需构造空对象。
• 数组 value 上限 500：in/not_in等操作符的数组元素个数超过 500 会校验失败，需拆分多次调用后自行汇总。
• 嵌套与 OR 规则数限制：嵌套超过 3 层、单层 OR 超过 20 条会被CommonCountFilter.Validate拒绝，报参数错误（对应错误码CCErrCommParamsInvalid）。
• between/not_between不可用：当前 querybuilder 实现不支持这两个操作符，区间场景请组合greater_or_equal与less_or_equal。
• 只返回数量、不返回明细：需要关联明细列表时，请使用姊妹接口search_instance_associations（POST /api/v3/search/instance_associations/object/{bk_obj_id}）。

延伸阅读

• 实例关联查询接口 search_instance_associations
• QueryBuilder 查询规则组装详细说明
• CommonCountFilter 定义与校验实现
• 拓扑服务关联计数实现
• coreservice 关联计数实现

• 后端
• 企业应用
• 运维