企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

在蓝鲸智云配置平台（bk-cmdb）中，"模型引用"（Model Quote）是一种将内建表格（inner table）属性建模为独立实例数据的能力：当一个模型的某个属性是表格类型（如主机上的disk磁盘列表）时，每一行表格数据都会被持久化为一条"引用实例"（quoted instance）。本文以官方 API 文档 list_quoted_inst.md 为核心，结合仓库源码与测试用例，系统讲解list_quoted_inst接口的请求参数、过滤规则、分页语义、鉴权行为与底层实现，帮助你快速上手通过 API 精确查询某模型引用的实例列表，并理解其与普通实例查询的差异。

一、接口概述：从业务视角查询被引用实例

1.1 功能与适用场景

list_quoted_inst用于查询引用该模型的实例列表，接口版本要求v3.10.30+。其典型场景包括：

• 查询某台主机（host）上挂载的磁盘列表（即主机模型disk属性引用的实例）；
• 查询业务内自定义模型中被引用的表格型属性数据；
• 配合fields字段裁剪返回内容，仅获取需要的属性，减少网络流量与接口耗时。

1.2 权限语义

接口权限与是否传入bk_biz_id密切相关（可参考源码 quoted_instance.go 中的鉴权逻辑）：

• 传入bk_biz_id（业务视角查询）：当被引用模型是**业务（biz）**时，校验"业务查看"权限；否则校验"业务访问"权限；
• 未传入bk_biz_id：校验对应模型实例的查看权限。

对应到代码实现：

if opt.BizID != 0 { bizAction := meta.ViewBusinessResource if opt.ObjID == common.BKInnerObjIDApp { bizAction = meta.Find } ... } else { authResp, authorized, err := s.AuthManager.HasFindModelInstAuth(cts.Kit, []string{opt.ObjID}) ... }

即：不传业务 ID 时走模型实例查看权限；传业务 ID 时以业务视角鉴权，业务模型本身走Find权限，其他模型走ViewBusinessResource权限。

二、请求参数详解

2.1 公共参数

请求包含bk_app_code、bk_app_secret、bk_username、bk_token等公共参数（common_args_desc），用于 API 网关的身份认证。

2.2 接口参数表

其中bk_obj_id与bk_property_id两者共同定位"哪一张引用实例表"。在源码中，二者用于解析引用目标对象 ID（quoted objID），见 model_quote.go：

// GetQuotedObjID get quoted object id by source object id & property id func (q *quote) GetQuotedObjID(kit *rest.Kit, objID string, propertyID string) (string, error) { expr, err := filtertools.And(filtertools.GenAtomFilter(common.BKSrcModelField, filter.Equal, objID), filtertools.GenAtomFilter(common.BKPropertyIDField, filter.Equal, propertyID)) ... // 查询模型引用关系表（ModelQuoteRelation），返回 DestModel return res.Info[0].DestModel, nil }

引用关系的元数据结构定义在 model_quote.go（ModelQuoteRelation）：DestModel（派生模型，如bk_host_disk）、SrcModel（源模型，如host）、PropertyID（属性 ID，如disk）、Type（引用类型，如 table）。GenerateModelQuoteObjID生成的引用目标对象 ID 形如bk_<源模型>#<属性ID>（见 model_quote.go）。

三、filter 过滤规则：两级嵌套组合查询

filter用于按被引用模型的属性字段搜索数据，支持两种规则类型，可嵌套组合，组合层级最多两层。

3.1 组合过滤规则（Combination Filtering Rules）

由其他规则组合而成，节点间支持逻辑与/或关系：

3.2 原子过滤规则（Atomic Filtering Rules）

表示对某一字段进行过滤的基础规则，任何过滤规则要么直接是原子规则，要么由多个原子规则组合而成：

3.3 操作符语义补充

尽管接口文档正文列出 10 个操作符，通用过滤模块 pkg/filter 实际支持的 operator 更加丰富，便于深入理解过滤能力边界：

• 通用操作符：equal、not_equal（value 为数值/bool/字符串等基本类型）；
• 集合操作符：in、not_in（value 为同类型基本数据组成的数组）；
• 数字操作符：less、less_or_equal、greater、greater_or_equal（value 为数值，支持数值与时间戳字段）；
• 时间操作符：datetime_less、datetime_less_or_equal、datetime_greater、datetime_greater_or_equal（value 支持时间戳数值与 CC 时间格式字符串）；
• 字符串操作符：begins_with、contains、ends_with及其大小写敏感/不敏感、否定变体；
• 数组与空值操作符：is_empty、is_not_empty、size、is_null、is_not_null；
• 字段存在状态操作符：exist、not_exist。

过滤表达式在服务端会被校验并转换为 MongoDB 查询条件。核心转换逻辑见 CommonFilterOption 的Validate与ToMgo：先调用c.Filter.Validate(op)校验表达式合法性，再通过c.Filter.ToMgo()生成 Mongo 过滤条件。关于通用查询参数的完整组装规则，可阅读仓库内 pkg/filter/README.md（即接口文档引用的规则说明的本地化版本）。

四、page 分页参数

page用于控制分页与计数，字段如下：

分页结构的底层定义是 BasePage，其校验逻辑（ValidateWithEnableCount，见 page.go）与接口文档描述一致：

• enable_count = true时，start、limit、sort必须均为初始值，否则报参数非法；
• start不能小于 0，limit必须大于 0；
• 超限时报分页超限错误。全局常量定义于 definitions.go：单页最大BKMaxPageSize = 1000，接口限制BKMaxLimitSize = 500。

4.1 请求参数示例（详情查询）

{ "bk_app_code": "code", "bk_app_secret": "secret", "bk_username": "xxx", "bk_token": "xxxx", "bk_obj_id": "host", "bk_property_id": "disk", "filter": { "condition": "AND", "rules": [ { "field": "name", "operator": "not_equal", "value": "test" }, { "condition": "OR", "rules": [ { "field": "operator", "operator": "not_in", "value": [ "me" ] }, { "field": "bk_inst_id", "operator": "equal", "value": 123 } ] } ] }, "fields": [ "name", "description" ], "page": { "start": 0, "limit": 2, "sort": "name", "enable_count": false } }

该示例展示了"组合规则 + 原子规则"的二级嵌套：外层AND组合两个条件，内层OR组合not_in与equal两个原子规则，fields仅返回name与description。

4.2 请求参数示例（纯计数查询）

{ "bk_app_code": "code", "bk_app_secret": "secret", "bk_username": "xxx", "bk_token": "xxxx", "bk_obj_id": "host", "bk_property_id": "disk", "filter": { "field": "name", "operator": "equal", "value": "test" }, "page": { "enable_count": true } }

五、响应结果说明

5.1 顶层响应字段

5.2 data 字段

5.3 info 字段

5.4 详情响应示例

{ "result": true, "code": 0, "message": "success", "permission": null, "request_id": "87de106ab55549bfbcc46e47ecf5bcc7", "data": { "count": 0, "info": [ { "name": "test1", "description": "test instance 1" }, { "name": "test2", "description": "test instance 2" } ] } }

5.5 计数响应示例

{ "result": true, "code": 0, "message": "success", "permission": null, "request_id": "87de106ab55549bfbcc46e47ecf5bcc7", "data": { "count": 5, "info": [] } }

注意：计数模式下info为空数组，仅通过count返回符合条件的记录总数。

六、源码级实现原理：一次查询的完整调用链

从顶层 API 到底层存储，list_quoted_inst的调用链可以拆解为四层：

1. 路由注册：topo_server 在 service_model_quote_initfunc.go 中注册POST /findmany/quoted/instance路由，绑定ListQuotedInstance处理器；
2. 业务逻辑层：quoted_instance.go 中的ListQuotedInstance负责参数解码与校验、鉴权、解析引用目标对象 ID（GetQuotedObjID），随后调用 coreservice 的ModelQuote().ListQuotedInstance；
3. API 网关层（apimachinery）：instance.go 中通过POST /findmany/quoted/model/<objID>/instance请求 coreservice；
4. 数据访问层（coreservice）：quoted_inst.go 中ListQuotedInstance将CommonQueryOption转为 Mongo 查询：

table := common.GetInstTableName(objID, cts.Kit.SupplierAccount) filter, err := opt.ToMgo() ... if opt.Page.EnableCount { count, err := mongodb.Client().Table(table).Find(filter).Count(cts.Kit.Ctx) ... cts.RespEntity(metadata.InstDataInfo{Count: int(count)}) return } instances := make([]mapstr.MapStr, 0) err = mongodb.Client().Table(table).Find(filter).Start(uint64(opt.Page.Start)).Limit(uint64(opt.Page.Limit)). Fields(opt.Fields...).All(cts.Kit.Ctx, &instances) ... cts.RespEntity(metadata.InstDataInfo{Info: instances})

从实现可观察到三个关键行为：

• enable_count = true时只执行Count查询，不返回实例明细，与接口文档的计数语义一致；
• fields直接映射为 MongoDB 的Fields(...)投影，服务端即裁剪字段，这正是"加速请求、降低网络传输"的实现机制；
• 查询会自动追加SetModOwner的所属（supplier account）过滤条件，保证多租户数据隔离。

七、测试用例验证

仓库中的集成测试 model_quote_test.go 完整覆盖了模型引用的生命周期，其中与查询相关的用例包括：

• 创建模型分类、模型、表格类型属性（PropertyType: common.FieldTypeInnerTable，option 中包含header列定义）及模型实例；
• 批量创建引用实例（BatchCreateQuotedInstOption，携带bk_inst_id关联源实例）；
• 列表查询（ListQuotedInstance，limit 100）验证返回 2 条记录，且bk_inst_id均等于源实例 ID（见 model_quote_test.go）；
• 更新引用实例后再次查询，验证字段值已被更新（cc1=30、cc2="ccc"，见 model_quote_test.go）；
• 删除引用实例后再次查询，验证返回 0 条记录（见 model_quote_test.go）。

该测试同时验证了引用实例的bk_inst_id必须对应真实存在的源模型实例，以及属性必须存在等前置校验（prop_no_exist与不存在的实例 ID 均会报错）。

八、实践要点与注意事项

1. 必填参数不可缺：bk_obj_id、bk_property_id、page为必填，缺失时参数校验直接报错（对应ListQuotedInstOption.Validate，见 model_quote.go）；
2. 组合嵌套最多两层：构造复杂filter时注意层级上限，超深嵌套会被拒绝；
3. 计数与详情是两种模式：需要总数时设置enable_count=true并让start/limit/sort保持初始值；需要明细时按需设置fields裁剪字段；
4. limit上限 500：单页最大记录数为 500（BKMaxLimitSize），超出会报分页超限；
5. 权限前置校验：请确保调用方已具备对应模型实例的查看权限，或业务视角的业务查看/访问权限；
6. 关联理解：查询接口与批量创建、批量更新、批量删除接口共同构成引用实例的完整操作集合，路由均为/quoted/instance系列，可组合用于表格型属性的数据治理场景。

结语

list_quoted_inst是 bk-cmdb 模型引用能力的重要读取入口。本文从官方文档的请求/响应结构出发，结合 quoted_instance.go、quoted_inst.go、pkg/filter 等源码与集成测试，完整还原了该接口的参数语义、鉴权行为、过滤转换、分页校验与底层 MongoDB 执行逻辑。掌握本文内容后，你可以直接在业务开发中正确构造请求参数，并通过fields与两级filter组合实现高效、精准的引用实例数据查询。

• 后端
• 企业应用
• 运维