后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文围绕蓝鲸智云配置平台BlueKing CMDBbk-cmdb的find_module_with_relation接口展开它是业务拓扑管理场景中按条件查询模块的标准入口开发者可通过集群 IDbk_set_ids与服务模板 IDbk_service_template_ids组合筛选出指定业务bk_biz_id下的模块并自主控制返回字段与分页。读完本文你将掌握该接口的完整请求/响应格式、参数约束与取值范围、底层实现链路toposerver → coreservice → MongoDB并能结合仓库内的服务端实现与集成测试用例正确接入或二次开发。接口概览与适用场景find_module_with_relation是 bk-cmdb 开放给第三方系统ESB/API 网关的标准查询类接口接口说明原文为“根据条件查询业务下的模块”首次发布于 v3.9.7 版本。它属于query查询类型接口对外路径为/v2/cc/find_module_with_relation/该路径映射关系定义在 docs/apidoc/cc/cc.yaml 中其中明确记录了suggest_method: POST建议使用 POST 方法调用dest_path: /api/v3/findmany/module/with_relation/biz/{bk_biz_id}内部转发到 topo_server 的实际处理路径dest_http_method: POST内部转发同样使用 POSTapi_type: query接口类型为查询。同时在 API 网关侧的 OpenAPI 描述 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中也可以看到该资源被标记为isPublic: false非公开资源、allowApplyPermission: true允许申请权限并配置了默认限流每 1 秒 100 个令牌。典型使用场景当第三方系统需要同步某业务下“归属于若干指定集群Set”或“关联了若干指定服务模板Service Template”的模块清单时无需逐集群遍历只需一次调用即可按关系批量捞出模块同时可通过fields精确裁剪返回字段降低传输与解析成本。请求参数说明公共参数接口请求头中需要携带 ESB/蓝鲸 API 网关的公共鉴权参数即文档中的common_args_desc典型字段包括字段类型说明bk_app_codestring应用编码ESB 注册的 app codebk_app_secretstring应用密钥用于接口鉴权bk_usernamestring操作者用户名用于权限校验与审计bk_tokenstring登录态 Token供已登录用户调用这些参数在示例请求体中以 JSON 形式给出实际对接时按 ESB 网关约定的鉴权方式Header 或 Body传递即可。接口参数字段类型必填说明bk_biz_idint是业务 IDbk_set_idsarray否集群 ID 列表最多 200 个bk_service_template_idsarray否服务模板 ID 列表fieldsarray是模块属性字段列表控制模块信息中返回哪些字段pageobject是分页信息注意文档中标注了bk_set_ids上限为 200 个服务模板 ID 列表虽未在文档中明确标注数量上限但源码实现中存在对应的超限校验见下文“服务端实现剖析”。page 分页字段说明字段类型必填说明startint是记录起始位置从 0 开始limitint是每页记录数最大为 500请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 2, bk_set_ids:[1,2], bk_service_template_ids: [3,4], fields:[bk_module_id, bk_module_name], page: { start: 0, limit: 10 } }该示例的含义是在业务 ID 为2的业务下查询集群 ID 为1、2、服务模板 ID 为3、4所关联的模块仅返回bk_module_id与bk_module_name两个字段从第 0 条开始取 10 条。响应示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { count: 2, info: [ { bk_module_id: 8, bk_module_name: license }, { bk_module_id: 12, bk_module_name: gse_proc } ] } }响应参数说明顶层响应字段字段类型说明resultbool请求是否成功。true成功false失败codeint错误码。0 表示成功0 表示失败错误码messagestring失败时返回的错误信息permissionobject权限信息request_idstring请求链路 ID用于全链路日志追踪dataobject请求返回的数据data 字段说明字段类型说明countint记录总数infoobject array模块的实际数据数组data.info 字段说明info中的每个元素是一个模块对象字段为模块属性。文档列出的字段含义如下字段类型说明bk_module_idint模块 IDbk_module_namestring模块名称defaultint标识模块类型如普通模块/内置模块等create_timestring创建时间bk_set_idint集群 IDbk_bak_operatorstring备份维护人bk_biz_idint业务 IDbk_module_typestring模块类型bk_parent_idint父节点 IDbk_supplier_accountstring开发商账户last_timestring更新时间host_apply_enabledbool是否开启主机属性自动应用operatorstring主要维护人service_category_idinteger服务分类 IDservice_template_idint服务模板 IDset_template_idint集群模板 IDbk_created_atstring创建时间bk_updated_atstring更新时间bk_created_bystring创建者需要说明的是返回的字段集合由请求参数fields控制data.info中的字段是模块模型支持查询的常见字段全集实际返回内容以请求时指定的fields为准。服务端实现剖析路由注册内部真实接口路径为/findmany/module/with_relation/biz/{bk_biz_id}注册于 topo_server 服务模块的路由初始化逻辑中src/scene_server/topo_server/service/service_initfunc.go对应处理器为s.SearchModuleWithRelation。该接口属于initModule路由组与创建模块、删除模块、批量查询模块等接口并列。处理函数核心逻辑核心处理逻辑位于 src/scene_server/topo_server/service/inst_module.go实现步骤可归纳为解析业务 ID从 URL 路径参数bk_biz_id中取出业务 ID 并转换为 int64解析失败则返回CCErrCommParamsInvalid错误解析请求体通过ctx.DecodeInto将请求 JSON 反序列化到结构体中结构体字段与文档完全对应BkSetIdS []int64→bk_set_idsBkServiceTemplateIds []int64→bk_service_template_idsFields []string→fieldsPage metadata.BasePage→page参数校验fields为空时返回CCErrCommParamsNeedSet参数必须设置错误bk_set_ids数量超过 200 时返回CCErrCommOverLimit超限错误常量定义见 inst_module.gobkSetIdSMaxSize 200page.limit超过 500 时同样返回超限错误bKMaxPageSize 500与文档中“每页最大 500 条”的描述一致。组装查询条件以bk_biz_id为基础条件当bk_set_ids非空时追加bk_set_id的$in条件当bk_service_template_ids非空时追加service_template_id的$in条件。两个过滤条件均先经util.IntArrayUnique去重。字段常量定义见 src/common/definitions.go 与 src/common/definitions.go调用 coreservice 查询构造metadata.QueryCondition包含fields、page、condition调用CoreService().Instance().ReadInstance读取模块实例common.BKInnerObjIDModule实际数据读取发生在 coreservice → 存储层MongoDB返回结果成功后以RespEntityWithCount返回count记录总数与info模块数据数组失败则记录错误日志并返回对应错误。从源码实现可以推断该接口是“先按业务 ID 锁定范围再用集群 ID / 服务模板 ID 做交集过滤”的查询语义两个可选条件都未提供时等价于按业务 ID 全量分页查询模块。分页对象metadata.BasePage还额外支持sort与enable_count字段定义见 src/common/metadata/page.go因此实际调用时也可按需补充排序字段。SDK 客户端封装在 Go SDK 侧接口被封装为instanceClient.SearchModuleWithRelationsrc/apimachinery/toposerver/inst/module.go通过client.Post().SubResourcef(/findmany/module/with_relation/biz/%s, appID)发起 POST 请求返回metadata.ResponseInstData。接口方法声明位于 src/apimachinery/toposerver/inst/api.go属于InstClientInterface实例客户端接口的一部分。集成测试验证仓库在 src/test/topo_server/object_test.go 提供了针对该接口的集成测试用例search module with relation先构造bk_set_ids单个集群 ID与bk_service_template_ids单个服务模板 IDfields取[bk_module_id, bk_module_name]page为{start: 0, limit: 500}调用topoServerClient.Instance().SearchModuleWithRelation发起真实请求断言result true、count 1并校验返回模块的 ID 与名称与预期一致。该测试用例完整走通了“调用方 → topo_server → coreservice → 存储”的整条链路可作为二次开发或本地调试时的直接参考。调用注意事项与最佳实践fields必填请求中必须显式指定需要返回的模块字段服务端会在缺少该参数时直接报错建议只声明业务真正需要的字段以减少网络传输与解析开销。遵守数量上限bk_set_ids最多 200 个、page.limit最多 500超出即报超限错误需要拉取全量时可通过start递增分页或按文档与代码约定的上限分批处理。条件为空即全量bk_set_ids与bk_service_template_ids均为可选同时省略时接口退化为按业务 ID 查询该业务下的全部模块可用于模块清单的全量同步。鉴权与权限该接口在 API 网关侧为非公开资源需申请权限后调用ESB 模式下需携带bk_app_code/bk_app_secret/bk_username/bk_token等公共参数。结果一致性服务端会对集群 ID 与服务模板 ID 列表先做去重IntArrayUnique再查询因此重复传入相同 ID 不会影响结果集。审计与排查每次响应均携带request_id结合服务端日志中的rid可对异常调用进行全链路追踪。小结find_module_with_relation是 bk-cmdb 对外提供的、基于业务 ID 集群 ID 服务模板 ID 组合条件查询模块的接口从 docs/apidoc/cc/en/find_module_with_relation.md 的 API 文档、docs/apidoc/cc/cc.yaml 的 ESB 路由定义到 src/scene_server/topo_server/service/inst_module.go 的服务端实现与 src/test/topo_server/object_test.go 的集成测试整条链路在仓库中完整可查、可运行、可验证。无论是对接蓝鲸平台做资源同步还是基于该接口进行二次开发掌握其参数约束、响应结构与底层调用链都将是高效落地的关键。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台BlueKing CMDB开放 APIfind_module_with_relation 接口详解——按条件批量查询业务下的模块蓝鲸配置平台BlueKing CMDB开放 APIfind_module_with_relation 接口详解——按条件批量查询业务下的模块 本文讲解 B后端企业应用运维蓝鲸配置平台 bk-cmdb 服务模板查询指南list_proc_template 接口详解蓝鲸配置平台 bk cmdb 服务模板查询指南list_proc_template 接口详解 导读 list_proc_template 是蓝鲸智云配置平台后端企业应用运维蓝鲸配置平台 bk-cmdb get_mainline_object_topo 接口详解查询主线模型的业务拓扑蓝鲸配置平台 bk cmdb get_mainline_object_topo 接口详解查询主线模型的业务拓扑 本文面向需要调用蓝鲸配置平台bk cmdb后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考