// Go 的气质一屏看完：并发是语言原语
// ⚠️ 这是「预览」——现在一行看不懂都正常，06 章会从头讲
package main

import "fmt"

func fetch(u string, ch chan string) {
  ch <- "fetched " + u   // 把结果送进 channel
}

func main() {
  urls := []string{"a.com", "b.com", "c.com"}
  ch := make(chan string)

  for _, u := range urls {
    go fetch(u, ch)      // go 一个关键字就开启并发
  }
  for range urls {
    fmt.Println(<-ch)    // 从 channel 收结果
  }
}

// main.go —— 最小可运行程序
package main        // ① 本文件属于 main 包 = 可执行程序

import "fmt"        // ② 引入标准库的 fmt 包

func main() {        // ③ 入口，{ 必须在这一行（见下卡分号规则）
  msg := "Hello, Go!"   // ④ 短变量声明，类型推断为 string
  fmt.Println(msg)
}

// ---- 终端里依次执行 ----
// mkdir hello && cd hello
// go mod init hello   → 生成 go.mod
// go run .            → Hello, Go!
// go build -o hello   → 产出单个静态二进制

var name string = "Alice"
count := 0                 // 推断为 int
var price, qty = 9.99, 3  // 多变量

// 零值：声明即可用，无需初始化
var i int      // 0
var s string   // ""
var p *int     // nil

// 必须显式转换，无隐式
var x int = 10
var y float64 = float64(x)

// 常量 + iota 枚举（自增，从 0 开始）
const (
  StatusPending  = iota  // 0
  StatusActive            // 1
  StatusClosed            // 2
)

// 未使用的变量会编译报错，用 _ 丢弃
_, err := fmt.Println("hi")

// if 带初始化，val/ok 仅在 if-else 内有效
if val, ok := myMap["key"]; ok {
  fmt.Println(val)
}

for i := 0; i < 10; i++ { }   // 三段式
for count < 10 { count++ }      // 相当于 while
for { if done { break } }      // 无限循环

for i, v := range nums { }        // range 切片：索引,值
for k, v := range myMap { }       // range map：顺序随机！
for i := range 5 { }              // Go1.22+：range 整数 0..4

// switch 自动 break，一个 case 可多值
switch day {
case 6, 7: fmt.Println("周末")
default: fmt.Println("工作日")
}

// 无表达式 switch：替代 if-else 链
switch {
case score >= 90: grade = "A"
case score >= 80: grade = "B"
default:           grade = "C"
}

nums := []int{1, 2, 3}
nums = append(nums, 4, 5)
buf := make([]int, 0, 10)   // len=0, cap=10
sub := nums[1:3]               // [start:end)，共享底层数组

dst := make([]int, len(sub))
copy(dst, sub)                  // 需要独立副本时显式 copy

ages := map[string]int{"Alice": 28}
ages["Bob"] = 25             // 增 / 改
delete(ages, "Bob")            // 删

// comma-ok：区分"不存在"和"值为零值"
if age, ok := ages["Dave"]; ok {
  fmt.Println(age)
}

x := 10
p := &x            // p 是 *int，指向 x
fmt.Println(*p)    // 解引用：10
*p = 20            // 通过指针改原值
fmt.Println(x)     // 20

var np *int        // 零值 nil
// fmt.Println(*np) // 解引用 nil 会 panic

// 传指针，函数才能改到调用方的变量
func double(n *int) { *n *= 2 }
double(&x)          // x 变成 40

// 大结构体传指针，省一次拷贝
func scale(r *Rectangle, f float64) { r.Width *= f }

// map/slice 本身是引用：传值即共享，无需再取 &
func fill(m map[string]int) { m["k"] = 1 } // 原 map 被改

s := "héllo，世界"
fmt.Println(len(s))          // 字节数，不是字符数

// 索引取字节；range 按 rune（字符）遍历
for i, r := range s {
  fmt.Printf("%d:%c ", i, r) // i 是字节偏移，r 是 rune
}

// 字符串不可变：s[0] = 'H' 编译报错
b := []byte(s)               // 按字节拆
b[0] = 'H'                   // 只能改副本
s2 := string(b)              // []byte 转回 string

r := []rune(s)               // 按码点拆
fmt.Println(len(r))          // 这才是字符个数

// —— fmt 三兄弟：Println / Printf / Sprintf ——
name, price := "Go", 3.14159
fmt.Println("hello", name)             // 空格分隔 + 自动换行
fmt.Printf("%.2f 元\n", price)        // 精度：保留 2 位小数
msg := fmt.Sprintf("%s=%v", name, price)  // 只返回字符串，不打印
fmt.Fprintln(os.Stderr, "出错了")      // 错误信息走 stderr

// 常用动词：%v 万能 · %#v Go 语法 · %T 类型（%+v 等 04 章结构体再用）
ages := map[string]int{"Ann": 18}   // map 见本章「数组、切片与 Map」卡
fmt.Printf("%v | %#v | %T\n", ages, ages, ages)
// 输出：map[Ann:18] | map[string]int{"Ann":18} | map[string]int
fmt.Printf("%q\n", name)              // "Go"（带引号，排查空白）

// —— 读输入的标准姿势：bufio.Scanner 按行循环 ——
scanner := bufio.NewScanner(os.Stdin)
for scanner.Scan() {                    // 每次读一行（不含换行符）
  line := scanner.Text()
  fmt.Println("读到:", line)
}
if err := scanner.Err(); err != nil {   // 循环结束必须查错
  fmt.Fprintln(os.Stderr, err)
}

// —— 文件：小文件一步到位，大文件流式 ——
data, err := os.ReadFile("config.txt")  // 整个文件读成 []byte
if err != nil { log.Fatal(err) }
fmt.Println(string(data))               // []byte 转 string 要显式

os.WriteFile("out.txt", []byte(msg), 0644)  // 0644 权限位

f, err := os.Open("huge.log")          // 大文件别一次读进内存
if err != nil { log.Fatal(err) }
defer f.Close()                         // defer 保证句柄释放
sc := bufio.NewScanner(f)
for sc.Scan() { process(sc.Text()) }    // 逐行流式，内存恒定

func divide(a, b float64) (float64, error) {
  if b == 0 {
    return 0, errors.New("除数为 0")
  }
  return a / b, nil
}
result, err := divide(10, 2)

// 可变参数，内部是切片
func sum(nums ...int) int {
  total := 0
  for _, n := range nums { total += n }
  return total
}
sum(1, 2, 3)
sum(xs...)                      // 展开切片

func readFile(path string) error {
  f, err := os.Open(path)
  if err != nil { return err }
  defer f.Close()             // 函数结束自动关闭
  // ... 读取
  return nil
}

type Rectangle struct { Width, Height float64 }

func (r Rectangle) Area() float64 {   // 值接收者
  return r.Width * r.Height
}
func (r *Rectangle) Scale(f float64) { // 指针接收者，可改原值
  r.Width *= f
  r.Height *= f
}

rect := Rectangle{Width: 10, Height: 5}
rect.Scale(2)                  // 自动 (&rect).Scale(2)
fmt.Println(rect.Area())       // 200

// 闭包：捕获外层变量
func makeCounter() func() int {
  count := 0
  return func() int { count++; return count }
}
c := makeCounter()
c(); c()                        // 1, 2（count 被闭包记住）

// ① 命名返回值 + defer 统一包装错误
func loadConfig(path string) (cfg *Config, err error) {
  defer func() {
    if err != nil {                // 每个出口的 err 都被套上同一层上下文
      err = fmt.Errorf("loadConfig %s: %w", path, err)
    }
  }()
  f, err := os.Open(path)
  if err != nil { return nil, err }   // 这里的 err 会被 defer 回写
  defer f.Close()
  return parse(f)                    // 出错时同样被包装
}

// ② defer 里 recover，把 panic 转成普通 error（naked return）
func safeParse(b []byte) (n int, err error) {
  defer func() {
    if r := recover(); r != nil {
      err = fmt.Errorf("parse panicked: %v", r) // 写回命名返回值 err
    }
  }()
  n = mustParse(b)                    // 内部可能 panic
  return                              // naked return：交出 n、err 的当前值
}

type Address struct { City, Country string }

type Employee struct {
  Name    string
  Address              // 匿名嵌入：字段被提升
  Salary  float64
}

emp := Employee{Name: "Dave", Address: Address{City: "BJ"}}
fmt.Println(emp.City)  // 直接访问，等价 emp.Address.City

// 字段标签：控制 JSON 序列化
type Product struct {
  Name  string  `json:"name"`
  Price float64 `json:"price,omitempty"` // 为 0 时省略
  SKU   string  `json:"-"`               // 永不序列化
}

type Shape interface {
  Area() float64
}

type Circle struct { R float64 }
func (c Circle) Area() float64 { return math.Pi * c.R * c.R }
// Circle 自动满足 Shape，无需声明

func describe(s Shape) { fmt.Println(s.Area()) }
describe(Circle{R: 5})

// 类型断言（comma-ok 不 panic）
var s Shape = Circle{R: 5}
if c, ok := s.(Circle); ok { fmt.Println(c.R) }

// 类型 switch
func kind(v any) {
  switch x := v.(type) {
  case int:    fmt.Println("int", x)
  case string: fmt.Println("string", x)
  default:     fmt.Println("other")
  }
}

// 接口嵌入：方法集取并集，小接口拼成大接口
type Reader interface { Read(p []byte) (int, error) }
type Writer interface { Write(p []byte) (int, error) }
type ReadWriter interface {   // = Reader + Writer
  Reader
  Writer
}

type Status int

const (
  Pending Status = iota   // 0
  Active                    // 1
  Closed                    // 2
)

// 实现 String()，即自动满足 fmt.Stringer
func (s Status) String() string {
  switch s {
  case Pending: return "Pending"
  case Active:  return "Active"
  case Closed:  return "Closed"
  default:      return fmt.Sprintf("Status(%d)", int(s))
  }
}

fmt.Println(Active)           // 打印 "Active"，不是 1
fmt.Printf("%v", Pending)   // "Pending"（%v/%s 都会调 String）

import "errors"

// 哨兵错误 + 包裹
var ErrNotFound = errors.New("not found")

func getUser(id int) (*User, error) {
  u, err := db.Query(id)
  if err != nil {
    return nil, fmt.Errorf("getUser %d: %w", id, err)
  }
  return u, nil
}

// 即使被 wrap，也能识别原始错误
if errors.Is(err, ErrNotFound) { ... }

// 自定义错误类型
type ValidationError struct { Field, Msg string }
func (e *ValidationError) Error() string {
  return fmt.Sprintf("%s: %s", e.Field, e.Msg)
}

var ve *ValidationError
if errors.As(err, &ve) { fmt.Println(ve.Field) }

// recover 必须在 defer 里
func safe(fn func()) {
  defer func() {
    if r := recover(); r != nil {
      log.Printf("recovered: %v", r)
    }
  }()
  fn()
}

// HTTP 中间件中的典型兜底
func recoverMW(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    defer func() {
      if err := recover(); err != nil {
        http.Error(w, "500", http.StatusInternalServerError)
        log.Printf("panic: %v", err)
      }
    }()
    next.ServeHTTP(w, r)
  })
}

func processAll(items []string) {
  var wg sync.WaitGroup
  for _, item := range items {
    wg.Add(1)               // 计数 +1
    go func(it string) {
      defer wg.Done()       // 结束时 -1
      process(it)
    }(item)
  }
  wg.Wait()                 // 阻塞到计数归零
}

ch := make(chan int)        // 无缓冲
buf := make(chan int, 10)   // 带缓冲

go func() {
  defer close(ch)            // 生产者关闭
  for i := 0; i < 3; i++ { ch <- i }
}()
for v := range ch {          // 收到 close 才退出
  fmt.Println(v)
}

// select：多路等待 + 超时
select {
case msg := <-ch1: fmt.Println(msg)
case <-time.After(3 * time.Second): fmt.Println("超时")
default: fmt.Println("无数据（非阻塞）")
}

// 单向 channel：编译期限制方向
func producer(out chan<- int) { out <- 1 }  // 只写
func consumer(in <-chan int) { <-in }      // 只读

// stage1：生成数据，返回只读 channel
func gen(nums ...int) <-chan int {
  out := make(chan int)
  go func() {
    defer close(out)
    for _, n := range nums { out <- n }
  }()
  return out
}

// stage2：平方，入 → 出
func sq(in <-chan int) <-chan int {
  out := make(chan int)
  go func() {
    defer close(out)
    for n := range in { out <- n * n }
  }()
  return out
}

// fan-in：把多个 channel 合并成一个
func merge(cs ...<-chan int) <-chan int {
  out := make(chan int)
  var wg sync.WaitGroup
  wg.Add(len(cs))
  for _, c := range cs {
    go func(c <-chan int) {
      defer wg.Done()
      for v := range c { out <- v }
    }(c)
  }
  go func() { wg.Wait(); close(out) }()  // 全部收完再关
  return out
}

in := gen(2, 3, 4, 5)
// fan-out：两个 sq 并行消费同一个 in
c1, c2 := sq(in), sq(in)
for v := range merge(c1, c2) {          // fan-in 合并
  fmt.Println(v)                         // 4 9 16 25（顺序不定）
}

func fetch(ctx context.Context, url string) error {
  ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
  defer cancel()            // 必须调用，否则泄漏

  req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
  _, err := http.DefaultClient.Do(req)
  return err              // 超时会自动取消请求
}

// 在耗时任务中响应取消
func work(ctx context.Context) error {
  for {
    select {
    case <-ctx.Done(): return ctx.Err() // 提前退出
    default: // 继续干活...
    }
  }
}

type Counter struct {
  mu sync.Mutex
  n  int
}
func (c *Counter) Inc() {
  c.mu.Lock()
  defer c.mu.Unlock()
  c.n++                     // 同一时刻仅一个 goroutine 能改
}

// Worker Pool：固定 worker 消费同一 channel
func pool(jobs <-chan int, results chan<- int, n int) {
  var wg sync.WaitGroup
  for i := 0; i < n; i++ {
    wg.Add(1)
    go func() {
      defer wg.Done()
      for j := range jobs { results <- j * j }
    }()
  }
  wg.Wait(); close(results)
}

// errgroup：任一失败即取消其余
g, ctx := errgroup.WithContext(ctx)
for _, url := range urls {
  g.Go(func() error { return fetch(ctx, url) })
}
if err := g.Wait(); err != nil { ... }

// atomic：无锁计数器（比 Mutex 轻）
var hits atomic.Int64          // Go1.19+ 类型化原子
hits.Add(1)                    // 并发安全自增
fmt.Println(hits.Load())       // 读取当前值

// RWMutex：读多写少，多个读可并发
type Cache struct {
  mu sync.RWMutex
  m  map[string]string
}
func (c *Cache) Get(k string) string {
  c.mu.RLock()                 // 读锁：多个 goroutine 可同时持有
  defer c.mu.RUnlock()
  return c.m[k]
}
func (c *Cache) Set(k, v string) {
  c.mu.Lock()                  // 写锁：独占
  defer c.mu.Unlock()
  c.m[k] = v
}

// sync.Pool：复用临时对象，减轻 GC
var bufPool = sync.Pool{
  New: func() any { return new(bytes.Buffer) },
}
buf := bufPool.Get().(*bytes.Buffer)
buf.Reset()
defer bufPool.Put(buf)         // 用完归还池中

// ✗ 数据竞争：done 无同步，读方可能永远看不到 true（UB，不只是慢）
var done bool
var msg string
go func() { msg = "hi"; done = true }()
for !done {}                 // 可能死循环；即便退出，msg 也未必可见

// ✓ 用 channel 建立 happens-before：发送前的写，接收后一定可见
var msg2 string
ch := make(chan struct{})
go func() {
  msg2 = "hi"              // 这次写……
  close(ch)                 // ……happens-before 下面的接收
}()
<-ch                        // 收到后读 msg2 保证是 "hi"
fmt.Println(msg2)

// 泛型函数：类型自动推断
func Map[T, U any](s []T, f func(T) U) []U {
  r := make([]U, len(s))
  for i, v := range s { r[i] = f(v) }
  return r
}
doubled := Map(nums, func(n int) int { return n * 2 })

// 联合类型约束
type Number interface { ~int | ~int64 | ~float64 }

func Sum[T Number](s []T) T {
  var total T
  for _, v := range s { total += v }
  return total
}

// comparable 约束
func Contains[T comparable](s []T, target T) bool {
  for _, v := range s { if v == target { return true } }
  return false
}

type Stack[T any] struct { items []T }

func (s *Stack[T]) Push(x T) { s.items = append(s.items, x) }
func (s *Stack[T]) Pop() (T, bool) {
  var zero T
  if len(s.items) == 0 { return zero, false }
  x := s.items[len(s.items)-1]
  s.items = s.items[:len(s.items)-1]
  return x, true
}

st := &Stack[int]{}
st.Push(1); st.Push(2)
v, ok := st.Pop()             // v 是 int，无需断言

// 标准库泛型函数（Go1.21+）
slices.Contains([]int{1, 2, 3}, 2)  // true
slices.Sort(nums)                       // 原地排序
slices.Index(nums, 5)               // 找不到返回 -1
for k := range maps.Keys(m) { ... }     // 迭代器（Go1.23+）

import ("iter"; "maps"; "slices")

// 一个迭代器就是这个形状的函数
func Countdown(n int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := n; i > 0; i-- {
            if !yield(i) {
                return   // 消费方 break 了，必须立刻收摊
            }
        }
    }
}

for v := range Countdown(5) { fmt.Print(v, " ") }   // 5 4 3 2 1

// 惰性：数到 3 就 break，生产端只跑 3 次
for v := range Countdown(1000000) { if ... { break } }

// 标准库：Keys 返回迭代器，不是切片
keys := slices.Sorted(maps.Keys(m))   // []string，已排序
all  := slices.Collect(Countdown(3))  // [3 2 1]

package models

type User struct {
  Name  string     // 大写：导出
  email string     // 小写：包内私有
}

func NewUser(name string) *User { // 导出构造函数
  return &User{Name: name}
}

import (
  "fmt"                       // 标准库
  "myapp/internal/models"     // 本项目（internal 仅本模块可导）
  "github.com/gin-gonic/gin"   // 第三方

  pgx "github.com/jackc/pgx/v5" // 别名导入
)

package config

var defaults = loadDefaults()   // ① 包级变量先算

func init() {                   // ② 再跑 init（可有多个）
  if os.Getenv("APP_ENV") == "" {
    log.Fatal("APP_ENV 必填")   // 启动期校验，缺失就别启动
  }
}

// 匿名导入：只为触发对方包的 init（注册驱动），不直接用它的符号
import _ "github.com/lib/pq"   // pq 的 init 里 sql.Register("postgres", ...)

go mod init github.com/me/myapp

// go.mod
module github.com/me/myapp
go 1.25
require (
  github.com/gin-gonic/gin v1.12.0
  gorm.io/gorm v1.31.0
)

go mod tidy                 // 增补/清理依赖
go get pkg@v1.2.3           // 装指定版本
go build ./cmd/server       // 编译成单一可执行文件

// 约定结构
// myapp/
//   cmd/server/main.go   入口
//   internal/            私有实现（handler/service/repo）
//   pkg/                 可外部复用

// 参考时刻：01 月 02 日 03 时(12h) 04 分 05 秒 06 年，15 是 24 小时制
t := time.Date(2025, 3, 7, 15, 4, 5, 0, time.UTC)

t.Format("2006-01-02 15:04:05")   // 2025-03-07 15:04:05
t.Format("01/02 03:04PM")         // 03/07 03:04PM
t.Format(time.RFC3339)             // 跨系统传输用这个
t.Format("%Y-%m-%d")             // %Y-%m-%d —— 不报错，原样输出！

// 解析：布局串写法完全一样
ts, err := time.Parse(time.RFC3339, "2025-03-07T15:04:05Z")

// Duration 是带类型的 int64，打印有单位
d := 90 * time.Second        // 打印为 1m30s
d.Seconds()                   // 90（float64）

var n int = 30
// timeout := n * time.Second     // 编译错误：类型不匹配
timeout := time.Duration(n) * time.Second   // 变量要显式转换

// 比较：Equal / Before / After，别用 ==
if t.Equal(other) { }
if t.Before(deadline) { }
elapsed := time.Since(start)   // 等价于 time.Now().Sub(start)

User{Name: "a", Age: 0, Admin: false, Tags: []string{}}
  →  {"name":"a"}

type User struct {
    Name  string   `json:"name"`
    Age   int      `json:"age,omitempty"`     // 0 会被省略
    Admin bool     `json:"admin,omitempty"`   // false 会被省略！
    Notes string   `json:"-"`                  // 永不参与
    id    string                                // 小写：反射看不见，静默忽略
}

// 要区分「零」和「没有」，用指针
type Patch struct {
    Age   *int   `json:"age,omitempty"`    // nil=没填, &0=真的是 0
    Admin *bool  `json:"admin,omitempty"`
}

// 动态解析：数字默认全是 float64
var v interface{}
json.Unmarshal(data, &v)
m := v.(map[string]interface{})
// n := m["n"].(int)        // panic：实际是 float64
n := int(m["n"].(float64))

// 大整数要保精度：UseNumber
dec := json.NewDecoder(r)
dec.UseNumber()                      // 数字保留为 json.Number
dec.Decode(&v)
id, err := m["id"].(json.Number).Int64()

// 大流用 Decoder/Encoder，别把整个文件读进内存再 Unmarshal
for dec.More() {
    var u User
    if err := dec.Decode(&u); err != nil { break }
}

n=10     sort.Slice 保持原序? true     与 SliceStable 结果相同? true
n=12     sort.Slice 保持原序? true     与 SliceStable 结果相同? true
n=13     sort.Slice 保持原序? false    与 SliceStable 结果相同? false
n=20     保持原序? false
n=1000   保持原序? false

import ("cmp"; "slices"; "sort")

// Go 1.21+ 首选：泛型、类型安全、三态比较
slices.SortFunc(users, func(a, b User) int {
    return cmp.Compare(a.Age, b.Age)      // 别写 a.Age - b.Age
})

// 需要稳定就明写 Stable 版
slices.SortStableFunc(users, func(a, b User) int {
    return cmp.Compare(a.Age, b.Age)
})

// 更稳妥：让键唯一，稳不稳定都不影响结果
slices.SortFunc(users, func(a, b User) int {
    if c := cmp.Compare(a.Age, b.Age); c != 0 {
        return c
    }
    return cmp.Compare(a.ID, b.ID)          // 决胜字段
})

// 老 API：less(i, j) 必须是【严格】小于，相等返回 false
sort.Slice(users, func(i, j int) bool {
    return users[i].Age < users[j].Age    // 写 <= 会破坏全序
})

// slices 包顺带的实用函数（都不需要预排序，除了 BinarySearch）
slices.Contains(s, v)
slices.Index(s, v)
slices.Reverse(s)
i, found := slices.BinarySearch(sorted, v)   // 前提：已排序

s := "héllo"

len(s)                        // 6 —— 字节数，不是字符数
s[1]                         // 195 —— 一个 byte，不是 'é'
utf8.RuneCountInString(s)      // 5 —— 字符（码点）数
[]rune(s)[1]                  // 'é' —— 但转换会整体拷贝

// 按字符遍历：i 是字节下标（不连续），r 是码点
for i, r := range s {
    fmt.Printf("%d:%c ", i, r)   // 0:h 1:é 3:l 4:l 5:o
}

// 拼接：只要有循环就用 Builder
var sb strings.Builder
sb.Grow(200000)                 // 已知总长可以预分配
for _, part := range parts {
    sb.WriteString(part)
}
result := sb.String()

// 数字转换：返回值和 error 都要看
n, err := strconv.Atoi("12abc")
// err: strconv.Atoi: parsing "12abc": invalid syntax

// 热路径上别用 Sprintf 做简单转换
s1 := fmt.Sprintf("%d", n)      // 走反射，慢
s2 := strconv.Itoa(n)          // 直接得多

// 包装：用 %w 保住原错误
if err != nil {
    return fmt.Errorf("读配置 %s: %w", path, err)   // %w 不是 %v
}

// 判断哨兵值：Is 会沿着整条包装链找
if errors.Is(err, sql.ErrNoRows) { }
if errors.Is(err, context.DeadlineExceeded) { }

// 判断错误类型并取出字段：As
var pathErr *os.PathError
if errors.As(err, &pathErr) {
    log.Println("出问题的路径:", pathErr.Path)
}

// 自定义哨兵错误
var ErrNotFound = errors.New("not found")

// ---------- context ----------
// 创建方负责 cancel，一律 defer
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()                     // 漏了就泄漏

// ctx 永远是第一个参数
func FetchUser(ctx context.Context, id int64) (*User, error) {
    select {
    case <-ctx.Done():
        return nil, ctx.Err()      // deadline exceeded / canceled
    case r := <-work:
        return r, nil
    }
}

// WithValue 的 key 用自定义类型，别用裸字符串
type ctxKey struct{}
ctx = context.WithValue(ctx, ctxKey{}, traceID)

// —— 字符串 · 格式化 · 文本 ——
fmt.Sprintf("%s=%d", name, age)               // 格式化 I/O：Printf / Errorf(%w) / Sscanf  ★
strings.Split("a,b,c", ",")                   // 查找 / 切分 / 替换 / 拼接 Builder  ★
strconv.Atoi("42")                            // 字符串↔数字：Itoa / ParseFloat / FormatInt  ★
bytes.NewBuffer(nil)                          // []byte 版 strings，可变缓冲 Buffer
utf8.RuneCountInString("héllo")               // rune 与 UTF-8：DecodeRune（unicode/utf8）
regexp.MustCompile("[0-9]+")                  // 正则：FindStringSubmatch / ReplaceAllString
template.New("t").Parse(src)                  // text/template 文本模板：Execute

// —— 集合 · 排序 · 算法 ——
slices.Sort(xs)                               // 切片泛型 1.21+：Contains / Index / BinarySearch  ★
maps.Clone(m)                                 // map 泛型 1.21+：Keys / Values / Equal  ★
sort.Slice(xs, less)                          // 泛型前老 API：Search / Ints / Strings  ★
cmp.Compare(a, b)                             // 有序比较辅助：Ordered / Or（配 slices）
heap.Push(&h, 3)                              // container/heap 堆；list 双向链表

// —— 文件 · I/O · 路径 ——
os.ReadFile("cfg.json")                       // 文件 / 环境 / 进程：Open / Getenv / Args / Exit  ★
io.Copy(dst, src)                             // 流式接口：Reader / Writer / ReadAll  ★
bufio.NewScanner(os.Stdin)                    // 缓冲读写、按行扫描：NewReader / Writer  ★
filepath.Join("a", "b.txt")                   // 跨平台路径：Base / Ext / Walk（path/filepath）
os.DirFS("assets")                            // io/fs 只读文件系统；//go:embed 编译期嵌入

// —— 编码 · 序列化 ——
json.Marshal(v)                               // JSON：Unmarshal / NewEncoder / Decoder  ★
xml.Marshal(v)                                // encoding/xml、encoding/csv 同风格
base64.StdEncoding.EncodeToString(b)          // base64 / hex：二进制↔文本
gob.NewEncoder(w)                             // encoding/gob：Go 专用二进制序列化

// —— 网络 · Web ——
http.ListenAndServe(":8080", mux)             // HTTP 服务 / 客户端：ServeMux / Get / Client  ★
url.Parse("https://x?q=1")                    // net/url：Values / QueryEscape
net.Dial("tcp", addr)                         // net 底层：Listen / LookupHost
template.ParseFiles("p.html")                 // html/template：自动转义防 XSS

// —— 并发 · 时间 ——
sync.WaitGroup{}                              // 锁 / 等待组 / 单次：Mutex / RWMutex / Once / Map  ★
atomic.Int64{}                                // sync/atomic 无锁原子：Add / CompareAndSwap
context.WithTimeout(ctx, d)                   // 取消 / 超时 / 传值：WithCancel / Done  ★
time.Since(start)                             // 时刻 / 时长 / 定时：Now / Format / Ticker / After  ★

// —— 错误 · 日志 · 运行时 · 数学 · 工具 ——
errors.Is(err, ErrNotFound)                   // 错误链：New / As / Join / Unwrap  ★
slog.Info("msg", "k", v)                      // log/slog 结构化日志 ★；log.Fatal 简单日志
runtime.NumGoroutine()                        // 运行时 / GC：GOMAXPROCS；reflect 反射（慎用）
math.Sqrt(2); rand.Intn(6)                    // math / math/rand / math/big 大数
sha256.Sum256(b)                              // crypto/sha256 哈希；crypto/rand 安全随机
flag.Parse()                                  // flag 命令行参数；exec.Command 跑外部命令
t.Run("case", fn)                             // testing 单测 / 基准 / 模糊：httptest（↓见 12 章）

type User struct {
  ID   int    `json:"id"`
  Name string `json:"name"`
}

func getUser(w http.ResponseWriter, r *http.Request) {
  id := r.PathValue("id")        // Go1.22+ 路径参数
  log.Printf("查询用户 id=%s", id)  // 用上路径参数（否则未使用会编译报错）
  u := User{ID: 1, Name: "Alice"}
  w.Header().Set("Content-Type", "application/json")
  json.NewEncoder(w).Encode(u)
}

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("GET /users/{id}", getUser)
  mux.HandleFunc("POST /users", createUser)
  http.ListenAndServe(":8080", mux)
}

// 中间件：函数包装函数
func logging(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    start := time.Now()
    next.ServeHTTP(w, r)
    log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
  })
}

// —— 打印到 stdout ——
name, age := "Alice", 30
fmt.Print("no newline")                // 不换行，参数间按需补空格
fmt.Println("hi", name)                 // hi Alice（参数间自动空格 + 换行）
fmt.Printf("%s is %d\n", name, age)    // 按动词格式化 %d %s %v %+v %T

// —— 格式化为字符串 / 写入 Writer ——
s := fmt.Sprintf("%s-%03d", name, age) // 返回字符串而非打印，最常用
fmt.Fprintf(w, "id=%d\n", 1)           // 写入任意 io.Writer（文件 / http.ResponseWriter）

// —— 造错误 ——
err := fmt.Errorf("open: %w", base)    // %w 包裹底层 error，供 errors.Is/As 解包

// —— 反向解析 ——
var x, y int
fmt.Scan(&x, &y)                         // 从 stdin 按空白分词读值
fmt.Sscan("3 5", &x, &y)                // 从字符串按空白分词读值 → 3 5
var maj, min int
fmt.Sscanf("v1.22", "v%d.%d", &maj, &min) // 从字符串按格式反解 → 1 22

// —— strings：判断与查找 ——
strings.Contains("gopher", "go")      // true
strings.HasPrefix("gopher", "go")     // true：前缀判断
strings.HasSuffix("main.go", ".go")   // true：后缀判断
strings.Index("gopher", "ph")         // 3：首次出现下标，无则 -1

// —— strings：切分与拼接 ——
strings.Split("a,b,c", ",")             // [a b c]
strings.Join([]string{"a", "b"}, "-")  // "a-b"
strings.Fields("  a  b c ")           // [a b c]：按连续空白切分
strings.Repeat("ab", 3)                 // "ababab"

// —— strings：替换与裁剪 ——
strings.Replace("a.b.c", ".", "/", 1) // "a/b.c"：替换前 n 处（-1 全部）
strings.ReplaceAll("a.b.c", ".", "/") // "a/b/c"
strings.TrimSpace("  hi  ")            // "hi"：去两端空白
strings.Trim("[hi]", "[]")            // "hi"：去两端属于 cutset 的字符
strings.ToUpper("go")                   // "GO"
strings.ToLower("GO")                   // "go"

// —— strings.Builder：高效拼接，免 += 反复分配 ——
var b strings.Builder
b.WriteString("id=")                  // 累积字符串
b.WriteByte('!')                       // 累积单字节
s := b.String()                          // 取最终结果 "id=!"

// —— strconv：字符串 ↔ 数字 ——
n, err := strconv.Atoi("42")          // string → int，最常用
str := strconv.Itoa(42)                // int → "42"
i, _ := strconv.ParseInt("ff", 16, 64)  // 按 base 解析 → int64(255)
f, _ := strconv.ParseFloat("3.14", 64) // → float64
ok, _ := strconv.ParseBool("true")     // → bool
strconv.FormatInt(255, 16)             // "ff"：int64 → 指定进制串
strconv.FormatFloat(3.14, 'f', 2, 64) // "3.14"：float64 → 串
strconv.Quote("a\tb")                 // 加双引号并转义特殊字符

// —— slices（Go 1.21+ 泛型）——
xs := []int{3, 1, 2}
slices.Contains(xs, 2)                   // true
slices.Index(xs, 2)                      // 2：元素下标，无则 -1
slices.Sort(xs)                          // [1 2 3] 原地升序（需 cmp.Ordered）
slices.Max(xs)                           // 3：最大值
slices.Min(xs)                           // 1：最小值
slices.Reverse(xs)                       // [3 2 1] 原地反转
slices.Equal(xs, []int{3, 2, 1})       // true：逐元素相等
i, ok := slices.BinarySearch(xs, 2)      // 需已排序 → 下标, 是否命中
xs = slices.Insert(xs, 1, 9)             // 在下标 1 处插入 9
xs = slices.Delete(xs, 0, 1)              // 删除 [0,1) 区间
slices.SortFunc(users, func(a, b User) int {
  return cmp.Compare(a.Age, b.Age)       // 自定义比较：返回 <0 / 0 / >0
})

// —— maps（Go 1.21+）——
m := map[string]int{"a": 1, "b": 2}
c := maps.Clone(m)                       // 浅拷贝
maps.Equal(m, c)                         // true：键值相等判断
maps.DeleteFunc(m, func(k string, v int) bool { return v == 1 }) // 按条件批量删除
ks := slices.Sorted(maps.Keys(m))        // Keys → iter.Seq（1.23+）收成有序键
vs := slices.Sorted(maps.Values(m))      // Values 同理取值迭代器

// —— sort（老 API，泛型前的做法）——
sort.Slice(users, func(i, j int) bool {
  return users[i].Age < users[j].Age    // 按下标比较，最常用
})
sort.SliceStable(users, less)            // 稳定版，相等元素保持原序
sort.Sort(data)                          // data 需实现 Len/Less/Swap
sort.Search(n, f)                        // 二分找满足条件的最小下标
sort.Ints([]int{3, 1, 2})              // 基础类型快捷排序
sort.Strings([]string{"b", "a"})        // 字符串升序

// —— os：文件读写 ——
src, _ := os.Open("in.txt")             // 只读打开 → *os.File
dst, _ := os.Create("copy.txt")          // 创建或截断 → *os.File
data, err := os.ReadFile("cfg.json")  // 小文件一次读全 → []byte
os.WriteFile("out.txt", data, 0644)     // 一次写全

// —— os：环境变量与进程 ——
url := os.Getenv("DATABASE_URL")        // 未设返回 ""
v, ok := os.LookupEnv("PORT")           // ok 可区分未设与空值
_ = os.Args                              // []string 命令行参数，Args[0] 是程序名
if len(os.Args) < 2 { os.Exit(1) }      // 立即退出，不执行 defer

// —— io：流式处理 ——
io.Copy(dst, src)                        // 流式拷贝，不把整块读进内存
all, _ := io.ReadAll(src)                // 读到 EOF → []byte（取代旧 ioutil.ReadAll）

// —— bufio：缓冲（详见输入解析卡）——
sc := bufio.NewScanner(os.Stdin)         // 逐行 / 逐词扫描输入
for sc.Scan() { process(sc.Text()) }
br := bufio.NewReader(src)               // 缓冲读
bw := bufio.NewWriter(dst)               // 缓冲写，收尾必须 Flush

// —— 取时刻与计时 ——
start := time.Now()                      // 当前时刻 Time
elapsed := time.Since(start)             // 距 start 的 Duration（= Now().Sub(start)），计时首选
time.Sleep(2 * time.Second)              // 阻塞休眠；Duration 常量按倍数相乘

// —— 格式化与解析（layout = 参考时刻）——
time.Now().Format("2006-01-02 15:04:05") // 参考时刻当模板，别写 YYYY
t, _ := time.Parse("2006-01-02", "2024-01-15") // 按 layout 解析

// —— 与 Unix 时间戳互转 ——
sec := t.Unix()                          // Time → Unix 秒时间戳
t2 := time.Unix(sec, 0)                 // Unix 秒 → Time

// —— 定时器与超时 ——
select {
case <-time.After(3 * time.Second):      // 超时分支，返回 <-chan Time
  fmt.Println("timeout")
case r := <-ch:
  use(r)
}
tk := time.NewTicker(time.Second)        // 周期触发，用完 Stop 防泄漏
defer tk.Stop()

// —— errors：错误链 ——
var ErrNotFound = errors.New("not found") // 造简单错误
err := fmt.Errorf("query: %w", ErrNotFound) // %w 包裹下层
errors.Is(err, ErrNotFound)              // true：沿 %w 链比较（替代 ==）
var pathErr *os.PathError
errors.As(err, &pathErr)                 // 提取链中特定类型
errors.Unwrap(err)                       // 取被包裹的下一层错误

// —— sync：并发原语 ——
var mu sync.Mutex
mu.Lock(); mu.Unlock()                   // 互斥锁
var rw sync.RWMutex
rw.RLock(); rw.RUnlock()                 // 读写锁：多读少写场景
var once sync.Once
once.Do(setup)                           // f 只执行一次（懒初始化 / 单例）
var sm sync.Map
sm.Store("k", 1)                        // 并发安全 map：Load/Store/Delete/Range
var wg sync.WaitGroup
for _, job := range jobs {
  wg.Add(1)
  go func() { defer wg.Done(); run(job) }()
}
wg.Wait()                                // 等一组 goroutine 全部完成

// —— context：取消传播 ——
root := context.Background()             // 根 context
ctx1, cancel1 := context.WithCancel(root) // 派生可手动取消的 ctx
defer cancel1()
ctx, cancel := context.WithTimeout(root, 5*time.Second) // 到时自动取消
defer cancel()                          // 务必 defer cancel()
ctx = context.WithValue(ctx, keyID, 42) // 挂请求域值
<-ctx.Done()                             // <-chan struct{}：取消信号

type User struct {
  ID   int        // 导出字段才会被编解码；键名 / omitempty 用 struct 标签控制
  Name string
}
u := User{ID: 1, Name: "Alice"}

// —— 字节级编解码 ——
b, _ := json.Marshal(u)                  // 值 → JSON 字节 {"ID":1,"Name":"Alice"}
b2, _ := json.MarshalIndent(u, "", "  ") // 带缩进美化
var u2 User
json.Unmarshal(b, &u2)                   // JSON → 值，第二参须传指针

// —— 流式编解码：直接对接 http / 文件 ——
json.NewEncoder(w).Encode(u)             // 写入 io.Writer（如 ResponseWriter）
json.NewDecoder(r.Body).Decode(&u2)      // 从 io.Reader 读取（如 r.Body）

// 02 章的 Scanner 骨架 + strconv 解析：从 stdin 求和
scanner := bufio.NewScanner(os.Stdin)
sum := 0
for scanner.Scan() {
  n, err := strconv.Atoi(scanner.Text()) // 字符串 → int
  if err != nil { continue }            // 非数字行跳过
  sum += n
}
if err := scanner.Err(); err != nil { log.Fatal(err) }

// —— fmt.Scan / Sscanf：按空白或格式读简单值 ——
var a, b int
fmt.Scan(&a, &b)                        // 输入 "3 5" → a=3 b=5
var major, minor int
fmt.Sscanf("v1.22", "v%d.%d", &major, &minor)

// —— 缓冲写：Create + NewWriter，defer 顺序决定数据是否有效 ——
f, err := os.Create("out.txt")
if err != nil { log.Fatal(err) }
defer f.Close()                         // 后执行：关句柄
w := bufio.NewWriter(f)
defer w.Flush()                         // 先执行：刷缓冲（LIFO）
fmt.Fprintf(w, "sum=%d\n", sum)

// 直接用默认 logger（输出到 stderr）
slog.Info("user login", "uid", 42, "ip", "1.2.3.4")
slog.Error("db failed", "err", err)   // key/value 成对给

// 换成 JSON 输出（生产常用），并设最低级别
h := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
  Level: slog.LevelInfo,
})
logger := slog.New(h)
slog.SetDefault(logger)              // 设为全局默认
// 输出：{"time":"...","level":"INFO","msg":"user login","uid":42,...}

// With：绑定一组公共字段，衍生子 logger
reqLog := logger.With("request_id", rid)
reqLog.Info("handling", "path", r.URL.Path) // 每条都自动带 request_id

func TestAdd(t *testing.T) {
  tests := []struct {
    name     string
    a, b     int
    want     int
  }{
    {"正数", 2, 3, 5},
    {"负数", -1, -1, -2},
  }
  for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {   // 子测试，独立显示
      if got := Add(tt.a, tt.b); got != tt.want {
        t.Errorf("got %d, want %d", got, tt.want)
      }
    })
  }
}

// 用 httptest 测 handler（无需真实端口）
func TestGetUser(t *testing.T) {
  req := httptest.NewRequest("GET", "/users/1", nil)
  w := httptest.NewRecorder()
  getUser(w, req)
  if w.Code != http.StatusOK {
    t.Errorf("want 200, got %d", w.Code)
  }
}

// ── 日常 ──────────────────────────
// go run .              编译并运行当前目录
// go build -o app .     产出单个二进制
// go test ./...         跑所有包的测试
// go fmt ./...          官方格式化（无配置项）

// ── 检查 ──────────────────────────
// go vet ./...          静态检查，提交前跑
// go test -race ./...   竞态检测，写并发后必跑

// ── 依赖 ──────────────────────────
// go mod init hello              初始化模块
// go get github.com/gin-gonic/gin  添加依赖
// go mod tidy                    补齐/清理依赖

// ── 查文档，不用开浏览器 ──────────
// go doc fmt.Println    看某个函数的签名与说明
// go doc -all strings   看整个包的全部导出内容

func BenchmarkAdd(b *testing.B) {
  for i := 0; i < b.N; i++ {   // b.N 自动调整
    Add(2, 3)
  }
}
// go test -bench=. -benchmem

// 必备命令
gofmt -w .          // 自动格式化（统一风格）
go vet ./...        // 静态分析常见错误
golangci-lint run   // 综合 linter（业界标准）

// 模糊测试：自动灌随机输入找 panic/边界 bug
func FuzzReverse(f *testing.F) {
  f.Add("hello")                 // 种子语料
  f.Fuzz(func(t *testing.T, s string) {
    r := Reverse(Reverse(s))
    if r != s {                  // 反转两次应还原
      t.Errorf("往返失败: %q != %q", r, s)
    }
  })
}
// go test -fuzz=FuzzReverse

// 用接口做 mock，无需第三方框架
type Store interface { Get(id int) (string, error) }

type fakeStore struct{ data map[int]string }
func (s fakeStore) Get(id int) (string, error) {
  return s.data[id], nil        // 测试用假实现
}

func TestService(t *testing.T) {
  svc := NewService(fakeStore{data: map[int]string{1: "Ann"}})
  got, _ := svc.Name(1)
  if got != "Ann" { t.Fatalf("got %q", got) }
}

// 测试辅助：临时目录用完自动清理
func TestWrite(t *testing.T) {
  dir := t.TempDir()             // 测试结束自动删除
  path := filepath.Join(dir, "f.txt")
  t.Cleanup(func() { /* 释放资源 */ })
  _ = path
}

import ("testing"; "testing/synctest"; "time")

func TestTimeout(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        start := time.Now()
        done := make(chan struct{})

        go func() {
            time.Sleep(24 * time.Hour)   // 假时钟：瞬间
            close(done)
        }()

        <-done
        t.Log(time.Since(start))   // 泡泡内读到 24h0m0s
    })
    // 墙上时钟0s，整个测试 PASS (0.00s)
}

// 泡泡内全员阻塞 → 立刻 panic，不用等 -timeout：
//   deadlock: all goroutines in bubble are blocked
// 泡泡结束时还有 goroutine 没退 → 也 panic：
//   deadlock: main bubble goroutine has exited but
//   blocked goroutines remain

package main

import (
  "net/http"
  "github.com/gin-gonic/gin"
)

func main() {
  r := gin.Default()           // 含 Logger + Recovery

  r.GET("/ping", func(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"message": "pong"})
  })

  // 路由分组：版本 + 参数
  v1 := r.Group("/api/v1")
  {
    v1.GET("/users/:id", func(c *gin.Context) {
      id := c.Param("id")                // 路径参数
      page := c.DefaultQuery("page", "1") // 查询参数
      c.JSON(http.StatusOK, gin.H{"id": id, "page": page})
    })
  }

  r.Run(":8080")                  // 监听 0.0.0.0:8080
}

type CreateUserReq struct {
  Name  string `json:"name"  binding:"required,min=2"`
  Email string `json:"email" binding:"required,email"`
  Age   int    `json:"age"   binding:"gte=0,lte=130"`
  Role  string `json:"role"  binding:"oneof=admin user"`
}

func createUser(c *gin.Context) {
  var req CreateUserReq
  if err := c.ShouldBindJSON(&req); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
    return                     // 别忘了 return！
  }
  // req 已通过校验，安全使用
  c.JSON(http.StatusCreated, req)
}

// 计时中间件
func Timer() gin.HandlerFunc {
  return func(c *gin.Context) {
    start := time.Now()
    c.Next()                   // 执行后续 handler
    log.Printf("%s %v", c.Request.URL.Path, time.Since(start))
  }
}

// 鉴权中间件
func Auth() gin.HandlerFunc {
  return func(c *gin.Context) {
    token := c.GetHeader("Authorization")
    uid, err := verify(token)
    if err != nil {
      c.AbortWithStatusJSON(http.StatusUnauthorized,
        gin.H{"error": "未授权"})
      return
    }
    c.Set("userID", uid)         // 传给后续 handler
    c.Next()
  }
}

r.Use(Timer())                 // 全局
authorized := r.Group("/admin", Auth())  // 仅该组