wonder/knowledge-graph-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d939c2d5e1eeafd45b33249ae65c567ece86faec
knowledge-graph-agent/backend
T
History

README.md

knowledge-graph-backend

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

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

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

一、系统定位

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

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

二、运行时架构

2.1 整体调用链

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 控制流关系

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 数据结构关系

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

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

返回示例：

{
  "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 上下文注入
  • 快速摘要
  • 轻量前端消费

八、目录结构

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/ 目录下运行：

go run ./cmd/server

9.3 Swagger 地址

启动后访问：

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

9.4 生成 Swagger 文档

仓库根目录提供了两个脚本，方便重新生成 API 文档：

  • Linux / WSL / macOS：./gen_swagger.sh
  • Windows PowerShell：./gen_swagger.ps1

脚本会自动切换到 backend/ 目录，并执行：

swag init -g ./cmd/server/main.go --parseDependency --parseInternal

生成产物位于 backend/docs/ 下：

  • docs.go
  • swagger.json
  • swagger.yaml

如果遇到 cannot find type definition: model.GraphData 之类的报错，通常是 handler 文件里缺少 internal/model 的显式导入。

十、当前实现特点

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
  • 后续扩展点在哪里
Reference in New Issue View Git Blame Copy Permalink