因為我的一次疏忽而帶來的golang1.23新特性

apocelipes發表於2024-05-16
Golang

距離golang 1.23釋出還有兩個月不到，按照慣例很快要進入1.23的功能凍結期了。在凍結期間不會再新增新功能，已經新增的功能不出大的意外一般也不會被移除。這正好可以讓我們提前嚐鮮這些即將到來的新特性。

今天要說的就是1.23中對//go:linkname指令的變更。這個新特性可以說和我的一次失誤息息相關。

重要的事情得先寫在前面：//go:linkname指令官方並不推薦使用，且不保證任何向前或者向後相容性，因此明智的做法是儘量別用

牢記這一點之後，我們可以接著往下看了。至於為啥和“我”也就是本文的作者有關，我們先看完新版本帶來的新變化再說。

linkname指令是做什麼的

簡單的說，linkname指令用於向編譯器和連結器傳遞資訊。具體的含義根據用法可以分為三類。

第一類叫做“pull”，意思是拉取，使用方式如下：

import _ "unsafe" // 必須有這行才能用linkname

import _ "fmt" // 被拉取的包需要顯式匯入（除了runtime包）

//go:linkname my_func fmt.Println
func my_func(...any) (n int, err error)

這種用法的指令格式是//go:linkname <指令下方的只有宣告的函式或包級別變數名> <本包或者其他包中的有完整定義的函式或變數>。

這個指令的作用就是告訴編譯器和聯結器，my_func的函式體直接使用fmt.Println的，my_func類似fmt.Println的別名，和它共享同一份程式碼，就像把指令第二個引數指定的函式和變數拉取下來給第一個引數使用一樣。

正因如此，指令下方給出的宣告必須和被拉取的函式/變數完全一致，否則很容易因為型別不匹配導致panic（是的沒錯，除非拉取的物件不存在，否則都不會出現編譯錯誤）。

這個指令最恐怖的地方在於它能無視函式或者變數是否是export的，包私有的東西也能被拉取出來使用。因為這一點這種用法在早期的社群中很常見，比如很多人喜歡這麼幹：//go:linkname myRand runtime.fastrand，因為runtime提供了一個效能還不錯的隨機數實現，但沒有公開出來，所以有人會用linkname指令把它匯出為己所用，當然隨著1.21的釋出這種用法不再有任何意義了，請永遠都不要去模仿。

第二種用法叫做“push”，即推送。形式上是下面這樣：

import _ "unsafe" // 必須有這行才能用linkname

//go:linkname main.fastHandle
func fastHandle(input io.Writer) error {
    ...
}

// package main
func fastHandle(input io.Writer) error

// 後面main包中可以直接使用fastHandle
// 這種情況下需要在main包下建立一個空的asm檔案（通常以.s作為副檔名），以告訴編譯器fastHandle的定義在別處

在這種用法中，我們只需要把函式/變數名當作第一個引數傳給指令，注意需要給出想用這個函式/變數的包的名字，這裡是main。同時在指令下方的函式/變數必須有完整的定義。

這種用法是告訴編譯器和連結器這個函式/變數的名字就是xxx.yyy，如果遇到這個函式就使用linkname指定的函式/變數的程式碼，這個模式下甚至能在本包定義別的包裡的函式。

當然這種用法的語義作用更明顯，它意味著這個函式會在任何地方被使用，修改它需要小心，因為改變了函式的行為可能會讓其他呼叫它的程式碼出bug；修改了函式的簽名則很可能導致執行時panic；刪除了這個函式則會導致程式碼無法編譯。

最後一類叫做“handshake”，即握手。他是把第一類和第二類方法結合使用：

package mypkg

import _ "unsafe" // 必須有這行才能用linkname

//go:linkname fastHandle
func fastHandle(input io.Writer) error {
    ...
}

package main

import _ "unsafe" // 必須有這行才能用linkname

//go:linkname fastHandle mypkg.fastHandle 
func fastHandle(input io.Writer) error

“pull”的一方沒什麼區別，但“push”的一方不用再寫包名，同時用來告訴編譯器函式定義在別的地方的空的asm檔案也不需要了。這種就像通訊協議中的“握手”，一方告訴編譯器這邊允許某個函式/變數被linkname操作，另一邊則明確像編譯器要求它要使用某個包的某個函式/變數。

通常“pull”和“push”應該成對出現，也就是你只應該使用“handshake”模式。

然而不幸的是，當前（1.22）的go語言支援“pull-only”的用法，即可以隨便拉取任何包裡的任何函式/變數，但不需要被拉取的物件使用“push”標記自己。而被linkname拉取的一方是完全無感知的。

這就導致了非常大的隱患。

linkname帶來的隱患

最大的隱患在於這個指令可以在不通知被拉取的packages的情況下隨意使用包中私有的函式/變數。

舉個例子：

// pkg/mymath/mymath.go
package mymath

func uintPow(n uint) uint {
    return n*n
}

// main.go
package main

import (
	"fmt"
	_ "linkname/pkg/mymath"
	_ "unsafe"
)

//go:linkname pow linkname/pkg/mymath.uintPow
func pow(n uint) uint

func main() {
	fmt.Println(pow(6))  // 36
}

正常來說，uintPow是不可能被外部使用的，然而透過linkname指令我們直接無視了介面的公開和私有，有什麼就能用什麼了。

這當然是非常危險的，比如我們把uintPow的引數型別改成string：

package mymath

func uintPow(n string) string {
	return n + n
}

這時候編譯還是能正常編譯，但執行的時候就會出現各種bug，在我的機器上表現是卡死和段錯誤。為什麼呢？因為我們把uint強行傳遞了過去，但引數需要是string，型別對不上，自然會出現稀奇古怪的bug。這種在別的語言裡是嚴重的型別相關的記憶體錯誤。

另外如果我們直接刪了uintPow或者給他改個名，連結器會在編譯期間報錯：

$ go build

# linkname
main.main: relocation target linkname/pkg/mymath.uintPow not defined

而且我們匯出的是私有函式，通常沒人會認為自己寫的私有級別的幫助函式會被匯出到包外並被使用，因此在開發時大家都是保證公開介面的穩定性，私有的函式/變數是隨時可以被大規模修改甚至刪除的。

而linkname將這種在別的語言裡最基本的規矩給粉碎了。

而且事實上也是如此，從1.18開始幾乎每個版本都有因為編譯器或者標準庫內部的私有函式被修改/刪除從而導致某些第三方庫在新版本無法使用的問題，因為這些庫在內部悄悄用//go:linkname用了一些未公開的功能。最近一次發生在廣泛使用的知名json庫上類似的問題可以在這裡看到。

linkname的正面作用

既然這個指令如此危險，為什麼還一直存在呢？答案是有不得不用的理由，其中一個就在啟動go程式的時候。

我們來看下go的runtime裡是怎麼用linkname的：

// runtime/proc.go

//go:linkname main_main main.main
func main_main()

// runtime.main
// 所有go程式的入口
func main() {
    // 初始化runtime
    // 呼叫main.main
    fn := main_main // make an indirect call, as the linker doesn't know the address of the main package when laying down the runtime
    fn()
    // main退出後做清理工作
}

因為程式的入口在runtime裡（要初始化runtime，比如gc等），所以入口函式必須在runtime包裡。而我們又需要呼叫使用者定義在main包裡的main函式，但main包不能被import，因此只能靠linkname指令讓連結器繞過所有編譯器附加的限制來呼叫main函式。

這是目前在go自身的原始碼裡看到的唯一一處不得不使用“pull-only”模式的地方。

另外“handshake”模式也有存在的必要性，因為像runtime和reflect需要共享很多實現上的細節，因此reflect作為pull的一方，runtime作為push的一方，可以極大減少程式碼維護的複雜度。

除了上述這些情況，絕大數linkname的使用都可以算作abuse。

golang1.23對linkname指令的改動

鑑於上述情況，golang核心團隊決定限制linkname的使用。

第一個改動是標準庫裡新新增的包全部禁止使用linkname匯出其中的內容，目前是透過黑名單實現的，1.23中新新增的幾個包以及它們的internal依賴都在名單上，這樣可以防止已有的linkname問題繼續擴大。這對已有的程式碼也是完全無害的。

第二個變更時新增了新的ldflags: -checklinkname=1。1代表開啟對linkname的限制，0代表維持1.22的行為不變。目前預設是0，但官方決定在1.23釋出時預設值為1開啟限制。個人建議儘量不要關閉這個限制。這個限制眼下只針對標準庫，但按官方的說法效果好的話以後所有的程式碼不管標準庫還是第三方都會啟用限制。

最後也是最大的變動，禁止對標準庫的 “pull-only” linkname指令，但允許“handshake”模式。

雖然go從來不保證linkname的向後相容性，但這樣還是會大量較大的破壞，因此官方已經對常見的go第三方庫做了掃描，會把一些經常被人用linkname拉取的介面改成符合“handshake”模式的形式，這種改動只用加一行指令即可。而且該限制目前只針對標準庫，其他第三方庫暫時不受影響。

因為這個變更，下面的程式碼在1.23是無法編譯透過的：

package main

import _ "unsafe"

//go:linkname corostart runtime.corostart
func corostart()

func main() {
	corostart()
}

因為runtime.corostart並不符合handshake模式，所以對它的linkname被禁止了：

$ go version

go version devel go1.23-13d36a9b46 Wed May 15 21:51:49 2024 +0000 windows/amd64

$ go build -ldflags=-checklinkname=1

# linkname
link: main: invalid reference to runtime.corostart

linkname指令今後的發展

大趨勢肯定是以後只允許handshake模式。不過作為過渡目前還是允許push模式的，並且官方應該會在進入功能凍結後把之前說的掃描到的常用的內部函式新增上linkname指令。

這裡比較重要的是作為開發者的我們應該怎麼辦：

  1. 1.23釋出之後或者現在就開始利用-checklinkname=1排查程式碼，及時清除不必要的linkname指令。
  2. 如果linkname指令非用不可，建議馬上提issue或者熟悉go開發流程的立刻提pr補上handshake模式需要的指令，不過我不怎麼推薦這種做法，因為內部api尤其是runtime以外的庫的本來就不該隨便被匯出使用，沒有一個強力的能說服所有人的理由，這些issue和pr多半不會被接受。
  3. 向官方提案，嘗試把你要用的私有api變成公開介面，這一步難度也很高，私有api之所以當初不公開一定是有原因的，現在再想公開可能性也不高。
  4. 你的追求比較低，只要程式碼能跑就行，那可以在構建指令碼里加上-ldflags=-checklinkname=0關閉限制，這樣也許能歲月靜好幾個版本，直到某一天程式突然沒法編譯或者執行了一半被莫名其妙的panic打斷。

4是萬不得已時的保底方案，按優先度我推薦1 > 3 > 2的順序去適配go1.23。2和3不僅僅適用於go標準庫，常用的第三方庫也可以。透過這些適配工作說不定也有機會讓你成為go或者知名第三方庫的貢獻者。

從現在開始完全是來得及的，畢竟離1.23的第一個測試版釋出還有一個月左右，離正式版釋出還有兩個月。而且方案2的修改並不算作新功能，不受功能凍結的影響。

當然，大部分開發者應該不用擔心，比較linkname的使用是少數，一些主動使用linkname的庫比如quic-go也知道相容性問題，很小心地做了不同版本的適配，加上官方承諾的兜底這一對linkname指令的改動的影響應該比想象中小，但是是提高程式碼安全性的一大步。

說了這麼多，和本文的作者有啥關係呢

那肯定有關係，老丟人了。

其實之所以會在開發視窗的中後期有這樣大的變動，多半是因為我捅的簍子：前面也說過以前也有不少linkname引用的私有api變化導致的相容問題，但要麼影響範圍很小要麼作者及時適配使得這些問題沒引起太大的波瀾；但這次我的改動影響到了某個廣泛應用的基礎庫，這個庫用linkname指令引用了大量的內部api，更恐怖的是k8s也在用它，有人用master分支的go編譯了一下k8s問題才被發現，要是沒能及時發現的話會有一大堆軟體在1.23測試版釋出的時候出現相容問題。其實在我的提交之前這些內部api已經變得面目全非了，但因為函式名字和欄位型別沒怎麼變所以庫的程式碼還能接著跑，直到我的提交打破了這一切。

當然問題要說大其實也不大，像那樣大量使用linkname且沒怎麼適配版本的第三方庫本身就不多，其次把變更的內部函式的簽名還原之後問題很快就解決了，因此除了核心開發者和谷歌內部之外應該沒多少人發覺這個問題。這也充分體現了linkname的危險性：在不算缺乏經驗的我以及至少三位經驗豐富的稽核者的review下也沒預料到這樣功能簡單且使用面極窄的內部私有函式會被linkname指令拉取出來使用。

後續庫作者也說這些linkname引用的內部api其實很早之前就已經沒啥用處了，他會盡快刪除；實際上我跟蹤了一下庫程式碼發現這些被linkname匯出的內部api除了設定了一些簡單的flag值之外也確實沒啥用處，flag值有些也沒用上。

認識到這樣的危險性後go官方自然不會坐視不管，官方以前應該也有類似想做限制的想法，這次也算是找到了合情合理的理由了，所以這回行動也意外的快，不到一星期從黑名單禁止匯出新的庫到linkname指令的檢查都實現了。不出意外的話我們應該能在1.23看到一個更健壯的go以及它的標準庫。

這樣的問題怎麼避免？答案是不可能，因為linkname能無視幾乎一切限制私有函式/變數的辦法，而且你也很難知道有哪些程式碼透過linkname訪問了你寫的函式/變數，因此只要一天不做限制類似這次問題的事故就會越來越多，總不可能讓開發者每次改完程式碼都掃描一遍go語言編寫的常見的專案吧。而且go的相容性保證的是公開的介面和語法，內部實現的細節從來都不是也不應該是保證的物件。

我捅的這個簍子現在作為example被放在新提案裡呢，雖說本質上用日本話講叫“お互い様”（大家都有不對的地方），但作為廣泛應用的程式語言也確實有需求和義務要相容那些作為生態基石的應用廣泛的第三方庫，作為go的貢獻者之一卻忽視了這一點被結結實實地被上了一課也是應該的，算是經驗教訓了。。。

總結

最後總結就一句話：沒事別用//go:linkname。。。。。。

想跟進這一變更的進展的話，可以看這個issue：https://github.com/golang/go/issues/67401

相關文章