Go cfg.New 怎样为函数体建立控制流图

如果要分析 Go 函数的分支结构，直接遍历 AST 只能看到语法嵌套关系，还不够回答“某个基本块之后会走到哪里”。golang.org/x/tools/go/cfg 的 cfg.New 专门为单个函数体建立简单控制流图：每个 Block 保存一组按顺序执行的节点，Succs 保存后继块，Kind 和 Stmt 说明这个块由哪类控制语句产生。

官方资料：https://pkg.go.dev/golang.org/x/tools/go/cfg#New

最小做法是先从 AST 准备一个非 nil 的 *ast.BlockStmt，再调用 cfg.New(body, mayReturn)。如果只想理解普通分支，可以让 mayReturn 对所有调用返回 true；如果要识别 panic、os.Exit 或 log.Fatal 一类不返回调用，就在回调里返回 false，让 CFG 去掉后续不可行边。

cfg.New 接收的不是整个函数声明

cfg.New 的第一个参数是函数体 *ast.BlockStmt，不是 *ast.FuncDecl。因此通常先用 go/parser 解析源文件，再从函数声明的 Body 字段取出函数体。第二个参数 mayReturn 只用于判断表达式语句里的函数调用是否可能返回。

这个边界很重要：CFG 关注的是单个函数体内部的控制流，不负责跨函数推断，也不会自动替你判断每个外部函数的异常行为。回调应当是一个保守、可解释的策略。

先用最小示例建立 CFG

下面的示例从内存中的 Go 源码找到目标函数，然后把它的函数体交给 cfg.New。示例中的回调默认认为调用可以返回，适合先观察普通的 if/else 结构。

package main

import (
    "fmt"
    "go/ast"
    "go/parser"
    "go/token"

    "golang.org/x/tools/go/cfg"
)

func main() {
    const source = `package demo
func choose(ok bool) int {
    if ok {
        return 1
    }
    return 0
}`

    // 解析源代码，得到可以被 cfg.New 消费的 AST。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", source, 0)
    if err != nil {
        panic(fmt.Errorf("解析 Go 源码: %w", err))
    }

    var body *ast.BlockStmt
    // 这里只取名为 choose 的函数体，避免把多个函数混进同一张图。
    for _, decl := range file.Decls {
        fn, ok := decl.(*ast.FuncDecl)
        if ok && fn.Name.Name == "choose" {
            body = fn.Body
            break
        }
    }
    if body == nil {
        panic("没有找到目标函数体")
    }

    // 默认把调用视为可能返回，先保留普通控制流边。
    graph := cfg.New(body, func(*ast.CallExpr) bool { return true })
    fmt.Printf("入口块: %d，块数量: %d\n", graph.Blocks[0].Index, len(graph.Blocks))
    for _, block := range graph.Blocks {
        // Nodes 是块内按顺序执行的语句和表达式，Succs 是后继基本块。
        fmt.Printf("block=%d kind=%s nodes=%d succs=%d live=%t\n",
            block.Index, block.Kind, len(block.Nodes), len(block.Succs), block.Live)
    }
}

返回的 CFG.Blocks 中，Blocks[0] 是入口块，但其余块的顺序不应被当成执行顺序。真正的控制流关系要沿着每个块的 Succs 读取。

用 Nodes、Succs 和 Kind 读懂一张图

一个基本块可以理解为“始终连续执行的一组节点”。普通块通常只有一个后继，条件块最多有两个后继；条件块的最后一个 Nodes 元素是条件表达式，Succs[0] 表示条件为真时的后继，Succs[1] 表示条件为假时的后继。

Kind 用来说明块的来源，例如函数体是 KindBody，if 的两个分支分别是 KindIfThen 和 KindIfElse，if 之后的合流位置是 KindIfDone。Stmt 则保存产生该块的控制语句；它和 Kind 配合起来，适合在静态分析报告里解释“为什么出现这个块”。

返回语句也会出现在 CFG 中，函数末尾隐式返回同样可能被物化。块的 Return() 方法可用于读取末尾的返回语句；一个返回块通常没有后继。

mayReturn 决定调用之后是否还能继续

如果表达式语句里出现一个不会返回的调用，调用之后的语句就不应继续连到可达路径。cfg.New 会调用 mayReturn 来作这个判断。官方文档以 panic、os.Exit 和 log.Fatal 为例，说明它们可以被识别为不返回调用。

func callMayReturn(call *ast.CallExpr) bool {
    // 只识别简单包函数名；复杂选择器或间接调用应保持保守判断。
    selector, ok := call.Fun.(*ast.SelectorExpr)
    if !ok {
        return true
    }
    pkg, ok := selector.X.(*ast.Ident)
    if !ok {
        return true
    }

    // 这些调用之后没有正常返回路径，因此让 CFG 删除后续不可行边。
    if pkg.Name == "os" && selector.Sel.Name == "Exit" {
        return false
    }
    if pkg.Name == "log" && selector.Sel.Name == "Fatal" {
        return false
    }
    return true
}

// 使用方式：graph := cfg.New(functionBody, callMayReturn)

回调只在位于表达式语句下的 CallExpr 上被调用，因此不能把它当成完整的调用图分析器。它的职责是提供当前函数体 CFG 是否保留后续边所需的局部信息。

Format 和 Dot 适合不同的观察任务

需要快速看文本时，可以使用 graph.Format(fset)；它是面向调试的格式化输出。需要把节点关系交给图形工具时，可以使用 graph.Dot(fset) 获得 DOT 描述，再交给外部 DOT 工具渲染。官方文档明确提示，Dot 输出的细节属于调试辅助，可能发生变化，不应把它当成稳定交换格式。

// fset 必须与解析函数体时使用的 FileSet 对应，位置才能正确映射回源代码。
fmt.Println(graph.Format(fset))

// Dot 只负责生成图描述；渲染动作由调用方和外部工具决定。
dotText := graph.Dot(fset)
fmt.Println(dotText)

cfg 包的边界要提前记住

cfg 构建的是简单控制流图，不记录条件分支边上的具体条件，也不记录 && 和 || 的短路语义，更不会表达 panic 引起的异常控制流。如果分析需要这些信息，官方文档建议转向 golang.org/x/tools/go/ssa 等更高层表示。

一套实用的接入顺序

1. 先解析源文件并定位目标函数的 Body，确保传入 cfg.New 的值非 nil。
2. 先用全部返回 true 的 mayReturn 得到基础图，再按项目规则补充确定不返回的调用。
3. 把 Block.Kind 和 Block.Stmt 用于解释，把 Succs 用于实际遍历。
4. 调试阶段用 Format 快速查看，图形化展示再使用 Dot，不要依赖 DOT 的未承诺细节。
5. 如果需要精确条件、短路或异常控制流，及时评估更完整的分析表示，不要强行从简单 CFG 推断。

归纳起来，cfg.New 的核心不是把 AST 重新打印一遍，而是把函数体转成“块内节点 + 后继边 + 块来源”的关系数据。准备好函数体、明确 mayReturn 策略，再沿 Succs 遍历，就能把它稳定地接入静态检查、可视化和调试工具。

常见问题

cfg.New 能直接接收 *ast.FuncDecl 吗？

不能。需要传入函数声明的 Body，也就是非 nil 的 *ast.BlockStmt。

CFG.Blocks 的顺序就是执行顺序吗？

不是。入口是 Blocks[0]，其余块的顺序未定义，应沿着每个块的 Succs 读取控制流。

为什么图里会有不可达块？

当 mayReturn 判断某个调用不会返回时，调用之后的路径可能被标记为不可达；此外，复杂控制结构本来就可能产生不可达块。

什么时候应该换用 SSA？

当你需要条件边的更细语义、短路操作或异常控制流时，简单 CFG 的信息不足，应根据分析目标选择更完整的 SSA 表示。