4.3 多语言集成与 HTTP 接口：模式的推广与边界

4.3 多语言集成与 HTTP 接口：模式的推广与边界

本节摘要：4.1 的驱动模式不是 Python 专属：Java、JavaScript、.NET、Go 的官方驱动同构，三层对象与托管事务一一对应。本节先给出跨语言的对照片段与"查询封装"工程清单，再正面回答一个历史遗留问题——HTTP 接口还要不要用：结论是新项目默认不用，但两种场景仍会遇到它。

驱动编程的骨架在语言间高度一致。把骨架抽出来，学一门新语言的驱动就只是查 API 名称的体力活。

一、跨语言同构：同一段业务的三种写法

同一个"查共同出演并幂等建立同事关系"的需求，三种语言的对照：

// Java
try (Session session = driver.session(SessionConfig.forDatabase("neo4j"))) {
    session.executeWrite(tx -> {
        tx.run("MERGE (p:Person {name: $n})", Map.of("n", name));
        return null;
    });
}
​

// JavaScript
const session = driver.session({ database: 'neo4j' });
try {
  await session.executeWrite(tx =>
    tx.run('MERGE (p:Person {name: $n})', { n: name })
  );
} finally {
  await session.close();
}
​

# Python（对照锚）
with driver.session(database="neo4j") as s:
    s.execute_write(lambda tx: tx.run(
        "MERGE (p:Person {name: $n})", n=name))
​

三段代码的对应关系：driver 对 driver，executeWrite 对 executeWrite，参数全部走 $占位符 绑定。参数化不是可选项：字符串拼接查询既给注入攻击开门，又让服务端缓存形同虚设——每个不同字符串都是一条新的执行计划。

二、查询封装：应用层的工程清单

真实项目不会让查询散落在业务代码里。一份能直接落地的封装清单：

# repo.py：查询集中在仓库层，参数化 + 结果映射 + 超时
class PersonRepo:
    FIND_COACTORS = """
      MATCH (a:Person {name: $name})-[:ACTED_IN]->(m:Movie)
            <-[:ACTED_IN]-(b:Person)
      WHERE b <> a
      RETURN m.title AS title, collect(b.name) AS coactors
    """

    def coactors(self, name: str) -> list[dict]:
        res = self.driver.execute_query(
            self.FIND_COACTORS, name=name,
            database_="neo4j",
        )
        return [r.data() for r in res.records]     # 记录 → 字典
​

封装清单（每项对应一个真实事故来源）：
1. 查询集中于仓库层     → 评审与调优有单一入口
2. 一律参数化           → 防注入 + 计划缓存命中
3. 结果显式映射         → 图结构变化不直接泄漏到业务层
4. 超时必须配置         → 失控查询不拖垮服务线程
5. 只读走 execute_read  → 未来集群化时读路由现成
6. 错误分层上报         → TransientError 已重试，业务错误才告警
​

超时值得多说一句：生产上"一条查询拖垮整个服务"的故事，多数始于没配超时的失控遍历。给查询设置语句级超时，把最坏情况的损失锁死：

// 语句级超时：5 秒跑不完即中止
CALL { MATCH (a)-[:KNOWS*1..5]-(b) RETURN count(*) AS c }
IN TRANSACTIONS OF 1000 ROWS
RETURN c
​

三、HTTP 接口：历史地位与残存场景

老版本文档里的 HTTP API（事务端点、提交 Cypher 到 7474）曾是唯一的程序化入口。Bolt 驱动成熟后，它的位置已被明确取代：

仍会用到它的两个场景：一是纯脚本或受限网络环境里没有驱动可用，curl 直接打 7474 最省事；二是部分第三方工具只实现了 HTTP 接入。用的时候认准事务端点的三段式（开启、语句、提交）即可：

# 最小示例：单语句自动提交
curl -X POST http://localhost:7474/db/neo4j/tx/commit ^
  -H "Content-Type: application/json" ^
  -d "{\"statements\":[{\"statement\":\"MATCH (n) RETURN count(n) AS c\"}]}"
​

💡 新项目评审遇到"通过 HTTP 接口访问 Neo4j"的方案，先问一句为什么没有用驱动——答案通常是历史包袱而非技术选型，能换则换。

四、一次真实的集成复盘

把本章清单用在一个小需求上："每小时统计一次新增用户并写入报表表"。设计路径：

1. 查询定型（Browser）：调好 Cypher，PROFILE 确认走索引
2. 脚本固化（cypher-shell）：巡检账号 + 退出码检查 + 定时调度
3. 数据出图：--format plain 输出，下游报表系统直接消费
4. 故障面：查询失败 exit 1 → 调度平台告警 → 次日人工重跑
​

这个需求没有写一行应用代码——cypher-shell 加调度平台就够了。先想清楚要不要写代码，是集成设计的第一步；许多"集成需求"其实是脚本需求。

本节要点回顾

• 五大官方驱动同构：Driver/Session/Transaction + executeWrite + $参数；
• 参数化是硬纪律：防注入、保计划缓存；
• 查询封装六清单：集中、参数化、映射、超时、读写分离、错误分层；
• HTTP 接口已被 Bolt 取代，仅残存于脚本便利与三方工具；
• 语句级超时把失控查询的最坏损失锁死。

应用层的连接、工具、模式都齐了。下一章下探引擎：存储、集群与图算法的内核故事。