一 前言
代碼文本不是簡單的二維平面結構，看懂一段代碼需要反覆地通過定義與引用的跳轉，才能將代碼深層次的邏輯和片段影響範圍理解透徹。純文本形式的代碼瀏覽是網頁端代碼評審的最大痛點之一，朱熹老先生常說“心不在此，則眼不看仔細，心眼既不專一，卻只漫浪誦讀，決不能記，記亦不能久也。”代碼文本扁平式地漫浪誦讀只能達到眼到、口到的境界，如果你是一個認真負責的代碼評審者，阿里云云效代碼智能語法服務一定是幫助你充分理解代碼變更，超越眼口，到達“心到”境界的功能。心既到矣，眼口豈不到乎？
那麼什麼是代碼智能語法服務呢？語法服務提供了基於雲端備份的快速代碼導航服務，無須本地克隆即可在頁面體驗熟悉的定義引用快速查看跳轉功能，大幅提升代碼評審的效率和質量。
二 技術基礎
阿里云云效代碼智能語法服務的底層技術是LSIF（Language Server Index Format），它是一種持久化語言的索引的圖存儲格式，通過圖的格式，表示了“代碼文檔”-> “語法智能結果”之間的事件關係。
在LSIF之前，LSP（Language Server Protocol）定義了編碼語言與各類終端代碼編輯器之前的交互協議。原先開發者需要為每一款編輯器都定義適配一種語法分析服務應用，那麼M個語言要在M個代碼編輯器中使用的話需要MxN個應用。而有了LSP的出現，開發者在解析代碼語法時只需要遵循LSP協議格式，實現代碼補全、定義展示、代碼診斷等接口，就只需要開發M+N個應用。
然而代碼分析往往需要耗費大量的時間和資源，當用戶請求某個語法服務（如查看定義），後端需要克隆代碼，下載依賴包，解析語法，構建索引（類比一下IntelliJ Idea初始化工程的場景），編輯器場景用戶已經習慣於這樣的方式，等待幾分鐘或許問題不大。但CR場景或者輕量級的代碼瀏覽場景，這種方式就顯得時效性比較低了，幾分鐘後或許用戶已經完成了代碼瀏覽，而且缺少持久化的存儲會導致資源過度消耗。於是，LSIF就在這樣的背景下應運而生，秉承用空間換時間的思想，提前計算好語法分析結果以特定的索引格式存儲在雲上，從而快速響應不同用戶的多次請求。
援引官方示例來簡單介紹下LSIF，如下方代碼：
// this is a sample class
public class Sample {
}假定只有一種交互，當鼠標移動到Sample的類名上，就會出現“this is a sample class”的註釋信息。用LSIF的圖就可以如下描述。
一個sample文件，包含了一個range信息，這個range關聯了一個hoverResult。含義是該文件的某個位置範圍內，觸發hover事件的話，就給出hoverResult存儲的結果。
如果用Json文件描述這張圖的存儲，就可以得到如下結果：
{ id: 1, type: "vertex", label: "document", uri: "file:///abc/sample.java", languageId: "java" }
{ id: 2, type: "vertex", label: "range", start: { line: 0, character: 13}, end: { line: 0, character: 18 } }
{ id: 3, type: "edge", label: "contains", outV: 1, inVs: [2] }
{ id: 4, type: "vertex", label: "hoverResult", result: {["this is a sample class"]} }
{ id: 5, type: "edge", label: "textDocument/hover", outV: 2, inV: 4 }實際一個工程的LSIF圖會非常複雜，經常會包含幾十萬個節點。感興趣的同學可以參考LSIF具體描述[1]。
三 實現方式
阿里云云效的語法服務架構圖主要分為兩部分：
- 基於事件觸發的索引構建過程
- 基於用戶請求的語法服務響應
1 索引構建
用戶對代碼的瀏覽場景主要集中在代碼評審和主幹分支的代碼瀏覽，所以我們目前主要支持兩種場景的語法服務。語法服務接收來自代碼平臺的事件消息，如代碼推送事件，評審的創建、更新、合併、關閉、重新開啟事件，來觸發語法服務構建。
我們的構建工作流調度主要基於阿里巴巴開源的分佈式調度框架tbschedule，該系統會通過zookeeper維護一個任務集群，通過zookeeper做節點管理和任務分發，不重複不遺漏地快速處理調度任務。
針對不同語言，我們只需要實現一次從源代碼到LSIF格式的轉換，就能將其應用在多種場景。多種代碼語言代碼語言都會被解析成統一的LSIF格式文件。
針對阿里巴巴內部主要的Java語言，我們利用開源Java代碼解析工具Spoon[2]將Java源代碼分析為AST（抽象語法樹），然後捕捉定義和引用、定義與註釋之間的關聯，將座標信息、註釋內容，文本類型，所屬文件等信息聚合，輸出為統一的LSIF的Json格式。
開發期間修復並適配了一些lsif-java的問題，如位置範圍信息錯亂，召回多種遺漏的高亮詞類型，適配非Maven倉庫的索引構建。同時還修復了Spoon關於無法正確解析註釋中的部分註解的問題，PR已被Spoon社區接受合併[3]。
生成lsif.json文件後，由於這個Json文件較大，直接由前端加載並響應請求不太合理，後期增量生成與維護難度也很大，所以我們還需要一步：將lsif.json轉化為結構化數據，從而按需響應用戶查詢請求。lsif的圖存儲格式讓人自然地聯想到用圖數據結構存儲，圖查詢的速度也比較快，然而由於索引變化迭代較快，頻繁更換的ID導致圖存儲難以適配增量方案，不同代碼庫不同語言的索引數據很難在一張圖中結構化，參考了社區的相關實踐，考慮到成本和性能，因為ES天然地適合大規模的數據存儲和索引，我們最後選擇了用ES（Elasticsearch）做結構化數據存儲。
我們將這種結構化的數據上傳到ES，然後語法服務後端服務器會基於用戶的語法請求，構造ES請求Query，查詢定義、引用或註釋信息，將其拼裝返回。
對於分支，我們會持續更新和保留最新版本的索引數據；對於代碼評審，我們會構建源分支的每次Push版本和源目標分支的merge-base版本的索引。
索引構建的另外一個難點是增量計算。如上文所述，語法服務索引構建對資源的要求非常高，而現實中代碼庫不可避免地會存在頻繁提交的現象。如此引申出了兩個優化點：
- 利用增量的方式減少存儲內容的變更，加快索引構建速度。
- 利用分佈式時序鎖減少頻繁請求帶來的壓力。
增量方案
每次分支索引構建成功，我們都會在數據庫中記錄分支對應的版本號，當該分支有了一次新的提交後，在生成lsif.json後，系統會比較兩個分支的Diff，獲取到變更文件和變更類型，通過變更文件來進一步提取索引受到影響的文件（引用或定義的座標信息變更），分析出所有受影響的文件和對應的ES增刪操作後，完成增量索引上傳。這個增量的過程平均能減少45%的分支構建時間。
時序鎖管理
根據庫大小的區別，LSIF的索引構建時間為10秒至數分鐘不等，而用戶對同一個代碼倉庫的提交操作峰值可能會達到每分鐘近百次，即使我們採用了增量技術也很難滿足高頻的構建請求，並且提交事件觸達和調度任務執行無法保證精準的時序性。綜上所述，我們需要一個分佈式時序鎖來保證任務調度的順序和儘量減少重複調度。
當同一代碼庫的不同推動消息紛湧而至，Redis維護的分佈式鎖會做如下判斷：若該庫當前沒有正在運行的任務，將任務置於隊首，立即運行；若已有一個正在執行的任務，比較新來的Push消息是否是最新的，若是，則加入隊尾；當隊伍已有兩個成員時，則將任務丟棄，因為每次執行任務時，系統都會克隆分支代碼，基於最新的版本構建索引，如此就避免了多少次Push就需要執行多少次索引構建的可能性。考慮到線程意外退出的情況，隊首會每隔5秒鐘全局發送心跳，當隊尾或新來的任務監聽到心跳超時，則會將隊首的任務放棄並執行新的任務。
2 語法服務響應
如前言的示例，用戶在使用語法服務時，主要有以下三個請求：
- 每次打開文件獲取所有的可點擊高亮詞
- 點擊高亮詞獲取對應的定義與引用列表
- 點擊定義和引用實現跳轉
針對第一個請求，系統會構造基於文件路徑的過濾條件構造ES的Query請求，將當前文件的所有高亮詞座標信息發送給前端，避免了前端做語法分詞，沒有構建好的文件自然也不會在頁面上被高亮出來。另外，為了避免超大文件對ES的壓力，前端會做分批動態加載。
針對第二個請求，我們在獲取定義與引用列表的過程中，不光要得到文件名和位置信息，還需要將對應的代碼內容展示出來，方便用戶理解。為了實現這個效果，我們新增了批量獲取文件片段的接口。
對於第三個請求，同一個文件內的跳轉會自動高亮到對應的代碼行，不同文件間的跳轉會新開頁面並跳轉。
語法服務響應和語法索引構建是完全異步的，互不影響，支持獨立的資源擴縮。
3 索引清理
語法服務的索引大小約是代碼文件內容的數倍，比較消耗存儲資源。所以針對用戶通常的使用習慣和場景，制定了一系列索引清理任務來避免資源過度的損耗。
當代碼評審合併或刪除時，當分支刪除時，系統會開始執行索引清理任務，釋放索引資源。
四 語法服務展望
缺少符號跳轉長久以來一直是頁面上代碼閱讀的痛點之一，各種語法協議和技術層出不窮，如LSIF、Kythe、SARIF、UAST、Tree-sitter，ctags，全球技術人都在為更智能的代碼分析，更好的代碼體驗，更高的代碼質量做努力。雲效語法服務後續也會逐漸加快語法構建速度，支持更多的代碼語言，滿足更多的語法場景，提升用戶的代碼瀏覽體驗。
相關鏈接
[1]https://microsoft.github.io/language-server-protocol/specifications/lsif/0.4.0/specification/
[2]http://spoon.gforge.inria.fr/
[3]https://github.com/INRIA/spoon/pull/3513