企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

本文以蓝鲸智云配置平台（bk-cmdb）开放 API 中的"查询 Container 列表"接口（list_kube_container，版本 v3.12.1+）为核心，系统讲解其请求参数、基于通用 filter 的嵌套过滤规则、分页与计数语义，并结合仓库源码剖析该接口从网关到 coreservice 的完整调用链路。读完本文，你将能独立构造"按业务 + 按 Pod + 多条件组合过滤"的容器查询请求，掌握enable_count计数模式的正确用法，并能快速定位相关源码以便二次开发。

一、接口概览

list_kube_container用于在蓝鲸 CMDB 的容器资源管理中查询 Container（容器）列表，是 Kube 容器数据管理能力的一部分（容器数据模型可参考 docs/db/container_data_manage.md）。该接口具备以下特性：

• 最低版本：v3.12.1+；
• 权限要求：业务访问（需通过蓝鲸权限中心鉴权，资源类型为 KubeContainer）；
• 查询维度：按bk_biz_id（业务）维度查询，可选用bk_pod_id（所属 Pod）进一步收窄范围；
• 返回控制：通过fields精确指定需要返回的字段，减少网络传输；
• 过滤能力：通过filter支持组合/原子两种过滤规则，可嵌套使用。

从源码路由注册看，该接口对应的 HTTP 端点为POST/findmany/kube/container，由拓扑服务（topo_server）处理，注册代码位于 src/scene_server/topo_server/service/kube/service.go：

// container utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/findmany/kube/container", Handler: s.ListContainer}) utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/findmany/kube/container/by_topo", Handler: s.ListContainerByTopo})

二、输入参数说明

接口请求体为 JSON，核心参数如下：

其中bk_biz_id与bk_pod_id的含义可以从数据模型得到印证：Container 结构体中同时携带bk_pod_id、bk_biz_id、bk_cluster_id、bk_namespace_id等关联字段，定义见 src/kube/types/pod.go。

关于bk_pod_id的实现细节：从 src/scene_server/topo_server/service/kube/pod.go 可以看到，当bk_pod_id > 0时，服务端会将其自动转换为一条bk_pod_id字段的equal原子过滤规则，并与请求中的filter做AND组合后下发给 coreservice：

containerCond := req.Filter if req.PodID > 0 { containerCond, err = filtertools.And(filtertools.GenAtomFilter(types.BKPodIDField, filter.Equal, req.PodID), req.Filter) ... }

因此bk_pod_id与filter中的 Pod 相关条件是叠加生效的（AND 关系）。

filter 字段说明

filter是 container 属性字段的过滤规则，用于根据 container 的属性字段搜索数据。该参数支持组合过滤规则与原子过滤规则两种类型，其中组合过滤规则可以嵌套，最多嵌套 2 层。该过滤语法是 bk-cmdb 的通用查询模块（pkg/filter）的标准格式，完整定义见 pkg/filter/README.md。

组合过滤规则

由其它规则组合而成的过滤规则，组合的规则间支持逻辑与/或关系：

原子过滤规则

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

关于 value 的取值格式可以参照 pkg/filter/README.md 的约定：equal/not_equal接受数值、bool、字符串等基本类型；in/not_in接受类型一致的基本类型数组；less/less_or_equal/greater/greater_or_equal用于数值或时间戳字段；between/not_between用于区间匹配。该通用模块还额外提供了字符串模糊匹配（如contains、begins_with等）、空值判断（is_null、is_not_null）、数组操作符（is_empty、size）等更丰富的操作符，可用于其它支持 filter 的接口。

字段合法性校验：服务端在校验阶段会用 Container 的字段类型定义校验 filter 中field与operator的匹配性，防止用错误的字段类型查询导致误判，校验代码见 src/kube/types/pod.go 中的ContainerQueryOption.Validate()：

op := filter.NewDefaultExprOpt(ContainerFields.FieldsType()) if err := p.Filter.Validate(op); err != nil { ... }

page 字段说明

分页上限 500 在源码中有直接体现：containerQueryLimit = 500，并通过p.Page.ValidateWithEnableCount(false, containerQueryLimit)校验，见 src/kube/types/pod.go。此外，若sort为空，服务端会默认按id排序，保证结果有序可复现，见 src/scene_server/topo_server/service/kube/pod.go。

三、调用示例

获取详细信息请求参数示例

以下请求在业务 4 中查询 Pod ID 为 4 下的容器，过滤规则为：name不等于container1，并且（container_uid不在集合["xxxxxx"]中或image等于xxx），只返回name与container_uid两个字段：

{ "bk_biz_id": 4, "bk_pod_id": 4, "filter": { "condition": "AND", "rules": [ { "field": "name", "operator": "not_equal", "value": "container1" }, { "condition": "OR", "rules": [ { "field": "container_uid", "operator": "not_in", "value": [ "xxxxxx" ] }, { "field": "image", "operator": "equal", "value": "xxx" } ] } ] }, "fields": [ "name", "container_uid" ], "page": { "start": 0, "limit": 10, "sort": "name", "enable_count": false } }

可以看到该示例中组合过滤规则正好嵌套了 2 层：外层AND下挂一条原子规则和一个OR组合规则，OR内再挂两条原子规则。

获取数量请求参数示例

仅统计满足条件的容器数量，此时page只需设置enable_count: true，start、limit、sort均为初始化值：

{ "bk_biz_id": 4, "filter": { "condition": "AND", "rules": [ { "field": "name", "operator": "not_equal", "value": "container1" }, { "condition": "OR", "rules": [ { "field": "container_uid", "operator": "not_in", "value": [ "xxxxxx" ] }, { "field": "image", "operator": "equal", "value": "xxx" } ] } ] }, "page": { "enable_count": true } }

四、响应示例

获取详细信息返回结果示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": { "count": 0, "info": [ { "name": "container2", "container_uid": "xxx" }, { "name": "container3", "container_uid": "xxx" } ] } }

info数组中的每个元素只包含请求fields中声明的字段。这正是fields参数的作用——服务端将其透传为 MongoDB 查询的Fields(...)投影，从而只返回指定列，见 src/source_controller/coreservice/service/kube/pod.go。

获取数量返回结果示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": { "count": 100, "info": [] } }

计数模式下data.info为空数组，data.count为满足过滤条件的容器总数。

五、响应参数说明

data

info[x]

info[x]中的字段与 Container 数据模型（src/kube/types/pod.go）一一对应，完整字段清单如下：

从Container结构体的bson标签可以看到，container_uid、started、limits、requests、liveness、environment、mounts等字段与 Kubernetes 容器描述信息对齐，说明 CMDB 将 Kubernetes 的容器规格信息（端口、探针、资源、环境变量、挂载）完整纳入了自身的数据模型。

六、源码级调用链路剖析

为了便于理解该接口的完整处理流程，下面梳理从请求进入到数据返回的关键路径：

1. 路由注册：topo_server 注册POST /findmany/kube/container端点，见 src/scene_server/topo_server/service/kube/service.go。

2. 参数解析与校验：ListContainer将请求体解析为ContainerQueryOption，随后执行req.Validate()。校验内容依次为：bk_biz_id必填、bk_pod_id合法性、分页参数（limit 上限 500）、filter 表达式合法性（基于ContainerFields的字段类型定义），见 src/scene_server/topo_server/service/kube/pod.go 与 src/kube/types/pod.go。

3. 鉴权：构造KubeContainer资源类型 +Find动作的权限属性，调用AuthManager.Authorize完成权限校验（对应文档中的"权限：业务访问"），见 src/scene_server/topo_server/service/kube/pod.go。

4. 共享集群兼容：通过GenSharedNsListCond结合业务与命名空间信息生成实际查询条件，兼容共享集群（多个业务共享同一命名空间）的场景，见 src/scene_server/topo_server/service/kube/pod.go。

5. 计数模式：当page.enable_count = true时，走GetCountByFilter直接对cc_ContainerBase表统计数量并返回，见 src/scene_server/topo_server/service/kube/pod.go。

6. 数据查询：非计数模式下，构造metadata.QueryCondition调用 coreservice 的ListContainer，底层执行对cc_ContainerBase表的Find + Start + Limit + Sort + Fields组合查询，见 src/source_controller/coreservice/service/kube/pod.go。

7. 测试验证：仓库中的集成测试覆盖了完整的"建业务/集群/命名空间 → 建 Pod/Container → 查询"链路，其中find container用例验证了按name+bk_pod_id过滤查询与计数查询的正确性，见 src/test/topo_server/pod_test.go。

七、实战建议与注意事项

• 善用fields裁剪字段：info[x]中可能包含ports、environment、mounts等嵌套结构，若业务只关心name、container_uid、image，务必在fields中显式声明，既加速查询又降低流量。
• enable_count的用法：统计数量时，请求中除page.enable_count = true外，start必须为 0、limit必须为 0、sort必须为空字符串；响应中data.info为空数组，数量在data.count中。
• filter 嵌套层级：组合过滤规则最多嵌套 2 层，构造复杂条件时注意控制层级，超过限制会校验失败。
• 操作符与 value 匹配：in/not_in的 value 必须是同类型数组；数值/时间戳字段才可使用大小比较操作符；between/not_between需要成对区间值。用错类型或字段会返回参数校验错误。
• bk_pod_id与filter的关系：二者为 AND 叠加，无需在filter中重复声明bk_pod_id条件。
• 分页上限：单次limit最大 500，需要全量数据时请分页拉取，并结合sort（不传默认按id升序）保证分页稳定。

• 后端
• 企业应用
• 运维