企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

本篇文章围绕 bk-cmdb 开放 API 中的「查询资源池主机」接口（POST /api/v3/hosts/list_resource_pool_hosts）展开。资源池是蓝鲸配置平台中承载「未分配业务」主机（空闲机）的默认容器，运维人员常需要批量盘点资源池内主机的 IP、OS、云厂商等信息。读完本文，你将掌握该接口的完整输入/输出参数语义、host_property_filter组合过滤规则的组装方法与操作符取值范围、分页与字段裁剪的实战技巧，以及从开放 API 入口到 coreservice 底层查询的完整调用链。

一、接口概述与适用场景

1.1 接口定位

list_resource_pool_hosts用于查询资源池（Resource Pool）中的主机，调用方需要具备主机池主机查看权限。在 bk-cmdb 的模型中，资源池是每个业务体系下由系统自动生成的默认容器（默认业务bk_default下的资源池模块），从资源池把主机分配到具体业务、或从业务回收主机回资源池，都属于主机全生命周期管理的常见操作。

该接口与「查询业务下主机」（list_biz_hosts）的核心区别在于：它不需要调用方显式传入业务 ID，服务端会自动定位资源池所属的默认业务。从源码看，这一逻辑位于 findhost.go：服务端通过查询bk_default=1的默认业务实例来定位资源池。

1.2 适用场景

• 资源池主机批量盘点与巡检：定时拉取资源池内全部主机，核对 IP、MAC、CPU、内存、磁盘等资产信息；
• 资源池清理与容量规划：查询符合特定条件（如云厂商、OS 类型）的主机，辅助回收或分配决策；
• 与add_host_to_resource_pool、move_host_to_resource_pool、delete_host_batch_from_resource_pool等接口配合，完成资源池主机的完整管理闭环（相关实现见 hostserver.go）。

二、输入参数详解

接口的请求体是一个 JSON 对象，共三个可选参数：

2.1 page 分页参数

分页参数的结构定义在 page.go 中（BasePage：sort、limit、start、enable_count）。服务端对分页有严格校验：

• start不能小于 0；
• limit必须大于 0 且不超过系统最大页大小；
• 系统级最大页大小BKMaxPageSize = 1000定义在 definitions.go，而本接口文档明确限制每页最大 500 条，实际使用时请以接口文档为准，避免因超出限制被拒绝（exceed max page size）。

实战建议：

• 资源池主机量通常较大，务必使用分页遍历，避免一次性拉取全量数据；
• sort建议显式指定排序字段（如bk_host_id），保证多次翻页时数据顺序稳定，避免分页过程中因排序不稳定产生重复或遗漏。

2.2 fields 字段裁剪

fields是一个字符串数组，用于指定返回结果中每个主机对象包含哪些属性字段。例如：

"fields": [ "bk_host_id", "bk_cloud_id", "bk_host_innerip", "bk_os_type", "bk_mac" ]

不填fields时默认返回所有字段；填写后服务端只投影（projection）指定字段，既减少网络流量，也能显著加速大结果集的查询。需要注意：只应填写实际需要展示或使用的字段，且必须确保字段名拼写正确（与响应参数中的系统内置字段或自定义属性字段名一致），否则该字段不会出现在返回结果中。

2.3 host_property_filter 组合查询条件

host_property_filter是「根据主机属性字段搜索主机」的核心参数，采用与 querybuilder 模块一致的规则语法：

关键约束：

• 组合支持AND和OR两种方式；
• 规则可以嵌套，最多嵌套 2 层（即整体深度不超过 3 层）；
• 嵌套深度由querybuilder中的MaxDeep = 3常量控制（树高度计算，最多嵌套 2 层），定义见 types.go；服务端校验超深时会返回exceed max query condition deepth错误（校验逻辑见 hostserver.go）。

rules 原子过滤规则

过滤规则本质是field、operator、value三元组（文档中称四元组field,operator,value，实际即为这三个字段）：

operator 可选值：

其中between/not_between之外的通用、数组、数字、字符串、空值、时间等操作符的更完整语义（如is_empty、is_not_empty、datetime_less、contains、is_null、exist等）可参考 querybuilder 官方文档。不过，本接口实际允许的操作符以本文表格所列为准——服务端在 ListHostsParameter.Validate 中校验host_property_filter，超深或值类型不一致（NeedSameSliceElementType: true）都会报参数错误。源码中 operator 常量定义可见 types.go。

组装规则：原子规则（field+operator+value）与组合节点（condition+rules）可自由混合，形成一棵过滤条件树；根节点与嵌套节点都可以是condition+rules的组合形式。querybuilder 的完整设计与 demo 见 README。

三、完整调用示例

3.1 请求体

以下请求演示了「AND 组合内嵌套 OR 组合」的两层嵌套用法：查询「外网 IP 等于 127.0.0.1，且（OS 类型不属于 3 或 SLA 等于 1）」的资源池主机，并按bk_host_id升序返回前 10 条：

{ "page": { "start": 0, "limit": 10, "sort": "bk_host_id" }, "fields": [ "bk_host_id", "bk_cloud_id", "bk_host_innerip", "bk_os_type", "bk_mac" ], "host_property_filter": { "condition": "AND", "rules": [ { "field": "bk_host_outerip", "operator": "equal", "value": "127.0.0.1" }, { "condition": "OR", "rules": [{ "field": "bk_os_type", "operator": "not_in", "value": ["3"] }, { "field": "bk_sla", "operator": "equal", "value": "1" }] }] } }

要点拆解：

• 根节点condition为AND，两个子规则分别是原子规则（bk_host_outerip = "127.0.0.1"）和嵌套的 OR 组合规则；
• 嵌套层数 = 根节点(1) + 内层(1) = 2 层，符合「最多嵌套 2 层」约束；
• not_in的 value 必须是同类型数组（此处为字符串数组["3"]）；
• 若不传page/host_property_filter/fields，等价于无条件查询资源池全部主机并返回所有字段，此时应配合fields控制返回体量。

3.2 响应示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": { "count": 1, "info": [ { "bk_cloud_id": "0", "bk_host_id": 17, "bk_host_innerip": "192.168.1.1", "bk_mac": "", "bk_os_type": "1" } ] } }

四、响应参数说明

4.1 顶层响应

4.2 data

4.3 data.info 系统内置字段

info数组中每个元素是一台主机的属性对象，以下是系统内置属性字段（其余返回值取决于用户自定义的属性字段）：

注意：此处的返回值仅对系统内置属性字段做了说明，其余返回值取决于用户自己定义的属性字段。也就是说，如果业务方在主机模型上扩展了自定义属性（如机房机柜位rack、上架日期等），只要在fields中声明，也会一并出现在info元素中。

五、源码级调用链与实现原理

为了让读者不仅「会调」，还能「看懂」，下面从路由注册到数据库查询梳理该接口的完整调用链。

5.1 路由注册

接口在 hostserver 初始化时注册，路由为POST /hosts/list_resource_pool_hosts，对应处理函数ListResourcePoolHosts（见 service_initfunc.go）。通过该路由可知完整开放 API 路径为/api/v3/hosts/list_resource_pool_hosts。

5.2 资源池定位

ListResourcePoolHosts 的实现步骤如下：

1. 将请求体解码为meta.ListHostsParameter（结构定义见 hostserver.go）；
2. 查询bk_default=1的默认业务（资源池业务），通过ReadInstance读取业务实例；
3. 若存在多个默认业务，仅采用与请求头supplier_account一致的业务（多供应商场景兼容）；
4. 取得资源池业务 ID 后，调用listBizHosts完成主机查询。

5.3 主机查询与过滤条件构建

listBizHosts在 findhost.go 中完成参数合法性校验（page是否非法、bk_set_ids与set_cond是否互斥等），然后将HostPropertyFilter、Fields、Page组装为meta.ListHosts请求，最终调用 coreservice 的ListHosts接口。

底层查询在 coreservice 的 searcher.go 中执行：

• buildListHostsFilter先根据拓扑关系计算需要过滤的主机 ID 集合；
• 再通过option.GetHostPropertyFilter(kit.Ctx)将host_property_filter规则树转换为 MongoDB 查询条件；
• 最终将主机 ID 过滤与属性过滤合并为$and查询条件执行分页查询。

可以看到，host_property_filter的「AND/OR 嵌套规则」最终会映射为 MongoDB 的$and/$or查询表达式——这正是该参数能精确表达复杂主机筛选条件的底层原理（querybuilder 的Rule接口ToMgo定义了这一转换，见 querybuilder README）。

5.4 响应结构

data中的count为符合条件的总记录数，info为当前页主机列表（仅包含fields指定的字段）。若fields为空，则返回主机全量属性。

六、常见问题与最佳实践

6.1 过滤规则报「超出最大深度」

若构造了三层以上嵌套（如 AND 内套 OR、OR 内再套 AND），服务端会返回参数错误。请保持嵌套不超过 2 层：一层「根组合 + 原子规则」最常见；复杂筛选优先通过in/not_in或把条件拆分为多个并列原子规则来表达，而不是一味加深嵌套。

6.2 分页 limit 超限

每页最多 500 条。需要拉取全量时，请用start递增翻页循环，直至返回的info为空或start + limit >= count。count反映的是满足过滤条件的总记录数，与是否使用fields裁剪无关。

6.3 字段名写错导致结果为空

fields与host_property_filter中的field都必须是主机模型上真实存在的属性名。建议先不带过滤条件调用一次接口（fields只带bk_host_id），观察返回的内置字段，再按需构造过滤与投影，避免因拼写错误（如把bk_host_innerip写成bk_innerip）拿到空结果或报字段不存在错误。

6.4 组合条件优先级

同一层rules数组内多条原子规则之间按condition（AND 或 OR）组合；嵌套的子rules作为整体参与父层逻辑。因此「AND 内嵌 OR」与「OR 内嵌 AND」的语义完全不同，组装时应先在草稿中画出规则树再落 JSON。

6.5 相关配套接口

资源池主机的完整运维闭环还包括：

• 添加主机到资源池（POST /hosts/add_host_to_resource_pool）；
• 从资源池移出主机到业务（assign_host_to_app）；
• 业务主机移入资源池（move_host_to_resource_pool）；
• 批量删除资源池主机（delete_host_batch_from_resource_pool）。

配合本接口的查询能力，即可实现「查询 → 分配/回收 → 再次查询校验」的资源池主机管理自动化流程。

七、小结

list_resource_pool_hosts是 bk-cmdb 面向资源池场景的标准主机查询接口，其能力由三块构成：page（分页排序）、fields（字段投影裁剪）、host_property_filter（基于 querybuilder 的 AND/OR 可嵌套属性过滤）。掌握规则树的组装与操作符语义，就能精确圈定资源池内的任意主机子集；理解从 hostserver 路由到 coreservice 的ListHosts的调用链，则有助于排查参数校验、权限、排序等各类问题。建议在实际集成时结合 querybuilder 规则参考 与本文的操作符对照表进行参数构造，并通过小规模分页先行验证，再应用到生产脚本或自动化任务中。

• 后端
• 企业应用
• 运维