DataOps-platform/docs/api_data_metric_delete.md

数据指标删除接口文档

API 接口

删除数据指标

接口路径: /api/data_metric/delete

请求方法: POST

请求参数:

参数名	类型	必填	说明
id	Integer	是	指标节点ID

请求示例:

{
  "id": 1378
}

响应格式:

成功响应：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": 1378,
    "message": "成功删除数据指标节点 (ID: 1378)"
  }
}

失败响应（节点不存在）：

{
  "code": 500,
  "msg": "数据指标节点不存在 (ID: 1378)",
  "data": {
    "id": 1378,
    "message": "数据指标节点不存在 (ID: 1378)"
  }
}

失败响应（参数错误）：

{
  "code": 500,
  "msg": {
    "error": "指标ID不能为空"
  },
  "data": {}
}

核心功能

metric_delete 函数

位置: app/core/data_metric/metric_interface.py

函数签名:

def metric_delete(metric_node_id: int) -> dict:
    """
    删除数据指标节点及其所有关联关系
    
    Args:
        metric_node_id: 指标节点ID
        
    Returns:
        dict: 删除结果，包含 success 状态和 message 信息
    """

功能说明:

1. 连接 Neo4j 图数据库
2. 检查指定ID的 DataMetric 节点是否存在
3. 使用 DETACH DELETE 删除节点及其所有关联关系
4. 返回删除结果状态

返回值结构:

{
    "success": True/False,  # 删除是否成功
    "message": "状态信息"    # 详细的状态描述
}

删除机制

Cypher 查询

检查节点存在:

MATCH (n:DataMetric)
WHERE id(n) = $nodeId
RETURN n

删除节点和关系:

MATCH (n:DataMetric)
WHERE id(n) = $nodeId
DETACH DELETE n
RETURN count(n) as deleted_count

DETACH DELETE 说明

DETACH DELETE 是 Neo4j 的关键字，功能包括：

1. 自动删除节点的所有传入关系（incoming relationships）
2. 自动删除节点的所有传出关系（outgoing relationships）
3. 删除节点本身

这意味着不需要手动遍历和删除关系，一条语句即可完成。

删除的关系类型

根据 DataMetric 节点的关系模型，删除时会自动清理以下关系：

关系类型	方向	目标节点	说明
origin	传出	DataModel / DataMetric	指标来源
connection	传出	DataMeta	元数据连接
LABEL	传出	DataLabel	数据标签
child	传出/传入	DataMetric	父子关系

错误处理

异常情况

1. 数据库连接失败

   • 返回: {"success": False, "message": "无法连接到数据库"}
   • HTTP 状态: 500

2. 节点不存在

   • 返回: {"success": False, "message": "数据指标节点不存在 (ID: xxx)"}
   • HTTP 状态: 500

3. 参数错误

   • 缺少 ID: {"error": "指标ID不能为空"}
   • 无效 ID: {"error": "指标ID必须为整数"}
   • HTTP 状态: 500

4. 删除异常

   • 返回: {"success": False, "message": "删除失败: [错误详情]"}
   • HTTP 状态: 500

使用示例

Python 请求示例

import requests
import json

url = "http://localhost:5500/api/data_metric/delete"
headers = {"Content-Type": "application/json"}
data = {"id": 1378}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["code"] == 200:
    print(f"删除成功: {result['data']['message']}")
else:
    print(f"删除失败: {result['msg']}")

cURL 请求示例

curl -X POST http://localhost:5500/api/data_metric/delete \
  -H "Content-Type: application/json" \
  -d '{"id": 1378}'

JavaScript/Fetch 示例

fetch('http://localhost:5500/api/data_metric/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ id: 1378 })
})
.then(response => response.json())
.then(data => {
  if (data.code === 200) {
    console.log('删除成功:', data.data.message);
  } else {
    console.log('删除失败:', data.msg);
  }
})
.catch(error => console.error('请求错误:', error));

日志记录

删除操作会在以下情况记录日志：

日志级别	场景	日志内容
ERROR	数据库连接失败	"无法连接到数据库"
WARNING	节点不存在	"数据指标节点不存在: ID={id}"
INFO	删除成功	"成功删除数据指标节点: ID={id}"
WARNING	删除失败	"删除失败，节点可能已被删除: ID={id}"
ERROR	异常错误	"删除数据指标节点失败: {错误详情}"

注意事项

⚠️ 重要提示:

1. 不可恢复: 删除操作是永久性的，无法撤销
2. 级联影响: 删除会清除所有关联关系，可能影响其他节点的关系结构
3. 权限控制: 建议在生产环境中添加权限验证
4. 审计日志: 建议记录删除操作的审计信息（操作人、时间等）
5. 业务验证: 删除前应检查是否有其他业务逻辑依赖此节点

最佳实践

1. 删除前确认: 在前端添加二次确认对话框
2. 批量删除: 如需批量删除，建议在循环中调用，并记录每次结果
3. 事务管理: 当前实现使用单次会话，确保原子性
4. 错误通知: 删除失败时应通知用户具体原因
5. 软删除: 对于重要数据，考虑实现软删除（标记而不是物理删除）

测试建议

单元测试场景

1. 测试删除存在的节点
2. 测试删除不存在的节点
3. 测试无效的节点ID（非整数、null等）
4. 测试数据库连接失败的情况
5. 测试删除后关系是否被清理

集成测试场景

1. 创建节点 -> 删除节点 -> 验证删除
2. 创建带关系的节点 -> 删除节点 -> 验证关系被清理
3. 验证删除后其他相关节点的状态

版本历史

版本	日期	变更说明
1.0	2025-11-03	初始版本，实现基本删除功能

相关接口

• POST /api/data_metric/add - 新增数据指标
• POST /api/data_metric/update - 更新数据指标
• POST /api/data_metric/detail - 查询指标详情
• POST /api/data_metric/list - 指标列表查询