go-backend-handbook 1.0.0 → 1.0.1

package/00-linux.md

@@ -2,6 +2,18 @@
 
 > 目标：能连上远程开发机、看懂机器状态、出问题能自己排查第一层。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 远程 Linux shell | 本机终端，只是换了台机器 | 代码、进程、依赖、环境变量全在远端 |
+> | 进程 | `node app.js` 启动的进程 | 后端进程长期驻留，要管 PID、信号、日志轮转 |
+> | systemd | `pm2` 的自动重启 | 系统级守护，开机自启、崩溃拉起 |
+> | top / htop | Chrome 任务管理器 | 看整机 CPU/内存/磁盘 |
+> | 磁盘满 | `node_modules` 占满硬盘 | 后端会导致日志写失败、DB 异常 |
+> | 没有对应物 | — | nginx / Docker / k8s 是纯后端概念，不用硬套 |
+
+
 ## 0.1 为什么后端要有一台"开发机"
 
 前端本地跑个 dev server 就够了；后端不行，因为依赖太多：

package/01-go-basics.md

@@ -3,6 +3,9 @@
 > 目标：会 JS 的人，2 小时能读懂 Go 业务代码，1 周能写。
 > 重点不是穷举语法，而是**JS 有但 Go 没有的东西**，以及**Go 有而 JS 没有的东西**。
 
+> **JS 类比使用说明**：本章类比最多，但请始终记住——模块/包、对象/struct、数组/slice、异常/error、Promise/goroutine、AbortController/context 都只是**相似的抓手**，不是等价物。Go 有编译期类型检查、固定零值、显式错误返回和真正的多核并发，这些是 JS 没有的。
+
+
 ## 1.1 先建立一个心智模型
 
 | JS | Go |

package/02-service-architecture.md

@@ -2,6 +2,18 @@
 
 > 目标：拿到一个陌生后端项目，能在 20 分钟内从入口追到一个请求的落库路径。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | main 入口 | `index.js` 的 bootstrap | 负责装配依赖，一个进程一个 main |
+> | handler | Express / Koa route handler | 只做协议层，不含业务规则 |
+> | service | 前端 store / service 模块 | 多请求并发执行，共享进程内存 |
+> | repository | 封装 `fetch` 的 api client | 这里封装 SQL / 缓存 |
+> | proto / OpenAPI | TypeScript 类型 + 接口契约 | 同时约束服务端和客户端 |
+> | 依赖注入 | 构造函数传依赖 | 便于测试替换 |
+
+
 ## 2.1 分层不是形式主义
 
 ```

package/03-concurrency.md

@@ -2,6 +2,21 @@
 
 > 目标：理解 Go 的并发模型，能写出"不漏、不重、不崩"的并发代码。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | goroutine | `Promise` / 异步任务 | 由 Go 运行时调度，可真并行 |
+> | `go f()` | 不 `await` 的调用 | 主流程不等待，但协程仍执行 |
+> | channel | `postMessage` / AsyncIterator | 有缓冲、阻塞、关闭语义 |
+> | `select` | `Promise.race` | 同时等多个 channel，可配超时 |
+> | WaitGroup | `Promise.all` | 只等结束，不收返回值 |
+> | context | `AbortController` / `AbortSignal` | 显式沿调用链传递 |
+> | Mutex | 无直接等价物 | JS 主线程默认没有共享内存竞争 |
+> | worker pool | `p-limit` | 固定协程 + channel |
+> | panic | 未捕获异常 | 不 recover 会让整个进程退出 |
+
+
 ## 3.1 进程、线程、协程
 
 | 概念 | 是什么 | 开销 |

package/04-mysql.md

@@ -2,6 +2,18 @@
 
 > 目标：能独立完成建表、建索引、写查询、加字段、改类型、数据迁移、刷数据，并知道容量边界在哪。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 表 | 一类对象的数组 | 有 schema、约束、主键 |
+> | 行 | 数组里的对象 | 字段类型固定，有 NULL 语义 |
+> | 索引 | 额外建的查找表（类似 Map） | 占空间、拖慢写入 |
+> | 事务 | IndexedDB transaction 有点像 | SQL 还有隔离级别、锁、死锁 |
+> | JOIN | 按 id 手动 merge 两个数组 | 数据库靠执行计划完成 |
+> | 迁移 | schema 的版本提交 | DDL 可能锁表 |
+
+
 ## 4.1 先建三张表
 
 ```sql

package/05-database-selection.md

@@ -2,6 +2,18 @@
 
 > 目标：知道每类数据库解决什么问题，能在评审会上说出"为什么选它、不选它"。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | MySQL / PostgreSQL | 关系型数据库，像有严格 schema 的对象表 | SQL、事务、约束是核心 |
+> | MongoDB | 文档库，数据形态接近 JS 对象 | 但查询、索引、一致性、部署都不同，不是"存 JSON" |
+> | Redis | 跨进程共享的 `Map` + TTL | 不是 localStorage |
+> | ClickHouse | 列式分析库 | 适合聚合分析，不适合高频单行更新 |
+> | Elasticsearch | 搜索索引 | 不是主存储，最终一致 |
+> | 选型 | 没有银弹 | 按读写模式、一致性、规模、团队成本选 |
+
+
 ## 5.1 选型先问五个问题
 
 1. **数据模型**：强关系（订单-支付-退款）还是文档/键值/时序/图？

package/06-redis.md

@@ -2,6 +2,17 @@
 
 > 目标：会用 Redis 做缓存、锁、限流、计数，并能处理穿透/击穿/雪崩、大 key、热 key。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | Redis | 跨进程共享的 `Map`，可设 TTL | 不是 localStorage：服务端共享、有淘汰策略 |
+> | 缓存 | React Query / SWR 的缓存 | 所有用户共享，key 设计错会串数据 |
+> | 分布式锁 | 多个标签页共享一把锁 | 跨机器、靠 TTL + 唯一 token |
+> | 限流 | 前端按钮防抖 | 服务端限流保护整个系统 |
+> | 大 key | 一个巨大 JSON 塞进一个 key | 单线程执行命令，大 value 会卡住所有请求 |
+
+
 ## 6.1 数据结构与典型用途
 
 | 结构 | 命令示例 | 用途 |

package/07-message-queue.md

@@ -2,6 +2,17 @@
 
 > 目标：理解 MQ 的三种价值（解耦、异步、削峰），能设计不丢、不重、可追踪的消费链路。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | MQ | 后端事件总线，类似 `EventTarget` | 持久化、跨进程、可重放 |
+> | producer | `dispatchEvent` | 可能失败、重复、乱序 |
+> | consumer | `addEventListener` | 多实例、offset/ack、失败重投 |
+> | topic | 事件类型频道 | 有分区、顺序、保留策略 |
+> | 幂等 | 前端防重复提交 | 服务端消费端必须自己保证 |
+
+
 ## 7.1 为什么需要 MQ
 
 支付成功后要做 5 件事：更新订单、发短信、发券、上报、通知风控。

package/08-api-and-rpc.md

@@ -2,6 +2,16 @@
 
 > 目标：设计一个让前端好用、三年后还能兼容、出问题能定位的接口。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | HTTP 接口 | 你平时调的 REST API | 契约、版本、错误码都要稳定 |
+> | gRPC / proto | TypeScript interface + 生成 SDK | HTTP/2 + protobuf 二进制 |
+> | interceptor | Express middleware | 可做鉴权、日志、超时 |
+> | 超时 / 重试 | `fetch` 的 AbortSignal + 重试 | 必须退避、有上限、只重试幂等操作 |
+
+
 ## 8.1 HTTP 接口设计要点
 
 ### URL 用名词，动作用方法

package/09-observability.md

@@ -2,6 +2,17 @@
 
 > 目标：线上出问题时，能在 5 分钟内回答"哪个请求、哪一步、为什么慢/失败"。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 配置 | `.env` / `import.meta.env` | 多环境、可热更新 |
+> | 结构化日志 | `console.log({ ... })` | 可采集、检索、聚合、报警 |
+> | request id | Network 面板的请求标识 | 要跨服务透传 |
+> | trace | Network waterfall | 跨服务、跨进程 |
+> | metrics | 前端埋点 / Performance API | 聚合指标，不是单条日志 |
+
+
 ## 9.1 配置管理
 
 ### 分层

package/10-resilience.md

@@ -2,6 +2,17 @@
 
 > 目标：流量翻 10 倍、下游挂掉时，服务还能活着，核心功能还能用。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | QPS | 每秒 `fetch` 数量 | 服务端是所有客户端之和 |
+> | 限流 | 按钮节流 | 服务端限流是全局的 |
+> | 熔断 | 失败后暂停重试 | 按下游统计，半开试探 |
+> | 降级 | 兜底数据 / 隐藏入口 | 要有明确业务策略 |
+> | 重试 | `fetch` 重试 | 退避 + 上限 + 幂等 |
+
+
 ## 10.1 先厘清几个概念
 
 | 概念 | 作用 | 类比 |

package/11-monitoring.md

@@ -2,6 +2,16 @@
 
 > 目标：搭出一套"出问题 1 分钟内知道、5 分钟内定位"的监控。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | Prometheus | 时序数据库 + 查询语言 | 拉模式采集，PromQL 按窗口计算 |
+> | Grafana | 图表看板 | 只负责展示 |
+> | 报警 | 前端错误监控告警 | 阈值 + 持续时间 + 分级 + 静默 |
+> | SLI / SLO | Core Web Vitals 目标 | 按成功率/延迟/饱和度定义 |
+
+
 ## 11.1 监控四层
 
 | 层 | 指标 |

package/12-testing.md

@@ -2,6 +2,17 @@
 
 > 目标：用最低成本获得最高信心。测试不是"写完补"，是设计的一部分。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | `go test` | Vitest / Jest | 编译执行、可并行、表驱动 |
+> | 表驱动 | `test.each` | 用结构体切片描述用例 |
+> | mock | `vi.mock` / `jest.mock` | Go 常用接口注入 |
+> | 集成测试 | msw 但连真依赖 | miniredis / testcontainers |
+> | `-race` | 无直接等价物 | 检测共享内存数据竞争 |
+
+
 ## 12.1 测试金字塔
 
 ```

package/13-performance-debug.md

@@ -2,6 +2,16 @@
 
 > 目标：能量化性能、找到瓶颈、复现并修掉线上 bug。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | k6 | 就是 JS 脚本 | 不代表被测服务是 JS |
+> | pprof | Chrome Performance | CPU / heap / goroutine |
+> | 火焰图 | flame chart | 按调用栈聚合 |
+> | dlv | DevTools 断点 | 常连远程进程 |
+
+
 ## 13.1 压测基本概念
 
 | 指标 | 含义 |

package/14-security.md

@@ -2,6 +2,17 @@
 
 > 目标：不写出能被一条 curl 打穿的接口。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 鉴权 | 登录态 / token | 服务端必须重新校验 |
+> | XSS | 渲染转义 | 后端按上下文输出转义 |
+> | CSRF | 自动带 cookie 的风险 | SameSite / CSRF token |
+> | SQL 注入 | 不要拼 SQL | 类比不要 `eval` 用户输入 |
+> | 签名 | 请求签名 | 防重放要时间戳 + nonce |
+
+
 ## 14.1 认证 vs 授权
 
 - **认证 Authentication**：你是谁（登录、token、证书）；

package/15-development-process.md

@@ -2,6 +2,16 @@
 
 > 目标：知道一个需求从提出到上线，后端要做哪些动作、每个动作产出什么。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 需求评审 | 前端需求评审 + 技术方案 | 后端多容量、兼容、回滚 |
+> | 分支 + CI | PR + GitHub Actions | 还要迁移和部署证据 |
+> | 灰度 | 前端灰度 / CDN 回滚 | 后端要考虑数据兼容 |
+> | 复盘 | 故障复盘 | 时间线、影响面、根因、改进项 |
+
+
 ## 15.1 全流程
 
 ```

package/16-api-docs.md

@@ -2,6 +2,17 @@
 
 > 目标：写出前端不用问人就能对接的接口文档，并且自己能在提测前把接口验证一遍。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 接口文档 | 你平时看的 YApi / OpenAPI | 必须和实现同步 |
+> | curl | Copy as cURL | 能看到原始 header / 状态码 / 耗时 |
+> | Postman | 图形化 fetch + 断言 | 手工回归和集合运行 |
+> | grpcurl | 命令行版 Postman | 针对 gRPC |
+> | Mock | 前端 mock 数据 | 前后端并行开发 |
+
+
 ## 16.1 接口文档由谁写、什么时候写
 
 **后端写，和代码一起提交，评审时一起看。**

package/17-deploy-ops.md

@@ -2,6 +2,16 @@
 
 > 目标：能把自己的 Go 服务打包、部署、暴露、扩容、回滚，并知道运维该学到什么程度。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | Docker | 服务 + 依赖的可复制运行环境 | 比 lockfile + Node 版本更彻底 |
+> | nginx | 反向代理 / 静态服务器 | 还要管超时、限流、TLS |
+> | k8s | 没有 JS 对应物 | 容器编排，别硬类比 |
+> | 微服务 | 微前端有点像 | 网络调用和数据一致性完全不同 |
+
+
 ## 17.1 一次发布要解决什么
 
 ```

package/18-ai-assisted.md

@@ -2,6 +2,16 @@
 
 > 目标：把 AI 当"结对程序员 + 代码检索器 + 测试生成器"，而不是"代写一切的黑盒"。
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | AI 写代码 | Copilot / Claude Code | 要给足上下文和约束 |
+> | AI 读代码库 | 把相关文件喂给模型 | 先定位、再改、再验证 |
+> | AI 写测试 | 生成表驱动用例 | 边界条件必须人审 |
+> | AI 排障 | 分析日志和堆栈 | 看不到线上真实状态 |
+
+
 ## 18.1 AI 最擅长什么
 
 | 场景 | 效果 |

package/19-appendix.md

@@ -1,5 +1,14 @@
 # 第 19 章 附录：容量估算、速查表与知识地图
 
+> **JS 类比速查**（帮助建立直觉，不表示语义等价；差异列必须看）
+>
+> | 后端概念 | JS / 前端里的近似物 | 关键差异 |
+> |---|---|---|
+> | 容量估算 | 前端性能预算 | 后端按 QPS、延迟、存储、增长估算 |
+> | 排障决策树 | 浏览器 Problems 面板的思路 | 后端要按指标→日志→trace 逐层缩小 |
+> | 知识地图 | 前端技能树 | 后端多了数据、网络、运维、稳定性 |
+
+
 ## 19.1 容量估算模板
 
 ```

package/README.md

@@ -7,6 +7,31 @@
 
 ---
 
+## JS 类比怎么用（先读这一节）
+
+你会 JS，这是优势，也是陷阱。本讲义在**两者真有相似概念**时会用 JS 打比方，帮你快速建立直觉：
+
+| 后端概念 | 可以类比的 JS / 前端概念 | 必须记住的差异 |
+|---|---|---|
+| 包 / 模块 | npm 包、ES Module | Go 按 import path 引用，首字母大写才导出 |
+| struct | 固定形状的对象 | 有编译期类型和零值，不是任意 JSON |
+| slice | 数组 | 带 len/capacity，可能共享底层数组 |
+| map | `Map` / 对象 | 遍历顺序不保证 |
+| error 返回值 | `throw` / `catch` | Go 把预期错误作为返回值显式处理 |
+| `defer` | `try/finally` | 函数退出时执行，多个按 LIFO |
+| interface | TypeScript interface / 鸭子类型 | Go 是结构化满足，接口通常很小 |
+| goroutine | `Promise` / async 任务 | 真并行，不是单线程事件循环 |
+| context | `AbortController` / `AbortSignal` | 显式沿调用链传递 |
+| 拦截器 | Express / Koa middleware | gRPC 的响应和错误语义不同 |
+| 链路追踪 | Network waterfall | 跨服务、跨进程传播 |
+| `go test` | Vitest / Jest | 编译执行、表驱动、`-race` |
+| k6 压测脚本 | 就是 JS 脚本 | 脚本语言不代表被测服务是 JS |
+| proto / OpenAPI | TypeScript 类型 + 接口契约 | 同时生成服务端接口和客户端 SDK |
+
+**JS 没有对应物的，不硬套**：指针、数据竞争、互斥锁、SQL 事务隔离级别、Docker、Kubernetes、集群、容量规划、数据库迁移的锁表风险。这些章节直接讲后端模型，类比只用来降低入门门槛，**不能替代对语义的理解**。
+
+---
+
 ## 这套讲义解决什么问题
 
 前端转后端最常见的断层不是语法，而是**系统观**：

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "go-backend-handbook",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Go 后端开发全景讲义：语言、并发、数据库、缓存、消息队列、gRPC、监控告警、测试、性能、安全、部署与完整开发流程",
-  "keywords": ["go", "golang", "backend", "handbook", "tutorial", "mysql", "redis", "kafka", "grpc", "kubernetes"],
+  "keywords": [
+    "go",
+    "golang",
+    "backend",
+    "handbook",
+    "tutorial",
+    "mysql",
+    "redis",
+    "kafka",
+    "grpc",
+    "kubernetes"
+  ],
   "license": "MIT",
   "files": [
     "*.md",