go-backend-handbook 0.0.0-stage → 1.0.0

package/00-linux.md

@@ -0,0 +1,175 @@
+# 第 0 章 开发机与 Linux 入门
+
+> 目标：能连上远程开发机、看懂机器状态、出问题能自己排查第一层。
+
+## 0.1 为什么后端要有一台"开发机"
+
+前端本地跑个 dev server 就够了；后端不行，因为依赖太多：
+
+- MySQL / Redis / Kafka 通常跑在机房或容器平台；
+- 服务要访问测试环境、注册中心、配置中心；
+- 编译产物、日志、抓包、压测都需要一台长期在线的 Linux。
+
+所以团队一般给每人一台**远程 Linux 开发机**，代码、编译、联调都在上面做。
+
+## 0.2 怎么连
+
+```bash
+# 1. 看本机 SSH 配置里有没有目标主机
+cat ~/.ssh/config
+
+# 2. 连接（主机别名来自 ssh config）
+ssh devbox
+
+# 3. 首次连接会问 yes/no，输入 yes
+# 4. 免密登录靠公钥：把 ~/.ssh/id_ed25519.pub 内容加到目标机 ~/.ssh/authorized_keys
+```
+
+`~/.ssh/config` 示例（**用占位符，不要照抄真实内网地址**）：
+
+```
+Host devbox
+  HostName devbox.example.com
+  Port 22
+  User demo
+  IdentityFile ~/.ssh/id_ed25519_demo
+  IdentitiesOnly yes
+  ServerAliveInterval 30
+```
+
+`ServerAliveInterval 30` 能防止长时间不操作被防火墙断开。
+
+### 连不上，按这个顺序排查
+
+| 现象 | 排查命令 | 常见原因 |
+|---|---|---|
+| `Connection timed out` | `ping devbox.example.com`、`nc -vz host 22` | 不在内网/VPN、防火墙、安全组 |
+| `Connection refused` | `nc -vz host 22` | sshd 没启动、端口错 |
+| `Permission denied (publickey)` | `ssh -vvv devbox` | 公钥没放对、权限不是 600 |
+| `Host key verification failed` | `ssh-keygen -R host` | 机器重装，主机指纹变了 |
+| 连上就断 | `ssh -vvv`，看服务端 `/var/log/auth.log` | 账号被锁、磁盘满、sshd 限制 |
+| 卡在 `Connecting` | `curl -v telnet://host:22` | 代理/跳板机问题 |
+
+固定排查套路：**网络通不通 → 端口开不开 → 认证过不过 → 登录后环境对不对**。
+
+```bash
+# 一次性确认四层
+ping -c 2 devbox.example.com
+nc -vz devbox.example.com 22
+ssh -o BatchMode=yes devbox 'echo ok'
+ssh devbox 'hostname; whoami; uptime'
+```
+
+## 0.3 登录后先看什么
+
+```bash
+hostnamectl          # 主机名、系统版本、内核
+whoami; id           # 我是谁、在哪些组
+pwd; df -h           # 当前目录、磁盘
+free -h              # 内存
+nproc                # CPU 核数
+uptime               # 负载
+top -b -n1 | head -20
+```
+
+**负载（load average）怎么读**：三个数分别是 1/5/15 分钟平均。经验值：`load > CPU 核数` 说明有排队，`load > 2 × 核数` 说明明显过载。但 IO 密集时 load 高不一定 CPU 忙，要结合 `%wa` 看。
+
+## 0.4 磁盘和内存满了怎么办
+
+### 磁盘
+
+```bash
+df -h                                  # 哪个分区满
+du -sh /var/* 2>/dev/null | sort -h    # 一级目录谁大
+du -sh /var/log/* | sort -h | tail     # 日志大户
+lsof +L1                               # 已删除但被进程占用的文件（空间不释放的元凶）
+```
+
+处理顺序：
+
+1. **先止血**：清日志前先确认不是审计/事故证据，优先 `truncate -s 0 file` 而不是 `rm`（`rm` 对正在写的文件不释放空间）。
+2. **找根因**：日志没轮转？临时文件没清？core dump？
+3. **加防线**：logrotate、磁盘告警阈值 80%/90%、容器日志大小限制。
+
+```bash
+# 安全清空一个正在被写的日志
+truncate -s 0 /var/log/app/app.log
+
+# 找 7 天前的临时文件（先看再删）
+find /tmp -type f -mtime +7 -ls | head
+```
+
+### 内存
+
+```bash
+free -h
+ps aux --sort=-%mem | head
+cat /proc/meminfo | head
+```
+
+Linux 会把空闲内存用作 page cache，`free` 的 `available` 才是真正可用的。如果 `available` 很低且 `swap` 在涨，就是真紧张。处理：限容器内存、查泄漏（pprof）、加 swap 只是缓冲不是方案。
+
+## 0.5 必会命令清单
+
+```bash
+# 文件
+ls -lah; cd; pwd; cp -r; mv; mkdir -p; find . -name '*.go'
+# 文本
+cat; less; head -n 50; tail -f; grep -rn 'keyword' .; sed -n '10,20p' file
+# 进程
+ps aux | grep app; top; kill -15 PID; kill -9 PID   # 先 15 再 9
+# 端口
+ss -lntp | grep 8080; lsof -i:8080
+# 网络
+curl -v; curl -sS -w '%{http_code} %{time_total}\n' -o /dev/null URL
+# 压缩
+tar -czf x.tar.gz dir/; tar -xzf x.tar.gz
+# 权限
+chmod 600 key; chown user:group file
+```
+
+`kill -15`（SIGTERM）让程序优雅退出，`kill -9` 强杀不给清理机会，生产环境优先 15。
+
+## 0.6 环境变量与 shell
+
+```bash
+export APP_ENV=dev
+env | grep APP_
+echo $PATH
+which go
+```
+
+`~/.bashrc` 放交互式配置，`~/.bash_profile` 放登录配置。**不要把密码写进 shell 历史**：用 `read -s` 或密钥管理。
+
+## 习题
+
+1. 写出连接 `devbox.example.com`、用户 `demo`、密钥 `~/.ssh/id_ed25519_demo` 的 ssh config 片段。
+2. `ssh` 报 `Permission denied (publickey)`，列出至少 4 个可能原因和验证命令。
+3. 磁盘 100%，`du` 显示 `/var/log` 只有 2G，但 `df` 显示少了 20G，怎么查？
+4. `free -h` 显示 free 很低但 available 很高，正常吗？为什么？
+5. load average = 16，机器 8 核，说明什么？还要看哪个指标才能判断是 CPU 还是 IO 问题？
+6. 用一条命令找出当前监听 8080 端口的进程。
+7. 为什么清理正在写入的日志推荐 `truncate` 而不是 `rm`？
+8. 写一个命令，输出某 URL 的 HTTP 状态码和总耗时。
+
+## 参考答案
+
+<details>
+<summary>展开</summary>
+
+1.
+```
+Host devbox
+  HostName devbox.example.com
+  User demo
+  IdentityFile ~/.ssh/id_ed25519_demo
+  IdentitiesOnly yes
+```
+2. 公钥未加入 `authorized_keys`；`~/.ssh` 或公钥权限过宽（应为 700/600）；ssh config 指错 IdentityFile；服务端禁用该用户或 `PubkeyAuthentication no`；密钥类型不被服务端支持。验证：`ssh -vvv devbox` 看 `Offering public key` 与 `Authentications that can continue`；`ssh devbox 'ls -ld ~ ~/.ssh ~/.ssh/authorized_keys'`。
+3. `lsof +L1` 找 deleted 但被进程占用的文件；常见是应用日志被 `rm` 后进程仍持有 fd。
+4. 正常。page cache 会占用 free，`available` 估算可回收部分。真紧张看 `available` 和 swap 使用。
+5. 有明显排队/过载。还要看 `top` 的 `%us/%sy/%wa`、`iostat -x 1` 的 `%util` 和 await。
+6. `ss -lntp | grep :8080` 或 `lsof -i:8080`。
+7. `rm` 只删目录项，进程仍持有 fd，空间不释放；`truncate` 直接把文件长度置 0，立即释放。
+8. `curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' https://api.example.com/healthz`
+</details>

package/01-go-basics.md

@@ -0,0 +1,402 @@
+# 第 1 章 Go 语言基础（JS 对照版）
+
+> 目标：会 JS 的人，2 小时能读懂 Go 业务代码，1 周能写。
+> 重点不是穷举语法，而是**JS 有但 Go 没有的东西**，以及**Go 有而 JS 没有的东西**。
+
+## 1.1 先建立一个心智模型
+
+| JS | Go |
+|---|---|
+| 动态类型，运行时才知道类型 | 静态类型，编译期就检查 |
+| 单线程 + 事件循环 | 多协程 + 调度器，真并发 |
+| 函数是第一公民 | 函数也是值，但更常用接口 |
+| `class` + 原型 | `struct` + 方法，没有继承 |
+| 异常 `try/catch` | 错误是返回值 `if err != nil` |
+| `null` / `undefined` | 每种类型有零值，`nil` 只用于指针/接口/map/slice/channel/func |
+| `npm` | `go mod` |
+| `node app.js` | `go run .` 开发 / `go build` 出二进制 |
+| 自动 GC | 自动 GC（并发三色标记） |
+
+## 1.2 一个最小程序
+
+```go
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Println("Hello, 后端")
+}
+```
+
+```bash
+go run .        # 编译到临时目录并立即执行
+go build -o app .   # 只编译，产出 ./app 二进制
+./app           # 运行产物
+```
+
+### `go run` 和 `go build` 到底差在哪
+
+| | `go run` | `go build` |
+|---|---|---|
+| 产物 | 编译到临时目录，执行完通常不可见 | 当前目录生成可执行文件（`-o` 指定名） |
+| 用途 | 本地快速调试 | 打发布包 / CI / Docker 镜像 |
+| 速度 | 每次都要编译（有缓存会快） | 编译一次，可以反复跑 |
+| 环境 | 需要 Go 工具链 | 只需要二进制（静态链接时无需 Go） |
+| 能不能上线 | 不能 | 能 |
+
+> 上线永远用 `go build` 的产物。`go run` 只是开发工具，它不会热更新，改了代码要重新跑。
+
+交叉编译（在 Linux 上给别的平台出包）：
+
+```bash
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o app .
+```
+
+`-trimpath` 去掉本机路径，`-s -w` 去符号表减小体积，`CGO_ENABLED=0` 产出静态二进制、方便塞进 scratch 镜像。
+
+## 1.3 变量、常量、零值
+
+```go
+var a int = 1
+b := 2                 // := 只能在函数内
+const MaxRetry = 3
+
+var s string           // ""
+var i int              // 0
+var p *int             // nil
+var ok bool            // false
+```
+
+**零值设计**让 Go 不需要构造函数也能安全使用很多类型：`var buf bytes.Buffer` 直接能用。
+
+JS 里 `let x;` 是 `undefined`，Go 里是类型的零值，不会出现 `undefined is not a function`。
+
+## 1.4 基础类型
+
+```go
+bool
+string
+int  int8 int16 int32 int64
+uint uint8 ... uintptr
+float32 float64
+byte   // = uint8
+rune   // = int32，表示一个 Unicode 码点
+```
+
+**钱不要用 float**。用 `int64` 存"分"，或用 `decimal` 库。
+
+```go
+type Money int64 // 单位：分
+
+func (m Money) Yuan() string {
+    return fmt.Sprintf("%d.%02d", int64(m)/100, int64(m)%100)
+}
+```
+
+字符串在 Go 里是**不可变字节序列**，`len(s)` 是字节数不是字符数：
+
+```go
+s := "你好"
+fmt.Println(len(s))         // 6（UTF-8 字节）
+fmt.Println(utf8.RuneCountInString(s)) // 2
+```
+
+## 1.5 数组、切片、map
+
+```go
+arr := [3]int{1, 2, 3}      // 数组：长度是类型的一部分，少用
+s := []int{1, 2, 3}         // 切片：最常用
+s = append(s, 4)
+
+m := map[string]int{"a": 1}
+m["b"] = 2
+v, ok := m["c"]             // 不存在时 v=0, ok=false
+if !ok { /* 处理 */ }
+delete(m, "a")
+```
+
+### 切片最常见的坑：共享底层数组
+
+```go
+a := []int{1, 2, 3, 4}
+b := a[1:3]        // b 和 a 共用底层数组
+b[0] = 99
+fmt.Println(a)     // [1 99 3 4]
+```
+
+要独立副本就 `append([]int(nil), b...)` 或 `slices.Clone(b)`。
+
+### nil 切片 vs 空切片
+
+```go
+var a []int          // nil，len=0，可 append
+b := []int{}         // 非 nil，len=0
+```
+
+JSON 序列化时 `nil` 变 `null`，空切片变 `[]`。接口返回列表时通常要保证是 `[]` 而不是 `null`。
+
+## 1.6 结构体与方法
+
+```go
+type Account struct {
+    UID     string
+    Balance int64 // 分
+}
+
+func (a *Account) Deposit(amount int64) error {
+    if amount <= 0 {
+        return fmt.Errorf("amount must be positive: %d", amount)
+    }
+    a.Balance += amount
+    return nil
+}
+```
+
+- **值接收者**：拷贝一份，改不到原对象。
+- **指针接收者**：能修改原对象，且避免大结构体拷贝。
+- 一个类型的方法集要求一致：要么都用指针接收者，要么都用值，混用容易踩接口实现问题。
+
+JS 的 `this` 在 Go 里是显式接收者，没有 `this` 绑定问题。
+
+### 嵌入（组合代替继承）
+
+```go
+type Base struct{ ID int64 }
+func (b Base) Describe() string { return fmt.Sprintf("id=%d", b.ID) }
+
+type User struct {
+    Base        // 匿名嵌入，User 自动获得 Describe 方法
+    Name string
+}
+```
+
+Go 没有 `extends`，只有组合。接口也是隐式实现：
+
+```go
+type Reader interface{ Read(p []byte) (int, error) }
+
+type MyReader struct{}
+func (MyReader) Read(p []byte) (int, error) { return 0, io.EOF }
+
+var r Reader = MyReader{} // 不用 implements 声明
+```
+
+## 1.7 错误处理
+
+Go 的错误是普通值：
+
+```go
+func Load(id string) (*Account, error) {
+    if id == "" {
+        return nil, errors.New("empty id")
+    }
+    a, err := repo.Get(id)
+    if err != nil {
+        return nil, fmt.Errorf("load account %s: %w", id, err)
+    }
+    return a, nil
+}
+```
+
+- `%w` 包装错误，保留链，可用 `errors.Is/As` 判断。
+- 不要写 `panic` 处理业务错误；panic 只用于不可恢复的程序错误。
+- 错误信息要带**上下文**，但不要带密码、token、完整身份证号。
+
+```go
+if errors.Is(err, sql.ErrNoRows) {
+    return ErrNotFound
+}
+
+var bizErr *BizError
+if errors.As(err, &bizErr) {
+    log.Println(bizErr.Code)
+}
+```
+
+### 自定义错误
+
+```go
+type BizError struct {
+    Code string
+    Msg  string
+}
+func (e *BizError) Error() string { return e.Code + ": " + e.Msg }
+```
+
+## 1.8 defer / panic / recover
+
+```go
+func ReadFile(path string) error {
+    f, err := os.Open(path)
+    if err != nil { return err }
+    defer f.Close()          // 函数返回前执行，后进先出
+    // ...
+    return nil
+}
+```
+
+`defer` 常用于释放资源、解锁、记录耗时。注意：`defer` 在循环里会堆积，循环内要显式调用或用小函数包一层。
+
+```go
+func SafeGo(fn func()) {
+    go func() {
+        defer func() {
+            if r := recover(); r != nil {
+                log.Printf("panic: %v", r)
+            }
+        }()
+        fn()
+    }()
+}
+```
+
+goroutine 里 panic 不 recover 会让**整个进程退出**，这一点和 JS 的单线程错误处理完全不同。
+
+## 1.9 接口与依赖注入
+
+```go
+type AccountRepo interface {
+    Get(ctx context.Context, uid string) (*Account, error)
+    Save(ctx context.Context, a *Account) error
+}
+
+type RechargeService struct {
+    repo AccountRepo
+}
+
+func NewRechargeService(repo AccountRepo) *RechargeService {
+    return &RechargeService{repo: repo}
+}
+```
+
+测试时传内存实现，生产传 MySQL 实现。这就是 `mini-coin` 的结构。
+
+## 1.10 泛型（了解即可）
+
+```go
+func Map[T, U any](in []T, f func(T) U) []U {
+    out := make([]U, 0, len(in))
+    for _, v := range in {
+        out = append(out, f(v))
+    }
+    return out
+}
+```
+
+Go 1.18+ 支持泛型，但业务代码里不要滥用，接口和代码生成往往更直观。
+
+## 1.11 包与模块
+
+```bash
+go mod init minicoin     # 生成 go.mod
+go get github.com/redis/go-redis/v9
+go mod tidy              # 清理/补齐依赖
+```
+
+目录约定：
+
+```
+cmd/server/main.go      # 可执行入口
+internal/service/       # 只允许本模块引用
+pkg/                    # 允许外部引用（可选）
+api/                    # proto / openapi
+migrations/             # SQL 迁移
+```
+
+`internal` 是 Go 的强制访问控制：模块外的代码无法 import。
+
+## 1.12 代码格式与静态检查
+
+```bash
+gofmt -w .
+go vet ./...
+staticcheck ./...    # 可选，需要安装
+golangci-lint run    # 团队常用聚合工具
+```
+
+**`gofmt` 不是可选风格问题**，它是 Go 社区统一的格式，CI 里通常要求 `gofmt -l .` 输出为空。
+
+## 1.13 一个完整的业务小例子
+
+```go
+package service
+
+import (
+    "context"
+    "errors"
+    "fmt"
+)
+
+var ErrInvalidAmount = errors.New("invalid amount")
+
+type RechargeRequest struct {
+    ReqID  string
+    UID    string
+    Amount int64
+}
+
+type RechargeResult struct {
+    OrderID string
+    Balance int64
+    Duplicated bool
+}
+
+func (s *RechargeService) Recharge(ctx context.Context, req RechargeRequest) (RechargeResult, error) {
+    if req.ReqID == "" || req.UID == "" {
+        return RechargeResult{}, fmt.Errorf("req_id/uid required")
+    }
+    if req.Amount <= 0 {
+        return RechargeResult{}, ErrInvalidAmount
+    }
+    return s.doRecharge(ctx, req)
+}
+```
+
+## 习题
+
+1. `var s []int` 和 `s := []int{}` 有什么区别？JSON 序列化结果分别是什么？
+2. 下面代码输出什么？为什么？
+```go
+a := []int{1,2,3,4}
+b := a[:2]
+b = append(b, 99)
+fmt.Println(a)
+```
+3. 写一个 `Money` 类型，方法 `String()` 返回 `"12.34"`，输入 1234。
+4. `errors.New` 和 `fmt.Errorf("%w")` 的区别是什么？什么时候用哪个？
+5. 为什么业务错误不建议用 `panic`？
+6. 写一个函数 `Divide(a, b int) (int, error)`，b 为 0 时返回错误。
+7. 解释 `go run .` 和 `go build .` 的区别，上线应该用哪个？
+8. 一个方法用指针接收者，另一个用值接收者，会有什么潜在问题？
+9. `defer` 在循环里写 10 万次会怎样？怎么改？
+10. 接口 `AccountRepo` 在测试和生产分别怎么用？这体现了什么设计原则？
+
+## 参考答案
+
+<details>
+<summary>展开</summary>
+
+1. 前者是 nil 切片，JSON 为 `null`；后者是空切片，JSON 为 `[]`。API 返回列表时通常用后者。
+2. `[1 2 99 4]`。`b` 与 `a` 共享底层数组，`append` 在容量足够时直接写回原数组。
+3.
+```go
+type Money int64
+func (m Money) String() string {
+    return fmt.Sprintf("%d.%02d", int64(m)/100, int64(m)%100)
+}
+```
+4. `errors.New` 创建无上下文的哨兵错误；`fmt.Errorf("%w")` 包装已有错误并附加上下文，保留 `errors.Is/As` 链。需要携带上下文用后者。
+5. panic 会中断正常控制流，未 recover 时进程退出；业务错误是可预期的，应作为返回值逐层处理。
+6.
+```go
+func Divide(a, b int) (int, error) {
+    if b == 0 { return 0, errors.New("division by zero") }
+    return a / b, nil
+}
+```
+7. `go run` 编译到临时目录立即执行，适合开发；`go build` 产出可交付二进制，上线、镜像、CI 都用它。
+8. 方法集不一致：值类型只拥有值接收者方法，指针类型拥有两者。若接口要求指针方法，传值会编译失败；也容易误以为修改生效实际没生效。
+9. 每次 `defer` 都注册一个延迟调用，循环内会堆积到函数返回才执行，可能内存暴涨或耗尽 fd。应把循环体抽成函数，在函数内 defer。
+10. 测试传内存实现，生产传 MySQL 实现；体现依赖倒置/面向接口编程，业务层不依赖具体存储。
+</details>