在 docs.grit.io 上从哪里开始学习 GritQL

想系统学 GritQL，最省力的路径是：先看 Overview 建立概念，再跟着 Interactive Tutorial 动手，然后用 CLI Quickstart 把 Grit 装到本地跑通第一条查询，遇到语法细节再查 Language Reference。这套顺序适合第一次接触 GritQL、想尽快把“搜索并改写代码”跑起来的人；如果你只想查某个语法点，直接跳到 Language Reference 即可。

各入口分别解决什么问题

docs.grit.io 的文档导航里，与入门直接相关的有四个入口，职责并不重叠：

此外导航中还有 Pattern Library、Config、Testing、Guides（如 Continuous Integration、Authoring GritQL、Imports、VS Code、Sharing Patterns）等页面，属于进阶内容，建议在跑通第一条查询之后再看。

先理解 GritQL 的核心机制

GritQL 是一种声明式的代码搜索与改写语言。它的关键设计是：任何代码片段本身就是一条合法的 GritQL 查询，不需要先掌握 AST 细节。配合反引号和元变量（如 $msg），就能表达“找到什么、改成什么”。

官方 Quick Example 给出的写法是：

grit apply '`console.log($msg)` => `winston.log($msg)`'

这条查询的含义是：匹配所有 console.log(...) 调用，把日志函数替换为 winston.log(...)，括号内的参数通过元变量 $msg 原样保留。左边是匹配模式，=> 右边是改写结果。

同一页面还展示了如何把模式保存为自定义 lint，并用 where 子句排除特定情况：

`console.log($msg)` => `winston.log($msg)` where {
  $msg <: not within or { `it($_, $_)`, `test($_, $_)` }
}

这里的 where 表示附加约束：当 $msg 出现在 it(...) 或 test(...) 调用内部时不改写。这正是 GritQL 从“简单替换”走向“可控重构”的地方——先写匹配和替换，再用条件收窄范围。

按目标选择学习路线

目标一：先判断要不要用

看 Overview 的 “Why GritQL?” 部分。文档给出的定位包括：无需学习 AST 细节即可上手；借助 Rust 和查询优化可扩展到千万行级仓库；通过内置模块系统复用 200+ 标准模式或分享自己的模式；支持 JavaScript/TypeScript、Python、JSON、Java、Terraform、Solidity、CSS、Markdown、YAML、Rust、Go、SQL 等多种语言；内置 auto-fix，便于快速修复。

文档列出的典型场景是：大规模迁移（跨百万行迁移 API、框架或重构代码库）、自定义 lint（落实团队规范）、代码质量改进、依赖升级时处理破坏性变更。对照你的任务属于哪一类，就能判断投入是否划算。

目标二：动手学会写模式

进入 Interactive Tutorial 按步骤练习。练习时建议始终围绕一个真实小任务，例如“把项目里的 console.log 换成统一日志库”，这样每学一个语法点都能立刻验证效果。

目标三：在本地或仓库里执行

看 CLI Quickstart，按文档安装并使用 Grit CLI，然后运行上面那条 grit apply 查询。验证方法是：在测试仓库里放一个含 console.log 的文件，执行后确认输出被替换；再把它放进 it(...) 内部，确认 where 条件生效、未被改写。常见卡点是模式里的反引号和元变量书写不正确，以及改写范围超出预期——先用小范围文件试跑，再扩大。

目标四：查语法细节

写模式过程中遇到条件、模式修饰符、作用域（Bubble and Scoping）、函数、常见惯用法等问题，查 Language Reference 下对应的 Pattern、Conditions、Pattern Modifiers、Functions、Common Idioms 等页面。Testing GritQL 页面则适合在把模式沉淀为团队规范前做验证。

入门之后可以看什么

跑通基本查询后，Config 用于配置，Pattern Library 用于查找可复用模式，Sharing Patterns 与 Imports 涉及模式共享和导入，VS Code 页面介绍编辑器集成，Guides 下的 Continuous Integration 则说明如何把检查接入流水线。这些都属于“已经会用”之后的效率提升，不必在第一天全部读完。