560 lines
11 KiB
Markdown
560 lines
11 KiB
Markdown
# 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
|
||
```
|
||
|
||
### 9.4 生成 Swagger 文档
|
||
|
||
仓库根目录提供了两个脚本，方便重新生成 API 文档：
|
||
|
||
- Linux / WSL / macOS：`./gen_swagger.sh`
|
||
- Windows PowerShell：`./gen_swagger.ps1`
|
||
|
||
脚本会自动切换到 `backend/` 目录，并执行：
|
||
|
||
```bash
|
||
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
|
||
- 后续扩展点在哪里
|