Neo4j Cypher Shell 实战指南从源码构建、连接运行到自动化测试【免费下载链接】neo4jGraphs for Everyone项目地址: https://gitcode.com/gh_mirrors/ne/neo4jCypher Shell 是 Neo4j 官方提供的命令行接口CLI用于通过 Bolt 协议向 Neo4j 实例提交 Cypher 查询并执行管理任务。本文以本仓库中 community/cypher-shell/README.md 为骨架结合cypher-shell子项目的源码与测试系统讲解如何在本地构建 JAR/ZIP 与 RPM/Debian 安装包、如何借助 Docker 快速起一个可用的 Neo4j 并连接、如何掌握全部命令行参数与环境变量以及如何运行集成测试与最小冒烟测试Tyre Kicking Test帮助你从能跑起来进阶到能测起来、能调试。Cypher Shell 是什么Cypher Shell 位于仓库的 community/cypher-shell 目录是 Neo4j 的命令行前端。从 CliArgHelper.java 中解析器自带的描述可以看到它的定位Cypher Shell is a command-line tool used to run queries and perform administrative tasks against a Neo4j instance. By default, the shell is interactive, but you can also use it for scripting by passing Cypher directly on the command line or by piping a file with Cypher statements... It communicates via the Bolt protocol.即它默认以交互式 REPL 方式工作也支持一条命令执行一段 Cypher 后退出以及从文件/管道批量喂入语句的脚本化用法所有通信都走 Bolt 协议默认端口 7687。在源码层面Main.java 是程序入口先用CliArgHelper解析命令行参数再构造CypherShell实例并启动交互或非交互执行循环。核心的执行器 CypherShell.java 会把每条输入区分为两类以:开头的 Shell 内建命令如:begin、:use走CommandHelper分发其余文本则作为 Cypher 语句交给BoltStateHandler通过驱动执行。如何构建JAR 与 ZIP 发行包JAR 和 ZIP 发行包由cypher-shell子项目通过 Maven 构建。从 Makefile 可以看到ZIP 包的产出路径为cypher-shell/target/cypher-shell-$(VERSION).zip其构建命令是cd ../.. mvn package --projects org.neo4j:cypher-shell --also-make -DskipTests即在仓库根目录对org.neo4j:cypher-shell模块及其依赖模块执行打包并跳过测试。构建产物 ZIP 内是可直接解压使用的cypher-shell/目录包含可执行脚本cypher-shell及其所需的 jar 包。RPM 与 Debian 安装包RPM 和 Debian 安装包通过packaging目录下的 Makefile 构建细节见 packaging/README.md执行make rpm构建 RPM 包产物位于out/cypher-shell-{rpm-version}.{rpm-release}.noarch.rpm执行make debian构建 Debian 包产物为cypher-shell_{debian-version}_all.deb使用make rpm-test验证 RPM 包需要 docker 环境。如何运行原文档给出了一套快速跑起来的标准流程清空本地缓存的已认证主机记录、用 docker 启动一个一次性 Neo4j 实例关闭认证然后用make run启动 Shell 连接它rm -rf ~/.neo4j/known_hosts docker run --rm -p 7687:7687 -e NEO4J_AUTHnone neo4j:4.1 make run其中各步骤的含义如下~/.neo4j/known_hosts是 Cypher Shell 缓存服务器指纹的本地文件删除它可以避免因之前记录过其他 Neo4j 实例的指纹而导致的连接校验失败保证每次连接的都是全新的容器实例docker run --rm -p 7687:7687 -e NEO4J_AUTHnone neo4j:4.1启动一个用完即弃的 Neo4j 容器将 7687Bolt 端口映射到本机并关闭认证NEO4J_AUTHnone这样无需用户名密码即可直连make run会按 Makefile 的定义先解压构建好的 ZIP 到tmp/install再执行其中的cypher-shell可执行文件进入交互式 Shell。如果你希望手动运行而不通过 make流程等价于先按上文构建出 ZIP解压后直接执行unzip cypher-shell/target/cypher-shell-version.zip -d /tmp/cypher-shell /tmp/cypher-shell/cypher-shell/cypher-shell命令行参数与连接配置构建并运行后最重要的就是理解 Cypher Shell 支持的参数。参数解析集中实现在 CliArgs.java 与 CliArgHelper.java 中下面按类别整理为可直接参考的表格。连接类参数参数说明默认值-a,--address,--uri连接的地址与端口格式[scheme://][username:password][host][:port]neo4j://localhost:7687-u,--username连接用户名空可交互提示-p,--password连接密码空可交互提示--impersonate以其他用户身份执行模拟用户无-d,--database要连接的数据库名由服务端决定--encryption是否加密连接取值true/false/defaultdefault时由地址推导如neo4jssc协议即加密须与 Neo4j 服务端配置一致default--access-mode访问模式READ或WRITEWRITE源码中的默认连接地址由 CliArgs.java 定义scheme 为neo4j、主机localhost、端口7687。若地址未带 schemeCliArgHelper.java 会自动补上neo4j://前缀端口缺省时补 7687同时它还会解析地址中内嵌的username:password用户信息。脚本与执行类参数参数说明cypher位置参数直接在命令行传入一段 Cypher执行后退出例如cypher-shell RETURN 1;-f,--file传入一个包含多条 Cypher 语句的文件执行完毕后 Shell 退出--fail-fast从文件读取时遇到第一个错误立即失败退出默认行为--fail-at-end从文件读取时处理完所有输入后在结尾统一报告失败-P,--param为会话添加参数可多次指定例如-P {a: 1}或-P {a: 1, b: duration({seconds: 1})}--change-password修改 neo4j 用户密码后退出--non-interactive强制非交互模式仅在自动检测失败如 Windows时需要除命令行参数外CliArgHelper.java 还定义了以下环境变量作为参数的回退来源环境变量作用NEO4J_URI/NEO4J_ADDRESS连接地址两者同时设置会报错只能二选一NEO4J_USERNAME用户名NEO4J_PASSWORD密码NEO4J_DATABASE目标数据库NEO4J_CYPHER_SHELL_HISTORY历史记录文件路径输出与体验类参数参数说明默认值--format输出格式auto交互用表格、脚本用最小格式、verbose表格 统计信息、plain最小格式化数据auto--sample-rows计算表格列宽时采样的行数仅verbose格式1000--wrap列过窄时是否换行仅verbose格式true--enable-autocompletions是否启用 CLI 内的 Cypher 自动补全仅 neo4j 5 及以后支持关闭--notifications在交互模式下显示通知关闭--history历史记录文件路径或in-memory使用内存历史默认用户目录/.neo4j/.cypher_shell_history见说明--log启用日志可指定文件缺省输出到标准错误关闭--idle-timeout交互模式下空闲指定时长后自动退出格式如1h、1h30m、30m默认禁用-v,--version打印 Cypher Shell 版本并退出无--driver-version打印 Neo4j Driver 版本并退出无从实现上看Main.java 的startShell()会先处理--version、--driver-version、--change-password三个即出即走的分支再进入常规的runShell()而runShell()中若检测到cypher位置参数就解析并执行这段语句后返回这正是单条命令脚本化的实现路径见 Main.java。交互式连接行为交互模式下若提供了用户名而未提供密码Shell 会提示输入认证失败时会再次提示用户名与密码重试当服务端要求强制改密时如首次登录会引导完成密码修改相关逻辑集中在 Main.java 的connectMaybeInteractively()中。非交互场景如管道输入下无法提示需通过参数或环境变量完整提供凭据。Shell 内建命令进入交互式 Shell 后以:开头的行会被解析为内建命令。这些命令由 CommandHelper.java 统一注册与分发当前注册的命令包括命令用途:begin开启显式事务:commit提交当前事务:rollback回滚当前事务:connect连接或重新连接到一个 Neo4j 实例:disconnect断开当前连接:exit退出 Shell:help查看可用命令的帮助:history查看命令与查询历史:param查看或设置会话参数:source执行一个文件中的 Cypher 语句:use切换当前使用的数据库:impersonate以指定用户身份执行这些命令各自对应commands/目录下的实现类如 Begin.java、Use.java、Source.java 等。若输入的命令名不存在CypherShell.java 会提示use :help to see available commands。开发与测试集成测试集成测试模块位于 integration-test运行方式在其 README.md 中有完整说明先在 localhost 上启动一个带 Bolt 驱动的 Neo4j 服务若需要认证默认约定用户名为neo4j、密码为neo使用 Maven 的integration-test目标并显式传入-DenableCypherShellIntegrationTest不加该标志时测试被禁用。例如从仓库根目录只跑 Cypher Shell 集成测试mvn integration-test --projects org.neo4j:cypher-shell-integration-test -DenableCypherShellIntegrationTest同样也提供快速方式清空known_hosts、用 docker 起一个免认证的一次性 Neo4j然后连同依赖一起跑集成测试rm -rf ~/.neo4j/known_hosts docker run --rm -p 7687:7687 -e NEO4J_AUTHnone neo4j:4.1 mvn integration-test --projects org.neo4j:cypher-shell-integration-test --also-make -DenableCypherShellIntegrationTestTyre Kicking Test最小冒烟测试make tyre-kicking-test会执行 tyrekicking.sh 脚本对构建出的可执行文件做一次最小化验证。该脚本的实测流程如下将 ZIP 包解压到临时工作区先以独立安装形态运行cypher-shell -u neo4j -p neo RETURN 1;成功即通过若失败再以打包形态尝试把所有 jar 移入cypher-shell/tools/子目录模拟发行版目录结构再运行cypher-shell -a bolt://localhost:7687 -u neo4j -p neo RETURN 1;两种形态任一成功即判定通过否则退出码为非零脚本中的注释说明4.X 系列默认关闭加密3.X 系列默认开启加密因此两套尝试分别覆盖两种连接场景。可以看出这是一个非常轻的冒烟测试——只验证 Shell 能启动、能连接、能执行一条最简查询适合在打包流水线中快速把关。运行它需要本机已存在可连接的 Neo4jRETURN 1需要真实连接才能成功。源码结构速览cypher-shell子项目的主要源码位于 cypher-shell/src/main/java/org/neo4j/shell按职责划分为以下包cli命令行参数模型与解析CliArgs、CliArgHelper、交互/非交互运行器、输出格式枚举commandsShell 内建命令实现:begin、:use、:source等及注册分发CommandHelperparser语句解析器区分内建命令与 Cypher 语句ShellStatementParserprettyprint结果格式化输出表格、纯文本、统计信息stateBolt 连接状态管理BoltStateHandler负责与驱动的交互terminal终端抽象JLine 交互终端、简单提示、历史行为startup启动引导CypherShellBoot同时提供 Java 8 兼容版本completions数据库信息与自动补全引擎util/system版本号与平台工具。如果希望了解某个具体参数或命令的底层行为从cli/CliArgs.java或commands/目录下的对应类入手是最直接的路径。小结Cypher Shell 作为 Neo4j 的官方 CLI兼顾交互式 REPL 与脚本化执行两种形态构建上支持 MavenJAR/ZIP与 MakeRPM/Debian两条链路运行上既可以通过make run结合一次性 docker 容器快速体验也可以解压 ZIP 手动执行连接配置上提供了完整的参数与环境变量体系配合:begin/:commit/:use等内建命令可完成事务、换库、参数注入等日常操作质量保障上则有集成测试与 Tyre Kicking Test 两级验证。结合 community/cypher-shell 目录下的 README 与源码即可在自己的环境中完整复现从构建到测试的全流程。【免费下载链接】neo4jGraphs for Everyone项目地址: https://gitcode.com/gh_mirrors/ne/neo4j创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考