企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

本文基于蓝鲸智云配置平台（bk-cmdb）开放 API 文档中「创建模型（Create Object）」接口的说明，完整讲解POST /api/v3/create/object接口的请求参数、请求/响应示例，并结合 src/scene_server/topo_server/logics/model/object.go 与 src/scene_server/topo_server/service/object.go 的源码，剖析模型创建背后的校验规则、建表逻辑、默认属性组与审计链路。读完本文，你将掌握如何通过开放 API 在 bk-cmdb 中安全、正确地创建一个自定义模型（对象模型），并理解每个参数在底层数据模型与数据库中的实际落点。

一、接口概述与权限要求

「创建模型」是 bk-cmdb 模型管理体系中最高频的基础操作之一：业务模型（如主机、模块）由系统内置，而业务自定义数据（如机柜、网络设备、存储资源等）则需要通过该接口以「模型 + 模型分组」的方式建模，随后才能向该模型写入实例数据。

• 接口路径：POST /api/v3/create/object
• 接口语义：创建一个模型（对象模型）
• 权限要求：创建模型（Create Model）权限，未授权时将返回无权限错误
• 网关注册：该路由在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中登记，operationId为create_object，后端转发方式为 HTTP POST，路径原样透传至 bk-cmdb 的/api/v3/create/object。

二、请求参数详解

创建模型接口的请求体为一个 JSON 对象，各字段定义如下表：

参数与元数据结构的对应关系

上述参数并非散落的业务字段，而是与 src/common/metadata/object.go 中定义的模型常量与Object结构体一一对应：

• ModelFieldObjCls = "bk_classification_id"：模型分组 ID，对应结构体字段ObjCls，数据库字段同样为bk_classification_id；
• ModelFieldObjectID = "bk_obj_id"：模型 ID，对应ObjectID；
• ModelFieldObjectName = "bk_obj_name"：模型名称，对应ObjectName；
• ModelFieldObjIcon = "bk_obj_icon"：模型图标，对应ObjIcon；
• ModelFieldObjSortNumber = "obj_sort_number"：排序序号，对应ObjSortNumber。

在 src/scene_server/topo_server/logics/model/object.go 的isValid参数校验逻辑中，请求体经由mapstruct.Decode2Struct反序列化为metadata.Object结构体，随后依次执行以下校验：

1. 模型 ID 校验：bk_obj_id必须通过valid.ValidModelIDField的模型 ID 格式校验；
2. 模型名称校验：bk_obj_name必须通过valid.ValidModelNameField校验；
3. 分组必填校验：创建时bk_classification_id必须存在，否则返回参数缺失错误；
4. 内置模型占用校验：bk_obj_id不得与系统内置模型 ID（如biz、set、module、host、proc等）冲突，源码中通过metadata.IsCommon(obj.ObjectID)判断，命中内置 ID 时提示 "the built-in object id, please use a new one"；
5. 供应商账户回填：OwnerID（即bk_supplier_account）由服务端以请求上下文中的kit.SupplierAccount自动填充，用户无需（也无法）在请求中指定。

创建前的分组存在性检查

分组 ID 必须是已存在的模型分组。在 createObjectParamCheck 中，会先调用isClassificationExist按bk_classification_id查询bkTableNameObjClassification（模型分组表）的计数，若分组不存在，直接返回错误码CCErrTopoObjectClassificationSelectFailed（1101024，见 src/common/errInfo.go）。同时该函数还强制校验：

• bk_obj_icon不能为空：图标未设置时返回CCErrCommParamsNeedSet；
• obj_sort_number不能小于 0：数值非法时返回CCErrCommParamsInvalid。

请求示例

以创建一个位于test分组下的test模型为例（与文档示例一致）：

{ "creator": "admin", "bk_classification_id": "test", "bk_obj_name": "test", "bk_obj_icon": "icon-cc-business", "bk_obj_id": "test", "obj_sort_number": 1 }

提示：上述示例为便于演示仅作最小化配置。生产实践中建议：bk_obj_id使用有业务语义的英文标识（如rack、switch），bk_obj_name使用中文或英文展示名，bk_obj_icon使用 bk-cmdb 前端已注册的图标类名（如icon-cc-business）。

三、响应示例与响应参数

接口返回统一结果结构，正常创建成功时：

{ "code": 0, "permission": null, "result": true, "message": "success", "data": { "description": "", "bk_ishidden": false, "bk_classification_id": "test", "creator": "admin", "bk_obj_name": "test", "bk_ispaused": false, "last_time": null, "bk_obj_id": "test", "create_time": null, "bk_supplier_account": "0", "position": "", "bk_obj_icon": "icon-cc-business", "modifier": "", "id": 2000002118, "ispre": false, "obj_sort_number": 1 } }

其中响应参数含义如下：

响应 data 中的关键字段解读

对照 Object 结构体 可以解释data中每个字段的来源与含义：

• id：系统生成的自增模型 ID（示例中为2000002118），是模型在数据库中的主键，后续创建属性、查询实例、配置权限时均会用到；
• bk_supplier_account：供应商账户，服务端自动写入，示例中为"0"（默认供应商账户），可推断默认场景下单供应商部署即为该值；
• ispre：是否内置模型（IsPre），新创建的模型为false；
• bk_ishidden：是否在页面上隐藏，新模型默认false；
• bk_ispaused：是否停用，新模型默认false；
• create_time/last_time：创建时间与最后修改时间，由数据库层写入，响应时可能为 null；
• modifier：最后修改者，刚创建时为空字符串。

CreateModelResult响应体定义于 src/common/metadata/toposerver.go，data字段类型即为metadata.Object，说明接口返回的是完整的模型元数据对象。

四、请求背后的完整调用链与实现原理

开放 API 的/api/v3/create/object请求在 bk-cmdb 内部会经过一条清晰的「网关 → apiserver → topo_server → core_service」链路，理解这条链路有助于排查问题与二次开发。

第 1 跳：apiserver 按 URL 路由并转发

apiserver 是 bk-cmdb 的统一接入层。在 src/apiserver/service/url.go 中，create动词的 URL 会被归类到 topo 组件，并由 TopoFilterChan 通过服务发现将请求转发至topo_server的/topo/v3前缀路径。

第 2 跳：topo_server 事务化创建

src/scene_server/topo_server/service/object.go 中的CreateObject处理器承担创建主流程：

1. 先建表，后建模型：调用createObjectTable提前调用 core_service 的CreateModelTables在 MongoDB 中创建模型对应的集合（collection）。源码注释解释了原因——避免模型创建后查询数据时出现 MongoDB 快照不可用错误（SnapshotUnavailable ... pending collection catalog changes），即建表与建模型必须严格分离；
2. 事务内执行创建：通过AutoRunTxn开启分布式事务，在事务内调用ObjectOperation().CreateObject真正创建模型；
3. 权限落库：若开启了鉴权（auth.EnableAuthorize()），则在 IAM 中登记新模型实例，使后续的模型管理操作具备权限判定依据；
4. 事务整体成功后，通过ctx.RespEntity(rsp)返回模型对象。

第 3 跳：core_service 的 CreateModel 与模型初始化

object.go 的 CreateObject 实现 展示了一个模型创建时服务端自动完成的全部初始化动作：

1. 参数校验：createObjectParamCheck完成前文所述的 ID/名称/分组/图标/排序号校验；
2. 写入模型元数据：调用 core_service 的Model().CreateModel（请求结构体见 src/common/metadata/core_service.go，Spec字段即模型对象），将模型记录写入模型表；
3. 创建默认属性分组：为模型创建名为Default的默认分组（GroupName: "Default"、IsDefault: true、GroupIndex: -1），新模型的所有属性在未手动分组前都归入该组；
4. 创建默认属性：createDefaultAttrs批量创建系统预置属性，包括创建时间（bk_created_at）、创建人（bk_created_by）、更新时间、更新人、实例 ID（bk_inst_id）、实例名称（bk_inst_name）等内置字段（预置属性定义可见 object.go 起的recordedAttrs）；
5. 创建唯一索引：将默认属性组成唯一键，调用CreateModelAttrUnique建立唯一索引。源码注释特别说明该索引与index.MainLineInstanceUniqueIndex、index.InstanceUniqueIndex强依赖，因为 MongoDB 4.2.6（4.4 之前）事务中不能建表，建表与建立索引是互斥操作，所以必须在本环节预建；
6. 生成审计日志：通过auditlog.NewObjectAuditLog生成AuditCreate类型的对象创建审计日志并落库，实现模型创建全程可追溯。

第 4 跳：返回结果

core_service 写入成功后，CreateObject将新模型的ID回填到obj.ID，最终以metadata.Object形式层层返回，形成第三节中的响应 JSON。

五、错误码与常见失败场景

创建模型最常见的失败场景及其对应错误码如下（错误码常量定义见 src/common/errInfo.go）：

此外，调用侧还需注意：bk_classification_id与bk_obj_id仅允许英文字母命名；模型创建是重操作，涉及建表、建索引与事务，请求超时阈值建议放宽；模型 ID 一旦创建不可随意修改，规划时应先确定命名规范。

六、验证方式：从测试用例看接口契约

仓库中的集成测试用例完整覆盖了该接口的正向与异常分支，可作为接口契约的补充验证。例如 src/test/topo_server/object_test.go 中多次调用objectClient.CreateObject创建模型并断言返回；src/test/topo_server/inst_test.go 在实例测试前置步骤中先创建模型再写实例。若需要二次开发或本地调试，可参考 docs/apidoc/apigw/README.md 了解开放 API 的整体接入方式。

七、小结

本文完整梳理了 bk-cmdb「创建模型」开放 API 的请求参数、请求/响应示例与底层实现：参数层面明确了bk_classification_id、bk_obj_id、bk_obj_name三个必填项以及creator、bk_obj_icon、obj_sort_number三个可选项的约束；实现层面揭示了「先建表再建模型」「事务化创建」「默认属性分组与唯一索引预建」「审计日志落库」等核心机制，并给出了可复现的测试用例路径。掌握这些内容后，你即可通过开放 API 稳定地批量建模，为后续实例数据写入与模型关联打下基础。

• 后端
• 企业应用
• 运维