企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

本篇文章围绕蓝鲸智云配置平台（bk-cmdb）的"查询某实例所有关联关系"接口（/api/v3/find/instassociation/related）展开，从接口参数、请求/返回报文示例到源码实现原理逐步拆解。读完本文，你将掌握如何通过bk_inst_id与bk_obj_id一次查询某实例作为关联关系源模型与目标模型的全量关联数据，并理解其底层基于 MongoDB OR 条件、权限鉴权与分页限制的完整调用链路，可直接用于二次开发与日常 API 调试。

一、功能概述与典型应用场景

在 bk-cmdb 中，模型（如交换机bk_switch、路由器bk_router）之间存在关联关系（Association），而实例之间则通过实例关联（Instance Association）建立具体的关联记录。该接口解决的问题是：给定一个模型实例，返回它参与的全部关联记录——既包括它作为"源模型实例"（bk_inst_id）发起的关联，也包括它作为"目标模型实例"（bk_asst_inst_id）被关联的情况。

典型应用场景包括：

• 拓扑图展示：给定某台交换机实例，反查它连接了哪些路由器、上联了哪些汇聚设备；
• 变更影响分析：删除或变更实例前，先查询其关联关系，评估连锁影响；
• 数据对账：批量核对模型实例的关联是否完整、是否符合预期。

调用该接口需要具备模型实例查询权限（HasFindModelInstAuth），无权限时会返回鉴权失败响应。

二、接口基本信息

该路由在 src/scene_server/topo_server/service/service_business_initfunc.go 中注册，对应的处理函数为SearchAssociationRelatedInst（位于 src/scene_server/topo_server/service/association.go），归属于 topo_server 的实例关联（instassociation）相关接口族，与find/instassociation、create/instassociation、delete/instassociation等接口并列。

三、请求参数详解

3.1 通用鉴权参数

接口调用首先需要携带蓝鲸应用与用户鉴权信息（common_args）：

3.2 接口业务参数

注意：接口业务参数位于请求体condition对象内（见下方示例），fields与page为平级参数。

page 分页对象

源码印证：请求结构体定义于 src/common/metadata/association.go：

type SearchAssociationRelatedInstRequest struct { Fields []string `json:"fields"` Page BasePage `json:"page"` Condition SearchAssociationRelatedInstRequestCond `json:"condition"` } type SearchAssociationRelatedInstRequestCond struct { ObjectID string `field:"bk_obj_id" json:"bk_obj_id,omitempty" bson:"bk_obj_id,omitempty"` InstID int64 `field:"bk_inst_id" json:"bk_inst_id,omitempty" bson:"bk_inst_id,omitempty"` }

其中Condition对应bk_obj_id与bk_inst_id，Page对应start/limit分页，Fields对应需要返回的字段列表。

四、请求参数示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "condition": { "bk_inst_id": 16, "bk_obj_id": "bk_router" }, "fields": [ "id", "bk_inst_id", "bk_obj_id", "bk_asst_inst_id", "bk_asst_obj_id", "bk_obj_asst_id", "bk_asst_id" ], "page": { "start":0, "limit":2 } }

上述示例的含义：查询模型bk_router（路由器）下实例 ID 为16的全部关联记录，无论该实例是关联的发起方（源模型实例）还是接收方（目标模型实例），只返回指定的 7 个字段，分页从第 0 条开始、每页 2 条。

五、返回结果示例

{ "result": true, "code": 0, "message": "success", "permission": null, "request_id": "e43da4ef221746868dc4c837d36f3807", "data": [ { "id": 4, "bk_inst_id": 1, "bk_obj_id": "bk_switch", "bk_asst_inst_id": 16, "bk_asst_obj_id": "bk_router", "bk_obj_asst_id": "bk_switch_default_bk_router", "bk_asst_id": "default" }, { "id": 6, "bk_inst_id": 2, "bk_obj_id": "bk_switch", "bk_asst_inst_id": 16, "bk_asst_obj_id": "bk_router", "bk_obj_asst_id": "bk_switch_default_bk_router", "bk_asst_id": "default" } ] }

从返回可以看出，虽然查询条件是"实例 16（bk_router）"，但命中的记录中实例 16 全部出现在bk_asst_inst_id（目标实例 ID）位置，而源侧分别是bk_switch下的实例 1 和实例 2——这正是"目标模型实例被关联"的场景，印证了接口的双向查询能力。

六、返回结果参数说明

6.1 response 通用封装

6.2 data 数据项说明

上述字段与源码中实例关联数据结构InstAsst完全对应，其定义位于 src/common/metadata/association.go：

type InstAsst struct { ID int64 `field:"id" json:"id,omitempty"` InstID int64 `field:"bk_inst_id" json:"bk_inst_id,omitempty" bson:"bk_inst_id"` ObjectID string `field:"bk_obj_id" json:"bk_obj_id,omitempty" bson:"bk_obj_id"` AsstInstID int64 `field:"bk_asst_inst_id" json:"bk_asst_inst_id,omitempty" bson:"bk_asst_inst_id"` AsstObjectID string `field:"bk_asst_obj_id" json:"bk_asst_obj_id,omitempty" bson:"bk_asst_obj_id"` OwnerID string `field:"bk_supplier_account" json:"bk_supplier_account,omitempty" bson:"bk_supplier_account"` ObjectAsstID string `field:"bk_obj_asst_id" json:"bk_obj_asst_id,omitempty" bson:"bk_obj_asst_id"` AssociationKindID string `field:"bk_asst_id" json:"bk_asst_id,omitempty" bson:"bk_asst_id"` BizID int64 `field:"bk_biz_id" json:"bk_biz_id,omitempty" bson:"bk_biz_id"` }

可见存储层还包含bk_supplier_account（开发商账号）与bk_biz_id（业务 ID）两个字段，若需要可在fields中补充返回。

七、源码级原理剖析

7.1 双向查询的核心：OR 条件构造

该接口"既能查源又能查目标"的关键在于查询条件中使用了 MongoDB 的$or（即代码中的common.BKDBOR）。在 src/scene_server/topo_server/service/association.go 中，SearchAssociationRelatedInst构造了如下条件：

queryCond := &metadata.InstAsstQueryCondition{ ObjID: request.Condition.ObjectID, Cond: metadata.QueryCondition{ Fields: request.Fields, Page: request.Page, Condition: mapstr.MapStr{ common.BKDBOR: []mapstr.MapStr{ { common.BKObjIDField: request.Condition.ObjectID, common.BKInstIDField: request.Condition.InstID, }, { common.BKAsstObjIDField: request.Condition.ObjectID, common.BKAsstInstIDField: request.Condition.InstID, }, }, }, }, }

翻译成 Mongo 查询语义即为：

$or: [ { bk_obj_id: <模型ID>, bk_inst_id: <实例ID> }, // 作为源模型实例 { bk_asst_obj_id: <模型ID>, bk_asst_inst_id: <实例ID> } // 作为目标模型实例 ]

InstAsstQueryCondition结构体定义于 src/common/metadata/association.go，包含Cond（查询条件 + 分页 + 字段投影）与ObjID（模型 ID）两部分。

7.2 参数强校验：缺一不可

接口处理函数在正式查询前执行了多层校验（src/scene_server/topo_server/service/association.go）：

1. 条件完整性：bk_inst_id == 0或bk_obj_id为空时，返回CCErrCommParamsNeedSet错误，提示必须同时提供'bk_inst_id' & 'bk_obj_id'；
2. 字段必填：fields为空数组时直接返回错误，避免无字段查询；
3. 分页上限：page.limit超过common.BKMaxInstanceLimit时返回CCErrCommPageLimitIsExceeded（分页限制超出）。

7.3 分页与排序约定

代码中强制将排序字段设置为id（request.Page.Sort = common.BKFieldID），即返回结果按关联记录 ID 升序排列，保证分页查询的数据顺序稳定，不会出现翻页时记录重复或遗漏。

关于 limit 上限，接口文档记载的"最大值 500"与源码中的常量定义一致：common.BKMaxInstanceLimit = 500（见 src/common/definitions.go）。文档中 page.limit 标注的"最大 200"为接口文档的历史描述，当前仓库源码中以 500 为硬性校验上限，实际调用时建议以服务端校验结果为准。

7.4 权限鉴权

查询前调用s.AuthManager.HasFindModelInstAuth(ctx.Kit, []string{request.Condition.ObjectID})校验用户对目标模型实例的查询权限（src/scene_server/topo_server/service/association.go）。鉴权失败时返回 403 无权限响应，这对应文档中"权限：模型实例查询权限"的说明。

7.5 底层调用链

SearchAssociationRelatedInst并不直接访问数据库，而是通过 apimachinery 客户端调用 coreservice 的Association().ReadInstAssociation（src/scene_server/topo_server/service/association.go），该 RPC 方法定义于 src/apimachinery/coreservice/association/association.go 与 src/apimachinery/coreservice/association/api.go，最终由 coreservice 模块完成 MongoDB 实例关联表的查询与投影，结果以[]*InstAsst形式封装进data返回。

完整调用链路可概括为：

HTTP POST /find/instassociation/related → topo_server Service.SearchAssociationRelatedInst → 参数校验 / 权限鉴权 / 分页排序预处理 → CoreService.Association().ReadInstAssociation (apimachinery 客户端) → coreservice 实例关联查询逻辑 → MongoDB 查询（$or 双向条件 + fields 投影 + 分页）

八、实战注意事项

1. fields是必填项：漏传或传空数组会被直接拒绝，建议至少包含id、bk_inst_id、bk_asst_inst_id、bk_obj_id、bk_asst_obj_id以便定位关联双方；
2. 分页要传全：page对象中start与limit均必填，limit受服务端 500 上限约束，超出会返回CCErrCommPageLimitIsExceeded；
3. 结果方向需自行区分：接口返回的data数组混合了"该实例作为源"与"该实例作为目标"两类记录，可通过比较bk_inst_id/bk_asst_inst_id与查询的bk_inst_id是否相等来判断记录方向；
4. 权限前置：调用方（应用）需要对查询的模型具备实例查询权限，否则即使参数正确也会被鉴权拦截；
5. 排查问题用request_id：返回报文中的request_id是请求链 ID，结合日志可按rid维度全链路排查查询失败原因。

九、关联资源延伸阅读

• 接口实现： src/scene_server/topo_server/service/association.go
• 路由注册： src/scene_server/topo_server/service/service_business_initfunc.go
• 请求/响应数据结构： src/common/metadata/association.go、InstAsst 定义
• 分页上限常量： src/common/definitions.go
• coreservice 查询入口： src/apimachinery/coreservice/association/api.go
• 同族接口参考（创建/批量创建/删除实例关联）：可对比阅读 docs/apidoc/cc/zh_hans/add_instance_association.md、docs/apidoc/cc/zh_hans/batch_create_instance_association.md、docs/apidoc/cc/zh_hans/batch_delete_inst.md

• 后端
• 企业应用
• 运维