bk-cmdb 业务集拓扑查询接口 list_business_set_topo 完整指南：参数、原理与实战

• 后端
• 企业应用
• 运维

业务集（Business Set）是蓝鲸智云配置平台（bk-cmdb）用于跨业务聚合管理拓扑与主机的核心概念。list_business_set_topo接口用于在指定业务集范围内，按父节点查询其下一层拓扑节点（模型实例）的 ID 与名称信息，是搭建"业务集拓扑树"的基础数据源。本文基于当前仓库的接口文档、API 网关配置与服务端源码，完整讲解该接口的请求参数、返回结构、底层实现原理与典型调用场景，读完即可独立接入并正确解析返回值。

接口概述

• 接口路径（ESB 版）：/v2/cc/list_business_set_topo/
• 底层转发路径（CMDB 版）：/api/v3/find/biz_set/topo_path
• 请求方法：POST
• 功能：查询业务集拓扑，即按父节点返回其子层拓扑节点的实例 ID、实例名称等信息
• 版本要求：v3.10.12+
• 权限要求：业务集访问（访问该接口需要具备对应业务集的访问权限）

该接口在 ESB 组件清单 docs/apidoc/cc/cc.yaml 中有明确登记：api_type: query（查询类接口），suggest_method: POST，网关组件为generic.v2.cc.cc_component，转发目标是dest_path: /api/v3/find/biz_set/topo_path。在 API 网关开放资源定义 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中，/api/v3/find/biz_set/topo_path对应的operationId即为list_business_set_topo，并配置了默认限流策略（1 秒 100 个令牌）。

请求参数详解

请求体中除通用鉴权参数（bk_app_code、bk_app_secret、bk_username、bk_token）外，接口参数如下：

请求参数示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_biz_set_id": 3, "bk_parent_obj_id": "bk_biz_set_obj", "bk_parent_id": 344 }

参数校验逻辑

服务端对三个必选字段逐一进行非空校验，见 src/common/metadata/toposerver.go 中FindBizSetTopoOption.Validate()的实现：bk_biz_set_id、bk_parent_id为 0 或bk_parent_obj_id为空字符串时，会返回参数缺失错误（CCErrCommParamsNeedSet）。因此业务集 ID 与拓扑实例 ID 都是从 1 开始的正整数，调用时务必确保三个字段同时给出。

返回结果详解

返回结果示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": [ { "bk_obj_id": "bk_biz_set_obj", "bk_inst_id": 5, "bk_inst_name": "xxx", "default": 0 }, { "bk_obj_id": "bk_biz_set_obj", "bk_inst_id": 6, "bk_inst_name": "xxx", "default": 0 } ], "request_id": "dsda1122adasadadada2222" }

response 字段说明

data 字段说明

data为拓扑节点数组，每个元素对应一个子层拓扑实例：

从返回结构可以看出，该接口返回的是子层拓扑节点的摘要信息（ID、名称、分类），而非完整实例字段。前端拿到bk_inst_id与bk_obj_id后可继续下钻，逐层展开业务集拓扑树。

底层实现原理

服务端处理流程

服务端路由注册在 src/scene_server/topo_server/service/service_initfunc.go，核心逻辑位于 src/scene_server/topo_server/service/inst_business_set.go 的FindBizSetTopo处理器与findBizSetTopo业务函数（L823-L912）。其处理流程可概括为：

1. 解析并校验请求体：将 JSON 反序列化为metadata.FindBizSetTopoOption，随后调用Validate()校验必填参数。
2. 解析业务集范围（scope）：根据bk_biz_set_id读取业务集配置，将其Scope（匹配范围：match_all全量匹配或filter条件过滤）转换为 Mongo 查询条件（见getBizSetBizCond，inst_business_set.go）。转换时默认排除资源池业务（default字段非1）与已停用业务（data_status非disabled）。
3. 判断父节点类型并确定子节点模型：
   • 父节点为业务集（bk_biz_set_obj）时，要求bk_parent_id必须等于bk_biz_set_id，直接返回该业务集范围内的业务（biz）节点列表；
   • 父节点为业务（biz）时，子节点为集群（set）；
   • 父节点为集群（set）时，子节点为模块（module）；
   • 父节点为模块（module）时，禁止继续查询（模块的子节点是主机，主机不属于主线拓扑对象），直接返回参数错误；
   • 其他自定义模型：通过主线关联（association_kind_id = mainline）查询其子模型，若父模型不是主线模型同样返回参数错误（见 inst_business_set.go）。
4. 校验父节点归属：调用checkTopoNodeInBizSet（L914-L951）确认父节点实例所属的业务确实在业务集范围内，防止越权/越界查询。
5. 查询子层节点摘要：调用getTopoBriefInfo（L953-L982）按父 ID 查询子层实例，仅返回bk_obj_id、bk_inst_id、bk_inst_name、default四个字段，并按实例 ID 升序排序。

一个值得注意的细节：当业务存在自定义主线层级时，业务（biz）下会同时存在"默认集群"和自定义主线子节点两类子层，服务端会合并返回（见 inst_business_set.go），并在查询集群节点时默认排除资源池集群（default为2的"空闲机池"所在集群）。

客户端封装

仓库为各服务提供了统一的 Go 客户端封装FindBizSetTopo，见 src/apimachinery/toposerver/inst/biz_set.go，它向/find/biz_set/topo_path发起POST请求并将响应解析为[]mapstr.MapStr。接口声明位于 src/apimachinery/toposerver/inst/api.go。前端 Web 页面同样封装了该方法（findChildren），见 src/ui/src/service/business-set/topology.js，业务集拓扑树组件逐层调用它以展开节点。

集成测试验证

仓库在 src/test/topo_server/biz_set_test.go 提供了完整的接口集成测试用例，覆盖了主要行为与异常路径：

• 查询业务集下的业务列表：返回 2 个业务节点，bk_obj_id均为biz；
• 查询业务下的子层拓扑：返回默认集群 + 自定义主线节点，验证"biz 下同时存在 set 与自定义主线子层"的合并返回逻辑；
• 沿自定义主线逐层下钻：自定义主线节点 → set → module，验证自定义主线模型的递归查询能力；
• 异常场景：业务集 ID 不存在、bk_parent_id与bk_biz_set_id不匹配、父对象为普通对象（host）、父节点不在业务集范围内，均返回错误。

这些用例可直接作为接入调试的参考：正确的入参组合是bk_parent_obj_id取业务集/业务/集群/模块或自定义主线模型 ID，且bk_parent_id必须真实存在于该业务集的范围内。

典型调用场景

该接口最典型的应用是渲染业务集拓扑树：以业务集为根节点，先传bk_parent_obj_id: "bk_biz_set_obj"、bk_parent_id: <业务集ID>拿到业务列表；再对每个业务传bk_parent_obj_id: "biz"、bk_parent_id: <业务ID>拿到集群与自定义主线子层；随后逐层下钻集群（set）、模块（module）与自定义主线模型，即可完整还原业务集范围内的拓扑结构。返回值中的default字段可用于区分内置默认实例与普通实例，配合bk_inst_id/bk_inst_name即可在前端展示节点标识。

调用时需注意：接口有版本门槛（v3.10.12+），且需要具备对应业务集的访问权限；bk_parent_id对应的父节点必须位于该业务集范围内，否则服务端会返回参数校验错误。

• 后端
• 企业应用
• 运维