企业官网建设流程全解析

• 后端
• 企业应用
• 运维

模型分类（Model Classification）是蓝鲸配置平台（bk-cmdb）中组织模型（对象）的第一层分组维度，平台内置的"主机管理""业务拓扑""组织架构"等分类即由它承载。本文围绕「添加模型分类」接口create_classification展开，完整讲解其请求参数、请求/返回示例、返回字段语义，并结合仓库源码揭示该接口从 ESB 网关、topo_server 到 coreservice 的完整调用链、字段校验规则与底层 MongoDB 持久化实现，帮助你准确理解并正确调用该接口，为自建模型分类、二次开发模型体系打下基础。

一、功能概述与权限要求

该接口用于添加一个模型分类，调用者需要拥有模型分组新建权限（对应create_classification操作）。在 CMDB 的模型管理体系中，模型分类是模型的容器：用户先创建分类（如"主机管理""业务拓扑"），再在分类下挂载具体模型（对象）。平台内置分类的 ID 在源码 src/common/metadata/classification.go 中以常量形式定义：

内置分类的bk_classification_type字段值为inner；通过本接口创建的自定义分类该字段默认为空字符串，二者在返回结果中可以直接区分。

二、请求说明

2.1 公共参数

接口公共参数（{{ common_args_desc }}）与 CMDB 其他 OpenAPI 一致，调用时需附带认证信息，典型字段包括：

实际鉴权方式（AppSecret/Token/用户名组合）由接入方部署的鉴权策略决定，建议通过蓝鲸 ESB 网关统一接入。

2.2 接口参数

其中bk_classification_id是系统内部标识，创建后将不可修改（更新接口会强制移除该字段，见 src/scene_server/topo_server/logics/model/classification.go），因此创建前务必规划好命名。

三、请求示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_classification_id": "cs_test", "bk_classification_name": "test_name", "bk_classification_icon": "icon-cc-business" }

四、返回结果示例

{ "result": true, "code": 0, "data": { "id": 11, "bk_classification_id": "cs_test", "bk_classification_name": "test_name", "bk_classification_type": "", "bk_classification_icon": "icon-cc-business", "bk_supplier_account": "" }, "message": "success", "permission": null, "request_id": "76e9134a953b4055bb55853bb248dcb7" }

五、返回结果参数说明

5.1 response 顶层字段

5.2 data 字段

返回的data对象与源码中的metadata.Classification结构体字段一一对应（src/common/metadata/classification.go），创建成功后接口会回读一次数据库中的完整分类记录再返回，因此data中包含服务端自动生成/补充的id、bk_classification_type、bk_supplier_account等字段。

六、接口完整调用链与源码级原理

6.1 网关映射与路由注册

在 ESB 网关配置 docs/apidoc/cc/cc.yaml 中，对外路径/v2/cc/create_classification/被映射到 CMDB 内部接口：

• 对外：POST /v2/cc/create_classification/（ESB，api_type 为 operate）
• 对内：POST /api/v3/create/objectclassification

内部路由由 topo_server 注册，见 src/scene_server/topo_server/service/service_business_initfunc.go，WebService 基础路径为/topo/v3/（src/scene_server/topo_server/service/service.go）。

6.2 topo_server 服务层：事务与权限联动

入口处理器CreateClassification（src/scene_server/topo_server/service/object_classification.go）做了两件关键事情：

1. 开启事务：通过CoreService().Txn().AutoRunTxn包裹整个创建流程，保证分类写入与后续操作原子性；
2. 注册 IAM 资源创建者：当开启鉴权（auth.EnableAuthorize()）时，将新分类以SysModelGroup资源类型注册到 IAM，并把当前用户记录为资源创建者（Creator），实现资源级细粒度权限控制。

6.3 业务逻辑层：字段校验规则

CreateClassification内部调用classification.CreateClassification（src/scene_server/topo_server/logics/model/classification.go），先通过isValid做参数校验，再调用 coreservice 落库，成功后回读记录并生成审计日志（auditlog.NewObjectClsAuditLog，动作类型AuditCreate）。

isValid（src/scene_server/topo_server/logics/model/classification.go）基于 src/common/valid/valid.go 中的校验函数执行：

• bk_classification_id：ValidModelIDField，必填字符串，长度不超过 128 字符，且必须匹配正则^[a-zA-Z]\w*$——即以英文字母开头，后续只能是字母、数字、下划线（常量定义于 src/common/definitions.go，长度上限AttributeIDMaxLength = 128）；
• bk_classification_name：ValidModelNameField，必填字符串，长度不超过 128 字符（AttributeNameMaxLength = 128）。

6.4 coreservice 存储层：ID 生成、前缀保护与去重

真正落库在 coreservice 的CreateOneModelClassification（src/source_controller/coreservice/core/model/classification.go），该函数额外把关三道：

1. 必填校验：bk_classification_id为空直接报错（错误码CCErrCommParamsNeedSet）；
2. 内置前缀保护：分类 ID 不允许以bk或BK开头（strings.HasPrefix(strings.ToLower(id), "bk")），防止用户自定义分类与平台内置分类冲突。注释明确说明：topo_server 上层虽已有 ID 校验，此处作为防止绕过上层直接调用 core service 的最后底线；
3. 唯一性保障：插入 MongoDB 表bk_obj_classification（common.BKTableNameObjClassification）时若命中唯一索引冲突，返回CCErrCommDuplicateItem。

ID 通过mongodb.Client().NextSequence从序列生成，同时自动写入OwnerID = kit.SupplierAccount（src/source_controller/coreservice/core/model/classification_crud.go），这就是返回data.id与bk_supplier_account的来源。

6.5 测试用例验证

仓库内置了针对该链路的行为测试，见 src/source_controller/coreservice/core/model/classification_test.go：

• 传入空的CreateOneModelClassification（分类 ID 为空）时，期望返回CCErrCommParamsNeedSet且指明bk_classification_id字段；
• 使用唯一 ID（xid生成）创建成功，返回的Created.ID非 0；
• 再次使用同一 ID 创建时，期望命中CCErrCommDuplicateItem重复项错误。

该测试直接印证了上文所述"必填校验 + 重复检测"两条规则的可观测行为。

七、调用注意事项与常见问题

1. 分类 ID 一旦创建即固定：bk_classification_id是系统内部标识，更新接口会强制剔除该字段（src/scene_server/topo_server/logics/model/classification.go），无法通过修改接口变更，只能删除后重建。
2. 命名规范：必须以英文字母开头，长度 ≤ 128，禁止以bk/BK开头（保留给平台内置分类，如bk_host_manage、bk_biz_topo）。
3. 删除前置条件：分类下挂有模型（对象）时不允许删除，删除接口会返回CCErrTopoObjectClassificationHasObject（见 src/scene_server/topo_server/logics/model/classification.go 与 src/source_controller/coreservice/core/model/classification.go）。
4. 权限联动：开启鉴权后，创建者会被自动注册为该分类资源的 Creator，后续对该分类的新建模型等操作将基于此做资源级授权。
5. 返回 data 的 type 区分：内置分类bk_classification_type为inner，本接口创建的自定义分类为空字符串，可用该字段区分内置与自定义分组。

八、相关接口

围绕模型分类，仓库还提供了一组配套接口（均在 docs/apidoc/cc/cc.yaml 中定义），可与本接口配合使用：

建议的调用顺序是：先通过本接口创建自定义分类，再使用"新建模型"接口将模型挂载到该分类下，从而构建出符合自身运维场景的模型分组体系。

• 后端
• 企业应用
• 运维