// 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 —— 第一个完整、可直接运行的 Go 程序
package main

import "fmt"

func main() {
  fmt.Println("Hello, Go!")
}

// ---- 在终端里依次执行 ----
// mkdir hello && cd hello
// go mod init hello     → 生成 go.mod
// go run .              → 编译并运行当前目录的包
// 输出：Hello, Go!

// 想要一个可分发的二进制文件：
// go build .            → 产出 hello（Windows 上自动叫 hello.exe）
// ./hello               → 直接运行，目标机器无需装 Go
// 注意：用 -o 指定名字时不会自动补 .exe，
// Windows 上要自己写 go build -o hello.exe .

package main        // ① 本文件属于 main 包 = 可执行程序

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

func main() {        // ③ 程序入口，{ 必须在这一行
  msg := "Hello, Go!"   // ④ 短变量声明，类型自动推断为 string
  fmt.Println(msg)
}

// 引入多个包时，第 ② 行改成括号块（顺序交给 gofmt 打理）：
// import (
//     "fmt"
//     "os"
//     "strings"
// )

// ❌ 花括号换行 —— 编译错误，不是风格问题
// func main()
// {
//     ...
// }

// ① 声明了不用 —— 编译错误，不是警告
func main() {
  x := 42
}
// ./main.go:4:3: declared and not used: x
// 临时绕过：_ = x

// ② import 了不用 —— 同样是错误
import (
  "fmt"
  "os"     // ./main.go:5:3: "os" imported and not used
)

// ③ 没有隐式转换：int 和 int64 也不能直接混算
var a int = 1
var b int64 = 2
// c := a + b
//   → invalid operation: a + b (mismatched types int and int64)
// var d int64 = a
//   → cannot use a (variable of type int) as int64 value in variable declaration
c := int64(a) + b   // ✅ 显式转换

// ④ 运行期 panic：编译零报错，跑起来才崩
func main() {
  s := []int{1, 2, 3}
  fmt.Println(s[10])
}
// panic: runtime error: index out of range [10] with length 3
// goroutine 1 [running]:
// main.main()
//     /path/main.go:8 +0x1d      ← 这一行就是出事位置

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)

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

// —— 字符串 · 格式化 · 文本 ——
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 章）

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())  // 仅该组

type APIError struct {
  Code int
  Msg  string
}
func (e *APIError) Error() string { return e.Msg }

// 收尾中间件：统一处理 c.Errors
func ErrorHandler() gin.HandlerFunc {
  return func(c *gin.Context) {
    c.Next()                          // 先跑完所有 handler
    if len(c.Errors) == 0 { return }
    err := c.Errors.Last().Err
    var ae *APIError
    if errors.As(err, &ae) {
      c.JSON(ae.Code, gin.H{"error": ae.Msg})
      return
    }
    c.JSON(http.StatusInternalServerError, gin.H{"error": "内部错误"})
  }
}

// handler 里只管把错误抛给收尾中间件
func getItem(c *gin.Context) {
  item, err := repo.Find(c.Param("id"))
  if err != nil { c.Error(err); return }
  c.JSON(http.StatusOK, item)
}

type UserHandler struct {
  db *sql.DB                         // 注入的依赖
}

func (h *UserHandler) Get(c *gin.Context) {
  id := c.Param("id")
  row := h.db.QueryRow("SELECT name FROM users WHERE id=$1", id)
  var name string
  if err := row.Scan(&name); err != nil {
    c.JSON(http.StatusNotFound, gin.H{"error": "不存在"})
    return
  }
  c.JSON(http.StatusOK, gin.H{"id": id, "name": name})
}

func main() {
  db := openDB()                     // 启动时初始化一次
  h := &UserHandler{db: db}          // 注入

  r := gin.Default()
  r.GET("/users/:id", h.Get)        // 方法即 handler
  r.Run(":8080")
}

func main() {
  r := gin.Default()
  r.Use(cors.Default())              // gin-contrib/cors
  r.GET("/healthz", func(c *gin.Context) { c.Status(200) })

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

  go func() {
    if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
      log.Fatal(err)
    }
  }()

  // 监听中断信号
  ctx, stop := signal.NotifyContext(context.Background(),
    os.Interrupt, syscall.SIGTERM)
  defer stop()
  <-ctx.Done()                       // 阻塞直到收到信号

  // 给在途请求 5 秒收尾
  shutCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
  defer cancel()
  srv.Shutdown(shutCtx)              // 优雅关闭
}

type User struct {
  Name string `json:"name"`
  Age  int    `json:"age"`
}

u := User{"Ann", 28}
t := reflect.TypeOf(u)          // 类型格：main.User
v := reflect.ValueOf(u)         // 值格：{Ann 28}

// 按字段遍历（Kind 是 Struct 才能 NumField）
for i := 0; i < t.NumField(); i++ {
  f := t.Field(i)               // StructField：名字、类型、标签
  fmt.Printf("%s=%v tag=%q\n", f.Name, v.Field(i), f.Tag.Get("json"))
}

// 第三定律：要改值，必须传指针再 Elem()，否则改的是副本
p := reflect.ValueOf(&u).Elem() // 指向 u 本体，可设置
if p.Field(0).CanSet() {
  p.Field(0).SetString("Bob")  // u.Name = "Bob"
}
fmt.Println(u.Name)             // Bob

type Config struct {
  Port    int    `env:"PORT"`
  Host    string `env:"HOST"`
  Debug   bool   `env:"DEBUG"`
}

// 反射遍历字段 → 读 env 标签 → 从环境变量填值
func Load(cfg any) error {
  v := reflect.ValueOf(cfg).Elem()   // 传 &Config，Elem 得可设置本体
  t := v.Type()
  for i := 0; i < t.NumField(); i++ {
    key := t.Field(i).Tag.Get("env")
    val, ok := os.LookupEnv(key)
    if key == "" || !ok { continue }
    f := v.Field(i)
    switch f.Kind() {              // 按底层种类转换
    case reflect.String:
      f.SetString(val)
    case reflect.Int:
      n, _ := strconv.Atoi(val)     // strconv 见 11 章
      f.SetInt(int64(n))
    case reflect.Bool:
      b, _ := strconv.ParseBool(val)
      f.SetBool(b)
    }
  }
  return nil
}

var cfg Config
Load(&cfg)                          // PORT=8080 DEBUG=1 → 自动填入

// 在源码里写一行指令（不是注释，go generate 会扫描它）
//go:generate stringer -type=Status
type Status int

const (
  Pending Status = iota
  Active
  Closed
)

// 跑一次生成，产出 status_string.go（含高效的 String()）
// $ go generate ./...

// 生成的代码是普通 Go：编译期检查、零反射、可读
// func (s Status) String() string {
//   ... return _Status_name[...] // 查表，纳秒级
// }

// P 的数量 = GOMAXPROCS，决定真正的并行度
fmt.Println(runtime.GOMAXPROCS(0))  // 传 0 只查询不修改
fmt.Println(runtime.NumCPU())        // 机器逻辑核数
fmt.Println(runtime.NumGoroutine())  // 当前活跃 goroutine 数

// 主动让出当前 P，把 M 交还给调度器（极少需要手动调）
runtime.Gosched()

// 并行 ≠ 并发：GOMAXPROCS=1 时 goroutine 仍并发（交替），
// 但同一时刻只有一个在真正执行——并行度由 P 的数量决定。

// 返回局部变量地址：Go 里安全，u 自动逃逸到堆
func newUser(name string) *User {
  u := User{Name: name}   // 看似栈变量
  return &u               // 地址逃逸 → 编译器改分配到堆，不是悬垂指针
}

// 用 -gcflags=-m 让编译器打印逃逸决策
// $ go build -gcflags=-m ./...
//   ./main.go:3:2: moved to heap: u        ← u 逃逸了
//   ./main.go:8:13: ... does not escape     ← 未逃逸，留栈上

// 常见逃逸诱因：赋给接口 / 被闭包捕获 / 存入更长命的对象
func logv(v any) { fmt.Println(v) } // 传入接口，实参常逃逸

// 环境变量调优（无需改代码）
// GOGC=200      触发阈值放宽一倍：GC 更少、内存更高
// GOGC=off      关闭比例触发（配合 GOMEMLIMIT 用）
// GOMEMLIMIT=512MiB  软上限，容器里配合内存 limit 设

// 代码内等价旋钮
debug.SetGCPercent(200)          // = GOGC=200
debug.SetMemoryLimit(512 << 20)  // = GOMEMLIMIT=512MiB

// 观测：真实内存与 GC 数据
var m runtime.MemStats
runtime.ReadMemStats(&m)
fmt.Printf("堆占用=%vMB GC次数=%v 累计STW=%v\n",
  m.HeapInuse>>20, m.NumGC, time.Duration(m.PauseTotalNs))

// 字段顺序影响大小：对齐 + padding 在作祟
type Bad  struct { a bool; b int64; c bool } // 24 字节（两处 padding）
type Good struct { b int64; a bool; c bool } // 16 字节（尾部一处）

fmt.Println(unsafe.Sizeof(Bad{}))   // 24
fmt.Println(unsafe.Sizeof(Good{}))  // 16
fmt.Println(unsafe.Alignof(int64(0)))  // 8：对齐边界

// unsafe 的正当用途之一：[]byte -> string 零拷贝（避免复制大缓冲）
func b2s(b []byte) string {
  return unsafe.String(unsafe.SliceData(b), len(b)) // Go 1.20+
}

// ① 线上服务：匿名 import 即自动挂 /debug/pprof
import _ "net/http/pprof"
go func() { log.Println(http.ListenAndServe("localhost:6060", nil)) }()

// 采集并分析（30s CPU 火焰图 / 当前堆 / goroutine 栈）
// $ go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
// $ go tool pprof http://localhost:6060/debug/pprof/heap
// $ curl localhost:6060/debug/pprof/goroutine?debug=2   # 所有 goroutine 栈

// ② 基准测试直接出 profile（配合 12 章 benchmark）
// $ go test -bench=. -cpuprofile=cpu.out -memprofile=mem.out
// $ go tool pprof -http=:8000 cpu.out   # 浏览器看火焰图

// pprof 交互里最常用三招：
//   top      按累计开销排热点函数
//   list Foo 看 Foo 逐行的耗时/分配
//   web      生成调用图 SVG

import "embed"

// ① 单个文件 → string / []byte
//go:embed version.txt
var version string

// ② 整个目录 → embed.FS（只读文件系统）
//go:embed templates/* static/*
var assets embed.FS

func main() {
  // 把嵌入的 static/ 当静态站点提供
  http.Handle("/static/", http.FileServer(http.FS(assets)))

  // 解析嵌入的整套 HTML 模板
  tmpl := template.Must(template.ParseFS(assets, "templates/*.html"))
  _ = tmpl
  http.ListenAndServe(":8080", nil)
}

// —— 文件顶部的约束行：必须在 package 之前、后跟一个空行 ——
//go:build linux && amd64

package store

// 慢的集成测试单独打 tag，日常快测不带它
//go:build integration
// $ go test -tags=integration ./...   # 显式带 tag 才编译/运行

// —— 交叉编译：一台机器产出所有平台 ——
// $ GOOS=linux   GOARCH=amd64 go build -o app-linux
// $ GOOS=windows GOARCH=amd64 go build -o app.exe
// $ GOOS=darwin  GOARCH=arm64 go build -o app-mac-m1
// 查看所有支持的平台组合：go tool dist list

/*
#include <stdlib.h>
#include <string.h>
*/
import "C"          // 必须紧跟在上面的 C 注释块之后，独占一行
import "unsafe"

func cLen(s string) int {
  cs := C.CString(s)          // Go string → C char*（在 C 堆上分配）
  defer C.free(unsafe.Pointer(cs)) // 必须手动释放，GC 不管这块！
  return int(C.strlen(cs))     // 调 C 的 strlen，返回值转回 Go int
}

db, err := sql.Open("postgres", dsn) // 启动时一次；返回的是连接池
if err != nil { log.Fatal(err) }
db.SetMaxOpenConns(25)          // 并发上限
db.SetMaxIdleConns(25)          // 空闲保活
db.SetConnMaxLifetime(5 * time.Minute) // 定期换新连接

// 查询：带 context 超时 + 参数化（防注入），rows 必须 Close
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
rows, err := db.QueryContext(ctx,
  "SELECT id, name FROM users WHERE age > $1", 18)
if err != nil { return err }
defer rows.Close()             // 忘了它 → 连接泄漏、池耗尽！
for rows.Next() {
  var id int; var name string
  if err := rows.Scan(&id, &name); err != nil { return err }
}

// 事务：defer Rollback 兜底，成功路径 Commit（提交后 Rollback 是 no-op）
tx, err := db.BeginTx(ctx, nil)
if err != nil { return err }
defer tx.Rollback()
if _, err := tx.ExecContext(ctx, "UPDATE ..."); err != nil { return err }
return tx.Commit()

# （Go 1.25.5, windows/amd64）
$ go build -o hello.exe hello.go            && ls -l hello.exe
2328064  # 2.22 MB —— 只是一句 fmt.Println
$ go build -ldflags "-s -w" -o hello-sw.exe hello.go
1586688  # 1.51 MB —— 去掉符号表与 DWARF

$ go build -o tui.exe .                      # Bubble Tea v2 + Lipgloss v2
5309440  # 5.06 MB
$ go build -ldflags "-s -w" -o tui-sw.exe .
3716608  # 3.54 MB

# 交叉编译（纯 Go 依赖时一条命令换平台，这是 Go 的最大优势之一）
$ GOOS=linux GOARCH=arm64 go build -o tool-linux-arm64 .

// go get charm.land/bubbletea/v2 charm.land/lipgloss/v2  ← 注意是 charm.land
package main

import (
    "fmt"
    tea "charm.land/bubbletea/v2"
    "charm.land/lipgloss/v2"
)

type model struct{ count int }

func (m model) Init() tea.Cmd { return nil }        // v2：只返回 Cmd

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:                          // v2：不再是 tea.KeyMsg
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        case "+":
            m.count++
        }
    }
    return m, nil
}

func (m model) View() tea.View {                     // v2：返回 tea.View
    s := lipgloss.NewStyle().Bold(true).Padding(1, 2)
    return tea.NewView(s.Render(fmt.Sprintf("计数 %d（+ 加一，q 退出）", m.count)))
}

func main() { tea.NewProgram(model{}).Run() }

# cgo 一旦启用，构建方式就变了
$ CGO_ENABLED=0 GOOS=linux go build .     # 纯 Go：任何机器上都能交叉编译
$ CGO_ENABLED=1 GOOS=linux go build .     # 带 cgo：需要目标平台的 C 工具链
#   常见报错：cgo: C compiler "gcc" not found
#   或运行时：/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.38' not found

# 实践上的解法：让 CI 在每个目标平台各构建一次
jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

# 「配置界面」的零依赖方案：本地起个 HTTP 服务，浏览器当界面
http.Handle("/", http.FileServer(http.FS(assets)))   // embed 进二进制
go openBrowser("http://127.0.0.1:8765")
http.ListenAndServe("127.0.0.1:8765", nil)