简介：基于Neo4j的《水浒传》人物关系可视化及问答系统，是一套适合课程设计、毕业设计或项目立项的完整参考实现，主要面向计算机、大数据、人工智能、通信等专业学生及企业开发者。资源通过实际项目展示如何利用Neo4j构建《水浒传》人物关系知识图谱，实现人物关系的可视化交互，并支持基于自然语言的简单问答，有助于深入理解图数据库建模、Cypher查询、前后端数据交互等核心技术。压缩包内共197个文件，包含Python源码、HTML/CSS/JS前端页面、Neo4j配置与数据脚本，以及说明文档、答辩PPT和示例图片；其中8个py文件构成系统核心逻辑，4个html文件呈现可视化界面，129张jpg清晰记录运行效果，并配有pptx/pdf材料便于答辩汇报，整体大小仅22.84MB，目录结构清晰，便于快速部署和二次开发。目前已有343人学习下载，不仅适合初学者作为实战练习，也可直接作为课程设计或初期项目演示的参考素材。
1. 把《水浒传》人物关系做成Neo4j图谱：这个课程设计到底能跑出什么
如果你学过一段时间Neo4j或者图数据库，手头一定堆了不少“员工-部门-项目”之类的示例数据，学是能学，但总感觉离真实项目隔着一层。这个课程设计资源最大的不一样，是它用《水浒传》这部小说做数据底座——一百单八将加上各路配角、派系、事件，天然就是一张带权有向图。把这样一部经典拆成节点和关系，比用虚构的电商数据练手直观得多，也比自己一篇篇翻原著整理人物关系省下大量体力活。整个系统包含人物关系可视化界面和自然语言问答两条主线：一边用ECharts在前端把人物关系渲染成力导向图，一边用Flask提供接口，接住类似“林冲的师傅是谁”“宋江和谁结义”这类问题，落到Cypher查询上。适合做图数据库课程设计、毕业设计演示，也适合想快速看一遍“文本 → 图谱 → 问答”全流程的初学者照着复现。
2. 为什么用Neo4j而不是MySQL：图模型怎么贴合《水浒传》人物关系
2.1 人物关系在关系型数据库里的别扭之处
先看一个很实际的问题：如果用MySQL存《水浒传》人物关系，最常见的做法是建一张person表，再建一张relation表，字段是person_id、related_person_id、relation_type。这套模型能跑，但查询“宋江通过最多三层关系能连到谁”会写成什么？要么嵌套好几层JOIN，要么在应用层写递归，代码又长又难维护。而且关系类型一多——结义、师徒、夫妻、上下级、仇敌、同乡、同僚——每条关系的属性还不一样，比如结义有排行，师徒有师承脉络，用外键表达这些语义非常吃力。
换成Neo4j之后，人物变成节点，关系变成边，查询“多层关系”就是一条Cypher语句的事。这个资源把《水浒传》里的人物关系抽象成节点和关系，本质上是换了一种数据建模思路：不再以“表”为中心，而是以“关系”为中心。理解这一点，是看懂后续所有代码的前提。
2.2 人物节点与关系类型的建模方式
这套系统的数据模型不复杂，核心就三类：人物节点（Person）、关系边（RELATION）、人物属性（如姓名、绰号、座次、阵营）。人物节点上通常会带name、alias（绰号）、rank（座次）、camp（招安派/反对派之类）等属性，关系边的type则用来区分不同的社交语义。
写Cypher创建节点时，常见做法是这样：
CREATE (l:Person {name: '林冲', alias: '豹子头', rank: 6, camp: '梁山泊'}) CREATE (s:Person {name: '鲁智深', alias: '花和尚', rank: 13, camp: '梁山泊'}) CREATE (l)-[:结义 {since: '东京'} ]->(s)逻辑说明：这里先用CREATE建了两个Person节点，属性包括姓名、绰号、座次和阵营，然后创建一条从林冲到鲁智深的“结义”关系。方向是有讲究的——林冲是哥哥，鲁智深是弟弟，关系方向从主动方指向被动方，这样后续回答“林冲和谁结义”时，沿着-[:结义]->方向查出去就是弟弟；如果问“谁和鲁智深结义”，则需要反向匹配。
参数说明：rank字段可以直接对应水浒排位，方便后面做“座次前10的人物关系”这类限定查询；camp字段建议别只存“梁山泊”这种单值，存“招安派”“反对派”“中立”会更实用，因为问答系统里“支持招安的人有哪些”是高频问题。
2.3 可视化为什么选ECharts而不是Neo4j自带工具
Neo4j Browser自带的可视化其实不错，但它是给开发调试用的，不适合直接交付成课程设计。这套资源用了ECharts的关系图（graph）系列，前端拿到后端返回的nodes和links数组就能出图，不需要额外引重量级库。ECharts的关系图支持力导向布局，节点可以拖拽，鼠标悬停显示人物信息和关系类型，这几点正好覆盖演示场景的需求。
对比一下：Neo4j Browser里看到的图是散的，没法直接嵌进自己的Web页面；ECharts则能完全控制节点颜色、大小、标签。资源里的做法是后端把人物和关系查出来之后拼成JSON，前端用ECharts的graph类型接收，然后做颜色映射——比如按阵营上色，梁山好汉一个色，朝廷官员另一个色。这个设计虽然不是特别复杂，但它把图数据库和前端可视化串起来了，比只跑通Cypher查询完整太多。
3. 从零复现数据导入：把《水浒传》人物写进Neo4j的完整路径
3.1 环境准备与初始数据装载
拿到源码包之后，不建议一上来就翻PPT，先把环境跑通。这套资源依赖Neo4j Community Edition、Python 3.8以上、Flask、py2neo或neo4j驱动。Neo4j版本建议直接用4.x或者5.x，社区版完全够用，不需要企业版。
数据导入有两种路径，源码包里通常自带了一份整理好的人物关系数据，可能是CSV，也可能是Cypher脚本。如果拿到的是CSV，用LOAD CSV导入是最省事的，尤其是人物数据量级只有一两百条时，没必要上apoc。
LOAD CSV WITH HEADERS FROM 'file:///characters.csv' AS row CREATE (p:Person { name: row.name, alias: row.alias, rank: toInteger(row.rank), camp: row.camp })逻辑说明：LOAD CSV按行读取characters.csv，每一行生成一个Person节点。WITH HEADERS表示第一行是字段名，row.name就是取当前行name列的值。注意toInteger(row.rank)，CSV里所有字段读进来都是字符串，座次是数字，不转换的话后面做排序、比较大小会出错。
参数说明：file:///characters.csv对应Neo4j安装目录下的import文件夹，文件必须放在那里，路径写错了会报“Couldn't load the external resource”错误。如果你把CSV放在其他位置，可以在Neo4j配置文件里改server.directories.import，但最简单的做法就是把文件丢进import目录。
3.2 批量导入人物关系：如何避免重复建边
人物节点建好之后，下一步是导入关系。关系数据通常是“A-B-关系类型-关系属性”的一行行记录，比如“宋江-李逵-主仆”“武松-施恩-结义”。如果直接用MERGE逐条写，一两百条还行，再多就建议用UNWIND批量处理，一个语句搞定。
WITH [ ['宋江', '李逵', '主仆', '忠义堂'], ['武松', '施恩', '结义', '孟州'], ['林冲', '鲁智深', '结义', '东京'], ['武松', '宋江', '结义', '柴进庄上'], ['林冲', '高俅', '仇敌', '东京'] ] AS relations UNWIND relations AS rel MATCH (a:Person {name: rel[0]}), (b:Person {name: rel[1]}) MERGE (a)-[r:RELATION {type: rel[2]}]->(b) SET r.place = rel[3]逻辑说明：UNWIND把一个嵌套列表展开成一行行记录，每条记录包含起点、终点、关系类型、关系地点。MATCH先按名字找到两个端点节点，MERGE保证同类型关系不重复创建，SET把地点的属性补上去。这个批处理方式比逐条执行快得多，也方便后期往列表里追加新关系。
参数说明：关系类型建议统一用RELATION这个标签，再通过type属性区分具体类型，这样写Cypher时只要查一种关系类型，配合type过滤就行。如果你把“结义”“仇敌”直接建成了不同的关系类型，查询时确实更直观，但导入和统计时会麻烦一点，自己权衡。
3.3 复现过程中的索引与约束设置
数据导入完成后，强烈建议给Person的name属性建唯一约束，防止同一个人被重复创建。这个坑几乎每个初做图数据库的人都会踩：LOAD CSV执行两遍，人物节点就多了一倍，问“梁山有多少好汉”出来个两百多人。唯一约束能从根上杜绝这个问题。
CREATE CONSTRAINT person_name_unique IF NOT EXISTS FOR (p:Person) REQUIRE p.name IS UNIQUE逻辑说明：约束创建好之后，再执行CREATE或MERGE时，如果name重复，语句会直接报错而不是静默创建重复节点。如果是已经导入了重复数据的库，执行约束前得先手动去重，否则约束建不上。
参数说明：Neo4j 4.x版本用REQUIRE p.name IS UNIQUE语法，3.x及更早版本用的是ASSERT p.name IS UNIQUE，源码包如果是按4.x写的，你装的是3.x就得改语法。这是跨版本复现最常见的兼容性问题。
4. 后端问答系统拆解：从问题到Cypher的转换逻辑
4.1 问答接口的整体流程
问答系统听起来玄学，拆开看就三步：接收自然语言问题、识别意图和实体、拼Cypher查库。这套资源的后端基于Flask实现，核心是一个/qa接口，接收JSON格式的{question: "林冲的师傅是谁"}，返回答案列表和对应的Cypher语句。
这个流程里最费功夫的是第二步——实体识别和意图识别。因为语料只围绕《水浒传》人物关系，不需要上大模型，写规则就能覆盖大部分问题。源码里通常维护了两类映射表：一类是人物别名映射，比如“豹子头”要能对回“林冲”；另一类是问题模板映射，比如问题里含有“师傅”就把意图定为query_mentor，含有“结义”就定为query_sworn_brother。
4.2 编写一个可用的问题解析函数
我自己复现时会把解析逻辑收敛到一个函数里，输入原始问题，输出结构化查询条件。这样做的好处是后期加新问题类型时不用动接口层，只加映射规则就行。
def parse_question(question): name = None intent = None for alias, real_name in ALIAS_MAP.items(): if alias in question: name = real_name break if '师傅' in question: intent = 'MENTOR' elif '结义' in question or '兄弟' in question: intent = 'SWORN_BROTHER' elif '仇' in question or '杀' in question: intent = 'ENEMY' elif '哪个派' in question or '阵营' in question: intent = 'CAMP' return { 'name': name, 'intent': intent }逻辑说明：这段代码先遍历别名映射表，把“豹子头”这类绰号转换成正式姓名；然后用关键词匹配意图。注意匹配顺序是有讲究的，“仇”和“杀”这类关键词要放在“结义”后面，因为“林冲和鲁智深有仇吗”这种问题里同时含“鲁智深”和“仇”，意图识别错了答案就完全跑偏。
参数说明：ALIAS_MAP是写死在代码里的字典，比如{'豹子头': '林冲', '花和尚': '鲁智深', '及时雨': '宋江'}。这里有个常见改进点——人物名称识别不要只靠映射表，可以用if name in question直接判断，因为《水浒传》里大部分人问问题时会直接用本名。先判断本名再兜底绰号，准确率会高不少。
4.3 把意图翻译成Cypher查询
拿到结构化的name和intent之后，下一步就是拼Cypher。这一部分源码里通常会内置一个查询函数，根据不同的intent走不同的查询分支，比如查师傅就是查Mentor类型的关系，查结义兄弟就是沿[:结义]方向查出去再收回来。
def build_cypher(name, intent): if intent == 'MENTOR': return ( "MATCH (p:Person {name: $name})-[:师徒]->(m:Person) " "RETURN m.name AS result" ) elif intent == 'SWORN_BROTHER': return ( "MATCH (p:Person {name: $name})-[:结义]-(b:Person) " "RETURN b.name AS result" ) elif intent == 'CAMP': return ( "MATCH (p:Person {name: $name}) " "RETURN p.camp AS result" )逻辑说明：查师徒关系时用了有向匹配-[:师徒]->，因为“师傅”是一个有方向的关系，林冲指向他的师傅，反方向查出来的是徒弟；查结义兄弟时用了无向匹配-[:结义]-，因为结义是双向的，武松和林冲互为兄弟，不能只沿一个方向查。这个方向意识的差异，是做问答系统最容易翻车的地方。
参数说明：Cypher语句里用了$name参数占位符，实际执行时通过py2neo或neo4j driver的参数接口传入。不建议用f-string直接拼接字符串，一是防注入，二是参数化查询能复用执行计划，速度更快。如果你用的py2neo版本是2021.2.3之后的，执行方式略有差异，具体看源码里的调用方式。
4.4 Flask接口层的错误兜底
问答系统跑起来之后，大概率会遇到两类问题：一类是用户输入的名字库里没有，一类是用户问的问题角度刁钻，意图匹配不到。这两类都得在接口层做兜底，否则前端会收到500错误。
@app.route('/qa', methods=['POST']) def qa(): data = request.get_json() question = data.get('question', '') parsed = parse_question(question) if not parsed['name']: return jsonify({'answer': ['未找到相关人物，请换个问法'], 'cypher': ''}) cypher = build_cypher(parsed['name'], parsed['intent']) if not cypher: return jsonify({'answer': ['暂不支持这类问题'], 'cypher': ''}) results = graph.run(cypher, name=parsed['name']).data() if not results: return jsonify({'answer': ['没有查到相关关系，可能是原始数据里没收录'], 'cypher': cypher}) return jsonify({'answer': [r['result'] for r in results], 'cypher': cypher})逻辑说明：这里按“名字未识别 → 意图未识别 → 查询结果为空”三个层次依次处理。顺序很重要——先判断名字，因为意图识别依赖名字，名字都没了，后面的查询没有任何意义。查询结果为空时返回原始Cypher，方便调试者直接在Neo4j Browser里手动执行确认是数据问题还是语句问题。
参数说明：graph.run(...).data()返回的是列表套字典的结构，比如[{'result': '鲁智深'}]，取结果时用r['result']。如果源码里用的是fetch()或者to_subgraph()，说明它用的py2neo版本比较新，返回结构不一样，复现时按源码来，不要照抄我这里。
5. 可视化页面与部署踩坑：从后端数据到前端力导向图
5.1 ECharts关系图的数据格式对接
可视化部分的实现思路是：前端页面加载时调用/graph接口，后端把整个图谱的人物和关系全量查出来，拼成ECharts需要的nodes和links结构，返回给前端渲染。这个接口和问答接口是分开的，问答接口只返回文本答案，图谱接口返回结构化数据，职责划分比较清楚。
@app.route('/graph', methods=['GET']) def graph(): nodes = graph.run( "MATCH (p:Person) RETURN p.name AS name, p.alias AS alias, p.camp AS camp" ).data() links = graph.run( "MATCH (a:Person)-[r:RELATION]->(b:Person) " "RETURN a.name AS source, b.name AS target, r.type AS relation" ).data() node_list = [{'name': n['name'], 'category': n['camp'], 'alias': n['alias']} for n in nodes] link_list = [{'source': l['source'], 'target': l['target'], 'relation': l['relation']} for l in links] return jsonify({'nodes': node_list, 'links': link_list})逻辑说明：这个接口做了两件事，分别查节点和查关系。节点数据带了阵营字段，前端拿它做颜色分类；关系数据带了关系类型，前端鼠标悬停时展示。数据量不大时这么写没问题，但如果你之后把整本书的关系全导进去，超过几百条边，建议加上limit参数或者分组加载，不然前端一次渲染上千条关系会卡顿。
参数说明：ECharts关系图的source和target字段要求字符串或数字，不能是对象，所以这里直接传人物姓名。如果图谱里有两个重名人物，这个设计就有问题，但《水浒传》人物集合里重名基本不存在，可以忽略。
5.2 前端配置力导向图的关键参数
前端页面里ECharts的配置项是可视化的灵魂，同样的nodes和links数据，配置项不同渲染效果天差地别。源码里graph的type设置为'graph'，layout设置为'force'，这两个是基础。真正影响观感的是force参数里的repulsion（斥力）和edgeLength（边的长度）。
option = { series: [{ type: 'graph', layout: 'force', roam: true, draggable: true, force: { repulsion: 300, edgeLength: [80, 150], gravity: 0.1 }, label: { show: true, position: 'right', formatter: function(params) { return params.data.name + ' (' + params.data.alias + ')'; } }, categories: [ { name: '梁山泊' }, { name: '朝廷' }, { name: '其他' } ], color: ['#c23531', '#2f4554', '#61a0a8'], lineStyle: { color: '#999', width: 1, opacity: 0.6 } }] };逻辑说明：roam: true允许用户缩放拖拽画布，draggable: true允许拖拽单个节点，这两个是演示时的核心交互。label的formatter里把绰号和姓名一起展示，鼠标不用悬停就能看到“林冲（豹子头）”。categories配合color做阵营着色，梁山泊用红色，朝廷用深蓝灰，其他用青色，一眼能分辨派系。
参数说明：repulsion是节点之间的斥力系数，数值越大节点分得越开。这套数据人物只有几十个节点时用300比较合适，如果你把全书的人物都导进去，建议调到500以上。edgeLength是数组形式，[80, 150]表示最短边80像素、最长边150像素，关系越多的两个节点边越短，视觉上会自动聚成一团。
5.3 部署与运行中的高频踩坑记录
这一节是复现时最值得看的。结合我自己跑通的经历和网上常见问题，总结了四条高频坑，按“现象 → 原因 → 解决”的顺序写。
坑一：前端页面打不开，控制台报404，但Flask后端明明启动了
现象：浏览器访问http://localhost:5000显示404，后端日志显示请求进来了但没有对应路由。原因：Flask的静态页面没有放在正确目录下。很多课程设计会把templates和static目录放在项目根目录，如果你的启动文件不在根目录，Flask找不到index.html。
解决：检查启动文件里Flask(__name__)的位置，确认项目目录结构里有templates/index.html和static/目录。如果用的是一级目录套一级目录的结构，需要在初始化Flask时指定template_folder和static_folder参数。
坑二：Neo4j连接成功，但查询报“Relationship type not found”
现象：后台日志显示Neo.ClientError.Statement.SyntaxError，提示某个关系类型不存在。原因：关系类型写错了，或者导入关系时用的标签和查询时不一致。比如导入用的[:主仆]，查询时写成了[:主仆关系]，肯定查不到。
解决：先在Neo4j Browser里执行MATCH ()-[r]->() RETURN DISTINCT type(r)，看库里到底有哪些关系类型，再去源码里全局搜索，把不一致的地方改掉。这个命令是排查关系类型问题最快的路径。
坑三：问答接口报错，提示“py2neo.errors.ClientError: The endpoint is not available”
现象：Flask能启动，前端也能打开，但一点问答按钮就报这个错。原因：py2neo连不上Neo4j，大概率是连接密码不对，或者Neo4j服务根本没启动。很多课程设计源码里写死了密码neo4j，但你自己电脑上装Neo4j时改过密码。
解决：打开源码里初始化Graph对象的文件，找到类似Graph("http://localhost:7474", auth=("neo4j", "123456"))的代码，把密码改成你自己的Neo4j密码。注意Neo4j 5.x默认不开启http://localhost:7474这个端口，需要确认你的Neo4j版本和源码匹配。
坑四：数据导入后，前端图谱里人物节点只有一小部分，关系更少
现象：后端查询MATCH (p:Person) RETURN count(p)显示一两百个节点，但前端图里只画了其中一部分，很多人物之间没有连线。原因：关系数据导入不全，或者导入时有些人物节点没匹配上导致关系没建成。最常见的情况是CSV里人物A的姓名和人物表中A的姓名不一致，比如一个叫“宋江”，另一个叫“宋公明”，MERGE时匹配不到，关系就静默跳过了。
解决：用MATCH (p:Person) WHERE NOT EXISTS((p)-[]-()) RETURN p.name找出孤立节点，逐个检查它们的关系数据里是否用了别名。处理方式要么在关系CSV里统一改成正式姓名，要么在导入时先用MATCH做一次别名转换。
6. 进阶玩法：给这个系统加一点你自己的东西
6.1 加一个“人物关系链路查询”功能
原系统的问答只支持单跳关系，比如“林冲的师傅是谁”。你可以扩展成多跳查询，问“宋江和武松之间有几个人”。这个功能只需要新加一个意图和一条Cypher，不需要动前端结构。
MATCH path = shortestPath( (a:Person {name: '宋江'})-[*..5]-(b:Person {name: '武松'}) ) RETURN [n IN nodes(path) | n.name] AS chain逻辑说明：shortestPath求两点之间的最短路径，[*..5]限定最多5跳。[n IN nodes(path) | n.name]是列表推导式，把路径上的所有节点名提取成一个数组，前端可以直接按顺序展示“宋江 → 柴进 → 武松”。跳数超过5时结果为空，可以提示用户关系链太远，这也是图数据库相对关系型数据库最有说服力的演示功能。
参数说明：把*..5改成*..2就变成“两人之间隔了谁”的查询，改小数值能控制查询深度。Neo4j如果数据量很大，最短路算法性能很好，但你这套数据只有一两百个节点，完全不用担心性能。
6.2 给问答系统加一个“反向关系”的兜底
原系统的意图识别是关键词匹配，比如问“武松的师傅是谁”，能匹配到“师傅”关键词。但如果你问“谁是武松的师傅”，关键词匹配依然能命中；反过来说，问“武松教过谁”，原系统大概率识别不了。这里可以加一个简单的反向意图映射：问题里含“教过”“带过”“指点过”，就沿用师徒关系的Cypher，但把方向反过来查。
MENTOR_REVERSE_KEYWORDS = ['教过', '带过', '指点过'] if any(kw in question for kw in MENTOR_REVERSE_KEYWORDS): intent = 'MENTOR_REVERSE'然后在build_cypher里加一个分支，把(p)-[:师徒]->(m)换成(p)<-[:师徒]-(m)，答案就从“师傅”变成了“徒弟”。这个小改动成本极低，但能让问答系统的覆盖面实打实地扩大一截，答辩时也能多讲一个“语义方向”的设计点。
6.3 验证系统正确性的三个自查步骤
跑完整套系统以后，别急着截图放PPT里，先做三件事验证数据正确性。
第一，核对人物总数。在Neo4j Browser里执行MATCH (p:Person) RETURN count(p)，对照原著的一百单八将加重要配角，数字对得上再放图。第二，抽查关键人物关系。比如查“李逵”的所有关系，确认主仆关系指向宋江，兄弟关系指向宋江、朱贵等人，如果有明显不合理的关系，回到数据导入脚本排查。第三，问答盲测。准备十个人物、每类关系准备两个问题，逐个输入，看答案是否和原著一致。这一步最容易暴露问题，比如有些关系方向反了，问“谁是谁的师傅”时答案对，但问“谁是谁的徒弟”时答案就变成了师傅的名字。
顺着这个思路改完，这套系统就不仅是一个能跑的课程设计，而是一个你自己能说清楚每一行代码、每一条Cypher含义的完整项目。我最早拿到类似资源时图省事，直接用原数据跑通就交了，结果答辩被问“这个关系方向怎么定的”一时答不上来。从那以后我每次复现别人的图数据库项目，都会强制自己重新走一遍数据建模到查询验证的全流程——这一步省不了，也希望帮到你。
本文还有配套的精品资源，点击获取
