net/http — HTTP 服务器与客户端

package main

import "net/http"

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })
    http.ListenAndServe(":8080", nil) // nil → DefaultServeMux
}

srv := &http.Server{
    Addr:    ":8080",
    Handler: router,

    ReadHeaderTimeout: 10 * time.Second, // 只读请求头：防 slowloris 的关键一项
    ReadTimeout:       15 * time.Second, // 读整个请求（头 + 体）
    WriteTimeout:      30 * time.Second, // 写响应（从读完请求体之后开始计时）
    IdleTimeout:       120 * time.Second, // keep-alive 空闲连接的超时

    MaxHeaderBytes:      1 << 20, // 请求头总大小上限，默认 1MB
    MaxHeaderValueCount: 100,     // Go 1.27：单个头名字最多多少个值（防 header flood）

    BaseContext: func(net.Listener) context.Context {
        return ctx // 所有请求 ctx 的父 ctx：关停时一起取消
    },
    ConnContext: func(c context.Context, cn net.Conn) context.Context {
        return context.WithValue(c, connIDKey{}, cn.RemoteAddr()) // 每连接附加信息
    },
}

go func() {
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
    <-sigCh

    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()
    if err := srv.Shutdown(ctx); err != nil { // 关闭监听、等活跃请求结束
        log.Printf("shutdown: %v", err)
        srv.Close() // 兜底：暴力关掉所有连接
    }
}()

if err := srv.ListenAndServe(); err != http.ErrServerClosed {
    log.Fatal(err) // ErrServerClosed 是 Shutdown/Close 的正常返回值
}

mux := http.NewServeMux()

mux.HandleFunc("GET /healthz", healthz)              // 限定方法
mux.HandleFunc("POST /items", createItem)            // 有方法的模式优先于同名无方法的
mux.HandleFunc("GET /items/{id}", itemByID)          // 单段通配
mux.HandleFunc("GET /files/{path...}", serveFile)    // 多段通配，必须在末尾
mux.HandleFunc("GET /api/v1/{$}", exactNoTrailingSlash) // {$} 精确匹配，不做斜杠重定向
mux.HandleFunc("/", fallback)                        // 前缀匹配（以 / 结尾）

// 取通配值
func itemByID(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    ...
}

func upload(w http.ResponseWriter, r *http.Request) {
    // 1) 硬上限：超了 r.Body 会返回错误，且会自动把响应置为 413 关掉连接
    r.Body = http.MaxBytesReader(w, r.Body, 10<<20) // 10MB

    // 2) multipart：内存上限 + 磁盘临时文件
    if err := r.ParseMultipartForm(32 << 10); err != nil {
        http.Error(w, "too large or malformed form", http.StatusBadRequest)
        return
    }
    file, header, err := r.FormFile("file")
    if err != nil {
        http.Error(w, "missing file", http.StatusBadRequest)
        return
    }
    defer file.Close()
    ...
}

type Middleware func(http.Handler) http.Handler

func Chain(h http.Handler, mws ...Middleware) http.Handler {
    for i := len(mws) - 1; i >= 0; i-- { // 倒序包装：第一个中间件在最外层
        h = mws[i](h)
    }
    return h
}

handler := Chain(actualHandler, Recovery, Logging, Timeout(5*time.Second), RequireAuth)

type statusWriter struct {
    http.ResponseWriter
    code int
    sent bool
}

func (w *statusWriter) WriteHeader(code int) {
    if !w.sent { // 只记第一次：二次 WriteHeader 本来就只会产生一条超日志
        w.code, w.sent = code, true
    }
    w.ResponseWriter.WriteHeader(code)
}

rc := http.NewResponseController(w)
rc.Flush()                                        // SSE
rc.SetWriteDeadline(time.Now().Add(time.Minute))  // 给单个请求放宽
rc.Hijack()                                       // 协议升级
rc.EnableFullDuplex()                             // 边读边写（WebSocket/双向流）

tr := &http.Transport{
    MaxIdleConns:          200, // 全局空闲连接上限（DefaultTransport 是 100）
    MaxIdleConnsPerHost:   50,  // 每 host 空闲上限；不设则用 DefaultMaxIdleConnsPerHost = 2
    MaxConnsPerHost:       0,   // 每 host 总连接上限（0 = 不限）；超限的请求会排队等待
    IdleConnTimeout:       90 * time.Second,
    DialContext:           (&net.Dialer{Timeout: 5 * time.Second, KeepAlive: 30 * time.Second}).DialContext,
    TLSHandshakeTimeout:   10 * time.Second,
    ResponseHeaderTimeout: 10 * time.Second, // 只等响应头，不含读 body
    ExpectContinueTimeout: time.Second,      // 只在请求带 Expect: 100-continue 时生效
    DisableCompression:    false,
    ForceAttemptHTTP2:     true,
}

// 需要精确控制协议时（Go 1.24+）：Protocols 是 nil 时默认只有 HTTP/1，
// 靠 ForceAttemptHTTP2 / TLSNextProto 参与决定要不要 HTTP/2；
// 显式赋值就是把可选协议集合钉死。
p := &http.Protocols{}
p.SetHTTP1(true)
p.SetUnencryptedHTTP2(true) // 明文 HTTP/2（prior knowledge）
tr.Protocols = p
client := &http.Client{Transport: tr, Timeout: 30 * time.Second}

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
    return err
}
req.Header.Set("Accept", "application/json")

resp, err := client.Do(req)
if err != nil {
    // err 通常是 *url.Error，里面包着真正的错误
    if errors.Is(err, context.DeadlineExceeded) { ... } // ctx 超时
    var ue *url.Error
    if errors.As(err, &ue) && ue.Timeout() { ... }       // Client.Timeout
    return err
}
defer resp.Body.Close() // 不 Close = 连接不归还池，长期泄漏 fd

body, err := io.ReadAll(io.LimitReader(resp.Body, 8<<20)) // 读也有上限
if err != nil {
    return err
}
if resp.StatusCode != http.StatusOK {
    return fmt.Errorf("unexpected status %s: %s", resp.Status, truncate(body, 256))
}

func doWithRetry(ctx context.Context, c *http.Client, newReq func() (*http.Request, error), attempts int) (*http.Response, error) {
    var lastErr error
    for i := range attempts {
        if i > 0 {
            backoff := time.Duration(1<<min(i, 5)) * 100 * time.Millisecond
            select {
            case <-time.After(backoff):
            case <-ctx.Done():
                return nil, ctx.Err()
            }
        }
        req, err := newReq() // 每次重新构造请求（body 不可复用！）
        if err != nil {
            return nil, err
        }
        req = req.WithContext(ctx)

        resp, err := c.Do(req)
        if err != nil {
            lastErr = err // 网络层错误：可能是幂等安全问题所在
            continue
        }
        if resp.StatusCode < 500 && resp.StatusCode != http.StatusTooManyRequests {
            return resp, nil // 非重试类状态码直接返回，调用方负责 Close
        }
        resp.Body.Close() // 只有确定要重试时才丢弃响应
        lastErr = fmt.Errorf("status %s", resp.Status)
    }
    return nil, fmt.Errorf("after %d attempts: %w", attempts, lastErr)
}

type breakerState int

const (
    stateClosed breakerState = iota
    stateHalfOpen
    stateOpen
)

type breaker struct {
    mu        sync.Mutex
    state     breakerState
    fails     int
    thresh    int       // 连续失败多少次后打开
    openUntil time.Time // open 状态的到期时间
}

func (b *breaker) allow() bool {
    b.mu.Lock()
    defer b.mu.Unlock()
    switch b.state {
    case stateOpen:
        if time.Now().After(b.openUntil) {
            b.state = stateHalfOpen // 进入半开：只放探测流量
            return true
        }
        return false
    default:
        return true
    }
}

func (b *breaker) onResult(err error, status int) {
    b.mu.Lock()
    defer b.mu.Unlock()
    if err != nil || status >= 500 {
        b.fails++
        if b.fails >= b.thresh {
            b.state, b.openUntil = stateOpen, time.Now().Add(10*time.Second)
        }
        return
    }
    if b.state == stateHalfOpen {
        b.state, b.fails = stateClosed, 0 // 探测成功，立即恢复
    }
}

func TestHandler(t *testing.T) {
    // 不打真网络：httptest.NewRequest + ResponseRecorder
    req := httptest.NewRequest(http.MethodGet, "/items/42", nil)
    // Go 1.23+：httptest.NewRequestWithContext 带上 ctx
    rec := httptest.NewRecorder()
    handler.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("code = %d, body = %s", rec.Code, rec.Body)
    }
}

func TestIntegration(t *testing.T) {
    srv := httptest.NewServer(router)      // 真实监听 127.0.0.1:随机端口
    defer srv.Close()
    resp, err := srv.Client().Get(srv.URL + "/healthz")
    ...
}

func TestWithSynctest(t *testing.T) {
    // Go 1.27：内存假网络，可与 testing/synctest 一起用，完全确定性
    srv := httptest.NewTestServer(t, handler) // t 作为参数，自动清理
    resp, err := srv.Client().Get("http://example.com/") // example.com 会被重定向到这个假服务器
    ...
}