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

距離golang 1.23發佈還有兩個月不到，按照慣例很快要進入1.23的功能凍結期了。在凍結期間不會再添加新功能，已經添加的功能不出大的意外一般也不會被移除。這正好可以讓我們提前嘗鮮這些即將到來的新特性。今天要說的就是1.23中對//go:linkname指令的變更。這個新特性可以說和我的一次失 ...

距離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.23發佈之後或者現在就開始利用-checklinkname=1排查代碼，及時清除不必要的linkname指令。
如果linkname指令非用不可，建議馬上提issue或者熟悉go開發流程的立刻提pr補上handshake模式需要的指令，不過我不怎麼推薦這種做法，因為內部api尤其是runtime以外的庫的本來就不該隨便被導出使用，沒有一個強力的能說服所有人的理由，這些issue和pr多半不會被接受。
向官方提案，嘗試把你要用的私有api變成公開介面，這一步難度也很高，私有api之所以當初不公開一定是有原因的，現在再想公開可能性也不高。
你的追求比較低，只要代碼能跑就行，那可以在構建腳本裡加上-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