knowledge-graph-agent/backend/README.md

# knowledge-graph-backend

知识图谱后端服务，基于 Go + Gin + Neo4j 构建，面向图谱查询、图谱编辑、搜索、统计与对话增强能力提供统一 API。

这份文档聚焦于后端当前已经实现的结构与运行方式，帮助你快速理解：

- 请求是如何进入系统的
- Handler / Service / Neo4j Driver 之间如何协作
- 图数据是如何从 Neo4j 读写出来的
- 后续扩展功能应该从哪里接入

---

## 一、系统定位

当前后端主要承担以下职责：

1. 对外暴露图谱相关 HTTP API
2. 将前端请求转换为对 Neo4j 的查询或写入
3. 统一节点、边、图数据、错误响应的格式
4. 为后续 LLM / 对话增强能力预留简化图数据与上下文检索接口

---

## 二、运行时架构

### 2.1 整体调用链

```mermaid
flowchart LR
  Client[前端 / Postman / curl] --> Router[gin.Engine]
  Router --> Health[/GET /health/]
  Router --> Swagger[/GET /swagger/*any/]
  Router --> API[/GET /api/*\nPOST /api/*\nPUT /api/*\nDELETE /api/*/]

  API --> GH[GraphHandler]
  API --> NH[NodeHandler]
  API --> SH[SearchHandler]
  API --> CRUD[NodeCRUDHandler / EdgeCRUDHandler]

  GH --> SVC[GraphService]
  NH --> SVC
  SH --> SVC
  CRUD --> SVC

  SVC --> Q[graph_queries.go]
  SVC --> C[graph_crud.go]
  SVC --> X[graph_simple.go]
  SVC --> U[neo4j_utils.go]

  Q --> D[Neo4j Driver]
  C --> D
  X --> D
  D --> DB[(Neo4j 5.x)]
```

### 2.2 分层职责

#### 路由层

入口位于 `cmd/server/main.go`。

这一层负责：

- 加载配置
- 初始化 Neo4j 驱动
- 创建 service 实例
- 创建 handler 实例
- 注册路由与 Swagger
- 启动 HTTP 服务

#### Handler 层

目录：`internal/handler/`

Handler 的职责只包括：

- 读取 path / query / body 参数
- 调用 service
- 按统一格式返回 JSON
- 在必要时返回错误状态码

当前 handler 组成：

- `graph_handler.go`
  - `GET /api/graph`
  - `GET /api/graph/stats`
  - `GET /api/graph/simpleJson`
- `node_handler.go`
  - `GET /api/nodes/:id`
  - `GET /api/nodes/:id/neighbors`
- `search_handler.go`
  - `GET /api/search?q=...`
- `crud_handler.go`
  - `POST /api/nodes`
  - `PUT /api/nodes/:id`
  - `DELETE /api/nodes/:id`
  - `POST /api/edges`
  - `DELETE /api/edges/:id`

#### Service 层

目录：`internal/service/`

Service 是核心业务层，负责：

- 查询图数据
- 搜索节点
- 获取邻居
- 增删改节点与边
- 对 Neo4j 结果做模型转换
- 封装公共工具函数

当前文件拆分如下：

- `interface.go`
  - 定义 `GraphService` 接口
- `graph_queries.go`
  - 图查询、搜索、统计、邻居、简化图数据
- `graph_crud.go`
  - 节点 / 边创建、更新、删除
- `graph_simple.go`
  - 简化图数据输出
- `neo4j_utils.go`
  - Neo4j 记录转换、属性提取、字段清洗、辅助函数

#### Repository / Driver 层

目录：`internal/repository/neo4j/`

这里负责 Neo4j 驱动初始化与连接配置。

---

## 三、模块关系图

### 3.1 控制流关系

```mermaid
flowchart TD
  subgraph HTTP[HTTP API]
    GH[GraphHandler]
    NH[NodeHandler]
    SH[SearchHandler]
    CH[NodeCRUDHandler]
    EH[EdgeCRUDHandler]
  end

  subgraph Domain[Service Layer]
    GS[GraphService Interface]
    GQ[graph_queries.go]
    GC[graph_crud.go]
    GSIMPLE[graph_simple.go]
    UTIL[neo4j_utils.go]
  end

  subgraph Infra[Infrastructure]
    DRIVER[Neo4j Driver]
    DB[(Neo4j Database)]
  end

  GH --> GS
  NH --> GS
  SH --> GS
  CH --> GS
  EH --> GS

  GS --> GQ
  GS --> GC
  GS --> GSIMPLE
  GQ --> UTIL
  GC --> UTIL
  GSIMPLE --> UTIL

  GQ --> DRIVER
  GC --> DRIVER
  GSIMPLE --> DRIVER
  DRIVER --> DB
```

### 3.2 数据结构关系

```mermaid
classDiagram
  class GraphData {
    +[]Node nodes
    +[]Edge edges
  }

  class SimpleGraphData {
    +[]SimpleNode nodes
    +[]SimpleEdge edges
  }

  class Node {
    +string id
    +string label
    +string type
    +float64 x
    +float64 y
    +map style
    +map properties
  }

  class Edge {
    +string id
    +string source
    +string target
    +string label
    +string type
    +map style
    +map properties
  }

  class GraphService {
    +GetGraphData() GraphData
    +GetSimpleGraphData() SimpleGraphData
    +GetNodeByID(id) Node
    +SearchNodes(query) []Node
    +GetNeighbors(nodeID) NeighborResponse
    +GetStats() map
    +CreateNode(req) Node
    +UpdateNode(id, req) Node
    +DeleteNode(id) error
    +CreateEdge(req) Edge
    +DeleteEdge(id) error
  }

  GraphData --> Node
  GraphData --> Edge
  SimpleGraphData --> Node
  SimpleGraphData --> Edge
  GraphService ..> GraphData
  GraphService ..> SimpleGraphData
  GraphService ..> Node
  GraphService ..> Edge
```

---

## 四、API 能力

### 4.1 健康检查

- `GET /health`

用途：确认服务是否运行。

返回示例：

```json
{
  "status": "ok",
  "message": "Knowledge Graph API is running",
  "version": "1.0.0"
}
```

### 4.2 图数据查询

- `GET /api/graph`
  - 返回完整节点与边
- `GET /api/graph/stats`
  - 返回节点数、边数和分类统计
- `GET /api/graph/simpleJson`
  - 返回简化图数据，适合 LLM 或轻量消费端

### 4.3 节点查询

- `GET /api/nodes/:id`
  - 获取单个节点
- `GET /api/nodes/:id/neighbors`
  - 获取该节点的邻居节点和相关边

### 4.4 搜索

- `GET /api/search?q=xxx`
  - 根据 `id`、`label`、`type` 模糊搜索节点

### 4.5 图谱编辑

- `POST /api/nodes`
- `PUT /api/nodes/:id`
- `DELETE /api/nodes/:id`
- `POST /api/edges`
- `DELETE /api/edges/:id`

---

## 五、请求与响应模型

### 5.1 节点模型

节点保留以下标准字段：

- `id`
- `label`
- `type`
- `x`
- `y`
- `style`
- `properties`

其中：

- `style` 适合前端可视化使用
- `properties` 用于存放扩展字段

### 5.2 边模型

边保留以下标准字段：

- `id`
- `source`
- `target`
- `label`
- `type`
- `style`
- `properties`

### 5.3 统一错误响应

后端使用统一的错误结构：

- `error`
- `message`

这样前端可以基于同一格式做提示与状态分支处理。

---

## 六、Neo4j 数据映射

### 6.1 节点映射原则

Neo4j 节点到 API 节点模型的映射规则：

- `id` → 节点唯一标识
- `label` → 显示名称
- `type` → 节点类型
- `x/y/style` → 可视化信息
- 其余字段 → 放入 `properties`

### 6.2 边映射原则

Neo4j 关系到 API 边模型的映射规则：

- `id` → 边唯一标识
- `label` → 边显示名称
- `type` → 关系类型
- `source/target` → 由起点和终点节点 ID 推导
- 其余字段 → 放入 `properties`

### 6.3 工具函数职责

`neo4j_utils.go` 集中处理：

- Neo4j Node / Relationship 转换
- 通用取值函数
- 保留字段判断
- 字段名和关系类型清洗

这样可以减少 CRUD 和查询代码里的重复逻辑。

---

## 七、服务拆分说明

### 7.1 `graph_queries.go`

负责读取类功能：

- `GetGraphData()`
- `GetNodeByID()`
- `SearchNodes()`
- `GetNeighbors()`
- `GetStats()`

这些方法面向“查询场景”，不修改数据库内容。

### 7.2 `graph_crud.go`

负责写入类功能：

- `CreateNode()`
- `UpdateNode()`
- `DeleteNode()`
- `CreateEdge()`
- `DeleteEdge()`

这些方法面向“编辑场景”，负责校验、写入、返回更新后的模型。

### 7.3 `graph_simple.go`

负责提供一个轻量版本的图数据：

- `GetSimpleGraphData()`

适合：

- LLM 上下文注入
- 快速摘要
- 轻量前端消费

---

## 八、目录结构

```mermaid
flowchart TD
  Root[backend/] --> Cmd[cmd/server/]
  Root --> Docs[docs/]
  Root --> Internal[internal/]
  Root --> README[README.md]

  Cmd --> Main[main.go]

  Internal --> Config[config/]
  Internal --> Handler[handler/]
  Internal --> Model[model/]
  Internal --> Repository[repository/neo4j/]
  Internal --> Service[service/]

  Handler --> GH[graph_handler.go]
  Handler --> NH[node_handler.go]
  Handler --> SH[search_handler.go]
  Handler --> CRUD[crud_handler.go]

  Service --> Interface[interface.go]
  Service --> Q[graph_queries.go]
  Service --> C[graph_crud.go]
  Service --> Simple[graph_simple.go]
  Service --> Utils[neo4j_utils.go]
```

---

## 九、配置与启动

### 9.1 常见配置项

后端通常会从配置文件或环境变量中读取以下信息：

- 服务端口
- Neo4j URI
- Neo4j 用户名
- Neo4j 密码
- CORS 允许源
- 数据文件或迁移相关配置（若启用）

### 9.2 启动方式

在 `backend/` 目录下运行：

```bash
go run ./cmd/server
```

### 9.3 Swagger 地址

启动后访问：

```text
http://localhost:3001/swagger/index.html
```

---

## 十、当前实现特点

### 10.1 已完成的结构优化

- Handler 与 Service 解耦
- 图查询与 CRUD 拆分
- 通用 Neo4j 工具统一收口
- 使用统一错误结构
- 使用 `GraphService` 接口约束业务能力

### 10.2 当前行为特征

- 图数据完全由 Neo4j 提供
- 节点与边都支持扩展属性
- 搜索同时覆盖 `id`、`label`、`type`
- 邻居查询会返回邻居节点和边
- 简化图数据适合 LLM 或摘要场景

### 10.3 已知设计取向

- 以可维护性优先，而不是一开始就追求极致抽象
- 保留较直观的 Cypher 语句，方便调试与演进
- 优先让 API 形状稳定，方便前端对接

---

## 十一、建议的下一步演进

1. 补齐测试
   - service 单元测试
   - handler 测试
   - Neo4j 交互测试

2. 增加批量写入能力
   - 批量创建节点
   - 批量创建边

3. 进一步规范错误语义
   - `400 Bad Request`
   - `404 Not Found`
   - `409 Conflict`
   - `500 Internal Server Error`

4. 为对话增强做准备
   - 上下文检索
   - 相关节点提取
   - 简化图摘要注入

5. 进一步细分 service
   - 如果后续功能继续增长，可以把查询、编辑、统计、上下文检索拆成更细粒度模块

---

## 十二、快速理解这套后端

如果你第一次接触这个项目，可以按这个顺序看：

1. `cmd/server/main.go`
2. `internal/handler/`
3. `internal/service/interface.go`
4. `internal/service/graph_queries.go`
5. `internal/service/graph_crud.go`
6. `internal/service/neo4j_utils.go`

这样能最快理解：

- 请求如何流动
- 图数据如何被读取和修改
- 模型如何映射到 Neo4j
- 后续扩展点在哪里