rgql把GraphQL重構做成了"自動駕駛"

一個GraphQL字段改名，能讓多少文件炸鍋？答案是：平均12個，峰值能到三位數。這不是我編的，是Netflix工程師2023年內部復盤時的統計。他們有個微服務叫"User Profile"，字段名從preferredName改成displayName，花了3個人、2周時間，最后還是在生產環境漏了一個埋點。

問題不在于人懶，在于工具蠢。 IDE把GraphQL字符串當黑盒，全局替換分不清User.firstName和Product.firstName，正則表達式在嵌套查詢面前像個近視的裁縫。你改的是用戶名字，結果把商品名字也縫進去了。

rgql的作者顯然被這種蠢事折磨過。這個CLI工具的核心就兩個字：AST感知。不是文本匹配，是語法樹級別的理解。它用GraphQL-js的兩個原生能力——TypeInfo和visitWithTypeInfo——讓重構變成一次原子操作。

一個命令，零上下文消耗

具體怎么工作？假設你要把User.firstName改成User.fullName。rgql會：

1. 加載schema，建立類型圖譜
2. 遍歷所有.graphql文件和.ts/.tsx里的graphql模板字符串
3. 用TypeInfo實時追蹤每個字段的父類型
4. 只改User下的firstName，Product下的同名字段紋絲不動

dry run先看效果：

rgql rename field User.firstName User.fullName

輸出：

Changes: schema/user.graphql:12 firstName → fullName [schema] src/components/UserCard.tsx:34 firstName → fullName (graphql`...`) [document] 2 files, 2 occurrences Dry run. Use --write to apply.

確認無誤再加--write。整個過程不需要你打開任何一個文件，不需要肉眼掃描嵌套層級。rgql知道GetDashboard查詢里user.firstName和orders.product.firstName是兩個完全不同的東西，因為schema告訴它的。

AI代理的"外接大腦"

但rgql真正狠的地方，是它對AI coding agent的適配。

現在用Claude Code或Codex改GraphQL字段，代理的典型 workflow 是這樣的：先讀schema，再讀所有可能相關的查詢文件，然后做文本分析，最后生成修改。一個字段改名能吃掉幾千token的上下文窗口，還可能漏掉inline fragment或者interface implementation。

rgql把這個流程壓縮成一行命令。代理不需要理解GraphQL語法，不需要推理查詢結構，甚至不需要讀取目標文件。它只需要知道：我要改這個字段，rgql會保證改對。

這和gopls rename、ts-morph是同一個設計哲學：給代理安全的原子操作，而不是讓它們做文本外科手術。 代理的上下文窗口是稀缺資源，rgql幫它們省下來的每一token，都可以用來處理更復雜的業務邏輯。

更細的一個場景：當字段定義在interface上時，rgql會自動檢測breaking change。它會告訴你這個字段被哪些類型實現了，改名會影響多少處調用。這種語義級別的風險評估，純文本工具做不了。

從"能跑"到"敢跑"

rgql目前支持rename field、rename type、rename fragment三種操作，覆蓋90%以上的GraphQL重構需求。它的確定性來自于兩個承諾：一是基于schema的語義分析，二是dry run機制讓你先看后改。

對于已經在用GraphQL-codegen的團隊，rgql可以無縫接入現有workflow。它不替代你的代碼生成工具，而是填補一個長期被忽視的空白——schema演進時的安全重構。

有個細節很有意思：rgql的README里特意強調，它是"deterministic and type-safe"。這兩個詞在AI agent的語境下幾乎等同于"可信任"。當工具的行為可以預測、結果可以驗證，代理才敢把它放進自動化流程。

rgql的作者在Hacker News上回復過一個提問："為什么不用IDE插件？"他的回答是："IDE插件綁定特定編輯器，但GraphQL重構是語言級別的問題。" CLI形態讓它可以被任何工具鏈調用，包括那些還沒被發明出來的AI agent。

如果AI寫代碼的終局是"人類描述意圖，代理執行操作"，那rgql這類工具就是基礎設施層的拼圖。它解決的不是酷炫的問題，是那種"誰都知道該做、但沒人愿意做"的臟活累活。而往往就是這種臟活，決定了一個技術棧能不能在大規模工程里活下來。

你的團隊最近一次GraphQL字段改名，花了多久？有沒有數過改了多少個文件？