企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本篇技术指南基于蓝鲸智云配置平台（bk-cmdb）的开放 API 文档，深入讲解「删除对象模型属性（delete_object_attribute）」接口的完整用法：包括调用路径与权限要求、输入参数、真实调用示例、响应体字段语义，以及其背后在 topo_server、coreservice 与鉴权模块中的完整实现链路。读完本文，你将能够通过开放 API 安全、准确地删除业务自定义模型字段，并理解删除动作背后的数据变更与权限校验机制。

接口概述

在 bk-cmdb 的开放 API 体系中，delete_object_attribute用于删除对象模型的属性字段。其核心使用场景是删除业务自定义字段：即通过创建模型属性接口新增的自定义字段，当业务模型演进、字段不再需要时，可以通过本接口将其从模型中移除。

该接口在文档层面的能力描述为：

删除对象模型属性，可以删除业务自定义字段（权限：模型编辑权限）。

需要强调的是，它面向的是业务自定义字段而非系统内置字段。从源码结构看，创建属性接口在写入时会强制attr.IsPre = false（即非预置字段），系统预置属性由平台内置，不通过该链路开放删除；同时，删除链路中存在attr.TemplateID != 0时拒绝删除的校验（字段模板引用的属性禁止删除），这些限制共同保证了删除操作只作用于可安全移除的自定义属性。

接口请求说明

请求方式与路径

该接口对应的 HTTP 请求为：

• Method：DELETE
• Path：/api/v3/delete/objectattr/{id}（其中{id}为属性记录 ID）

路由注册证据位于 service_business_initfunc.go，topo_server 将DELETE /delete/objectattr/{id}绑定到Service.DeleteObjectAttribute处理器；开放 API 网关侧由 apigw 转发，完整的GET /api/v3/delete/objectattr/{id}匹配与解析逻辑（要求 URL 中属性 ID 为数字）见 topolatest.go。

同时，apimachinery 客户端封装提供了同名的DeleteObjectAtt方法，内部以http.MethodDelete请求子路径/delete/objectattr/%s（attribute.go），可供 Go 服务端程序直接调用。

输入参数

调用时只需在请求 Body 中提交一个参数：

其中id即模型属性记录的主键 ID（对应Attribute结构体中的id字段，见 attribute.go）。该 ID 可以通过「查询对象模型属性（find/objectattr）」接口获取。

调用示例

请求 Body 示例：

{ "id" : 0 }

实际调用时应将id替换为目标属性的真实 ID（示例中的0仅为演示占位，真实的属性 ID 为大于 0 的整数，如32）。

响应示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": "success" }

响应参数说明

在成功删除场景下，code为0、result为true，data返回字符串"success"；当鉴权失败或校验不通过时，code返回对应的非 0 错误码，message给出可读的错误描述。

底层实现链路

1. 删除前的属性查询与合法性校验

topo_server 的DeleteObjectAttribute处理器（object_attribute.go）在真正执行删除前会完成以下步骤：

1. 解析路径参数：从请求路径中提取属性 ID，并解析请求 Body 中的ModelType（可携带bk_biz_id，用于区分公共属性与业务私有属性）；
2. 按 ID 查询属性记录：调用getModelAttrByID从 coreservice 读取属性详情（object_attribute.go）。若查不到记录（attr.ID == 0）则直接返回成功且不执行删除，保证接口幂等；
3. 字段模板保护校验：若属性TemplateID != 0（即属性由字段模板生成），返回CCErrorTopoFieldTemplateForbiddenDeleteAttr错误，拒绝删除由字段模板管理的属性；
4. 表格型（inner table）属性特殊处理：若属性类型为bk_property_type = inner_table（表格型字段），则走deleteTableObject分支（object_attribute.go），它会级联删除该表格对象及其数据；否则走普通属性删除链路。

2. 普通属性的删除逻辑

普通属性的删除在逻辑层attribute.DeleteObjectAttribute（attribute.go）中执行，关键动作包括：

• 校验属性类型：再次确认属性不是表格型字段（表格型字段必须在上一分支处理）；
• 生成审计日志：基于待删除属性生成AuditDelete类型的审计记录，保证删除操作可追踪、可审计；
• 调用 coreservice 删除：按bk_obj_id（模型 ID）将待删除属性 ID 组装为{id: {$in: [ids]}}删除条件，调用CoreService().Model().DeleteModelAttr真正从存储中删除属性元数据；
• 保存审计日志：删除成功后落库审计日志，若日志保存失败则整体返回错误。

3. 关联的主机属性自动应用规则清理

删除模型属性后，topo_server 还会执行deleteHostApplyRule（object_attribute.go）：以被删属性 ID 查询主机属性自动应用规则（Host Apply Rule），若存在引用该属性的规则，则一并删除。这是删除属性时的关联数据兜底清理，避免模型中残留指向已删除字段的规则记录。

4. 鉴权与权限模型

删除动作的权限校验由访问控制（AC）模块完成，权限类型为模型属性（ModelAttribute）的Delete动作，对应文档所述的「模型编辑权限」：

• URL 匹配规则^/api/v3/delete/objectattr/[0-9]+/?$（topolatest.go）将请求识别为删除属性操作；
• 鉴权时会先按属性 ID 反查属性详情，进而定位其所属模型（Layers中的Model）与业务范围（BusinessID），再构造meta.Delete权限资源请求（topolatest.go）；
• 鉴权失败时响应体中的permission字段会携带所需权限信息，result为false、code为非 0 错误码。

5. 事务与数据一致性

从调用链可以看到，删除操作在多个环节使用了 coreservice 提供的事务能力（Txn().AutoRunTxn）包裹关键写入（如表格对象的级联删除），确保属性元数据删除与关联数据处理之间的事务一致性；删除链路中涉及 coreservice 的DeleteModelAttr、DeleteTableModelCascade等接口，最终落在存储层（MongoDB）执行。

常见返回码与异常场景

结合源码中的错误分支，常见失败场景包括：

调用注意事项

1. 只删自定义字段：本接口面向业务自定义字段，系统预置属性（ispre=true）不在开放 API 可删除范围内；
2. 先查后删：删除前建议先通过「查询对象模型属性」接口确认属性 ID 与归属模型，避免误删；
3. 注意表格型字段：属性类型为inner_table时删除会级联清理表格对象数据，操作前请评估影响；
4. 关注关联规则：被删属性一旦被主机属性自动应用规则引用，相关规则会随属性删除一并清理；
5. 权限前置：调用方需具备对应模型（或业务）的模型编辑权限，权限不足时根据permission字段补齐授权。

相关文档与代码索引

• 接口文档（本文依据）：delete_object_attribute.md（英文版见 en/delete_object_attribute.md）
• 路由注册：service_business_initfunc.go
• 删除处理器：object_attribute.go
• 逻辑层实现：attribute.go
• 鉴权解析：topolatest.go
• 客户端封装：attribute.go
• 属性元数据定义：attribute.go

• 后端
• 企业应用
• 运维