Go 1.20 相比 Go 1.19 有哪些值得注意的改动？

本系列旨在梳理 Go 的 release notes 与发展史，来更加深入地理解 Go 语言设计的思路。

https://go.dev/doc/go1.20

Go 1.20 值得关注的改动：

1. 语言 Slice to Array 转换： Go 1.20 扩展了 Go 1.17 的功能，允许直接将 slice 转换为固定大小的数组，例如使用 [4]byte(x) 替代 *(*[4]byte)(x)。
2. unsafe 包更新： 新增 SliceData 、 String 和 StringData 函数，与 Go 1.17 的 Slice 函数一起，提供了不依赖具体内存布局来构造和解构 slice 与 string 值的能力。
3. 规范更新 结构体与数组比较： 语言规范明确了结构体按字段声明顺序、数组按索引顺序逐个比较，并在遇到第一个不匹配时即停止，这澄清了潜在的歧义，但与实际实现行为一致。
4. 泛型 comparable 约束放宽： 即使类型参数不是严格可比较的（运行时比较可能 panic），它们现在也可以满足 comparable 约束，允许将接口类型等用作泛型映射的键。
5. Runtime 垃圾回收器（Garbage Collector）优化： 通过重组内部数据结构，减少了内存开销并提高了 CPU 效率（整体 CPU 性能提升高达 2%），同时改善了 goroutine 辅助（goroutine assists）在某些情况下的行为稳定性。
6. 错误处理 多错误包装（Wrapping multiple errors）： 扩展了错误包装功能，允许一个错误通过实现返回 []error 的 Unwrap 方法来包装多个错误；errors.Is 、 errors.As 、 fmt.Errorf 的 %w 以及新增的 errors.Join 函数均已支持此特性。
7. net/http 新增 ResponseController： 引入 net/http.ResponseController 类型，提供了一种比可选接口更清晰、更易于发现的方式来访问每个请求的扩展功能，例如设置读写截止时间。
8. httputil.ReverseProxy 新增 Rewrite 钩子： 新的 Rewrite 钩子取代了原有的 Director 钩子，提供了对入站和出站请求更全面的控制，并引入了 ProxyRequest.SetURL 和 ProxyRequest.SetXForwarded 等辅助方法，同时修复了潜在的安全问题。

下面是一些值得展开的讨论：

Go 1.20 简化了从 Slice 到 Array 的转换语法

Go 1.17 版本引入了一个特性，允许将 slice 转换为指向数组的指针。例如，如果有一个 slice x，你可以通过 *(*[4]byte)(x) 的方式将其转换为一个指向包含 4 个字节的数组的指针。这种转换有其局限性，它得到的是一个指针。

Go 1.20 在此基础上更进一步，允许直接将 slice 转换为一个数组值（而不是数组指针）。现在，对于一个 slice x，你可以直接使用 [4]byte(x) 来获得一个包含 4 个字节的数组。

这种转换有一个前提条件：slice 的长度必须大于或等于目标数组的长度。如果 slice x 的长度 len(x) 小于目标数组的长度（在这个例子中是 4），那么在运行时会发生 panic。转换的结果数组将包含 slice x 的前 N 个元素，其中 N 是目标数组的长度。

让我们看一个简单的例子：

package main

import "fmt"

func main() {
    s := []byte{'g', 'o', 'l', 'a', 'n', 'g'}

    // Go 1.20: Direct conversion from slice to array
    var a4 [4]byte = [4]byte(s) // a4 will be {'g', 'o', 'l', 'a'}
    fmt.Printf("Array a4: %v\n", a4)
    fmt.Printf("Array a4 as string: %s\n", string(a4[:]))

    var a6 [6]byte = [6]byte(s) // a6 will be {'g', 'o', 'l', 'a', 'n', 'g'}
    fmt.Printf("Array a6: %v\n", a6)
    fmt.Printf("Array a6 as string: %s\n", string(a6[:]))

    // Contrast with Go 1.17 style (slice to array pointer)
    ap4 := (*[4]byte)(s) // ap4 is a pointer to the first 4 bytes of s's underlying array
    fmt.Printf("Array pointer ap4: %v\n", *ap4)
    // Modify the array through the pointer - this affects the original slice's underlying data!
    ap4[0] = 'G'
    fmt.Printf("Original slice s after modifying via pointer: %s\n", string(s)) // Output: Golang

    // Note: Direct conversion creates a *copy* of the data
    a4_copy := [4]byte(s)
    a4_copy[0] = 'F' // Modify the copy
    fmt.Printf("Original slice s after modifying direct conversion copy: %s\n", string(s)) // Output: Golang (unaffected)
    fmt.Printf("Copied array a4_copy: %s\n", string(a4_copy[:]))                     // Output: Fola

    // Example that would panic at runtime
    shortSlice := []byte{'h', 'i'}
    var a3 [3]byte = [3]byte(shortSlice) // This line would cause a panic: runtime error
    _ = a3
    _ = shortSlice // Avoid unused variable error
}

Array a4: [103 111 108 97]
Array a4 as string: gola
Array a6: [103 111 108 97 110 103]
Array a6 as string: golang
Array pointer ap4: [103 111 108 97]
Original slice s after modifying via pointer: Golang
Original slice s after modifying direct conversion copy: Golang
Copied array a4_copy: Fola
panic: runtime error: cannot convert slice with length 2 to array or pointer to array with length 3

这个改动使得代码更简洁、易读，特别是在需要数组值而不是指针的场景下。需要注意的是，直接转换为数组会复制数据，而转换为数组指针则不会，它只是创建一个指向 slice 底层数组对应部分的指针。

unsafe 包新增 SliceData, String, StringData，完善了 Slice 和 String 的底层操作能力

Go 语言的 unsafe 包提供了一些低层次的操作，允许开发者绕过 Go 的类型安全和内存安全检查。虽然应谨慎使用，但在某些高性能场景或与 C 语言库交互时非常有用。

Go 1.20 在 unsafe 包中引入了三个新的函数：SliceData、String 和 StringData。这些函数，连同 Go 1.17 引入的 unsafe.Slice，提供了一套完整的、不依赖于 slice 和 string 内部具体表示（这些表示在不同 Go 版本中可能变化）的构造和解构方法。

这意味着你可以编写更健壮的底层代码，即使未来 Go 改变了 slice 或 string 的内部结构（例如 SliceHeader 或 StringHeader 的字段），只要这些函数的语义不变，你的代码依然能工作。

这四个核心函数的功能如下：

1. SliceData(slice []T) *T ：返回指向 slice 底层数组第一个元素的指针。如果 slice 为 nil，则返回 nil。它等价于 &slice[0]，但即使 slice 为空（len(slice) == 0），只要容量不为零（cap(slice) > 0），它也能安全地返回底层数组的指针（而 &slice[0] 会 panic）。
2. StringData(str string) *byte ：返回指向 string 底层字节数组第一个元素的指针。如果 string 为空，则返回 nil。
3. Slice[T any](ptr *T, lenOrCap int) []T (Go 1.17 引入，Go 1.20 仍重要)：根据给定的指向类型 T 的指针 ptr 和指定的容量/长度 lenOrCap，创建一个新的 slice。这个 slice 的长度和容量都等于 lenOrCap，并且它的底层数组从 ptr 指向的内存开始。注意：早期版本中此函数可能接受两个参数 len 和 cap，但在 Go 1.17 稳定版及后续版本中，通常简化为接受一个 lenOrCap 参数，表示长度和容量相同。使用时请查阅对应 Go 版本的文档确认具体签名。 假设这里我们使用 Go 1.17 引入的 Slice(ptr *ArbitraryType, cap IntegerType) []ArbitraryType 形式，它创建一个长度和容量都为 cap 的切片。或者更通用的 Slice(ptr *T, len int) []T，如果 Go 版本支持（创建 len==cap 的切片）。为了演示，我们假设存在一个函数能创建指定 len 和 cap 的 slice。更新：根据 Go 1.17 及后续文档，unsafe.Slice(ptr *T, len IntegerType) []T 是标准形式，创建的 slice 长度和容量都为 len。
4. String(ptr *byte, len int) string：根据给定的指向字节的指针 ptr 和长度 len，创建一个新的 string。

使用 unsafe 包需要开发者深刻理解 Go 的内存模型和潜在风险。这些新函数提供了一个更稳定、面向未来的接口来执行这些底层操作，减少了代码因 Go 内部实现细节变化而失效的可能性。

语言规范明确了结构体和数组的比较规则：逐元素比较，遇首个差异即停止

Go 语言规范定义了哪些类型是可比较的（comparable）。结构体（struct）类型是可比较的，如果它的所有字段类型都是可比较的。数组（array）类型也是可比较的，如果它的元素类型是可比较的。

在 Go 1.20 之前，规范中关于结构体和数组如何进行比较的描述存在一定的模糊性。一种可能的解读是，比较两个结构体或数组时，需要比较完它们所有的字段或元素，即使在中间已经发现了不匹配。

Go 1.20 的规范明确了实际的比较行为，这也是 Go 编译器一直以来的实现方式：

1. 结构体比较 ：比较结构体时，会按照字段在 struct 类型定义中出现的顺序，逐个比较字段的值。一旦遇到第一个不匹配的字段，比较立即停止，并得出两者不相等的结果。如果所有字段都相等，则结构体相等。
2. 数组比较 ：比较数组时，会按照索引从 0 开始递增的顺序，逐个比较元素的值。一旦遇到第一个不匹配的元素，比较立即停止，并得出两者不相等的结果。如果所有元素都相等，则数组相等。

这个规范的明确化主要影响的是包含不可比较类型（如接口类型，其动态值可能不可比较）时的 panic 行为。考虑以下情况：

package main

import "fmt"

type Data struct {
    ID   int
    Meta interface{} // interface{} or any
}

func main() {
    // Slices are not comparable
    slice1 := []int{1}
    slice2 := []int{1}

    d1 := Data{ID: 1, Meta: slice1}
    d2 := Data{ID: 2, Meta: slice2} // Different ID
    d3 := Data{ID: 1, Meta: slice2} // Same ID, different slice instance (but content might be same)
    d4 := Data{ID: 1, Meta: slice1} // Same ID, same slice instance

    // Comparison stops at the first differing field (ID)
    // The Meta field (interface{} holding a slice) is never compared.
    fmt.Printf("d1 == d2: %t\n", d1 == d2) // Output: false. Comparison stops after comparing ID (1 != 2). No panic.

    // Comparison proceeds to Meta field because IDs are equal (1 == 1).
    // Comparing interfaces containing slices will cause a panic.
    // fmt.Printf("d1 == d3: %t\n", d1 == d3) // This line would panic: runtime error: comparing uncomparable type []int

    // Comparison proceeds to Meta field.
    // Even though it's the *same* slice instance, the comparison itself panics.
    // fmt.Printf("d1 == d4: %t\n", d1 == d4) // This line would also panic: runtime error: comparing uncomparable type []int

    // Array comparison example
    type Info struct {
        Count int
    }
    // Arrays of comparable types are comparable
    a1 := [2]Info{{Count: 1}, {Count: 2}}
    a2 := [2]Info{{Count: 1}, {Count: 3}} // Differs at index 1
    a3 := [2]Info{{Count: 0}, {Count: 2}} // Differs at index 0

    fmt.Printf("a1 == a2: %t\n", a1 == a2) // Output: false. Stops after comparing a1[1] and a2[1].
    fmt.Printf("a1 == a3: %t\n", a1 == a3) // Output: false. Stops after comparing a1[0] and a3[0].

    _, _, _, _ = d1, d2, d3, d4
}

虽然这个规范的明确化没有改变现有程序的行为（因为实现早已如此），但它消除了规范层面的歧义，使得开发者能更准确地理解比较操作何时会因遇到不可比较类型而 panic。如果比较在遇到不可比较的字段或元素之前就因其他部分不匹配而停止，则不会发生 panic。

Go 1.20 放宽 comparable 约束，允许接口等类型作为类型参数，即使运行时比较可能 panic

Go 1.18 引入泛型时，定义了一个 comparable 约束。这个约束用于限定类型参数必须是可比较的类型。这对于需要将类型参数用作 map 的键或在代码中进行 == 或 != 比较的泛型函数和类型非常重要。

最初，comparable 约束要求类型参数本身必须是严格可比较的。这意味着像接口类型（interface types）这样的类型不能满足 comparable 约束。为什么？因为虽然接口值本身可以用 == 比较（例如，比较它们是否都为 nil，或者是否持有相同的动态值），但如果两个接口持有不同的动态类型，或者持有的动态类型本身是不可比较的（如 slice、map、function），那么在运行时比较它们会引发 panic。由于这种潜在的运行时 panic，接口类型在 Go 1.18/1.19 中不被视为满足 comparable 约束。

这带来了一个问题：开发者无法轻松地创建以接口类型作为键的泛型 map 或 set。

Go 1.20 放宽了 comparable 约束的要求。现在，一个类型 T 满足 comparable 约束，只要类型 T 的值可以用 == 或 != 进行比较即可。这包括了接口类型，以及包含接口类型的复合类型（如结构体、数组）。

关键变化在于，满足 comparable 约束不再保证比较操作永远不会 panic。它仅仅保证了 == 和 != 运算符 可以 应用于该类型的值。比较是否真的会 panic 取决于运行时的具体值。

这个改动使得以下代码在 Go 1.20 中成为可能：

package main

import "fmt"

// Generic map using comparable constraint for the key
type GenericMap[K comparable, V any] struct {
    m map[K]V
}

func NewGenericMap[K comparable, V any]() *GenericMap[K, V] {
    return &GenericMap[K, V]{m: make(map[K]V)}
}

func (gm *GenericMap[K, V]) Put(key K, value V) {
    gm.m[key] = value
}

func (gm *GenericMap[K, V]) Get(key K) (V, bool) {
    v, ok := gm.m[key]
    return v, ok
}

func main() {
    // Instantiate GenericMap with K=int (strictly comparable) - Works always
    intMap := NewGenericMap[int, string]()
    intMap.Put(1, "one")
    fmt.Println(intMap.Get(1)) // Output: one true

    // Instantiate GenericMap with K=any (interface{}) - Works in Go 1.20+
    // In Go 1.18/1.19, this would fail compilation because 'any'/'interface{}'
    // did not satisfy the 'comparable' constraint.
    anyMap := NewGenericMap[any, string]()

    // Use comparable types as keys - Works fine
    anyMap.Put(10, "integer")
    anyMap.Put("hello", "string")
    type MyStruct struct{ V int }
    anyMap.Put(MyStruct{V: 5}, "struct")

    fmt.Println(anyMap.Get(10))      // Output: integer true
    fmt.Println(anyMap.Get("hello")) // Output: string true
    fmt.Println(anyMap.Get(MyStruct{V: 5})) // Output: struct true

    // Attempt to use an uncomparable type (slice) as a key.
    // The Put operation itself will cause a panic during the map key comparison.
    keySlice := []int{1, 2}
    fmt.Println("Attempting to put slice key...")
    // The following line will panic in Go 1.20+
    // panic: runtime error: hash of unhashable type []int
    // or panic: runtime error: comparing uncomparable type []int
    // (depending on map implementation details)
    // anyMap.Put(keySlice, "slice")
    _ = keySlice // Avoid unused variable

    // Using interface values holding different uncomparable types also panics
    var i1 any = []int{1}
    var i2 any = map[string]int{}
    // The comparison i1 == i2 during map access would panic.
    // anyMap.Put(i1, "interface holding slice")
    // anyMap.Put(i2, "interface holding map")
    _ = i1
    _ = i2
}

这个改变提高了泛型的灵活性，允许开发者编写适用于更广泛类型的泛型代码，特别是涉及 map 键时。但开发者需要意识到，当使用非严格可比较的类型（如 any 或包含接口的结构体）作为满足 comparable 约束的类型参数时，代码中涉及比较的操作（如 map 查找、插入、删除，或显式的 ==/!=）可能会在运行时 panic。

Go 1.20 引入了对包装多个错误的原生支持

在 Go 1.13 中，通过 errors.Unwrap、errors.Is、errors.As 以及 fmt.Errorf 的 %w 动词，引入了标准的错误包装（error wrapping）机制。这允许一个错误 "包含" 另一个错误，形成错误链，方便追踪错误的根本原因。然而，该机制仅支持一个错误包装 单个 其他错误。

在实际开发中，有时一个操作可能因为多个独立的原因而失败，或者一个聚合操作中的多个子操作都失败了。例如，尝试将数据写入数据库和文件系统都失败了。在这种情况下，将多个错误合并成一个错误会很有用。

Go 1.20 扩展了错误处理机制，原生支持一个错误包装 多个 其他错误。主要通过以下几种方式实现：

1. Unwrap() []error 方法

一个错误类型可以通过实现 Unwrap() []error 方法来表明它包装了多个错误。如果一个类型同时定义了 Unwrap() error 和 Unwrap() []error，那么 errors.Is 和 errors.As 将优先使用 Unwrap() []error。

2. fmt.Errorf 的多个 %w

fmt.Errorf 函数现在支持在格式字符串中多次使用 %w 动词。调用 fmt.Errorf("...%w...%w...", err1, err2) 将返回一个包装了 err1 和 err2 的新错误。这个返回的错误实现了 Unwrap() []error 方法。

3. errors.Join(...error) error 函数

新增的 errors.Join 函数接受一个或多个 error 参数，并返回一个包装了所有非 nil 输入错误的新错误。如果所有输入错误都是 nil，errors.Join 返回 nil。返回的错误也实现了 Unwrap() []error 方法。这是合并多个错误的推荐方式。

4. errors.Is 和 errors.As 更新

这两个函数现在能够递归地检查通过 Unwrap() []error 暴露出来的所有错误。errors.Is(multiErr, target) 会检查 multiErr 本身以及它（递归地）解包出来的任何一个错误是否等于 target。类似地，errors.As(multiErr, &targetVar) 会检查 multiErr 或其解包链中的任何错误是否可以赋值给 targetVar。

下面是一个结合生产场景的例子，演示如何使用这些新特性：

package main

import (
    "errors"
    "fmt"
    "os"
    "time"
    "syscall"
)

// 定义一些具体的错误类型
var ErrDatabaseTimeout = errors.New("database timeout")
var ErrCacheFailed = errors.New("cache operation failed")
var ErrFileSystemReadOnly = errors.New("file system is read-only")

type NetworkError struct {
    Op  string
    Err error // Underlying network error
}

func (e *NetworkError) Error() string {
    return fmt.Sprintf("network error during %s: %v", e.Op, e.Err)
}

func (e *NetworkError) Unwrap() error {
    return e.Err // Implements single error unwrapping
}

// 模拟保存数据的操作，可能同时涉及多个系统
func saveData(data string) error {
    var errs []error // 用于收集所有发生的错误

    // 模拟数据库操作
    if time.Now().Second()%2 == 0 { // 假设偶数秒时数据库超时
        errs = append(errs, ErrDatabaseTimeout)
    }

    // 模拟缓存操作
    if len(data) < 5 { // 假设数据太短时缓存失败
        // 包装一个更具体的网络错误
        netErr := &NetworkError{Op: "set cache", Err: errors.New("connection refused")}
        errs = append(errs, fmt.Errorf("%w: %w", ErrCacheFailed, netErr)) // 使用 %w 包装原始错误和网络错误
    }

    // 模拟文件系统操作
    if _, err := os.OpenFile("dummy.txt", os.O_WRONLY, 0666); err != nil {
        // 检查是否是只读文件系统错误（仅为示例，实际检查更复杂）
        if os.IsPermission(err) { // os.IsPermission is a common check
            errs = append(errs, ErrFileSystemReadOnly)
        } else {
            errs = append(errs, fmt.Errorf("failed to open file: %w", err)) // 包装底层 os 错误
        }
    }

    // 使用 errors.Join 将所有收集到的错误合并成一个
    // 如果 errs 为空 (即没有错误发生), errors.Join 会返回 nil
    return errors.Join(errs...)
}

func main() {
    err := saveData("dat") // "dat" is short, likely triggers cache error
    if err != nil {
        fmt.Printf("Failed to save data:\n%v\n\n", err) // errors.Join 产生的错误会自动格式化，显示所有子错误

        // 现在我们可以检查这个聚合错误中是否包含特定的错误类型或值

        // 检查是否包含数据库超时错误
        if errors.Is(err, ErrDatabaseTimeout) {
            // errors.Is 会遍历 err 解包出来的所有错误（通过 errors.Join 的 Unwrap() []error）
            // 如果找到 ErrDatabaseTimeout，则返回 true
            fmt.Println("Detected: Database Timeout")
        }

        // 检查是否包含文件系统只读错误
        if errors.Is(err, ErrFileSystemReadOnly) {
            // 同样，errors.Is 会检查所有被 Join 的错误
            fmt.Println("Detected: File System Read-Only")
        }

        // 提取具体的 NetworkError 类型
        var netErr *NetworkError
        if errors.As(err, &netErr) {
            // errors.As 会遍历 err 解包出来的所有错误
            // 如果找到一个类型为 *NetworkError 的错误，就将其赋值给 netErr 并返回 true
            fmt.Printf("Detected Network Error: Op=%s, Underlying=%v\n", netErr.Op, netErr.Err)
            // 我们甚至可以进一步检查 NetworkError 内部包装的错误
            if errors.Is(netErr, syscall.ECONNREFUSED) { // 假设底层是 connection refused
                fmt.Println("   Network error specifically was: connection refused")
            }
        }

        // 也可以检查原始的 Cache 失败错误
        if errors.Is(err, ErrCacheFailed) {
            // 这会找到 fmt.Errorf("%w: %w", ErrCacheFailed, netErr) 中包装的 ErrCacheFailed
            fmt.Println("Detected: Cache Failed (may have underlying network error)")
        }
    } else {
        fmt.Println("Data saved successfully!")
    }

    // 演示 fmt.Errorf 与多个 %w
    err1 := errors.New("error one")
    err2 := errors.New("error two")
    multiWError := fmt.Errorf("operation failed: %w; also %w", err1, err2)
    fmt.Printf("\nError from multiple %%w:\n%v\n", multiWError)
    if errors.Is(multiWError, err1) && errors.Is(multiWError, err2) {
        // multiWError 实现 Unwrap() []error，包含 err1 和 err2
        fmt.Println("Multiple %w error contains both err1 and err2.")
    }
}

Failed to save data:
database timeout
cache operation failed: network error during set cache: connection refused
failed to open file: open dummy.txt: no such file or directory

Detected: Database Timeout
Detected Network Error: Op=set cache, Underlying=connection refused
Detected: Cache Failed (may have underlying network error)

Error from multiple %w:
operation failed: error one; also error two
Multiple %w error contains both err1 and err2.

(注意: 上述代码中的 syscall.ECONNREFUSED 部分可能需要根据你的操作系统进行调整或替换为更通用的网络错误检查方式，这里仅作 errors.Is 嵌套使用的演示)

这个多错误包装功能使得错误处理更加灵活和富有表现力，特别是在需要聚合来自不同子系统或并发操作的错误时，能够提供更完整的失败上下文，同时保持了与现有 errors.Is 和 errors.As 的兼容性。

net/http 引入 ResponseController 以提供更清晰、可发现的扩展请求处理控制

在 Go 的 net/http 包中，http.ResponseWriter 接口是 HTTP handler 处理请求并构建响应的核心。然而，随着 HTTP 协议和服务器功能的发展，有时需要对请求处理过程进行更精细的控制，而这些控制功能超出了 ResponseWriter 接口的基本定义（如 Write, WriteHeader, Header）。

过去，net/http 包通常通过定义 可选接口（optional interfaces）来添加这些扩展功能。例如，如果 handler 需要主动将缓冲的数据刷新到客户端，它可以检查其接收到的 ResponseWriter 是否也实现了 http.Flusher 接口，如果实现了，就调用其 Flush() 方法。其他例子包括 http.Hijacker（用于接管 TCP 连接）和 http.Pusher（用于 HTTP/2 server push）。

这种依赖可选接口的模式有几个缺点：

1. 不易发现 ：开发者需要知道这些可选接口的存在，并在文档或代码中查找它们。
2. 使用笨拙 ：每次使用都需要进行类型断言（if hj, ok := w.(http.Hijacker); ok { ... }），使得代码略显冗长。
3. 扩展性问题 ：随着新功能的增加，可选接口的数量可能会不断增多。

为了解决这些问题，Go 1.20 引入了 net/http.ResponseController 类型。这是一个新的结构体，旨在提供一个统一的、更清晰、更易于发现的方式来访问附加的、针对每个请求（per-request）的响应控制功能。

你可以通过 http.NewResponseController(w ResponseWriter) 来获取与给定 ResponseWriter 关联的 ResponseController 实例。然后，你可以调用 ResponseController 上的方法来执行扩展操作。

Go 1.20 同时通过 ResponseController 引入了两个新的控制功能：

1. SetReadDeadline(time time.Time) error ：设置此请求的底层连接的读取截止时间。这对于需要长时间运行的 handler（例如，流式上传或 WebSocket）想要覆盖服务器的全局读取超时（Server.ReadTimeout）非常有用。
2. SetWriteDeadline(time time.Time) error ：设置此请求的底层连接的写入截止时间。这对于 handler 需要发送大量数据或进行流式响应，并希望覆盖服务器的全局写入超时（Server.WriteTimeout）很有用。将截止时间设置为空的 time.Time{} (即零值) 表示禁用超时。

以下是如何使用 ResponseController 设置写入截止时间的示例，改编自官方文档：

package main

import (
    "fmt"
    "io"
    "net/http"
    "time"
)

// 模拟一个需要发送大量数据的 handler
func bigDataHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Println("Handling request for big data...")

    // 获取与 ResponseWriter 关联的 ResponseController
    rc := http.NewResponseController(w)

    // 假设我们要发送大量数据，可能超过服务器的默认 WriteTimeout
    // 我们可以为这个特定的请求禁用写入超时
    // 将截止时间设置为空的 time.Time (零值) 即可禁用
    err := rc.SetWriteDeadline(time.Time{})
    if err != nil {
        // 如果设置截止时间失败 (例如，底层连接不支持或已关闭)
        // 记录错误并可能返回一个内部服务器错误
        fmt.Printf("Error setting write deadline: %v\n", err)
        http.Error(w, "Failed to set write deadline", http.StatusInternalServerError)
        return
    }
    fmt.Println("Write deadline disabled for this request.")

    // 设置响应头
    w.Header().Set("Content-Type", "text/plain")
    w.WriteHeader(http.StatusOK)

    // 模拟发送大量数据
    for i := 0; i < 10; i++ {
        _, err := io.WriteString(w, fmt.Sprintf("This is line %d of a large response.\n", i+1))
        if err != nil {
            // 如果写入过程中发生错误 (例如，连接被客户端关闭)
            fmt.Printf("Error writing response data: %v\n", err)
            // 此时可能无法再向客户端发送错误，但应记录日志
            return
        }
        // 模拟耗时操作
        time.Sleep(200 * time.Millisecond)
    }

    fmt.Println("Finished sending big data.")
}

// 模拟一个需要从客户端读取可能很慢的数据流的 handler
func slowUploadHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Println("Handling slow upload...")

    // 获取 ResponseController (虽然这里主要控制读取，但通过 ResponseWriter 获取)
    rc := http.NewResponseController(w)

    // 假设服务器有 ReadTimeout，但我们预期这个上传可能很慢
    // 我们可以延长读取截止时间，比如设置为 1 分钟后
    deadline := time.Now().Add(1 * time.Minute)
    err := rc.SetReadDeadline(deadline)
    if err != nil {
        fmt.Printf("Error setting read deadline: %v\n", err)
        http.Error(w, "Failed to set read deadline", http.StatusInternalServerError)
        return
    }
    fmt.Printf("Read deadline set to %v for this request.\n", deadline)

    // 现在可以安全地从 r.Body 读取，直到截止时间
    bodyBytes, err := io.ReadAll(r.Body)
    if err != nil {
        // 检查是否是超时错误
        if netErr, ok := err.(interface{ Timeout() bool }); ok && netErr.Timeout() {
            fmt.Println("Read timed out as expected.")
            http.Error(w, "Read timed out", http.StatusRequestTimeout)
        } else {
            fmt.Printf("Error reading request body: %v\n", err)
            http.Error(w, "Error reading body", http.StatusInternalServerError)
        }
        return
    }

    fmt.Printf("Received %d bytes.\n", len(bodyBytes))
    fmt.Fprintln(w, "Upload received successfully!")
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/bigdata", bigDataHandler)
    mux.HandleFunc("/upload", slowUploadHandler)

    // 创建一个带有默认超时的服务器 (例如 5 秒)
    server := &http.Server{
        Addr:         ":8080",
        Handler:      mux,
        ReadTimeout:  5 * time.Second, // 默认读取超时
        WriteTimeout: 5 * time.Second, // 默认写入超时
    }

    fmt.Println("Server starting on :8080...")
    fmt.Println("Try visiting http://localhost:8080/bigdata")
    fmt.Println("Try sending a POST request with a slow body to http://localhost:8080/upload")
    fmt.Println("Example using curl for slow upload:")
    fmt.Println(`  curl -X POST --data-binary @- http://localhost:8080/upload <<EOF`)
    fmt.Println(`  This is some data that will be sent slowly.`)
    fmt.Println(`  <You might need to wait or pipe slow input here>`)
    fmt.Println(`  EOF`)

    err := server.ListenAndServe()
    if err != nil && err != http.ErrServerClosed {
        fmt.Printf("Server error: %v\n", err)
    }
}

// 注意: SetReadDeadline/SetWriteDeadline 通常作用于底层的 net.Conn。
// 对于 HTTP/2，行为可能更复杂，因为一个连接上有多路复用的流。
// 对于 HTTP/3 (QUIC)，这些可能不适用或有不同的机制。
// 查阅具体 Go 版本的 net/http 文档了解详细语义。

ResponseController 提供了一个更健壮、面向未来的机制来添加和使用 net/http 的扩展功能。预期未来更多类似 SetReadDeadline 的细粒度控制将通过 ResponseController 的方法来提供，而不是增加新的可选接口。

httputil.ReverseProxy 获得新的 Rewrite 钩子，取代 Director，提供更安全、灵活的请求转发定制

net/http/httputil.ReverseProxy 是 Go 标准库中用于构建反向代理服务器的核心组件。它接收客户端（入站）请求，并将其转发给一个或多个后端（出站）服务器。开发者可以通过设置 ReverseProxy 结构体的字段来自定义其行为。

在 Go 1.20 之前，最主要的定制点是 Director 字段。Director 是一个函数 func(*http.Request)，它在请求被转发 之前 被调用。Director 的职责是修改传入的 *http.Request 对象，使其指向目标后端服务器，并进行必要的头部调整等。然而，Director 的设计存在一些局限和潜在的安全问题：

1. 只操作出站请求 ：Director 函数只接收即将发送到后端的请求对象。这个对象通常是入站请求的一个浅拷贝（shallow copy）。Director 无法直接访问 原始 的入站请求对象。
2. 安全风险 (Issue #50580) ：ReverseProxy 在调用 Director 之后，但在实际发送请求 之前，会执行一些默认的头部清理和设置操作（例如，移除 hop-by-hop headers，设置 X-Forwarded-* 头等）。恶意的客户端可以通过构造特殊的入站请求头，使得 Director 添加的某些头信息（如自定义的认证头）在后续的清理步骤中被意外移除或覆盖，从而绕过检查。
3. NewSingleHostReverseProxy 的局限 ：这是一个常用的辅助函数，用于创建一个将所有请求转发到单个后端主机的 ReverseProxy。但它设置 Director 的方式有时不能正确处理 Host 头部，并且不方便进行除目标 URL 之外的更多自定义。

Go 1.20 引入了一个新的钩子函数 Rewrite，旨在取代 Director，并解决上述问题。

Rewrite 钩子

• 类型 : func(*httputil.ProxyRequest)

• ProxyRequest 结构体 : 这是一个新引入的结构体，包含两个字段：

  • In *http.Request: 指向原始的、未经修改的入站请求。
  • Out *http.Request: 指向即将发送到后端的请求（初始时是 In 的浅拷贝）。Rewrite 函数应该修改 Out。

• 优势 :

  • 访问原始请求 : Rewrite 可以同时访问入站和出站请求，使得决策可以基于原始请求的真实信息。
  • 更安全的时机 : Rewrite 在 ReverseProxy 的默认头部处理逻辑 之后 执行（或者说，Rewrite 完全取代了 Director 和部分默认逻辑）。这意味着 Rewrite 设置的头部（如 Out.Header.Set(...)）不会被代理的后续步骤意外更改。
  • 更强大的控制 : 结合 ProxyRequest 提供的辅助方法，可以更方便、正确地完成常见任务。

ProxyRequest 的辅助方法

Go 1.20 同时为 ProxyRequest 添加了几个实用的方法：

1. SetURL(target *url.URL) :

   • 将出站请求 r.Out.URL 设置为 target。
   • 重要 : 它还会正确地设置出站请求的 Host 字段 (r.Out.Host = target.Host) 和 Host 头部 (r.Out.Header.Set("Host", target.Host))。
   • 这有效地取代了 NewSingleHostReverseProxy 的核心功能，并且做得更正确。

2. SetXForwarded() :

   • 这是一个便捷方法，用于在出站请求 r.Out 上设置标准的 X-Forwarded-For, X-Forwarded-Host, 和 X-Forwarded-Proto 头部。
   • 重要 : 当你提供 Rewrite 钩子时，ReverseProxy 默认不再自动添加 这些 X-Forwarded-* 头部。如果你的后端服务依赖这些头部，你 必须 在 Rewrite 函数中显式调用 r.SetXForwarded()。

示例用法

以下是如何使用 Rewrite 钩子来创建一个将请求转发到指定后端，并设置 X-Forwarded-* 头部以及一个自定义头部的 ReverseProxy：

package main

import (
    "log"
    "net/http"
    "net/http/httputil"
    "net/url"
    "os"
)

func main() {
    // 后端服务器的 URL
    backendURL, err := url.Parse("http://localhost:8081") // 假设后端服务运行在 8081 端口
    if err != nil {
        log.Fatal("Invalid backend URL")
    }

    // 创建一个简单的后端服务器用于测试
    go startBackendServer()

    // 创建 ReverseProxy 并设置 Rewrite 钩子
    proxy := &httputil.ReverseProxy{
        Rewrite: func(r *httputil.ProxyRequest) {
            // 1. 将出站请求的目标设置为后端 URL
            // SetURL 会同时设置 r.Out.URL 和 r.Out.Host，并设置 Host header
            r.SetURL(backendURL)

            // 2. (可选) 如果需要 X-Forwarded-* 头部，必须显式调用 SetXForwarded
            // 如果不调用，这些头部将不会被添加到出站请求中
            r.SetXForwarded()

            // 3. (可选) 添加或修改其他出站请求头部
            r.Out.Header.Set("X-My-Proxy-Header", "Hello from proxy")

            // 4. (可选) 可以基于入站请求 r.In 进行决策
            log.Printf("Rewriting request: In=%s %s, Out=%s %s",
                r.In.Method, r.In.URL.Path,
                r.Out.Method, r.Out.URL.String()) // 注意 r.Out.URL 已经被 SetURL 修改

            // 注意：不需要再手动设置 r.Out.Host 或 Host header，SetURL 已处理
            // 注意：默认情况下，ReverseProxy 会处理 hop-by-hop headers，这里无需手动处理
        },
        // 如果需要自定义错误处理
        ErrorHandler: func(rw http.ResponseWriter, req *http.Request, err error) {
            log.Printf("Proxy error: %v", err)
            http.Error(rw, "Proxy Error", http.StatusBadGateway)
        },
    }

    // 设置 Director 为 nil，因为我们使用了 Rewrite
    // proxy.Director = nil // 这行不是必需的，因为设置 Rewrite 优先

    // 启动代理服务器
    log.Println("Starting reverse proxy on :8080, forwarding to", backendURL)
    if err := http.ListenAndServe(":8080", proxy); err != nil {
        log.Fatal("ListenAndServe: ", err)
    }
}

// 简单的后端 HTTP 服务器
func startBackendServer() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        log.Printf("[Backend] Received request: %s %s", r.Method, r.URL.String())
        log.Printf("[Backend] Host header: %s", r.Host)
        log.Printf("[Backend] X-Forwarded-For: %s", r.Header.Get("X-Forwarded-For"))
        log.Printf("[Backend] X-Forwarded-Host: %s", r.Header.Get("X-Forwarded-Host"))
        log.Printf("[Backend] X-Forwarded-Proto: %s", r.Header.Get("X-Forwarded-Proto"))
        log.Printf("[Backend] X-My-Proxy-Header: %s", r.Header.Get("X-My-Proxy-Header"))
        log.Printf("[Backend] User-Agent: %s", r.Header.Get("User-Agent"))

        w.Header().Set("Content-Type", "text/plain")
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("Hello from backend!"))
    })
    log.Println("Starting backend server on :8081")
    if err := http.ListenAndServe(":8081", mux); err != nil {
        log.Printf("Backend server error: %v", err)
        os.Exit(1) // 如果后端无法启动，则退出
    }
}

User-Agent 行为变更

另外一个相关的改动是：如果入站请求 没有 User-Agent 头部，ReverseProxy（无论是否使用 Rewrite）在 Go 1.20 中将 不再 为出站请求自动添加一个默认的 User-Agent 头部。如果需要确保出站请求总是有 User-Agent，你需要在 Rewrite 钩子中检查并设置它。

// 在 Rewrite 函数中添加:
if r.Out.Header.Get("User-Agent") == "" {
    r.Out.Header.Set("User-Agent", "MyCustomProxy/1.0")
}

总而言之，Rewrite 钩子和 ProxyRequest 类型为 httputil.ReverseProxy 提供了更现代化、更安全、更灵活的定制方式，推荐在新的 Go 1.20+ 项目中使用 Rewrite 来替代 Director。