+ {items.map((item, index) => (
+
+ );
+};
+```
+
+A. 使用 item.id 作为 key 而非 index
+B. 使用虚拟滚动
+C. 使用 useMemo 包裹 items
+D. onClick 使用 useCallback
+
+**正确答案：** ABD
+**作答答案：** ABD ✅
+
+> [!TIP] 🔑 为什么不选 C？
+> `useMemo` 包裹 items 并不能直接优化列表渲染性能——items 来自 props，其变化由父组件决定。关键在于 **key 稳定性**（A）、**渲染策略**（B）和**事件处理器引用稳定**（D）。
+
+---
+
+#### 4. useEffect + 键盘事件监听
+
+【多选题】关于下面代码说法正确的是？（4分）
+
+```js
+useEffect(() => {
+ const onKeyDown = (e) => {
+ const userAgent = navigator.userAgent;
+ const isMac = /Macintosh|MacIntel|MacPPC|Mac68K/.test(userAgent);
+ if ((isMac && e.metaKey && e.key.toLowerCase() === 'k') ||
+ (!isMac && e.ctrlKey && e.key.toLowerCase() === 'k')) {
+ e.preventDefault();
+ inputRef.current?.focus();
+ }
+ };
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+}, []);
+```
+
+A. 在 Mac 设备上按下 Command+K 键，或在非 Mac 设备上按下 Ctrl+K 键时，让 inputRef 对应的输入框获取焦点
+B. 该 useEffect 仅在组件挂载时执行一次，因为其依赖数组为空
+C. 清理函数会在组件卸载时执行，用于移除添加的 keydown 事件监听，避免内存泄漏
+D. 清理函数的主要作用是阻止键盘事件的默认行为
+
+**正确答案：** ABC
+**作答答案：** ABCD
+
+> [!FAIL] 💔 易错点
+> **D 是错误的**：`e.preventDefault()` 阻止的是浏览器默认行为（如 Cmd+K 的搜索框聚焦），而清理函数 `removeEventListener` 的作用是**移除事件监听器本身**，二者职责完全不同。
+
+---
+
+#### 5. GIF 埋点 vs AJAX
+
+【多选题】相比较 AJAX，有些公司前端监控都喜欢用 GIF 做埋点上报，以下哪些是 GIF 的优势？（4分）
+
+```js
+// GIF 方案
+const report = (data) => {
+ const img = new Image();
+ img.src = `https://log.example.com/track.gif?data=${encodeURIComponent(JSON.stringify(data))}`;
+};
+
+// Ajax 方案
+const report = (data) => {
+ fetch('https://log.example.com/track', {
+ method: 'POST',
+ body: JSON.stringify(data)
+ });
+};
+```
+
+A. GIF 请求不需要等待响应，发送即走
+B. GIF 可以跨域，不受 CORS 限制
+C. 页面卸载时 GIF 请求不会被取消
+D. GIF 体积最小（1x1 像素）
+
+**正确答案：** ABD
+**作答答案：** ABD ✅
+
+> [!NOTE] ℹ️ 为什么不用 C？
+> 页面卸载（unload）时，`navigator.sendBeacon()` 可以保证请求发送，但普通 ` handleClick(item)}>
+ {item.name}
+
+ ))}
+ Redis / 内存 / DB"] + S3["⚠️ 集群环境下需要 Session 共享"] + end + subgraph JWTAuth["JWT 认证"] + J1["客户端: 保存 JWT Token"] + J2["服务端: 用私钥验证签名
无需存储会话"] + J3["✅ 天然无状态，水平扩展友好"] + end +``` + +### Gin 中 JWT 信息传递流程 + +```mermaid +flowchart TB + Middleware["JWT 中间件\nParseString(bearer token)"] --> Valid{"Token 有效?"} + Valid -->|否| Reject["返回 401 Unauthorized"] + Valid -->|是| Set["c.Set claims.UserID / c.Set claims.Role"] + Set --> Handler["业务 Handler\nc.Get claims.UserID"] +``` + +> [!TIP] Gin Context 的正确用法 +> `c.Set` / `c.Get` 是基于 `context.Context` 的键值存储，生命周期限定在当前请求范围内，线程安全，是 Gin 中跨中间件和 Handler 传递信息的标准做法。 + +### 原题回顾 + +#### 第27题：JWT 解析后的最佳实践 + +> [!CAUTION] 错题回顾 +> 不要用 `c.Redirect` 来传递用户信息！Redirect 会中断当前请求流程，把用户带到另一个页面，这与"把用户信息传给后续 Handler"的需求完全不符。 + +27. + +【单选题】当中间件成功解析并验证了前端请求头中的 JWT 令牌后，最佳的代码实践是？（5分） + +中间件是查票员，查验完 JWT 后，通过 `c.Set()` 把乘客信息存储在当前 HTTP 请求的生命周期上下文中，后续函数可以安全、隔离地拿到用户信息。 + +A. 将解析出的用户 ID 保存到全局变量中。 + +B. 使用 `c.Redirect` 将请求重定向，并在 URL 参数里带上用户 ID。 + +C. 使用 `c.Set("userID", id)` 将用户信息存储在上下文中。 + +D. 将用户信息打包成 JSON 写回到响应体中，结束请求。 + +**正确答案：** C +**作答答案：** B ❌ + +--- + +#### 第28题：JWT 解决的痛点 + +28. + +【单选题】JWT 解决了传统 Session 架构的什么核心痛点？（5分） + +JWT 是"无状态"的，服务端不需要存储会话记录就能验证其有效性，从而解决了传统 Session 在服务器集群环境下的共享与同步问题。 + +A. JWT 对用户密码进行了极强的加密，即便被黑客拦截也绝对安全。 + +B. 传统 Session 强依赖于服务端内存或集中存储，JWT 是"无状态"的。 + +C. JWT 生成的字符串非常短，比传统的 SessionID 更省网络带宽。 + +D. JWT 只能在 Go 语言和前端之间解析，跨语言安全性极高。 + +**正确答案：** B +**作答答案：** B ✅ + +> [!NOTE] JWT ≠ 加密 +> JWT 默认是 Base64 编码（可读的），不包含加密。即使加了签名防止篡改，Token 内容本身仍然是明文的。因此**不要在 JWT 中存放敏感信息**（如密码、身份证号）。 + +--- + +#### 第29题：HttpOnly Cookie + +> [!TIP] Cookie 安全防护体系 +> | 属性 | 作用 | 防御目标 | +> |------|------|----------| +> | `HttpOnly` | JavaScript 无法读取 | XSS 攻击 | +> | `Secure` | 仅 HTTPS 传输 | 中间人窃听 | +> | `SameSite` | 控制跨站发送 | CSRF 攻击 | +> | `maxAge` | 过期时间 | 长期驻留风险 | + +29. + +【单选题】在使用 Gin 设置 Cookie 时，为了防止前端恶意脚本通过 JavaScript 读取到包含用户登录凭证的敏感 Cookie，你应该将哪个参数设置为什么值？（5分） + +httpOnly 是防御 XSS 攻击的利器。当它设为 true 时，浏览器会把这个 Cookie 藏好，只有在向后端发送 HTTP 请求时才会默默带上，前端的任何 JS 代码都无权读取。顺便提一下，secure 也很重要，它表示该 Cookie 只能在 HTTPS 加密连接下传输，用来防止网络中间人窃听。 + +A. maxAge 设置为 0 + +B. secure 设置为 true + +C. httpOnly 设置为 true + +D. domain 设置为 "localhost" + +**正确答案：** C +**作答答案：** C ✅ + +--- + +#### 第30题：Gin 中 Session 的使用 + +30. + +【单选题】关于 Gin 框架中 Session 的运用，以下说法正确的是？（5分） + +Session 的本质是服务器在后端存储了用户状态，只把一个无意义的、随机的 SessionID 通过 Cookie 发给前端保存。Gin 核心库为了保持轻量，并没有内置 Session，推荐使用第三方中间件。 + +A. Gin 官方核心库自带了完善的 Session 管理器，无需引入第三方包。 + +B. Session 数据默认以明文形式保存在客户端的浏览器中。 + +C. Session 的本质是服务器在后端存储用户状态，只把 SessionID 发给前端。 + +D. 只要用户关闭浏览器页面，服务器端的 Session 数据就会被自动删除。 + +**正确答案：** C +**作答答案：** C ✅ + +> [!INFO] Gin + Session 常见组合 +> ```go +> // 常用第三方 Session 中间件 +> import "github.com/gin-contrib/sessions" +> import "github.com/gin-contrib/sessions/redis" +> +> store, _ := redis.NewStore(10, "tcp", "localhost:6379", "", []byte("secret")) +> r.Use(sessions.Sessions("session_name", store)) +> // 后续可通过 session.Get("user_id") 读取 +> ``` + +--- + +## 十一、多选题错题汇总 + +将所有做错的多选题汇总在此，方便集中复习： + +| 题号 | 知识点 | 你的答案 | 正确答案 | 失分原因 | +|------|--------|---------|---------|---------| +| 单选-8 | 索引失效 | B | A | 未能识别函数对索引的影响 | +| 多选-2 | Docker 构建加速 | AD | ACD | 漏选多阶段构建 | +| 多选-3 | 慢查询措施 | ACD | ABCD | 排除了合理选项（硬件/存储过程） | +| 多选-4 | 查询性能优化 | ABCD | ACD | 未排除"禁用外键"的错误选项 | +| 多选-6 | Docker 持久化 | BD | BC | 混淆了 Volume/Bind Mount/tmfs | +| 多选-7 | 查询优化方法 | ABCD | ABD | 误认为 ORM 能自动提升性能 | +| 多选-8 | 索引优化因素 | ABCD | ABD | 忽略了索引对写入性能的影响 | +| 多选-9 | Protobuf 优势 | AD | ACD | 未选"支持多种语言" | +| 单选-22 | depends_on | B | C | 拼写了不存在的指令 | +| 单选-27 | JWT 中间件 | B | C | 混淆了重定向与上下文传递 | +| 单选-20 | Protobuf varint | D | A | 理解不够精准 | + +> [!SUCCESS] 💪 复习建议 +> 从上面的表格可以看出，你的薄弱环节集中在： +> 1. **MySQL 索引原理**（函数导致索引失效、索引对写入的影响） +> 2. **Docker 概念辨析**（Volume vs tmpfs、depends_on 的作用） +> 3. **Protobuf 特性**（多语言支持） +> 下次考试前重点回顾这些模块的核心概念图。 + +--- + +## 关联笔记 + +- [[Docker 容器与镜像]] +- [[MySQL 索引优化]] +- [[Gin 框架使用]] +- [[JWT & Session 认证]] +- [[Protobuf 入门]] +- [[Nginx 反向代理]] +- [[CORS 跨域解决方案]] diff --git a/hhs/Redis/一文吃透/README.md b/hhs/Redis/一文吃透/README.md new file mode 100644 index 0000000..896de9c --- /dev/null +++ b/hhs/Redis/一文吃透/README.md @@ -0,0 +1,601 @@ +在分布式系统中，为了解决单点问题，通常会把redis服务部署到多个服务器上，满足故障恢复和[负载均衡](https://cloud.tencent.com/product/clb?from_column=20065&from=20065)等请求。 + +所谓的单点问题，就是某个服务器程序，只有一个节点（只有一个[物理服务器](https://cloud.tencent.com/product/cbm?from_column=20065&from=20065)，来部署这个服务器程序）。 + +存在的问题： + +- 可用性问题：如果这个机器挂了，那么部署的redis服务就挂了，服务就中断了。 +- 性能/支持的并发量有限：毕竟一台主机的硬件资源（比如CPU，硬盘，网络带宽等等）是有限的，一个请求就要消耗一定量的硬件资源。一旦并发量太高，如果请求超过主机所能提供这些资源，那么可能就会出现异常，甚至主机直接宕机了。 + +在分布式系统中，往往希望有多个服务器来部署redis服务，从而构成一个redis集群，此时就可以让这个集群给分布式系统中的其他服务，提供更稳定/更高效的数据存储功能 。 + +主要存在以下几种部署方式： + +- 主从模式 +- 主从+哨兵模式 +- 集群模式 + +### 一，主从复制 + +##### 1，配置主从复制 + +**主从模式，即在若干个redis节点中，有的是主节点，有的是从节点 。** + +**redis主从模式中，从节点上的数据，不允许修改，只允许读取数据。要想修改数据，只能访问主节点。** + +假设有三个物理服务器（三个节点），都部署了redis服务，此时就可以把其中一个看作是主节点，其余两个看作是从节点。从节点上的数据要跟随主节点的数据而变化，从节点的数据要和主节点保持一致。 + +本来，在主节点上保存了一堆数据，现在引入从节点，就是要把主节点上的数据复制出来，放到从节点中。后续，主节点这里对数据有任何修改，都会把这样的修改同步给从节点。 + + + +总结：主从模式，主要是针对读操作进行可用性和并发量的提高，而对于写操作来说，无论是可用性还是并发量，都很依赖与主节点，但是主节点又不能搞多个。 + +--- + +如何在一个云服务器上部署多个redis服务，按照主从模式，实现类似于分布系统的效果？（ubutun20.04） + +我们可以在一个云服务器主机上，运行多个redis-server进程，我们只需保证这几个服务的端口号不同即可。本来redis-server的默认端口号是6379，此时新启动的redis-server端口号就不能是6379了。 + +在这里我们创建两个从节点，端口号是6380和6381，而主节点就是原先的redis-server，端口号为默认的6379。 + +可以通过修改配置文件来改变： + +1，首先需要将配置文件拷贝两份 + +`cp /etc/redis/redis.conf slave1.conf` + +`cp /etc/redis/redis.conf slave2.conf` + +2，然后修改拷贝后的两个配置文件中的选项 + +修改端口号——`port 6380 port6381` + +将该服务设置为后台进程——`daemonize yes` + +只需修改这两个选项即可。 + +3，启动这两个redis-server（从节点） + +`redis-server slave1.conf` + +`redis-server slave2.conf` + +4，现在我们只是有了多个redis-server，还没有构成主从结构。 + +要想配置成主从结构，就需要使用slaveof。有如下三个方法： + +- 在配置文件中加入`slaveof{masterHost} {masterPort}`，之后随redis启动生效。 +- 在redis-server启动命令中加入--slaveof{masterHost}{masterPort}生效。 +- 直接使用redis命令：slaveof{masterHost}{masterPort}生效。 + +其中{masterHost}和{masterPort}分别指主节点的ip和端口。 + +5，在这里我们选择通过修改配置文件的方式来构成主从结构 + +在slave1.conf和slave2.conf配置文件中加上slaveof 127.0.0.1 6379即可，以6379的redis-server作为主节点。配置文件修改完毕之后，需要我们重新启动redis-server，配置文件才会生效，所以此时需要重启端口号为6380和6381的redis-server。 + +由于我们启动redis-server服务时，是使用`redis-server port`这样的方式启动的，所以在重启的时候，需要使用`kill -9`来杀掉该服务进程，然后再通过redis-server port重启即可。 + +而如果我们是使用`service redis-server start`来启动服务器，就需要使用`service redis-server stop`来终止程序。此时如果使用kill -9来终止服务进程，kill掉之后，这个redis-server进程能自动启动 。相当于有一个进程来专门监控指定服务器的运行状态，如果服务器挂了，会立即重新启动。 + +因此怎么启动的redis-server，就必须搭配对应的方式进行终止。 + +6，再次启动redis-server即可实现主从模式 + + + + + +##### 2，断开主从复制 + +使用命令slaveof no one可以断开主从关系，这只是暂时的，当redis-server重启之后，主从关系就会恢复，所以要想一直断开主从关系，还是需要修改配置文件。 + +##### 3，拓扑 + +我们的redis-server服务器可能有很多个节点，如何组织这些节点？ + +###### 一主一从结构 + + + +如果其他客户端想要读取数据，从主节点A或 从节点B读取都可以，两个服务器上的数据是一致的。 + +如果是写数据请求，那么只能由主节点A来完成。 + +如果此时写请求太多，也会给主节点造成 一定的压力。我们可以通过关闭主节点的AOF，毕竟写内存比写磁盘快，只打开从节点的AOF。但是这种设定，有一个严重缺陷，主节点一旦挂了，不能立即重启，因为主节点这边没有使用AOF保存数据，如果重启了，那么数据就会丢失，进一步的主从同步，也就使从节点上数据也丢失了。改进办法是，当主节点挂了，先从从节点那里获取AOF文件，再启动，这样就可以保证数据没有问题了。 + +###### 一主多从结构 + + + +同理，如果是读请求，可以访问主节点，也可以访问从节点。 + +如果是写请求 ，是能访问主节点，主节点上的数据发生变化，就会把改变的数据同步给其他从节点。 + +这个结构存在的问题：同步操作是需要消耗网络带宽的，如果子节点太多，就会大大消耗主节点主机的硬件资源。 + +###### 树形结构 + + + +主节点将数据同步给从节点B和从节点C，再由从节点B将数据同步给从节点D和从节点E。 + +此时主节点A就不需要太高的网络带宽，但此时数据同步的延时会更长。 + +##### 4，原理 + + + +同步数据的命令：**`PSYNC replicationid offset`**，这个命令是从节点执行的。 + +其中replicationid是复制id，是主节点生成的，主节点在启动的时候就会生成。 + +当从节点和主节点建立了复制关系，就会从主节点上 获取到这个id，这个id就表明了当前从节点是从哪个主节点上获取的数据。 + +在主节点和从节点上一般都有两个replicationid：replicationid和replicationid2。其中replicationid2其备份的作用，比如下面的例子。 + +> 现在有一个主节点A和一个从节点B，A在启动的时候会生成一个replicationid，之后B获取到A的replicationid。如果A和B通信过程中出现了一些网络抖动，B可能会认为A挂了，此时从节点B就会晋升为主节点，并给自己生成一个replicationid，此时B的replicationid2就保存了之前获取到的A的replicationid。等到网络稳定，B还可以根据这个replicationid2再次与节点A建立主从关系。（但是主从复制这种方法，当主节点挂了，一般从节点是不会晋升为主节点的） 这个再次建立主从关系的过程，一般是需要手动完成的。当然，在下面的哨兵机制部分，可以自动完成这个过程。 + +offset表示偏移量 + +主节点和从节点都会维护这个偏移量（一个整数）。 + +主节点的偏移量：主节点可能会收到很多的修改操作的命令，每个命令都选哟占据几个字节。主节点会把这些命令的字节数进行累加，这个数字就是主节点的偏移量。 + +从节点的偏移量：描述了当前数据同步的进度，从节点会每秒上报自身的偏移量给主节点。 + +如果从节点和主节点的偏移量一致，就表述数据 同步完成了。 + +**综上，replicationid描述了从哪个主节点同步数据，offset表示同步数据的进度。如果两个机器的replicationid和 offset一样，就表示这两个机器上的数据一致。** + +**replicationid和offset就共同描述了一个"数据集合"。** + +###### PSYNC工作流程 + +PSYNC可以从主节点获取全量数据，也可以获取部分数据。 + +主要看offset的值，如果设为-1，表示全量获取，如果设置为具体的整数，则表示从当前整数位置来进行获取。 + +当然，从节点想要全量的获取数据，还是增量的获取数据，同时也取决于主节点，主节点会自行判定，看当前是否方便给部分数据，如果不方便，会直接给 全量数据。 + + + +###### 全量复制的流程 + +在一个从节点与主节点第一次建立主从关系的时候，就会涉及到数据的同步，而此时一般就是进行全量复制。 + + + +在进行全量复制的时候，主节点要进行生成rdb文件的操作，然后再把该文件通过网络传输发送给从节点，从节点也是先将该rdb文件保存，然后读取该文件来获取数据。 + +而redis也支持"无硬盘模式"（diskless）：主节点生成的rdb的二进制数据，不直接保存到文件中，而是直接通过网络传输发送给从节点 ，省去了读写硬盘的操作，而从节点现在也可以省去这个操作了，直接将收到数据加载到内存中...... + +但是，即使引入了"无硬盘模式"，对全量复制的效率提升不是很大，因为全量复制整个操作是比较重量的，数据规模较大。相比于网络传输，读写硬盘操作算是快的了。所以减少了对硬盘的操作，但网络传输无法省去，意味着对整个操作的效率提升不大。 + +###### 部分复制流程 + +在主节点与从节点连接的过程中，可能由于网络抖动等原因，主从节点的连接断开，此时重新建立连接并进行数据同步的时候，使用的就是部分复制。 + + + +###### 实时复制 + +全量复制：主要适用于从节点刚连上主节点进行数据初始化的工作。 + +部分复制：是全量复制的一种特殊情况，属于全量复制的一种优化。 + +实时复制：在从节点与主节点建立好连接，并且完成数据同步之后，此时主节点可能会受到源源不断的请求，其中就会包含修改数据的请求，主节点的数据就会发生变化，此时就要把数据也同步给从节点。从节点和主节点之间建立有Tcp连接，当主节点收到修改数据的请求，就会通过该Tcp连接，将这个请求发送给从节点，从节点再根据这些请求修改数据即可。 + +所以在实时复制的时候，我们需要保证主节点与从节点的Tcp连接处于可用状态。在这里，使用**心跳包机制**来实现。 + +> **心跳包机制：** 主节点：默认每隔10s，向从节点发送一个ping命令，从节点收到后会返回一个"pong"。 从节点：默认每隔1s，向主节点发送一个特定的请求，告诉主节点当前的同步进度（offset），之后主节点也会给出一个响应。 如果，达到某个阈值，还没有收到响应，那么就认为这个主节点/从节点存在问题，判断下线了。 + +##### 5，总结 + +主从复制解决的问题：单点问题 + +单点问题：单个redis节点，可用性不高，性能有限。 + +主从复制的特点： + +1，主节点可以用来读写，从节点只能用来读，可以减少主节点的访问压力。 + +2，主从复制存在多种拓扑结构：可以在适当的场景使用适当的拓扑结构，比如一主多从的结构，同步操作快，但是消耗的网络资源多，因为主节点要通过网络和所有从节点实现同步。而树形结构，主节点消耗的网络资源减少了，但是如果树的层级太高，会造成数据同步的延迟增长加。 + +3，复制分为全量复制，部分复制和实时复制。 + +4，通过心跳机制保证主节点和从节点的正常通信和数据一致。 + +主从复制的缺点： + +1，从节点多了，数据复制的延时就会非常明显。 + +2，如果主节点挂了，从节点不会晋升为主节点，需要通过人工干预的方式恢复。 + +### 二，哨兵（Sentinel） + +主从复制最大的问题，还是在主机点上，如果主节点挂了，从节点不会晋升为主节点，需要通过人工干预的方式恢复。 + +因此Redis哨兵机制，就是为了解决上述问题，自动的对挂了的主节点进行替换，也就是将上述手动的过程改成自动。 + +哨兵机制是通过启动一个不同的进程来体现的，它和redis-servver服务器进程不是 同一个进程 。 + +##### 1，相关名词解释 + +|名词|逻辑结构|物理结构| +|---|---|---| +|主节点|Redis服务|一个独立的redis-server进程| +|从节点|Redis服务|一个独立的redis-server进程| +|Redis数据节点|主从节点|主节点和从节点的进程能| +|哨兵节点|监控Redis数据节点的节点|一个独立的redis-sentinel进程| +|哨兵节点集合|若干哨兵节点构成的整体|若干redis-sentinel进程| +|Redis哨兵(Sentinel)|Redis提供的高可用方案|哨兵节点集合和Redis主从节点| +|应用方|一个或多个客户端|一个或多个连接Redis的进程| + +##### 2，哨兵自动恢复主节点故障 + + + +如果一个哨兵节点发现主节点挂了，为了防止预判，还需多个哨兵节点共同认为这件事情。 + +如果主节点确实挂了，这些哨兵节点会选出一个作为leader，由这个哨兵节点负责从剩下的从节点中选一个出来，作为主节点。选出新的主节点之后，哨兵节点就会控制该节点执行slaveof no one，并且通知其他从节点，修改slaveof到新的主节点之上。哨兵节点会自动通知客户端程序，告知新的主节点是谁，并且此后客户端再进行写操作时，就会访问新的主节点了。 + +##### 3，哨兵机制的特点 + +监控：Sentinel节点会定期检查redis数据节点，使用心跳包机制。 + +故障转移：实现从节点晋升为主节点，并维护好正确的主从关系。 + +通知：Sentinel会将故障转移的结果通知给应用方。 + +##### 4，主从切换的具体流程 + +_**重点，面试题：**_ + +1，主观下线：哨兵节点通过心跳包进制，判读redis主节点服务器是否正常工作，如果没有沙鸥到响应，该哨兵节点就会认为该主节点下线了。 + +2，客观下线：当多个哨兵节点都认为主节点挂了之后，此时这个主节点就是主观下线了。 + +3，再从多个哨兵节点中，选举出一个leader节点，由这个leader节点负责从剩下的节点中选出一个作为主节点。 + +4，leader挑选完毕后，此时需要从剩下的从节点中选一个当作新的主节点。 + +- 首先会看这些从节点的优先级，每个 redis数据节点，都会有自己的配置文件，配置文件中就有一个优先级的设置。leader会选择优先级高的作为新的主节点。 +- 如果数据节点的优先级都一样，那么就比较这些数据节点的offset，offset表示从节点与原来主节点进行数据同步的进度，offset越大，说明这个节点与原来主节点的数据相似度最高，此时就会选择这个节点作为新的主节点。 +- 如果前面两个条件都一样，此时其实意味着从这些节点中任选一个都行。那么再看这些节点的runid（一串数字），每个redis数据节点启动时都会生成一个随机的runid，此时比较runid的大小。让runid更小的作为新的主节点。 +- 指定好新的主节点之后，此时leader就会控制这个主节点执行slaveof no one，让这个节点成为主节点（master）。再控制其他从节点，执行slaveof，让这些从节点，以新的mater作为主节点。 + +##### 5，总结 + +哨兵节点不能只有一个，因为哨兵节点挂了也会影响 系统的运作。 + +哨兵节点最好是奇数个，方便选举leader，得票数更容易超过一半。 + +哨兵+主从复制解决的问题是"提高可用性"，极端情况下写操作的数据丢失无法解决。 + +哨兵+主从复制不能提高数据的存储容量 ，当数据接近或者几乎超过机器的物理内存时，这样的结构就难以胜任了，**而接下来的redis集群，就是解决存储容量问题的有效方案。** + +### 三，集群 + +**广义上的集群，是指多个机器，构成的分布式系统，就可以称为一个集群，所以前面的主从复制和哨兵模式也可以看作是一个集群。** + +**而侠义上的集群，是redis提供的集群模式。这个集群模式之下，主要是解决存储空间不足的问题。** + +在redis哨兵模式中，本质还是redis数据节点存储数据，其中就要求主节点/从节点来存储数据的全集。为了提高 数据存储的容量，这时就引入多台机器，每台机器只存储一部分数据。 + +> 假设有1TB的数据需要存储： 拿两台机器来存储 ，每台机器需要存储512GB。 拿三台机器来存储，每台机器需要存储300多GB。 拿四台机器来存储，每台机器需要存储 256GB...... + +但是还存在一个问题，如果使用三台机器来存储1TB的数据，如果某个机器挂了怎么办，所以我们还需要为每个机器 再分配几个从节点。 + + + +这三组机器的数据都是不同的，每个 slave都是mster的备份，当master挂了，slave就会晋升为master。 + +如上图所示，每个虚线框就可以看作是一个分片（Sharding）。 + +_**重点面试题：**_ + +三种主流的分片算法：哈希求余，一致性哈希算法，哈希槽分区算法。 + +##### 1，哈希求余 + +借助hash函数，把一个key映射成为 一个数字，在对数组长度（这里就是分片的个数）进行求余，就可以得到这个key是在哪个分片中。 + +比如现在有3个分片，编号为0，1，2 + +此时就可以针对要查询的数据（或插入的数据）计算hash值（比如可以使用md5算法），再把这个值余上分片的个数，此时就会得到一个数字，这个数字就表示这个数据在哪个分片中。 + +但是当总体的数据增长时，就需要扩容，引入更多的分片，此时分片的个数就变了。 + +如果发现某个数据在扩容之后，不该待在当前的分片中，那么就需要重新分配数据（数据搬运）。这里涉及到的数据搬运不仅仅是主节点进行，从节点也需要进行。 + +这种方式开销极大，往往不能再生产环境上操作的，搬运成本比较大。 + +**数据搬运成本大的原因：这种哈希求余的方式，导致数据是交替出现的，比如100出现在0号分片，101出现在1号分片，102出现在2号分片，103又是0号分片 。这就导致在扩容之后，分片个数增长，就会有 大量的数据需要进行搬运。** + +##### 2，一致性哈希算法 + +这种方式可以降低上述的"搬运开销"。 + +key映射到分片序号的过程不再是简单的求余了，而是改成以下过程： + +第一步：把0~2^32-1这个数据空间，映射到一个圆环上，按照顺时针方向增长。 + + + +第二步：假设分成3个分片，将分片放到对应的位置上 + +每个分片就会对应一个值，比如0号分片对应的值就是0 + + + +第三步：假定有一个key，计算得到的hash值为H，如何计算这个key是在哪个分区？此时H会在圆环上的某个位置，从这个位置开始，顺时针向下找，找到的第一个分片，就是这个key所属 的分片。 + + + +这就相当于，N个分片，把整个圆环分成N个区域，key的hash值落在哪个区域，它就属于哪个分片。 + + + +因此在 一致性哈希这样的设定下，把数据交替出现，改进成了连续出现。 + +在这种情况下，如何进行扩容，假设新增一个分片。 + +如下图所示，在圆环上找一个位置，设为3号分片的位置。该部分本来是0号分片上的，这样一来，只需将0号分片上的这段数据搬运到3号分片上即可，其他分片上的数据不需要搬运。 + +这种搬运的成本是有的，但是比之前哈希求余的方式低了不少。 + + + +这种方式，虽然搬运的成本降低了，但是也导致了各个分片上的数据量不均匀，称作数据倾斜。 + +##### 3，哈希槽分区算法 + +这是Redis真正采用的分片算法。 + +哈希槽计算公式：hsah_slot=hash(key）%16384，一共有16384个槽。 + +假设现在有3个分片，一种分配方式如下： + +- 0号分片：[0,5461]，共5462个槽位。 +- 1号分片：[5462,10923]，共5462个槽位。 +- 2号分片：[5463,16384]，共5460个槽位。 + +这里只是分片的一种，分片可以很灵活。每个分片持有的槽位号：可以是连续的，也可以是不连续的。 + +此处 ，每个分片都会使用一个位图结构，来表示该分片有多少槽位号，16384个bit位，用每一位的0/1表示是否持有这个槽位。 + +现在假设要新增一个分片，那么此时可以从0号分片，1号分片，2号分片上分别截取一部分出来，放到新的分片上，这样就可以解决数据倾斜的问题。 + +##### 4，故障处理 + +如果某个主节点挂了，此时就会把该主节点旗下的某一个从节点提拔为主节点，保证我们的redis能够正常工作。 + +###### 故障判定 + +识别某个节点是否挂了。 + +1. 节点A给节点B发送ping包，B就会给A返回一个pong包。ping和pong除了携带message type属性之外，其他部分都是一样的。还会包含集群的配置信息（该节点的id，该节点属于哪个分片，该节点是主节点还是从节点，从属于哪个主节点，持有哪些slot槽位）。 +2. 每个节点，每秒钟都会给一些 随机的节点发送ping包，而不是给所有节点都发送。这样设定设为了在节点很多的时候，心跳包也会非常多。 +3. 当节点A向节点B发送ping包后，B不能如期回应的时候，此时A就会尝试重置和B的TCP连接，看能否连接成功，如果连接失败，就会认为B节点下线了，A就会把B设为PFAIL状态（相当于主观下线）。 +4. A判定B为PFAIL后，会通过redis内置的Gossip协议，和其他节点进行沟通，向其他节点确认B的状态。（每个 节点都会维护一个自己的下线列表，由于视角不同，每个节点的下线列表也就不同）。 +5. 此时A发现很多节点也认为B为PFAIL，并且数目超过集群节点个数的一半，那么A就会把B标记为PFAIL（相当于客观下线），并且把这个消息同步给其他节点（其他节点收到后，也会把B标记为PFAI）。 + +以下三种情况会出现集群宕机： + +- 某个分片，所有的主节点和从节点都挂了。 +- 某个分片，主节点挂了，没有从节点。 +- 整个集群超过一半的主节点挂了。 + +###### 故障迁移 + +还是上述的例子。 + +如果B是从节点挂了，那么就不需要进行故障迁移，毕竟从节点挂了，还可以通过访问同一个 分片内的主节点或者其他从节点来获取数据。 + +如果B是主节点，就会由B的从节点（比如C和D）发生故障迁移。重新挑选一个主节点，代替之前主节点的位置。 + +具体过程如下： + +1. 从节点需要判断自己是否具有参选资格，如果主节点和从节点太久没有进行通信（此时认为主节点和从节点的数据差异太大了），就失去竞选资格。 +2. 具有资格的节点，比如C和D，就会先休眠一段时间，休眠时间=500ms基础时间+【0，500ms】随机事件+排名*1000ms。offset值越大，排名就越靠前（越小）。offset表示主节点和从节点数据同步的进度。 +3. 比如C的休眠时间到了，C就会给集群中其他所有节点，进行拉票操作。但是只有主节点才有投票资格。 +4. 主节点就会把自己的票投给C节点（每个主节点只有一票），当C收到的票数超过主节点数目的一半，C就会晋升为主节点（C会自己执行slaveof no one，并且让D执行slaveof D）。 +5. 同时，C还会把自己称为主节点的消息，同步给集群中的其他节点，大家也都会更新自己保存的集群信息结构。 + +总之，哪个节点会成为主节点，就看哪个节点先被唤醒，哪个节点的休眠时间短，大概率就是新的主节点。 + +如果两个节点被唤醒的时间是差不多的，那么此时就各凭本事了，取决于网络延迟，线程调度等等因素。 + +**上述选举的过程，称为Raft算法。** + +### 四，Redis典型应用——缓存 + +Redis最主要的三个用途： + +1. 存储数据（内存数据库） +2. 缓存 +3. 消息队列 + +##### 1，使用redis作为数据库的缓存 + +在一个网站中，通常会使用[关系型数据库](https://cloud.tencent.com/product/tencentdb-catalog?from_column=20065&from=20065)（如MySQL）来存储数据，关系型数据库虽然强大，但是有一个很大的缺陷，就是性能不高。（换言之 ，进行一次 查询操作消耗的系统资源较多）。 + +> 为什么说关系型数据库的性能不高？ + +1. 数据库是把数据存储在硬盘上的，硬盘的IO速度并不快，尤其是随机访问。 +2. 如果查询不能命中索引，就需要进行表的遍历，这就会大大增加 IO的次数。 +3. 关系型数据库对SQL的操作会进行一系列的解析，校验，优化工作。 +4. 如果是一些复杂查询，比如联合查询，需要进行笛卡尔积的操作，效率更是降低很多。 + +因为MySQL等数据库 ，效率比较低，所以承担的并发量就有限了，一旦请求量多了，数据库的压力就很大，甚至很容易就宕机了。对于服务器的每一个请求，都要消耗一定的硬件资源（CPU，内存，硬盘，网络带宽等等），任意一种资源的消耗超出了机器能提供的上限，机器就很容易出故障。 + +如何提高MySQL能承担的并发量？ + +1. 开源：引入更多的机器，构成数据集群。 +2. 节流：引入缓存，将一些热点数据保存到缓存中。后续在查询数据的时候，如果数据库中已经存在了，就不再访问MySQL了。 + +##### 2，如何知道redis中应该存储哪些数据？ + +也就是怎么获得热点数据。 + +这涉及到缓存的两种更新策略：1，定期生成 2，实时生成 + +1，定期生成 + +将访问的数据 ，以日志的 形式记录下来。接下来就可以针对这些日志进行统计了，统计这一天/一周/一个月，数据出现的频率，然后再按照降序排序，取出前20%的数据数据，这些数据 就是热点数据。 + +优点：上述过程，实际上实现起来比较简单，过程更可控，缓存中的数据是比较扶额和预期的，方便排查问题。 + +缺点：实时性不够。如果出现一些突发事件，有些本来不是热词的内容成了热词，这就可能会给后面的数据库带来较大的压力。 + +2，实时生成 + +- 如果在redis中查到了数据，就直接返回。 +- 如果没有查到，就从数据库查，同时把查到的数据写入redis中。 + +这里就会有一个问题，如果不停的向redis中写入数据，就会使redis的内存占用越来越高，逐渐达到内存上限。 + +> 此时如果继续向redis中写入数据，就会出现问题，为了解决这个问题，redis就引入了"内存淘汰策略"。 _**经典面试题：**_ + +- FIFO（First In First Out）先进先出：把缓存中存在时间最久的（也就是先来的数据）淘汰掉。 +- LRU（Least Recently Used）淘汰最近未使用的：记录每个key的最近访问时间，把最近访问时间最老的key淘汰掉 +- LFU（Least Frequently Used）淘汰访问次数最少的：记录每个key最近一段时间的访问次数，把访问次数最少的淘汰掉。 +- Random 随机淘汰：从所有的key中随机抽取一个淘汰掉。 + +##### 3，缓存预热，缓存穿透，缓存雪崩和缓存击穿 + +**缓存预热（Cache preheating）** + +缓存中的数据，有两种更新策略：**1，定期生成 2，实时生成** + +1. 如果使定期生成，就不涉及到预热。 +2. 如果是实时生成，在redis服务首次接入之后，服务器里是没有数据的，此时客户端的所有请求就都会打给MySQL，如果请求量太多，可能就会导致MySQL服务挂了。随着时间的推移，reids中的数据越来越多，MySQl承担的压力也就越来越小了。 + +缓存预热，就是为了解决上述问题。把定期生成和实时生成相结合，先通过离线的方式，通过一些统计的途径，先找到一批热点数据，导入到redis中。此时导入的这批热点数据就能帮MySQL分担一些压力了。随着时间的推移，使用新的热点数据来淘汰旧的热点数据。 + +在刚开始架构演进的时候，没有缓存，此时要加入缓存，就要进行缓存预热。还有当服务器进行重启的时候，我们要保证重启之后缓存中是否有数据以及 这里的数据 是否是热点数据，这也涉及到缓存预热。 + +--- + +**缓存穿透（Cache penetration）** + +在一次查询的过程中，如果要查询的某个key，在redis中没有，在MySQL中也没有。也就意味着此时这个key是不会被放到redis中，那么下次访问依然会访问数据库，这就会导致数据库承担的请求太多，压力很大。这种情况称为缓存穿透。 + +出现这种情况可能的原因： + +- 业务设计不合理：比如缺少必要的参数检验环节，导致非法到的key也被进行查询了。 +- 开发/运维误操作：不小心把部分数据从数据库中删除。 +- 黑客恶意攻击。 + +解决方案： + +1. 如果发现这个key，在redis和MySQL中都不存在在，仍然写入redis，将value设成一个非法值（比如""）。再应用层程序可以检查出这是一个非法的key。 +2. 还可以引入布隆过滤器，每次查询redis/MySQL之前，都先判断一下key是否在布隆过滤器上存在。布隆过滤器本质是结合了hash+bitmap，以较小的空间开销，以较快的访问速度，实现针对key是否存在的判定。 + +--- + +**缓存雪崩（Cache avalanche）** + +由于在短时间内，redis上大规模的key失效，导致缓存命中率陡然下降，并且MySQL压力迅速上升，甚至导致MySQL直接宕机。 + +可能的原因： + +- redis直接挂了，redis宕机/redis集群模式下很多节点宕机。（这是最主要的） +- redis正常工作，但是可能之前短时间内设置了很多key给redis，并且设置的过期时间是相同的。在给redis里设置key作为缓存的时候，有的时候为了考虑时效性，就会设置过期时间（和redis的内存淘汰机制是配合使用的）。 + +解决方法： + +- 加强监控报警，加强redis集群可用性的保证。 +- 不给key设置过期时间，或者在设置过期时间的时候，添加随机因子（避免同一时刻过期 ）。 + +**缓存击穿（Cache breakdown）** + +相当于缓存雪崩的特殊情况，针对**热点key**，突然过期了，导致大量的请求访问到数据库上，导致数据库宕机了。 + +解决方案： + +1. 基于统计的方式发现热点key，并设置为永不过期。这种方案往往需要服务器做出较大的调整。比如把当前访问哪些key的日志记录下来，接到一个消息队列中，再通过一些计算，将结果再返回给我们的服务器。 +2. 进行必要的降级服务。例如访问数据库的时候，使用分布式锁，限制同时请求数据库的并发数。 + +### 五，分布式锁 + +在一个分布式系统中，会涉及到多个节点访问同一个公共资源的问题，此时就需要通过 锁 来做互斥控制，避免出现类似于 线程安全的问题。而C++中的std::mutex，这样的锁只能在当前进程中生效。 + +而在分布式系统中，是有很多进程的（每个服务器，都是独立的进程）。因此，之前的锁就难以对现在分布式系统中的多个进程之前产生制约。分布式系统中，多个进程之间的执行顺序也是不确定的。 + +此时就需要引入"分布式锁"，来解决上述 问题。 + +**所谓的分布式锁，也是一个/一组单独的服务器程序，给其他的服务器提供"加锁"这样的服务。redis是一种典型的可以是实现分布式锁的方案，但不是唯一的一种。** + + + +买票服务器在进行买票的过程中，就需要先加锁，就是往redis上尝试设置一个特殊的key-value，完成买票后，就会把这个key-value删掉。其他服务器在买票的过程中，也会去尝试设置这个key-value，如果发现key-value已经存在，就认为加锁失败（是放弃还是阻塞，就看具体的实现策略了）。 + +**这个加锁过程其实就对标redis中的一个命令setnx key val，这个命令如果key不存在才会设置，如果key存在就会执行出错，同时解锁过程也对标redis中的del key命令。** + +##### 1，引入过期时间 + +问题1：某个服务器加锁成功了(setnx成功)，如果该服务器执行后续逻辑的过程中，程序崩溃了，此时还没有执行到解锁操作。这种情况就会导致redis上的key无人删除，也就导致其他服务器无法获取到锁了。 + +解决办法：在加锁过程中，给这个key设置一个过期时间，set ex nx这样的命令来完成设置，时间到了，redis服务器会自动删除这个key，这是其他服务器就可以获取到锁了。 + +注意：在设置过期时间的时候，智能使用set nx ex这样的方式设置，不能使用set nx ，exprie这两个命令来设置。因为redis上多个命令之间，是无法保证原子性的，此时就可能出现，这两个命令，一个执行成功，一个执行失败。相比之下，使用一条命令设置，是更加稳妥的。 + +##### 2，引入校验id + +问题2：所谓的加锁，就是给redis上设置一个key-val，所谓的解锁，就是给redis上的key-val删除掉。锁，就可以认为是redis上的一个普通键值对。可能会出现服务器1执行了加锁，而服务器2误执行了解锁。因此就可能给我们的系统带来严重的问题。（比如票数超卖) + +为了解决这个问题，就引入了校验机制。 + +1. 给服务器编号，每个服务器都有自己的身份标识。 +2. 进行加锁的时候，设置key-val。**key对应着服务器要访问的资源，val表示服务器的编号。** +3. 在解锁的时候，先查询这个锁对应的服务器编号，然后判定这个编号和执行解锁的服务器的编号是否一致，如果是，才能真正执行del；否则，执行失败。 + +##### 3，引入lua脚本 + +对于问题2，我们引入了校验id，但是还存在问题。就是在解锁的时候，需要两步操作，先获取到key对应的val，在执行del，此处是两步操作（不是原子的），就可能会出现问题。 + +一个服务器内部，也可能是多线程的，此时，就可能服务器A的两个线程都在执行解锁操作，首先进行id校验，都通过了，然后开始执行del命令，del就会被重复执行。 + +这看起来没有什么问题，但是如果此时一个线程执行完了del，又有一个服务器B来进行加锁(set nx ex)，加锁成功，之后服务器A的另一个线程执行del，就会把服务器B的锁给解掉。 + +归根节点，是因为get 和 del这两个命令不是原子的，此时可以引入事务，将这两个操作打包成一个事务，使在执行get 和 del之间不会执行其他操作（避免插队）。 + +**使用事务，能解决上述问题，但是在实践中，往往推荐使用更好的方案——lua脚本。** + +**redis执行lua脚本的过程 ，也是原子的，相当于执行一条命令一样。** + +**在redis官方文档中，也明确说明了，lua就属于事务的替代方案。** + +##### 4，引入看门狗（Watch Dog） + +在前面提到过，服务器在进行加锁的时候，要给key设置一个过期时间。 + +- 这个过期时间，如果设置的太短，就可能在服务器的业务逻辑还未执行完，锁就释放了。 +- 如果设置的太长，也会导致"锁释放不及时"的问题。 + +**这里更好的方式是"动态续约"。** + +**初始情况下，设置一个过期时间（比如设置1s），就提前在还剩300ms的时候（不一定是300ms，数值可以灵活调整），如果当前任务还未执行完，就把过期时间再续上1s。等到时间又快到了，任务还未执行完，就再续。** + +这样设置也有一个好处：如果服务器中途崩溃了，也就没人续约了，此时，锁就可以再较短的时间内被释放。 + +服务器进行"动态续约"往往是需要有一个专门的线程来完成这个事情，这个线程就叫做**"看门狗"。** + +##### 5，redlock算法 + +使用redis作为分布式锁，redis本身是有可能挂了的。 + +要想保证redis的高可用，可以使用主从复制，哨兵，集群模式等方案。这里使用哨兵机制最合适。 + +进行加锁操作，就是把key设置到设置到主节点上，如果主节点挂了，有哨兵节点会把从节点升级为主节点，进一步保证刚才的锁可用。 + +**但是主节点和从节点的数据同步是有延迟的，可能主节点收到了加锁的请求(set nx ex），还没来得及推送给从节点，主节点就挂了。即使从节点升级成为了主节点，但是刚才加锁的对应的数据是不存在的。** + +**此时就需要使用 redlock算法。（redis作者给出的一种方案）核心思想：冗余，少数服从多数。** + +此时加锁，就是按照一定的顺序，针对这些redis都进行加锁操作。如果某个主节点挂了（加不上锁），没关系，继续给下一个主节点加锁。如果加锁成功的主节点个数超过总结点总数的一半，就视为加锁成功。同理，进行解锁的时候，每个主节点都会进行一遍解锁。 + + \ No newline at end of file diff --git a/hhs/finalhomework/hhs执行计划.md b/hhs/finalhomework/hhs执行计划.md deleted file mode 100644 index 18dc464..0000000 --- a/hhs/finalhomework/hhs执行计划.md +++ /dev/null @@ -1,592 +0,0 @@ ---- -tags: [全栈开发, 大作业, 执行计划, gRPC, Gin, OSS, Eino, React] -create time: 2026-05-09 14:30 ---- - -# 大作业·执行计划 — 双端 gRPC HR 招聘系统 - -## 概述 - -本文档基于《大作业项目要求》《思维导图》《工程结构设计》三份参考资料，梳理出分阶段、可落地的开发执行计划。整体采用 **六阶段推进** 策略：环境准备 → Proto 先行 → 后端双服务 → **前端一日冲刺** → 联调测试 → 视频录制与提交，每个阶段明确任务清单、前置依赖和验收标准，确保按期完成高质量交付。 - -> [!tip] 如何使用本计划 -> 建议按阶段的顺序推进，不要跳跃。Proto 定义是前后端的"契约"，必须先于业务代码完成。每个阶段完成后对照验收清单自检，避免返工。 - -## 一、整体时间规划与打勾进度 - -将整个开发周期拆分为 6 个阶段，各阶段之间存在明确的先后依赖关系。下方是总进度看板，每完成一个阶段就打勾： - -```mermaid -gantt - title 大作业开发总时间线 - dateFormat YYYY-MM-DD - axisFormat %m-%d - todayMarker stroke-width:3px,stroke:#fb8c00,opacity:0.6 - - section 阶段一 · 环境就绪 (M0) - Go / Node / MySQL / OSS :done, p1, 2026-05-10, 1d - .gitignore + .env.example :done, p1b, after p1, 30m - - section 阶段二 · Proto 先行 (M1) - 7 个接口定义文件 :done, p2, 2026-05-11, 1d - protoc 生成 Go 代码 :done, p2b, after p2, 30m - - section 阶段三 · 后端双服务 (M2) - 3A · MySQL 建表 : p3a, 2026-05-12, 1d - 3B · Logic 核心服务 (12项) :milestone, m3b, 2026-05-14, 0d - 3C · Web 网关服务 : p3c, after p3a, 2d - - section 阶段四 · 前端一日冲刺 (M3) - Foundation 共享基建 : p4a, 2026-05-15, 3h - 候选人用户端 (6页) : p4u, after p4a, 4h - HR 管理端 (7页) : p4h, after p4a, 5h - Build 验证 + Commit :milestone,m4z, 2026-05-15, 0d - - section 阶段五 · 联调自测 (M4) - 全链路跑通 : p5a, 2026-05-16, 1d - 专项测试 + Bug 修复 : p5b, 2026-05-17, 1d - - section 阶段六 · 录制提交 (M5) - 文档完善 : p6a, 2026-05-18, 2d - 视频录制 + KDoc 提交 :milestone,m6end, 2026-05-18, 0d - - %% 里程碑锚点 - milestone M0_环境就绪 :milestone, mk1, 2026-05-10, 0d - milestone M1_Protobuf冻结 :milestone, mk2, 2026-05-11, 0d - milestone M2_后端可运行 :milestone, mk3, 2026-05-14, 0d - milestone M3_双端完成 :milestone, mk4, 2026-05-15, 0d - milestone M4_联调通过 :milestone, mk5, 2026-05-17, 0d - milestone M5_正式提交 :milestone, mk6, 2026-05-18, 0d -``` - - - -| 阶段 | 日期 | 核心交付物 | 里程碑 | -| --------------- | ------------- | ------------------------------ | -------- | -| ~~阶段一：环境与基础建设~~ | ~~05-10~~ | Go / Node / MySQL / OSS 就绪 | ✅ **M0** | -| 阶段二：Proto 接口定义 | ~~05-11~~ | 7 个 `.proto` 文件 + 生成代码 | ⬜ **M1** | -| 阶段三：后端双服务 | 05-12 ~ 05-14 | Logic gRPC + Web Gin 均可独立运行 | ⬜ **M2** | -| 阶段四：前端一日冲刺 | 05-15 | hr-frontend + user-frontend 启动 | ⬜ **M3** | -| 阶段五：前后端联调 | 05-16 ~ 05-17 | 全链路测试通过 | ⬜ **M4** | -| 阶段六：视频录制与提交 | 05-18 | 视频 + 文档全部提交 | ⬜ **M5** | - -> [!tip] 使用说明 -> - 🟢 **绿色条** = 已完成阶段 · 🟡 **黄色条** = 当前活跃期 · 🔴 **菱形标记** = 里程碑检查点 -> - 橙色竖线为今日日期标注，直观对比当前所处阶段 -> - 甘特图下方表格同步映射 M0~M5 里程碑编号，与第九节里程碑总表一一对应 - -> [!question] 如果某个阶段超时了怎么办？ -> 优先级原则：核心功能（gRPC 分层调用、OSS 签名上传、Eino 对话）> 次要功能（分页搜索、数据可视化）。宁可缩减 UI 装饰细节，也要保住验收红线。 - -## 二、阶段一：环境与基础建设 - -> [!note] 进度追踪 -> - [x] T1.1 Go 1.21+ 安装并验证 -> - [x] T1.2 Node.js 18+ / npm 安装并验证 -> - [x] T1.3 MySQL 8.0+ 安装 + 数据库实例创建 -> - [x] T1.4 OSS 平台注册 + 私有 Bucket 创建 -> - [x] T1.5 Git 仓库初始化 + 目录结构建立 -> - [ ] T1.6 `.gitignore` + `.env.example` 初始化 - -
-
-
-### 2.2 前置条件
-
-- 无，这是第一个阶段。
-
-### 2.3 验收标准
-
-- [ ] `go version`、`node -v`、`mysql --version` 均正常输出
-- [ ] OSS Bucket 已创建且为私有（匿名访问已关闭）
-- [ ] 本地目录结构已按 `工程结构.md` 的顶层树创建出来
-- [ ] `.gitignore` 正确排除了敏感配置文件
-
-```bash
-# 预期目录骨架
-final_homework/
-├── hr-frontend/
-├── user-frontend/
-├── web-gin-service/
-├── logic-grpc-service/
-└── api/
-```
-
-> [!warning] 常见陷阱
-> - OSS 密钥务必写入 .env 或独立配置文件，**不要硬编码到业务代码中**。真实业务场景中 key 是绝对禁止提交到仓库的。
-> - 新建 Git 仓库后立刻添加 .gitignore，避免误提交 .env 文件。
-
-## 三、阶段二：Proto 接口定义（契约先行）
-
-> [!note] 进度追踪
-> - [ ] T2.1 `common.proto` — 通用响应码、分页参数
-> - [ ] T2.2 `auth.proto` — Login/RPC、Register/RPC、VerifyToken/RPC
-> - [ ] T2.3 `job.proto` — CreateJob/RPC、UpdateJob/RPC、ListJobs/RPC、DeleteJob/RPC
-> - [ ] T2.4 `application.proto` — SubmitApplication/RPC、ListApplications/RPC
-> - [ ] T2.5 `profile.proto` — GetProfile/RPC、UpdateProfile/RPC
-> - [ ] T2.6 `resume.proto` — GenOssSign/RPC、SaveResume/RPC
-> - [ ] T2.7 `chat.proto` — SendChat/RPC、GetHistory/RPC
-> - [ ] T2.8 protoc 生成 Go 代码
-
-📋 展开查看详细任务表
- -### 2.1 详细任务清单 - -| 编号 | 任务 | 耗时估计 | 说明 | -|------|------|----------|------| -| T1.1 | 安装并验证 Go 1.21+ | 30min | `go version`，配置 GOPATH 和 GOMODCACHE | -| T1.2 | 安装并验证 Node.js 18+ / npm | 30min | 后续用于两个前端项目 | -| T1.3 | 安装并验证 MySQL 8.0+ | 30min | 创建数据库实例，记录连接信息 | -| T1.4 | 注册 OSS 平台，创建私有 Bucket | 30min | 关闭匿名访问，关闭公开读权限 | -| T1.5 | 创建 Git 仓库，建立最终目录结构 | 30min | 参照 `final_homework/` 规范 | -| T1.6 | 初始化 .gitignore 和 .env.example | 30min | 敏感文件排除：.env、go.sum（可选）、node_modules | - -
-
-
-### 3.2 前置条件
-
-- 阶段一已完成（T1.1 ~ T1.6）
-- protoc 编译器及 go plugin 插件已安装
-
-### 3.3 验收标准
-
-- [ ] `protoc --go_out=... --go-grpc_out=...` 在 `api/proto/v1/` 下编译通过
-- [ ] 生成的 Go 代码存在于两个服务的 `proto/gen/v1/` 目录
-- [ ] 所有 RPC 方法签名覆盖项目需求文档中的全部接口
-
-> [!tip] Proto 设计最佳实践
-> - 每个 Service 对应一个 proto 文件，职责单一
-> - Request 和 Response 消息统一命名规范：`XxxRequest`、`XxxResponse`
-> - `common.proto` 中的 `CommonResponse{code, msg, data}` 作为所有响应的包装壳
-> - 字段使用 tag 编号，从 1 开始递增，预留扩展空间
-
-## 四、阶段三：后端双服务开发
-
-### 3.1 子阶段 3A：MySQL 数据库建表
-
-> [!note] 进度追踪
-> - [ ] T3A.1 根据 ER 图设计 SQL DDL
-> - [ ] T3A.2 执行建表 + 插入测试种子数据
-
-建表清单（对照 `db.md` 细化）：
-
-| 表名 | 用途 | 关键字段 |
-|------|------|----------|
-| `users` | 用户表 | id, username, password_hash, role, created_at |
-| `jobs` | 岗位表 | id, creator_id, title, description, status, created_at |
-| `applications` | 投递记录表 | id, job_id, candidate_id, applied_at |
-| `profiles` | 候选人档案表 | id, user_id, name, phone, education, school, experience, skills |
-| `resumes` | 简历信息表 | id, profile_id, file_key, oss_url, created_at |
-| `chat_records` | AI对话历史表 | id, hr_id, question, ai_reply, created_at |
-
-> [!note] 思考题
-> 为什么 `creator_id` 放在 jobs 表中而不是单独的 job_ownership 关联表？因为本系统架构轻量化，HR 仅管理本人发布的岗位，单字段外键足以表达这种一对一的归属关系。
-
-### 3.2 子阶段 3B：Logic 核心业务服务
-
-> [!note] 进度追踪
-> - [ ] T3B.1 gRPC Server 框架 + config 模块
-> - [ ] T3B.2 AuthService（注册/登录/JWT签发）
-> - [ ] T3B.3 JobService（岗位 CRUD + 创建者权限校验）
-> - [ ] T3B.4 ApplicationService（投递逻辑 + 校验拦截）
-> - [ ] T3B.5 ProfileService（候选人档案增改查）
-> - [ ] T3B.6 ResumeService + OSS signer（签名 URL 生成 + 文件头校验）
-> - [ ] T3B.7 ChatService（意图解析 → SQL查询 → Prompt拼接 → Eino推送 → 持久化）
-> - [ ] T3B.8 repository 层数据访问封装（6张表）
-> - [ ] T3B.9 converter 层 proto ↔ model 转换
-> - [ ] T3B.10 JWT 工具模块（签发 + 验证 + 角色提取）
-> - [ ] T3B.11 AI 模块封装（Eino Chat Engine + prompt 模板 + 意图解析器）
-> - [ ] T3B.12 Logic 服务独立启动测试
-
-📋 展开查看详细任务表 + 前置条件
- -### 3.1 详细任务清单 - -| 编号 | 任务 | 前置依赖 | 耗时估计 | -|------|------|----------|----------| -| T2.1 | 定义 `common.proto`（通用响应码、分页参数） | — | 30min | -| T2.2 | 定义 `auth.proto`（Login/RPC、Register/RPC、VerifyToken/RPC） | T2.1 | 30min | -| T2.3 | 定义 `job.proto`（CreateJob/RPC、UpdateJob/RPC、ListJobs/RPC、DeleteJob/RPC） | T2.1 | 30min | -| T2.4 | 定义 `application.proto`（SubmitApplication/RPC、ListApplications/RPC） | T2.1 | 30min | -| T2.5 | 定义 `profile.proto`（GetProfile/RPC、UpdateProfile/RPC） | T2.1 | 30min | -| T2.6 | 定义 `resume.proto`（GenOssSign/RPC、SaveResume/RPC） | T2.1 | 30min | -| T2.7 | 定义 `chat.proto`（SendChat/RPC、GetHistory/RPC） | T2.1 | 30min | -| T2.8 | protoc 生成 Go 代码 | T2.1 ~ T2.7 | 30min | - -
-
-
-#### Logic 核心流程自查
-
-- [ ] 用户注册时密码 bcrypt 加密存储
-- [ ] 登录成功签发 JWT（包含 userId + role）
-- [ ] 岗位编辑/下架时校验当前操作用户 == creator_id
-- [ ] 候选人投递时拦截：未完善资料或无简历 → 返回错误码
-- [ ] OSS 签名 URL 严格后缀白名单 (.pdf/.doc/.docx) + 文件头 Magic Number 校验
-- [ ] 简历不经过服务端缓存，客户端直传 OSS
-- [ ] AI 对话每条问答自动写入 chat_records 表
-
-> [!danger] 验收红线
-> Logic 服务内所有业务逻辑只能通过 gRPC Server 暴露，Web 服务不得通过同工程内部函数直连调用。如果同一个 Go module 里直接 import service 包 = 架构违规。
-
-### 3.3 子阶段 3C：Web 网关服务
-
-> [!note] 进度追踪
-> - [ ] T3C.1 Gin 项目框架 + router 注册
-> - [ ] T3C.2 CORS 中间件（全局跨域处理）
-> - [ ] T3C.3 JWT 鉴权中间件（读取 Token + 角色校验）
-> - [ ] T3C.4 参数合法性校验中间件
-> - [ ] T3C.5 gRPC Client 连接池 + codec JSON 转换
-> - [ ] T3C.6 Auth Handler
-> - [ ] T3C.7 Job Handler
-> - [ ] T3C.8 Application Handler
-> - [ ] T3C.9 Profile Handler
-> - [ ] T3C.10 Resume Handler
-> - [ ] T3C.11 Chat Handler
-> - [ ] T3C.12 Web 服务独立启动测试
-
-📋 展开查看 Logic 详细任务表
- -| 编号 | 任务 | 前置依赖 | 耗时估计 | -|------|------|----------|----------| -| T3B.1 | 搭建 gRPC Server 框架 + config 模块 | T3A.2 | 1h | -| T3B.2 | 实现 AuthService（注册/登录/JWT签发） | T3B.1 | 2h | -| T3B.3 | 实现 JobService（岗位 CRUD + 创建者权限校验） | T3B.1 | 2h | -| T3B.4 | 实现 ApplicationService（投递逻辑 + 校验拦截） | T3B.1, T3B.3 | 2h | -| T3B.5 | 实现 ProfileService（候选人档案增改查） | T3B.1 | 1.5h | -| T3B.6 | 实现 ResumeService + OSS signer（签名 URL 生成 + 文件头校验） | T3B.1 | 2h | -| T3B.7 | 实现 ChatService（意图解析 → SQL查询 → Prompt拼接 → Eino推送 → 持久化） | T3B.1, T3A.2 | 2.5h | -| T3B.8 | repository 层数据访问封装（6张表） | T3B.1 | 2h | -| T3B.9 | converter 层 proto ↔ model 转换 | T2.8, T3B.8 | 1h | -| T3B.10 | JWT 工具模块（签发 + 验证 + 角色提取） | T3B.1 | 1h | -| T3B.11 | AI 模块封装（Eino Chat Engine + prompt 模板 + 意图解析器） | T3B.1 | 2h | -| T3B.12 | Logic 服务独立启动测试 | T3B.2 ~ T3B.11 | 1h | - -
-
-
-#### Web 端架构自查
-
-- [ ] Handler 中没有任何核心业务逻辑——只有参数解析 + gRPC 调用转发
-- [ ] JWT 中间件在路由注册前挂载，未携带 Token 的请求一律返回 401
-- [ ] 所有 gRPC 调用都有 context deadline（防止阻塞）
-- [ ] 错误码统一通过 CommonResponse.code 传递
-
-## 五、阶段四：前端一日冲刺
-
-> [!tip] 技术选型确认
-> 前端统一使用 **React + Vite + TypeScript + Axios**，UI 组件库推荐 **Ant Design**（开箱即用、减少造轮子时间）。前端只负责页面渲染和接口请求，所有业务逻辑在后端处理。
-
-### 4.1 核心策略：共享基础层 + 下午独立填页
-
-两个前端共用了同一套后端 API 契约（`api/proto/v1/`），因此**不需要各自从零搭架子**。关键压缩思路：
-
-```mermaid
-graph LR
- subgraph Foundation["Foundation（共享基础层）"]
- A1["hr-frontend 脚手架初始化"] --> A2["user-frontend 脚手架初始化"]
- A2 --> A3["双方同步搭建: Router/Axios/AuthContext/布局组件"]
- A3 --> A4["Ant Design 主题配置"]
- end
-
- subgraph Candidate["候选人用户端（独立完成）"]
- B1["公开岗位列表"] --> B2["登录注册"] --> B3["档案表单"] --> B4["OSS直传"] --> B5["投递记录"]
- end
-
- subgraph HR["HR 管理端（独立完成）"]
- C1["登录注册"] --> C2["岗位CRUD"] --> C3["候选人列表"] --> C4["AI对话窗口"]
- end
-
- A4 -.-> B1
- A4 -.-> C1
-```
-
-| 模块 | 策略 | 复用收益 |
-|------|------|----------|
-| Foundation | 两个项目同时跑：Vite 初始化 + Router + Axios client + AuthContext + 布局组件 | 每个文件只写一次，两份代码各自 `cp -r` 起步，省去重复劳动 |
-| 候选人 / HR | 各自独立填充页面——候选人端 6 页 / HR 端 7 页，互不干扰 | 后端 API 已完成，前端只对接已有接口 |
-
-### 4.2 Foundation 搭建
-
-> [!note] 进度追踪
-> - [ ] T4.AM.1 hr-frontend 脚手架初始化 (`create-vite`)
-> - [ ] T4.AM.1b user-frontend 脚手架初始化 (`create-vite`)
-> - [ ] T4.AM.2 安装依赖 (antd, icons, react-router-dom)
-> - [ ] T4.AM.3 路由配置 + Layout 组件（hr: Sidebar/Header, user: Navbar/Footer）
-> - [ ] T4.AM.4 Axios client 封装（baseURL / interceptor / token 注入）
-> - [ ] T4.AM.5 AuthContext（useContext 管理 JWT，isAuthenticated / role 状态）
-> - [ ] T4.AM.6 Ant Design 全局主题 & 全局 CSS
-
-📋 展开查看 Web 网关详细任务表
- -| 编号 | 任务 | 前置依赖 | 耗时估计 | -|------|------|----------|----------| -| T3C.1 | 搭建 Gin 项目框架 + router 注册 | T3B.12 | 1h | -| T3C.2 | CORS 中间件（全局跨域处理） | T3C.1 | 30min | -| T3C.3 | JWT 鉴权中间件（读取 Token + 角色校验） | T3B.10 | 1h | -| T3C.4 | 参数合法性校验中间件 | T3C.1 | 1h | -| T3C.5 | gRPC Client 连接池 + codec JSON 转换 | T3B.12 | 1.5h | -| T3C.6 | Auth Handler（POST /api/auth/login, register） | T3C.5, T3B.2 | 1h | -| T3C.7 | Job Handler（CRUD 路由映射到 gRPC） | T3C.5, T3B.3 | 1.5h | -| T3C.8 | Application Handler | T3C.5, T3B.4 | 1h | -| T3C.9 | Profile Handler | T3C.5, T3B.5 | 1h | -| T3C.10 | Resume Handler（获取签名 URL 返回给前端） | T3C.5, T3B.6 | 1.5h | -| T3C.11 | Chat Handler（AI 对话转发） | T3C.5, T3B.7 | 1.5h | -| T3C.12 | Web 服务独立启动，用 curl/postman 测试 | T3C.6 ~ T3C.11 | 1h | - -
-
-
-#### AM 成果验证
-
-- [ ] 两个 `npm run dev` 均能启动，显示空白布局框架
-- [ ] 路由切换正常，Axios 请求可发送到 `http://localhost:8080/api`
-
-> [!note] 思考题
-> 为什么 AuthContext 只需要改"角色名"就可以复用？因为前后端的鉴权模型是一致的——都靠 JWT 中的 `role` 字段区分 HR/候选人。这个设计体现了"接口契约驱动开发"的思想：proto 定义了统一的用户身份模型，前端只需消费它。
-
-### 4.3 候选人用户端
-
-> [!note] 进度追踪
-> - [ ] T4.U.1 HomePage — 公开岗位列表（免登录浏览）
-> - [ ] T4.U.2 LoginPage + RegisterPage — 表单 + 提交到 `/api/auth/login`
-> - [ ] T4.U.3 JobDetailPage — 岗位详情 + 条件渲染投递按钮
-> - [ ] T4.U.4 SetupProfilePage — 结构化档案表单
-> - [ ] T4.U.5 ResumeUploadPage — OSS 签名 URL 直传组件
-> - [ ] T4.U.6 ApplicationPage + WarningModal — 投递记录 + 拦截弹窗
-
-📋 展开查看详细任务表
- -| 编号 | 任务 | 耗时 | 说明 | -|------|------|------|------| -| T4.AM.1 | `npx create-vite hr-frontend --template react-ts` | 5min | 同步创建两个项目 | -| T4.AM.1b | `npx create-vite user-frontend --template react-ts` | 5min | — | -| T4.AM.2 | 安装依赖 (`antd`, `@ant-design/icons`, `react-router-dom`) | 10min | 两端同步操作 | -| T4.AM.3 | 路由配置 + Layout 组件（hr: Sidebar/Header, user: Navbar/Footer） | 45min | 各自按风格定制 | -| T4.AM.4 | Axios client 封装（baseURL / interceptor / token 注入） | 30min | 模板几乎相同，改 baseURL 即可 | -| T4.AM.5 | AuthContext（useContext 管理 JWT，isAuthenticated / role 状态） | 30min | 两端复制 + 角色名差异 | -| T4.AM.6 | Ant Design 全局主题 & 全局 CSS | 20min | hr 用深色主题, user 用浅色主题 | - -
-
-
-#### 候选人端关键交互逻辑
-
-```mermaid
-flowchart TD
- A["游客打开 /user/"] --> B["查看岗位列表"]
- B --> C["点击投递按钮"]
- C --> D{"是否已登录？"}
- D -->|"否"| E["跳转 /user/login"]
- D -->|"是"| F{"是否完善档案？"}
- F -->|"否"| G["提示跳转到 /user/profile/setup"]
- F -->|"是"| H{"是否有合规简历？"}
- H -->|"否"| I["提示 /user/resume/upload📋 展开查看详细任务表
- -| 编号 | 任务 | 前置依赖 | 耗时 | 页面数 | -|------|------|----------|------|--------| -| T4.U.1 | HomePage：调用 `/api/jobs` 展示岗位卡片列表（免登录） | T4.AM | 40min | 1 | -| T4.U.2 | LoginPage + RegisterPage：表单 + 提交到 `/api/auth/login` | T4.AM | 40min | 2 | -| T4.U.3 | JobDetailPage：岗位详情 + 条件渲染投递按钮（已登录 && 有档案 && 有简历） | T4.U.1 | 40min | 1 | -| T4.U.4 | SetupProfilePage：Ant Design Form 表格单（姓名/电话/学历/院校/经历/技能） | T4.AM | 30min | 1 | -| T4.U.5 | ResumeUploadPage：选择文件 → 调 `/api/resume/upload` 拿签名 URL → 客户端 PUT 到 OSS | T4.AM, T3C.10 | 50min | 1 | -| T4.U.6 | ApplicationPage + WarningModal：投递记录 + 拦截弹窗 | T4.AM | 30min | 1+1 | - -PDF/DOC/DOCX 格式校验"] - H -->|"是"| J["发送 POST /api/applications"] - J --> K["投递成功 ✅"] -``` - -### 4.4 HR 管理端 - -> [!note] 进度追踪 -> - [ ] T4.H.1 LoginPage + RegisterPage（HR 账号体系） -> - [ ] T4.H.2 Dashboard/HomePage — 工作台概览 -> - [ ] T4.H.3 JobListPage — 本人岗位列表（分页 + 搜索） -> - [ ] T4.H.4 JobEditPage — 新建/编辑岗位表单 -> - [ ] T4.H.5 CandidatePage — 岗位下候选人列表 -> - [ ] T4.H.6 ProfileViewPage — 候选人结构化档案只读展示 -> - [ ] T4.H.7 ChatPage — AI 智能对话窗口 - -
-
-
-#### ChatPage 核心交互时序
-
-```mermaid
-sequenceDiagram
- participant P as ChatPage
- participant S as ChatContext
- participant A as Axios
- participant W as Web-Gin
-
- Note over P,W: 页面加载时自动拉历史
- P->>S: useEffect 触发
- S->>A: GET /api/chat/history
- A->>W: 带 JWT
- W-->>A: 历史消息数组
- A-->>S: state.push(...records)
- S-->>P: 渲染对话流
-
- Note over P,W: 用户输入新提问
- P->>A: POST /api/chat/messages {question}
- A->>W: 经 gRPC 转发到 Logic
- W-->>A: {reply, records[]}
- A-->>S: 追加 AI 回复
- S-->>P: 自动滚动到底部
-```
-
-### 4.5 收尾
-
-> [!note] 进度追踪
-> - [ ] T4.Z.1 两端 `npm run build` 验证无编译错误
-> - [ ] T4.Z.2 检查 .env 是否正确指向后端地址
-> - [ ] T4.Z.3 git add + commit 本阶段变更
-
-> [!warning] 前端权限边界
-> 前端只做视觉展示和跳转控制。**真正的权限校验必须发生在后端**。例如：即使前端显示了投递按钮，后端也应该再次校验候选人是否满足条件；不应依赖前端隐藏按钮来保护安全。验收时评委可能会故意绕过前端直接调接口测试。
-
-> [!tip] 加速技巧速查
-> - Ant Design 的 `Form` + `Input` + `Select` 可以直接粘贴文档示例修改
-> - 岗位列表复用同一个 `JobCard` 组件（候选人端和 HR 端都可以引用）
-> - Axios interceptor 写一次就能用在两个项目中
-> - 如果某个页面实在写不完，先用 `console.log` 占位，确保核心功能优先上线
-
-## 六、阶段五：前后端联调与自测
-
-> [!note] 进度追踪
-> - [ ] T5.1 全链路跑通：注册 → 登录 → 岗位发布 → 浏览
-> - [ ] T5.2 OSS 签名上传端到端测试（候选人端直传）
-> - [ ] T5.3 AI 对话完整流程测试（提问 → 数据查询 → 回答 → 历史加载）
-> - [ ] T5.4 权限隔离测试（非创建者操作他人岗位应被拒绝）
-> - [ ] T5.5 文件格式拦截测试（上传图片/TXT应为非法）
-> - [ ] T5.6 游客 vs 登录态功能边界测试
-> - [ ] T5.7 Bug 修复与体验优化
-
-### 6.1 详细任务清单
-
-| 编号 | 任务 | 前置依赖 | 耗时估计 |
-|------|------|----------|----------|
-| T5.1 | 全链路跑通：注册 → 登录 → 岗位发布 → 浏览 | T4.Z.3 | 2h |
-| T5.2 | OSS 签名上传端到端测试（候选人端直传） | T5.1 | 2h |
-| T5.3 | AI 对话完整流程测试（提问 → 数据查询 → 回答 → 历史加载） | T5.1 | 2h |
-| T5.4 | 权限隔离测试（非创建者操作他人岗位应被拒绝） | T5.1 | 1h |
-| T5.5 | 文件格式拦截测试（上传图片/TXT应为非法） | T5.2 | 1h |
-| T5.6 | 游客 vs 登录态功能边界测试 | T5.1 | 1h |
-| T5.7 | Bug 修复与体验优化 | T5.1 ~ T5.6 | 2h |
-
-### 6.2 验收 Checklist
-
-对照以下每一项逐项打勾：
-
-- [ ] gRPC 分层：Web 与 Logic 之间全部通过 gRPC 调用，无同工程内部函数调用
-- [ ] OSS 签名 URL：文件不落地本地，客户端直传 OSS
-- [ ] Eino 框架：使用了 Eino 封装的 Chat，非裸写 HTTP
-- [ ] JWT 鉴权：HR 只能管理自己发布的岗位，候选人未完善资料不可投递
-- [ ] AI 对话持久化：每条问答对入 MySQL，刷新页面自动加载历史上下文
-- [ ] 双端前端独立运行：hr-frontend 和 user-frontend 各自 `npm run dev` 均可启动
-- [ ] 四个源码目录完整、三个文档文件齐全
-
-## 七、阶段六：视频录制与提交
-
-> [!note] 进度追踪
-> - [ ] T6.1 撰写 answer.md（拓展设计方案：OpenClaw/Hermes 集成思路）
-> - [ ] T6.2 完善 README.md（启动部署指南 + 项目亮点）
-> - [ ] T6.3 完善 api.md（前后端接口说明）
-> - [ ] T6.4 完善 db.md（数据库设计文档补充）
-> - [ ] T6.5 整理代码仓库（检查 .gitignore、清理临时文件）
-> - [ ] T6.6 录制演示视频（原生实操、口述两大核心技术点）
-> - [ ] T6.7 提交至 KDoc 表单
-
-### 7.1 详细任务清单
-
-| 编号 | 任务 | 耗时估计 |
-|------|------|----------|
-| T6.1 | 撰写 answer.md（拓展设计方案：OpenClaw/Hermes 集成思路） | 2h |
-| T6.2 | 完善 README.md（启动部署指南 + 项目亮点） | 1.5h |
-| T6.3 | 完善 api.md（前后端接口说明） | 1.5h |
-| T6.4 | 完善 db.md（数据库设计文档补充） | 1h |
-| T6.5 | 整理代码仓库（检查 .gitignore、清理临时文件） | 1h |
-| T6.6 | 录制演示视频（原生实操、口述两大核心技术点） | 2h |
-| T6.7 | 提交至 KDoc 表单 | 30min |
-
-### 7.2 视频录制脚本大纲
-
-| 时间段 | 内容 | 口述要点 |
-|--------|------|----------|
-| 0:00-0:30 | 开场 + 服务启动演示 | "我现在依次启动 Logic 服务和 Web 网关服务..." |
-| 0:30-2:00 | 候选人端操作流程 | "候选人浏览岗位、注册、完善档案、上传简历、投递..." |
-| 2:00-3:00 | 口述核心技术点①：gRPC 两层架构 | "Web 网关接收 HTTP 请求后，通过 gRPC 远程调用 Logic 服务...这两个是独立进程..." |
-| 3:00-4:00 | 口述核心技术点②：OSS 签名 URL | "简历文件先获取签名URL，然后客户端直传 OSS，服务端零缓存..." |
-| 4:00-5:30 | HR 管理端操作流程 | "HR 登录、发布岗位、查看候选人、AI 对话..." |
-| 5:30-6:30 | AI 对话演示 | "输入自然语言提问，后端查询 MySQL 真实数据，通过 Eino 推送大模型..." |
-| 6:30-7:00 | 总结与结尾 | 简要说明个人开发收获和优化方向 |
-
-> [!important] 视频硬性要求
-> - **禁止剪辑拼接**：一次录完，保证画面真实
-> - **全程配语音解说**：不能无声黑屏
-> - **必录两大技术点口述**：gRPC 分层调用逻辑、OSS 签名 URL 安全上传下载
-> - **文件命名**：`姓名_学号_全栈大作业.mp4`
-
-## 八、风险识别与应对
-
-| 风险 | 影响范围 | 概率 | 应对措施 |
-|------|----------|------|----------|
-| OSS 平台注册审核慢 | 整个项目 | 中 | 提前注册，使用 MinIO 本地替代方案作为兜底 |
-| Eino 框架学习成本超预期 | AI 对话模块 | 中 | 官方文档优先，只使用基础 Chat 组件，不做复杂编排 |
-| Protobuf 字段频繁变更 | 前后端同步 | 高 | Proto 先行、冻结接口后再写业务代码；做好注释 |
-| gRPC 调试困难 | 后端通信 | 中 | 启用 grpcurl 命令行工具进行 RPC 调用调试 |
-| 前端样式适配耗时过长 | UI 呈现 | 中 | 使用现成 UI 组件库（Ant Design），不自研 CSS |
-| JWT Token 过期处理遗漏 | 用户体验 | 低 | 初期可不实现自动刷新，手动重新登录即可 |
-
-## 九、里程碑检查点
-
-> [!note] 里程碑进度追踪
-> 点击以下复选框标记里程碑完成情况：
-> - [ ] **M0** — 环境就绪
-> - [ ] **M1** — Proto 冻结
-> - [ ] **M2** — 后端可独立运行
-> - [ ] **M3** — 双端前端完成
-> - [ ] **M4** — 全链路联调通过
-> - [ ] **M5** — 视频已录制
-> - [ ] **M6** — 正式提交
-
-```mermaid
-graph LR
- M0["环境就绪📋 展开查看详细任务表
- -| 编号 | 任务 | 前置依赖 | 耗时 | 页面数 | -|------|------|----------|------|--------| -| T4.H.1 | LoginPage + RegisterPage（HR 账号体系） | T4.AM | 30min | 2 | -| T4.H.2 | Dashboard/HomePage：工作台概览（数据卡片） | T4.AM | 30min | 1 | -| T4.H.3 | JobListPage：本人岗位列表（Ant Design Table + 分页 + 搜索） | T4.AM | 50min | 1 | -| T4.H.4 | JobEditPage：新建/编辑岗位表单 | T4.AM | 40min | 1 | -| T4.H.5 | CandidatePage：岗位下候选人列表 + 跳转档案详情页 | T4.AM | 50min | 1 | -| T4.H.6 | ProfileViewPage：候选人结构化档案只读展示 | T4.H.5 | 30min | 1 | -| T4.H.7 | ChatPage：AI 智能对话窗口（消息气泡 + 历史加载） | T4.AM, T3C.11 | 80min | 1 | - -阶段一"] --> M1["Proto 冻结
阶段二"] - M1 --> M2["后端可独立运行
阶段三"] - M2 --> M3["双端前端完成
阶段四"] - M3 --> M4["全链路联调通过
阶段五"] - M4 --> M5["视频已录制
待提交"] - M5 --> M6["正式提交
KDoc表单"] - - classDef done fill:#c8e6c9; - classDef current fill:#fff9c4; - classDef future fill:#eceff1; - class M0,M1,M2,M3,M4 done; - class M5 current; - class M6 future; -``` - -## 关联笔记 - -- [[大作业项目要求]] — 作业完整需求文档 -- [[思维导图]] — 双端 gRPC HR 系统的知识体系与核心考点 -- [[工程结构]] — 详细的仓库目录结构与代码组织 diff --git a/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册.md b/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册.md index 4e58725..3c183d9 100644 --- a/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册.md +++ b/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册.md @@ -13,8 +13,8 @@ create time: 2026-05-11 16:00 ### 入门 -| # | 笔记 | 读它如果... | -|---|------|------------| +| # | 笔记 | 读它如果... | +| ----------------------------------------------------------------- | ------------------------------ | ---------------------- | | [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/01-Hello World 最小可运行 Server]] | **第一课**：三段式模板，从零搭起一个能跑的 server | 你是 gRPC 新手，想先看到"能跑的代码" | ### 核心概念 diff --git a/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式.md b/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式.md index e47e15b..03bf2ea 100644 --- a/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式.md +++ b/hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式.md @@ -1,20 +1,22 @@ --- tags: [gRPC, Go, Server, Best Practice] -create time: 2026-05-13 14:30 +create time: 2026-05-15 10:00 --- # Unimplemented 零-Stub 模式 ## 概述 -`UnimplementedXxxServer` 是 protoc-gen-go 为每个 gRPC service 自动生成的"空实现"结构体。通过嵌入它到自定义的 Service 结构体中，开发者只需编写实际需要的方法，其余方法自动获得 `codes.Unimplemented` 默认响应——这是一种兼顾开发便利性与接口契约安全的 Go 语言惯用模式。 +`UnimplementedXxxServer` 是 `protoc-gen-go` 为每个 gRPC service 自动生成的"空实现"结构体。通过将其嵌入自定义 Service 结构体，开发者只需编写实际需要的方法，未覆写的方法自动返回 `codes.Unimplemented` 错误——这是一种兼顾开发便利性与接口契约安全的 Go 语言惯用模式。 > [!question] 如果没有这个机制会怎样？ -> 想象你实现了三个 RPC method，后来 proto 新增了一个，编译器不报错——你的新方法永远不会被调用，直到线上某个 client 发出请求后才暴露出 Bug。这就是"静默失败"陷阱。 +> 假设你实现了三个 RPC method，后来 proto 新增了一个。**编译器不会报错**——你的新方法永远不会被调用，直到线上某个 client 发出请求后才暴露出 Bug。这就是"静默失败"陷阱。 + +核心思想：**把运行时 Bug 提前到编译期发现**。 ## Protobuf 生成的代码结构 -当你写一个 proto service： +当你定义一个 proto service： ```proto service UserService { @@ -23,12 +25,12 @@ service UserService { } ``` -protoc 会生成三类关键代码： +protoc 生成三类关键代码： | 生成物 | 作用 | |--------|------| -| `UserServiceServer` interface | 你必须实现的方法集合 | -| `UnimplementedUserServiceServer` struct | 所有方法都返回 `Unimplemented` 错误的默认实现 | +| `UserServiceServer` interface | 你必须满足的方法集合 | +| `UnimplementedUserServiceServer` struct | 所有方法都返回 `codes.Unimplemented` 错误的默认实现 | | `RegisterUserServiceServer()` 函数 | 将你的实现注册到 server 分发表 | 重点看 `UserServiceServer` interface 的定义： @@ -41,13 +43,14 @@ type UserServiceServer interface { } ``` -`mustEmbedUnimplementedUserServiceServer()` 是一个**无参数的空方法**。它的存在让 interface 成为封闭类型——其他任何想满足此接口的类型都必须显式嵌入 `UnimplementedUserServiceServer`，否则编译期直接拦截。这是 Go 社区著名的"封闭接口"（unexported method trick）反模式之一，但在 protobuf 场景下它是有意为之的设计。 +`mustEmbedUnimplementedUserServiceServer()` 是一个无参空方法。它让 interface 成为**封闭类型**——任何想满足此接口的类型都必须显式嵌入 `UnimplementedUserServiceServer`，否则编译期直接拦截。这是 Go 社区著名的"封闭接口"（unexported method trick）设计手法，在 protobuf 场景下是有意为之。 -## 为什么必须嵌入 +> [!note] 为什么叫 "closed set of methods"？ +> Go 的 interface 是 implicit（隐式实现），正常情况下你可以随时"默默"实现一个新接口。但 protobuf 通过注入一个只能由生成的 struct 提供的方法，把这个隐式契约变成了**显式嵌入**——你必须主动写下一行 `pb.UnimplementedUserServiceServer`，这种"被迫直面"就是安全感的来源。 -### 1. 减少样板代码 +## 嵌入用法 -嵌入后只需要实现你需要的那些方法： +嵌入后只需实现需要的业务方法： ```go type userService struct { @@ -62,89 +65,119 @@ func (s *userService) CreateUser(ctx context.Context, req *pb.CreateUserRequest) return &pb.CreateUserResponse{Id: generatedId}, nil } -// GetUser can be omitted — UnimplementedUserServiceServer returns the default error: +// GetUser 不写 — UnimplementedUserServiceServer 自动返回： // status.Error(codes.Unimplemented, "method GetUser not implemented") ``` -### 2. Proto 新增 RPC Method → 编译期告警 +### Proto 新增 Method → 编译期告警 -这是该模式最大的价值。假设后续你在 proto 里加了一个方法： +这是该模式最大的价值。**先回答一个疑惑**：proto 新增了 `DeleteUser`，重新运行 protoc 后 `UnimplementedUserServiceServer` 自身也会多出对应的默认实现，你的嵌入结构体照样能编译通过——那为什么说有风险前置？ -```proto -service UserService { - rpc CreateUser(...) returns (...); - rpc GetUser(...) returns (...); - rpc DeleteUser(...) returns (...); // ← 新增 -} -``` +原因在于两个实际场景： -重新运行 protoc 后，`UserServiceServer` interface 会多出 `DeleteUser` 签名。**此时编译就会失败**： +**场景 A：protoc 重新生成后忘记更新依赖** +如果你在同一份代码库里只改了 proto 文件，却忘了对所有 micro-service 跑 protoc，那些没更新的 service 就会报编译错误： ``` cannot use &userService{} as UserServiceServer: -missing method DeleteUser in receiver type userService + missing method DeleteUser in receiver type userService ``` -从"线上偶发 Bug"变成了"提交前就发现"——把风险前置到了编译期。 +CI 的编译检查会直接拦住——**某个服务漏跑 protoc**，而不是等到线上被调用的时候才发现这个方法从未被实现。 -### 3. 强制接口契约意识 +**场景 B：忘记嵌入 → 退化回普通接口** +如果不 embed `UnimplementedXxxServer`，proto 新增 method 时编译器照样不拦你。新方法永远不会被调用，直到线上某个 client 触发了它——这就退化成了"没这个机制之前"的样子。这也是为什么"正确嵌入"是这套模式生效的前提。 -如果不用 embed，你可以"选择性实现"——只有某些方法、其他全忽略。这会导致服务方和客户端对接口理解不一致。Zero-stub 模式强迫每次新增 method 时都做一次有意识的决策：**实现它**，还是保持 Unimplemented？ +--- -## 与反射型语言的对比 +> [!question] 那"强制接口契约意识"怎么理解？ +> +> 正确用法下，Proto 新增 method 后，`UnimplementedXxxServer` 也会跟着长出新的兜底实现，编译是**通过的**。但这正是设计者想要的效果： +> - **不强制你立刻实现**（不影响正常请求） +> - **但强制你在 protoc 重新生成的那一刻"看到"变更** +> - 从此时起你有两次决策机会：① 跑 protoc 时意识到契约变了；② 决定是否要把 `codes.Unimplemented` 替换成真实逻辑 +> - 对比非类型安全语言（Java 等），新方法可以永远不被实现且永远不被发现——Go 版本至少让每次 proto 变更都变得**可追踪** -在 Java 等语言中，gRPC 通常要求你继承一个基类（如 `UserServiceImplBase`），效果类似： +## 嵌入策略对比 -```java -public class UserServiceImpl extends UserServiceImplBase { - @Override - public void createUser(..., StreamObserver observer) { - // 只重写需要的 - } - // getUser 自动走父类的 Unimplemented +不同语言的 gRPC 框架提供了类似的保底机制，但 Go 的嵌入方式有其独特优势： + +| 维度 | Go（嵌入） | Java / C++（继承基类） | Python（抽象基类） | +|------|-----------|----------------------|-------------------| +| **语法** | `struct` 嵌入 | 继承 `ServiceImplBase` | 继承 `Servicer` + `@abc.abstractmethod` | +| **单继承限制** | 无（可嵌多个类型） | 有 | 有 | +| **方法优先级控制** | 嵌入顺序决定 | 虚函数重写 | MRO 决定 | +| **扩展性** | 可同时混入 store、logger 等依赖 | 只能通过构造函数传递 | 同上 | + +Go 版本的优势在于**嵌入比继承更灵活**——可以同时嵌入多个类型、控制方法优先级（离当前结构体越近优先匹配），并且没有单继承限制。 + +## Streaming RPC 下的行为 + +上面的例子都是 unary RPC。对于 streaming RPC，behavior 完全一致： + +```go +type MessageService struct { + pb.UnimplementedMessageServiceServer } + +// 只实现 stream-send 的场景 +func (s *MessageService) StreamMessages(req *StreamRequest, ss grpc.ServerStream) error { + for i := 0; i < req.Count; i++ { + if err := ss.SendMsg(&StreamResponse{Data: fmt.Sprintf("msg-%d", i)}); err != nil { + return status.Errorf(codes.Internal, "send failed: %v", err) + } + } + return nil +} + +// BidirectionalStreaming 不写 → 自动返回 codes.Unimplemented ``` -Go 版本的优势在于**嵌入比继承更灵活**——你可以同时嵌入多个类型、控制方法优先级（离当前结构体越近优先匹配），并且没有单继承限制。 +关键点： + +- UnimplementedStub 对 unary、server-streaming、client-streaming、bidirectional-streaming **统一处理** +- Streaming handler 的错误返回值仍然是 `error`，未覆写时同样走 `codes.Unimplemented` +- 如果你在 CI 中有编译检查，streaming 方法的遗漏也能被捕获 ## 执行流程图解 ```mermaid flowchart TD - Client["Client RPC Call"] --> Lookup["Server 查找 dispatch table"] + Client["Client RPC Call"] --> Lookup["Server dispatch table"] Lookup --> Found{"Method 是否被覆写？"} Found -->|"是"| Handler["Handler 执行业务逻辑"] - Found -->|"否"| Fallback["UnimplementedStub
codes.Unimplemented 错误"] + Found -->|"否"| Fallback["UnimplementedStub
codes.Unimplemented"] Handler --> Resp["Response to Client"] Fallback --> Resp ProtoChanged["Proto 新增 Method"] --> GenCode["Protoc 重新生成"] - GenCode --> CompileErr["userService 缺少新方法，编译失败 ✅"] + GenCode --> AllUpdated["所有 service 同步更新
Embed 自动继承新方法，编译通过"] + GenCode --> PartialUpdate["部分 service 漏跑 protoc
CI 拦截 ✅"] style Client fill:#E3F2FD,stroke:#1976D2 style Handler fill:#A8E6CF,stroke:#2E7D32 style Fallback fill:#FFB3BA,stroke:#C62828 - style CompileErr fill:#FFF3E0,color:#000,stroke:#E65100 + style AllUpdated fill:#FFF3E0,color:#000,stroke:#E65100 + style PartialUpdate fill:#FFF3E0,color:#000,stroke:#E65100 ``` ## 实际使用中的注意事项 > [!warning] 不要手动实现 Unimplemented 方法 +> +> 如果在自己的结构体中也定义了同名 method（比如不小心写了 `MustEmbedUnimplementedUserServiceServer()`），它会覆盖嵌入类型的空方法。虽然功能上不影响（interface 检查只看是否存在），但语义混乱，应避免。 -如果你在自己的结构体中也定义了一个同名 method（比如不小心写了 `func (s *userService) MustEmbedUnimplementedUserServiceServer()`），它会**覆盖**嵌入类型的空方法。虽然功能上不影响（interface 检查只看是否存在），但语义混乱，应避免。 - -> [!tip] 如何快速确认某个 Service 的所有方法都被覆盖了？ - -可以用 IDE 的 "implement interface" 功能列出未实现的方法，或者写一个简单的 compile test： - -```go -var _ pb.UserServiceServer = (*userService)(nil) // 编译期检查 -``` - -加上这一行后，任何遗漏的方法都会在这句编译报错，适合作为 CI 的一部分。 - -## 常见陷阱 +> [!warning] embed vs pointer embed 的选择 +> +> gRPC 生成的 `UnimplementedXxxServer` **值类型和指针类型都可以嵌入**，但效果不同： +> +> | 嵌入方式 | `*userService` 是否满足接口 | 说明 | +> |---------|---------------------------|------| +> | `pb.UnimplementedXxxServer`（值） | `*userService` ✅ | 推荐，指针接收者可调用值方法 | +> | `*pb.UnimplementedXxxServer`（指针） | `*userService` ✅ 且 `userService` ❌ | 仅指针满足接口 | +> +> **最佳实践**: 大多数 gRPC server 方法签名是 `func (s *Service) Method(...)`，所以嵌入值类型的 `Unimplemented` 即可同时支持两种调用方式。 > [!danger] 嵌入顺序决定方法优先级 > @@ -157,46 +190,38 @@ var _ pb.UserServiceServer = (*userService)(nil) // 编译期检查 > } > ``` > -> 养成**将 Unimplemented 嵌入放在最后**的习惯，避免意外覆盖： +> 养成**将 Unimplemented 嵌入放在最后**的习惯： > > ```go > type userService struct { > *UserStore // 业务依赖先放前面 -> someHelper // 工具类 +> logger // 工具类 > pb.UnimplementedUserServiceServer // 永远放最后 > } > ``` -> [!warning] `embed` vs `pointer embed` 的选择 -> -> gRPC 生成的 `UnimplementedXxxServer` **值类型和指针类型都可以嵌入**，但效果不同： -> -> | 嵌入方式 | `*userService` 是否满足接口 | 说明 | -> |---------|---------------------------|------| -> | `pb.UnimplementedXxxServer`（值） | `*userService` ✅ | 推荐，指针接收者可调用值方法 | -> | `*pb.UnimplementedXxxServer`（指针） | `*userService` ✅ 且 `userService` ❌ | 仅指针满足接口 | -> -> **最佳实践**: 大多数 gRPC server 方法签名是 `func (s *Service) Method(...)`，所以用指针 receiver。嵌入值类型的 `Unimplemented` 即可同时支持两种调用方式。 - ## Server 集成示例 -下面是一个完整的、可直接运行的 Server 搭建片段，展示 UnimplementedStub 在整个链路中的位置： +下面展示 UnimplementedStub 在整个服务链路中的位置（核心逻辑已简化）： ```go package server import ( "context" + "fmt" "log" "google.golang.org/grpc" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" pb "your/proto/package" ) // UserServiceImpl — 只需实现实际需要的方法 type UserServiceImpl struct { - store *UserStore // 业务依赖 - pb.UnimplementedUserServiceServer // 放最后 + store *UserStore // 业务依赖 + pb.UnimplementedUserServiceServer // 永远放最后 } func (s *UserServiceImpl) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.CreateUserResponse, error) { @@ -222,9 +247,39 @@ func Register(srv *grpc.Server, store *UserStore) { ``` 关键要点： -- `RegisterUserServiceServer()` 内部会校验你传入的类型是否实现了 `UserServiceServer` interface + +- `RegisterUserServiceServer()` 内部会校验传入的类型是否实现了 `UserServiceServer` interface - 由于 `UnimplementedUserServiceServer` 提供了所有方法的默认实现，你只需编写实际需要的 method -- Proto 新增 method → protoc 重新生成 → 编译失败 → **有意识的决策点** +- Proto 新增 method → protoc 重新生成 → **变更暴露** → 有意识的决策点（是否把 `codes.Unimplemented` 替换成真实逻辑） + +## 常见排错 + +> [!bug] 忘记 embed → "missing method xxx" 编译错误 +> +> 如果你看到类似下面的错误，首先检查是否忘写了嵌入行： +> +> ``` +> cannot use &userService{} as UserServiceServer: +> missing method CreateUser in receiver type userService +> ``` +> +> 确认嵌入 `pb.UnimplementedXxxServer` 后即可解决。 + +> [!bug] embed 的是指针而不是值 → `userService` 类型不满足接口 +> +> ```go +> type userService struct { +> *pb.UnimplementedUserServiceServer // 指针嵌入 +> } +> var _ UserServiceServer = &userService{} // ✅ +> var _ UserServiceServer = userService{} // ❌ compile error +> ``` +> +> 如果你的某些代码以值类型传 service，建议改用值嵌入。 + +> [!bug] 自定义方法与嵌入类型冲突 +> +> 如果你在结构体上手动定义了 `mustEmbedUnimplementedUserServiceServer()` 或其他与嵌入类型同名的方法，它会在方法解析时**遮蔽**嵌入类型的方法——虽然通常不会影响最终行为，但会造成混淆和潜在 bug。 ## 关联笔记 diff --git a/hzh/DEV/跨域问题调试.md b/hzh/DEV/跨域问题调试.md index 83e7d2e..af7f988 100644 --- a/hzh/DEV/跨域问题调试.md +++ b/hzh/DEV/跨域问题调试.md @@ -166,6 +166,8 @@ log.Printf("Response headers: Allow-Origin=%s", c.Writer.Header().Get("Access-Co #### 场景 4：Nginx / 反向代理挡住了 CORS header +> 详细的 Nginx 反向代理处理跨域的三种方案，详见 [[hzh/DEV/跨域问题调试/nginx-reverse-proxy-cors]]。 + 当你使用 Nginx 做反向代理时，它默认会过滤掉上游没有明确声明的 header。 ```nginx @@ -264,6 +266,7 @@ export default { ## 关联笔记 +- [[hzh/DEV/跨域问题调试/nginx-reverse-proxy-cors]] — Nginx 反向代理处理跨域的三种方案 - [[GIN/3-middleware/cors-registration-scope]] — 全局 vs 分组注册 CORS 中间件的取舍 - [[GIN/3-middleware/cors-preflight]] — OPTIONS 预检请求的触发条件与两轮对话流程 - [[GIN/3-middleware]] — 中间件三级作用域机制 \ No newline at end of file diff --git a/hzh/DEV/跨域问题调试/nginx-reverse-proxy-cors.md b/hzh/DEV/跨域问题调试/nginx-reverse-proxy-cors.md new file mode 100644 index 0000000..7ab7e1f --- /dev/null +++ b/hzh/DEV/跨域问题调试/nginx-reverse-proxy-cors.md @@ -0,0 +1,244 @@ +--- +tags: [Nginx, 反向代理, 跨域, CORS, 运维] +create time: 2026-05-15 18:00 +--- + +# Nginx 反向代理处理跨域 + +## 概述 + +本文档讲解如何利用 Nginx 反向代理解决浏览器端跨域（CORS）问题，从"最干净的方案"到"兜底方案"逐一展开，覆盖生产环境的典型场景。 + +> [!TIP] 核心思路 +> 跨域是浏览器的安全策略，不是后端的限制。Nginx 做反向代理的核心思想：**让浏览器看到的地址和页面同源**，或者 **由 Nginx 在响应头中注入合法的 CORS header**。 + +## 正文 + +### 三种方案总览 + +```mermaid +flowchart LR + A[遇到跨域问题] --> B{能否统一域名?} + B -- 能 --> C["方案一: 同源代理
零跨域, 最干净"] + B -- 不能 --> D{后端已设 CORS header?} + D -- 能控制后端 --> E["方案二: Nginx 注入
网关统一管理"] + D -- 无法改后端 --> F["方案三: 透传 Header
保留上游配置"] +``` + +--- + +### 方案一：同源代理 — 从根本上消灭跨域（推荐） + +请求的域名和页面域名完全一致，浏览器根本不认为这是跨域请求。 + +```nginx +server { + listen 80; + server_name app.example.com; + + # 前端静态资源 + location / { + root /usr/share/nginx/html; + try_files $uri $uri/ /index.html; + } + + # API 代理 — 浏览器看到 /api/xxx，和页面同源 + location /api/ { + proxy_pass http://backend:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +**请求链路示意：** + +```mermaid +sequenceDiagram + participant B as 浏览器 + participant N as Nginx + participant S as 后端服务 + + B->>N: GET /api/user （同源，无预检） + N->>S: GET /api/user + S-->>N: 200 OK (body) + N-->>B: 200 OK (body，不含 CORS header) +``` + +| 维度 | 说明 | +|------|------| +| 是否真正解决跨域 | ✅ 根本解决，浏览器不认为存在跨域 | +| Cookie / Session | 天然支持，无需额外配置 | +| 安全性 | 最高，不存在任何跨域风险 | +| 适用前提 | 你能控制前端部署域名 | + +> **思考**：如果前端和后端分别部署在不同的子域名（如 `app.example.com` 和 `api.example.com`），这个方案还适用吗？不适用——这就是下面两种方案的用武之地。 + +--- + +### 方案二：Nginx 注入 CORS header（前后端无法同域时） + +当 API 确实需要独立域名时，Nginx 充当"CORS 网关"，负责注入正确的响应头。 + +```nginx +server { + listen 80; + server_name api.example.com; + + # 允许的合法前端域名列表 + set $cors_origin ""; + + if ($http_origin ~* "^https://(app\.example\.com|dev\.example\.com)$") { + set $cors_origin $http_origin; + } + + location /api/ { + proxy_pass http://backend:8080; + + # 白名单校验后的 Origin（未匹配则不注入，防止随意跨域） + add_header Access-Control-Allow-Origin $cors_origin always; + add_header Access-Control-Allow-Credentials "true" always; + add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-Token" always; + add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always; + add_header Access-Control-Max-Age "3600" always; + add_header Access-Control-Expose-Headers "X-Total-Count, X-Request-Id" always; + + # 预检请求直接响应 204 + if ($request_method = OPTIONS) { + return 204; + } + } +} +``` + +**为什么这里用了正则白名单而不是直接回显 `$http_origin`？** + +因为直接回显虽然省事，但意味着**任意域名**都能通过白名单校验拿到 CORS header，等同于变相开放。通过 `~*` 正则限定具体域名，是安全加固的一层。 + +#### 关键参数解释 + +| 参数 | 作用 | 注意事项 | +|------|------|---------| +| `add_header ... always` | `always` 确保即使后端返回 4xx/5xx 也加上 CORS header | 不加 `always` 时错误响应会丢失跨域信息 | +| `set $cors_origin ""` | 初始化为空，默认不允许跨域 | 这是一种"拒绝所有、放行白名单"的安全策略 | +| `if ($request_method = OPTIONS)` | 拦截预检请求，避免转发给后端 | Nginx 的 `if` 在此处使用是安全的（官方推荐用法） | +| `Access-Control-Max-Age` | 浏览器缓存预检结果的时间（秒） | 开发时建议设为 `0`，生产可设 `3600`~`86400` | + +> [!WARNING] Credential 模式陷阱 +> 如果设置了 `Access-Control-Allow-Credentials: true`，`Access-Control-Allow-Origin` **绝对不能是 `*`**。必须动态回显具体域名或走白名单——上面的配置已经通过白名单规避了这个问题。 + +--- + +### 方案三：透传后端 CORS header + +当后端已经正确配置了 CORS header 时，**默认情况下 Nginx 不会移除这些响应头**，所以大多数场景你不需要任何额外配置。 + +> [!TIP] Nginx Header 传递规则（重点） +> - **无 `add_header` 时**：Nginx 完整透传上游响应头（包括 CORS header），且子级 `location` 会继承父级的 `add_header`。 +> - **有 `add_header` 时**：Nginx **丢弃所有父级 `add_header` + 上游的 CORS header**。此时必须显式重新添加需要的头。 +> +> 这是最常见的坑——你在某个 `location` 里加了一个自定义 header，结果发现 CORS header 突然消失了。 + +```nginx +# 如果你的 Nginx 配置里只有纯粹的 proxy_pass，无需额外操作： +location /api/ { + proxy_pass http://backend:8080; +} +``` + +但如果因为其他原因你已经在这个 `location` 里有 `add_header`（比如加了自定义 X-Custom-Header），就需要把 CORS header 一并补上： + +```nginx +location /api/ { + proxy_pass http://backend:8080; + + # 原有自定义 header + add_header X-Request-Id $request_id always; + + # 补充 CORS header（否则会被 Nginx 吞掉） + proxy_hide_header Access-Control-Allow-Origin; + if ($http_origin ~* "^https://.+\.example\.com$") { + add_header Access-Control-Allow-Origin $http_origin always; + add_header Access-Control-Allow-Credentials "true" always; + } +} +``` + +| 做法 | 效果 | 适用场景 | +|------|------|---------| +| 不加任何 header | ✅ 完全透传后端 CORS | 后端已配置 CORS，Nginx 只做纯代理 | +| 仅加 `proxy_hide_header` | ⚠️ 不发送 CORS header | 需要临时屏蔽后端的 CORS | +| 加 `add_header` + `proxy_hide_header` | ✅ 手动重建 CORS | 已在该 location 有其他 header 需共存时 | + +> [!NOTE] 最佳实践建议 +> 如果后端和前端都在你的控制范围内，**统一将 CORS 配置放在后端中间件层**是最推荐的做法。Nginx 只负责路由转发，不做跨域决策——这样配置清晰、易于维护和审计。只有当你无法修改后端代码时，才需要在 Nginx 层"代劳"设置 CORS header（即回到方案二）。 + +--- + +### 常见陷阱与调试技巧 + +#### 陷阱一：`proxy_pass` 尾部斜杠的语义差异 + +`location /api/` 和 `proxy_pass` URL 末尾的 `/` 组合会产生不同行为，这是最容易踩的坑。 + +| `location` | `proxy_pass` 结尾 | 请求 `/api/user` → 转发给后端的路径 | +|------------|------------------|-----------------------------------| +| `/api/` | 无 `/`（`http://backend:8080`） | `/api/user`（原样转发） | +| `/api/` | 有 `/`（`http://backend:8080/`） | `/user`（`/api/` 被截断替换） | + +> **记忆口诀**：`proxy_pass` URL 末尾有没有 `/`，决定了 location 匹配部分是否会被截断。 +> - 没 `/` → 保持前端路径前缀不变（适合前后端共用同一个 API 前缀） +> - 有 `/` → 自动去掉 location 前缀（适合后端路由不需要前缀的场景） + +#### 陷阱二：CORS header 突然消失 — Nginx 的继承规则 + +Nginx 的 `add_header` 有一个非常反直觉的行为：**一旦你在某个层级定义了 `add_header`，该层级及以下会丢弃所有父级的 header + 上游响应头。** + +排查方法： +1. 用 `curl -vI https://api.example.com/api/test` 直接看响应头 +2. 如果能看到 CORS header → 是 Nginx 配置层覆盖问题，回到方案三的规则修复 +3. 如果看不到 → 检查后端实际返回了哪些 header（可能后端根本没设） + +#### 陷阱三：`Access-Control-Allow-Headers` 遗漏字段 + +浏览器预检时会带上自定义 header（如 `X-Token`, `Authorization`），如果 Nginx 白名单中不包含这些字段，预检直接失败： + +```bash +# 在控制台观察到的典型错误 +# Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy: +# Request header field x-token is not allowed by Access-Control-Allow-Headers in preflight response. +``` + +解决：确保 `Access-Control-Allow-Headers` 包含前端所有可能发送的自定义 header。 + +#### 调试 Checklist + +```mermaid +flowchart TD + A[浏览器报 CORS 错误] --> B{curl 能正常访问?} + B -- No --> C["检查后端服务是否存活
及健康检查路径"] + B -- Yes --> D{"Response Header 有 CORS?"} + D -- No --> E["后端未设置 CORS header
→ 在后端中间件中添加"] + D -- Yes --> F{"curl 有但浏览器没有?"} + F -- Yes --> G["Nginx add_header 覆盖了上游
→ 检查方案三的继承规则"] + F -- No --> H["检查 Response Status Code
是否为 2xx/3xx?
(4xx/5xx 需加 always)"] +``` + +--- + +### 对比总结 + +| 维度 | 方案一（同源代理） | 方案二（Nginx 注入） | 方案三（透传后端） | +|------|------------------|--------------------|-------------------| +| 是否真正解决跨域 | ✅ 根本解决 | ⚠️ 表面绕过 | ⚠️ 取决于后端 | +| 安全性 | 最高（无跨域） | 高（白名单可控） | 低（信任后端） | +| Cookie 支持 | ✅ 天然支持 | ✅ 配合白名单可用 | ✅ 天然支持 | +| 维护成本 | 低 | 中等（域名变更需改配置） | 最低 | +| 推荐优先级 | 🥇 首选 | 🥈 次选 | 🥉 兜底 | + +## 关联笔记 + +- [[hzh/DEV/跨域问题调试]] — 跨域排查完整指南 +- [[GIN/3-middleware/cors-registration-scope]] — 后端 Go/Gin 端 CORS 中间件配置参考 diff --git a/hzh/GIN/11-static-files.md b/hzh/GIN/11-static-files.md index 1a87263..dff6bf9 100644 --- a/hzh/GIN/11-static-files.md +++ b/hzh/GIN/11-static-files.md @@ -7,7 +7,7 @@ create time: 2026-04-28 00:00 ## 概述 -Gin 提供了三种方式提供静态资源：`Static`（目录映射）、`StaticFS`（自定义文件系统）和 `StaticFile`（单文件）。理解它们的区别和使用场景，是构建完整 Web 服务的基础。 +Gin 提供了三种核心 API 提供静态资源：`Static`（目录映射）、`StaticFS`（自定义文件系统）和 `StaticFile`（单文件）。此外，通过 `io.Reader` 直接返回文件流以及自定义中间件也是实际项目中常见的手段。理解它们的区别和使用场景，是构建完整 Web 服务的基础。 思考题：为什么生产环境通常不推荐用 Go 直接提供静态文件？Nginx/CDN 相比有什么优势？ @@ -94,9 +94,9 @@ r.StaticFile("/robots.txt", "./static/robots.txt") r.Run(":8080") ``` -### 4. `io.Reader` 直接返回文件流 +### 4. 从内存直接返回文件 -对于不需要落盘的文件（如数据库读取的图片、动态生成的 PDF），可以直接从 Reader 输出： +对于不需要落盘的文件（如数据库读取的图片、动态生成的 PDF），可以直接从内存输出到响应体： ```go func getFileFromDB(c *gin.Context) { @@ -107,14 +107,14 @@ func getFileFromDB(c *gin.Context) { return } - // 直接用 io.Reader 写入响应 + // DataBytes 直接写入 body，比 SetHeader + Write 更简洁 c.DataBytes(http.StatusOK, contentType, fileData) - // 或者 - // c.Writer.Header().Set("Content-Type", contentType) - // c.Writer.Write(fileData) } ``` +> [!tip] Reader vs []byte +> Gin 没有提供专门的 `Reader` 接口写入流式数据。大文件场景建议配合 `c.File()`（内部使用 `sendfile`）或手动实现分块写入，避免一次性加载整个文件到内存。 + ### 5. 自定义文件服务器 如果需要控制缓存头、限速、访问权限等，可以自己实现 `StaticFS`： @@ -124,19 +124,22 @@ func secureStatic() gin.HandlerFunc { return func(c *gin.Context) { path := c.Request.URL.Path - // 安全检查：防止目录遍历攻击 + // 安全检查：确保请求路径在允许的目录范围内 + // filepath.Clean 会解析 ".."，防止目录遍历攻击 cleanPath := filepath.Clean(path) - if strings.Contains(cleanPath, "..") { + baseDir, _ := filepath.Abs("./static") // 允许的基础目录 + targetPath, _ := filepath.Abs(filepath.Join(baseDir, cleanPath)) + if !strings.HasPrefix(targetPath, baseDir+"/") && targetPath != baseDir { c.AbortWithStatus(http.StatusForbidden) return } - // 设置缓存头 + // 设置缓存和安全头 c.Header("Cache-Control", "public, max-age=31536000") // 一年 c.Header("X-Content-Type-Options", "nosniff") // 交给内置文件服务器 - http.FileServer(http.Dir("./static")).ServeHTTP(c.Writer, c.Request) + http.FileServer(http.Dir(baseDir)).ServeHTTP(c.Writer, c.Request) } } @@ -148,6 +151,9 @@ func main() { } ``` +> [!warning] 常见错误 +> 不要这样写：`strings.Contains(path, "..")`。因为 `filepath.Clean()` 已经解析了 `..`，清理后的路径中不会出现 `..`。正确做法是比较**解析后**的绝对路径是否仍在允许的基目录内。 + ### 6. 静态文件 vs API 性能对比 ```mermaid diff --git a/hzh/GIN/12-server-config.md b/hzh/GIN/12-server-config.md index 17da547..76aa1fe 100644 --- a/hzh/GIN/12-server-config.md +++ b/hzh/GIN/12-server-config.md @@ -157,7 +157,7 @@ func main() { > **安全警告：** 如果不设置可信代理，攻击者可以伪造 `X-Forwarded-For` 头注入任意 IP，绕过 IP 白名单限流。务必只信任你知道的代理 IP 段。 -### 5. 完整的生產環境啟動範例 +### 5. 完整的生产环境启动规范 ```go func main() { diff --git a/hzh/MS/02-服务治理/API网关/README.md b/hzh/MS/02-服务治理/01-API网关.md similarity index 96% rename from hzh/MS/02-服务治理/API网关/README.md rename to hzh/MS/02-服务治理/01-API网关.md index 8735d63..1c88bcd 100644 --- a/hzh/MS/02-服务治理/API网关/README.md +++ b/hzh/MS/02-服务治理/01-API网关.md @@ -148,6 +148,6 @@ graph TB ## 关联笔记 -- [[02-服务治理/服务发现/README]] — 网关需要订阅服务实例列表 -- [[02-服务治理/流量治理/README]] — 高级路由和灰度发布的延伸 +- [[02-服务治理/04-服务发现]] — 网关需要订阅服务实例列表 +- [[02-服务治理/08-流量治理]] — 高级路由和灰度发布的延伸 - [[hzh/MS/API 设计原则]] — API Gateway 的设计与 REST/gRPC 选型 diff --git a/hzh/MS/02-服务治理/安全机制/README.md b/hzh/MS/02-服务治理/02-安全机制.md similarity index 96% rename from hzh/MS/02-服务治理/安全机制/README.md rename to hzh/MS/02-服务治理/02-安全机制.md index af8aa58..4bc12ea 100644 --- a/hzh/MS/02-服务治理/安全机制/README.md +++ b/hzh/MS/02-服务治理/02-安全机制.md @@ -176,6 +176,6 @@ a1b2c3d4e5f6... ## 关联笔记 -- [[02-服务治理/API网关/README]] — 网关层的统一鉴权和限流 -- [[02-服务治理/服务发现/README]] — 服务注册时也需要安全认证 +- [[02-服务治理/01-API网关]] — 网关层的统一鉴权和限流 +- [[02-服务治理/04-服务发现]] — 服务注册时也需要安全认证 - [[hzh/MS/API 设计原则]] — API 设计中的安全考量 diff --git a/hzh/MS/02-服务治理/分布式追踪/README.md b/hzh/MS/02-服务治理/03-分布式追踪.md similarity index 96% rename from hzh/MS/02-服务治理/分布式追踪/README.md rename to hzh/MS/02-服务治理/03-分布式追踪.md index 97ae778..518ff49 100644 --- a/hzh/MS/02-服务治理/分布式追踪/README.md +++ b/hzh/MS/02-服务治理/03-分布式追踪.md @@ -204,6 +204,6 @@ flowchart LR ## 关联笔记 -- [[02-服务治理/API网关/README]] — API Gateway 可以在入口处注入 trace_id -- [[04-可观测性/链路追踪/README]] — 更详细的链路追踪设计方法论 -- [[02-服务治理/配置管理/README]] — 配置中心的动态刷新可以联动调整采样率 +- [[02-服务治理/01-API网关]] — API Gateway 可以在入口处注入 trace_id +- [[04-可观测性/03-链路追踪]] — 更详细的链路追踪设计方法论 +- [[02-服务治理/07-配置管理]] — 配置中心的动态刷新可以联动调整采样率 diff --git a/hzh/MS/02-服务治理/服务发现/README.md b/hzh/MS/02-服务治理/04-服务发现.md similarity index 96% rename from hzh/MS/02-服务治理/服务发现/README.md rename to hzh/MS/02-服务治理/04-服务发现.md index dda7e13..764d307 100644 --- a/hzh/MS/02-服务治理/服务发现/README.md +++ b/hzh/MS/02-服务治理/04-服务发现.md @@ -200,6 +200,6 @@ sequenceDiagram ## 关联笔记 -- [[02-服务治理/API网关/README]] — API Gateway 是服务发现的用户之一 -- [[02-服务治理/容错模式/README]] — 健康检查是容错体系的基础 -- [[05-部署运维/Kubernetes/README]] — K8s Service 的服务发现原理 +- [[02-服务治理/01-API网关]] — API Gateway 是服务发现的用户之一 +- [[02-服务治理/06-容错模式]] — 健康检查是容错体系的基础 +- [[05-部署运维/02-Kubernetes]] — K8s Service 的服务发现原理 diff --git a/hzh/MS/02-服务治理/服务间通信/README.md b/hzh/MS/02-服务治理/05-服务间通信.md similarity index 96% rename from hzh/MS/02-服务治理/服务间通信/README.md rename to hzh/MS/02-服务治理/05-服务间通信.md index 411db8e..231587d 100644 --- a/hzh/MS/02-服务治理/服务间通信/README.md +++ b/hzh/MS/02-服务治理/05-服务间通信.md @@ -199,6 +199,6 @@ sequenceDiagram ## 关联笔记 -- [[02-服务治理/API网关/README]] — API Gateway 负责协议转换 -- [[03-数据一致性/分布式事务/README]] — 消息投递的一致性保障 -- [[05-部署运维/Kubernetes/README]] — Sidecar 代理透明拦截通信流量 +- [[02-服务治理/01-API网关]] — API Gateway 负责协议转换 +- [[03-数据一致性/02-分布式事务]] — 消息投递的一致性保障 +- [[05-部署运维/02-Kubernetes]] — Sidecar 代理透明拦截通信流量 diff --git a/hzh/MS/02-服务治理/容错模式/README.md b/hzh/MS/02-服务治理/06-容错模式.md similarity index 98% rename from hzh/MS/02-服务治理/容错模式/README.md rename to hzh/MS/02-服务治理/06-容错模式.md index e3afc12..3cb09a6 100644 --- a/hzh/MS/02-服务治理/容错模式/README.md +++ b/hzh/MS/02-服务治理/06-容错模式.md @@ -536,6 +536,6 @@ sequenceDiagram ## 关联笔记 -- [[02-服务治理/API网关/README]] — 网关层的限流和熔断插件 -- [[02-服务治理/服务发现/README]] — 健康检查是服务发现的基础 -- [[04-可观测性/Metrics监控/README]] — 熔断器的指标暴露和告警联动 +- [[02-服务治理/01-API网关]] — 网关层的限流和熔断插件 +- [[02-服务治理/04-服务发现]] — 健康检查是服务发现的基础 +- [[04-可观测性/01-Metrics监控]] — 熔断器的指标暴露和告警联动 diff --git a/hzh/MS/02-服务治理/配置管理/README.md b/hzh/MS/02-服务治理/07-配置管理.md similarity index 96% rename from hzh/MS/02-服务治理/配置管理/README.md rename to hzh/MS/02-服务治理/07-配置管理.md index 468e784..2d4ae4c 100644 --- a/hzh/MS/02-服务治理/配置管理/README.md +++ b/hzh/MS/02-服务治理/07-配置管理.md @@ -169,5 +169,5 @@ flowchart LR ## 关联笔记 -- [[02-服务治理/服务发现/README]] — Nacos 同时提供服务发现和配置管理 -- [[05-部署运维/Kubernetes/README]] — ConfigMap/Secret 是 K8s 的配置注入方式 +- [[02-服务治理/04-服务发现]] — Nacos 同时提供服务发现和配置管理 +- [[05-部署运维/02-Kubernetes]] — ConfigMap/Secret 是 K8s 的配置注入方式 diff --git a/hzh/MS/02-服务治理/流量治理/README.md b/hzh/MS/02-服务治理/08-流量治理.md similarity index 93% rename from hzh/MS/02-服务治理/流量治理/README.md rename to hzh/MS/02-服务治理/08-流量治理.md index 2ccc6e9..425f209 100644 --- a/hzh/MS/02-服务治理/流量治理/README.md +++ b/hzh/MS/02-服务治理/08-流量治理.md @@ -138,9 +138,9 @@ http: | 能力 | 说明 | |------|------| -| **熔断降级** | 下游不可用时自动降级，参见 [[02-服务治理/容错模式/README]] | -| **限流** | 保护上游不因过量请求被打垮，参见 [[02-服务治理/容错模式/README]] | -| **重试** | 对瞬态故障自动恢复，参见 [[02-服务治理/容错模式/README]] | +| **熔断降级** | 下游不可用时自动降级，参见 [[02-服务治理/06-容错模式]] | +| **限流** | 保护上游不因过量请求被打垮，参见 [[02-服务治理/06-容错模式]] | +| **重试** | 对瞬态故障自动恢复，参见 [[02-服务治理/06-容错模式]] | | **黑白名单** | IP 级别访问控制 | | **A/B Testing** | 基于用户分组的长期实验 | @@ -159,6 +159,6 @@ http: ## 关联笔记 -- [[02-服务治理/API网关/README]] — API Gateway 的路由和权重分发 -- [[04-可观测性/Metrics监控/README]] — 灰度期间的监控面板设计 -- [[05-部署运维/SRE实践/README]] — 基于 SLO 的发布决策 +- [[02-服务治理/01-API网关]] — API Gateway 的路由和权重分发 +- [[04-可观测性/01-Metrics监控]] — 灰度期间的监控面板设计 +- [[05-部署运维/04-SRE实践]] — 基于 SLO 的发布决策 diff --git a/hzh/MS/02-服务治理/网关鉴权策略.md b/hzh/MS/02-服务治理/09-网关鉴权策略.md similarity index 100% rename from hzh/MS/02-服务治理/网关鉴权策略.md rename to hzh/MS/02-服务治理/09-网关鉴权策略.md diff --git a/hzh/MS/02-服务治理/README.md b/hzh/MS/02-服务治理/README.md index ffe8e33..33c2a64 100644 --- a/hzh/MS/02-服务治理/README.md +++ b/hzh/MS/02-服务治理/README.md @@ -29,14 +29,14 @@ graph LR | # | 主题 | 核心问题 | |---|------|----------| -| 1 | [[02-服务治理/服务发现/README]] | 服务如何找到彼此？注册中心的工作原理是什么？ | -| 2 | [[02-服务治理/API网关/README]] | 统一入口承担哪些职责？网关应该瘦还是胖？ | -| 3 | [[02-服务治理/服务间通信/README]] | RPC vs RESTful？同步 vs 异步怎么选？ | -| 4 | [[02-服务治理/容错模式/README]] | 网络不可靠，故障怎么隔离和恢复？ | -| 5 | [[02-服务治理/配置管理/README]] | 上百个服务的配置如何统一管理？ | -| 6 | [[02-服务治理/分布式追踪/README]] | 请求穿越多个服务后，如何追踪链路？ | -| 7 | [[02-服务治理/流量治理/README]] | 灰度发布如何做？高级路由策略有哪些？ | -| 8 | [[02-服务治理/安全机制/README]] | 服务间调用如何认证和授权？mTLS 是什么？ | +| 1 | [[02-服务治理/04-服务发现]] | 服务如何找到彼此？注册中心的工作原理是什么？ | +| 2 | [[02-服务治理/01-API网关]] | 统一入口承担哪些职责？网关应该瘦还是胖？ | +| 3 | [[02-服务治理/05-服务间通信]] | RPC vs RESTful？同步 vs 异步怎么选？ | +| 4 | [[02-服务治理/06-容错模式]] | 网络不可靠，故障怎么隔离和恢复？ | +| 5 | [[02-服务治理/07-配置管理]] | 上百个服务的配置如何统一管理？ | +| 6 | [[02-服务治理/03-分布式追踪]] | 请求穿越多个服务后，如何追踪链路？ | +| 7 | [[02-服务治理/08-流量治理]] | 灰度发布如何做？高级路由策略有哪些？ | +| 8 | [[02-服务治理/02-安全机制]] | 服务间调用如何认证和授权？mTLS 是什么？ | ### 学习建议 diff --git a/hzh/MS/03-数据一致性/数据库拆分/README.md b/hzh/MS/03-数据一致性/01-数据库拆分.md similarity index 98% rename from hzh/MS/03-数据一致性/数据库拆分/README.md rename to hzh/MS/03-数据一致性/01-数据库拆分.md index a1609e7..089e18a 100644 --- a/hzh/MS/03-数据一致性/数据库拆分/README.md +++ b/hzh/MS/03-数据一致性/01-数据库拆分.md @@ -194,5 +194,5 @@ db/migration/ ## 关联笔记 -- [[03-数据一致性/分布式事务/README]] — 拆分后的数据一致性问题 +- [[03-数据一致性/02-分布式事务]] — 拆分后的数据一致性问题 - [[01-基础概念]] — DDD 限界上下文与数据库拆分的对应关系 diff --git a/hzh/MS/03-数据一致性/分布式事务/README.md b/hzh/MS/03-数据一致性/02-分布式事务.md similarity index 96% rename from hzh/MS/03-数据一致性/分布式事务/README.md rename to hzh/MS/03-数据一致性/02-分布式事务.md index 030c5cb..02297b8 100644 --- a/hzh/MS/03-数据一致性/分布式事务/README.md +++ b/hzh/MS/03-数据一致性/02-分布式事务.md @@ -244,6 +244,6 @@ sequenceDiagram ## 关联笔记 -- [[03-数据一致性/数据库拆分/README]] — 数据库拆分是分布式事务的前提 -- [[02-服务治理/容错模式/README]] — 熔断器和重试在分布式事务中的作用 -- [[02-服务治理/服务间通信/README]] — 消息投递的一致性保障 +- [[03-数据一致性/01-数据库拆分]] — 数据库拆分是分布式事务的前提 +- [[02-服务治理/06-容错模式]] — 熔断器和重试在分布式事务中的作用 +- [[02-服务治理/05-服务间通信]] — 消息投递的一致性保障 diff --git a/hzh/MS/03-数据一致性/ID生成/README.md b/hzh/MS/03-数据一致性/03-ID生成.md similarity index 96% rename from hzh/MS/03-数据一致性/ID生成/README.md rename to hzh/MS/03-数据一致性/03-ID生成.md index 076fa0c..0f476e5 100644 --- a/hzh/MS/03-数据一致性/ID生成/README.md +++ b/hzh/MS/03-数据一致性/03-ID生成.md @@ -153,5 +153,5 @@ sequenceDiagram ## 关联笔记 -- [[03-数据一致性/数据库拆分/README]] — 分库分表场景下的 ID 生成 -- [[03-数据一致性/分布式事务/README]] — Outbox 消息 ID 也需要全局唯一 +- [[03-数据一致性/01-数据库拆分]] — 分库分表场景下的 ID 生成 +- [[03-数据一致性/02-分布式事务]] — Outbox 消息 ID 也需要全局唯一 diff --git a/hzh/MS/03-数据一致性/README.md b/hzh/MS/03-数据一致性/README.md index e191e2c..d92ff77 100644 --- a/hzh/MS/03-数据一致性/README.md +++ b/hzh/MS/03-数据一致性/README.md @@ -23,9 +23,9 @@ graph LR | # | 主题 | 核心问题 | |---|------|----------| -| 1 | [[03-数据一致性/数据库拆分/README]] | 每个服务独立 DB，表大了怎么拆分？跨库查询怎么做？ | -| 2 | [[03-数据一致性/分布式事务/README]] | 本地事务 + MQ、Saga、TCC，哪个方案最合适？ | -| 3 | [[03-数据一致性/ID生成/README]] | 没有自增主键了，全局唯一 ID 怎么生成？ | +| 1 | [[03-数据一致性/01-数据库拆分]] | 每个服务独立 DB，表大了怎么拆分？跨库查询怎么做？ | +| 2 | [[03-数据一致性/02-分布式事务]] | 本地事务 + MQ、Saga、TCC，哪个方案最合适？ | +| 3 | [[03-数据一致性/03-ID生成]] | 没有自增主键了，全局唯一 ID 怎么生成？ | ### 学习建议 diff --git a/hzh/MS/04-可观测性/Metrics监控/README.md b/hzh/MS/04-可观测性/01-Metrics监控.md similarity index 95% rename from hzh/MS/04-可观测性/Metrics监控/README.md rename to hzh/MS/04-可观测性/01-Metrics监控.md index 54871b8..3a05ef2 100644 --- a/hzh/MS/04-可观测性/Metrics监控/README.md +++ b/hzh/MS/04-可观测性/01-Metrics监控.md @@ -155,6 +155,6 @@ flowchart TB ## 关联笔记 -- [[04-可观测性/告警管理/README]] — Metrics 是告警的基础数据来源 -- [[04-可观测性/链路追踪/README]] — Tracing 与 Metrics 互补，定位具体故障 -- [[05-部署运维/SRE实践/README]] — SLO 基于 Metrics 数据 +- [[04-可观测性/04-告警管理]] — Metrics 是告警的基础数据来源 +- [[04-可观测性/03-链路追踪]] — Tracing 与 Metrics 互补，定位具体故障 +- [[05-部署运维/04-SRE实践]] — SLO 基于 Metrics 数据 diff --git a/hzh/MS/04-可观测性/日志系统/README.md b/hzh/MS/04-可观测性/02-日志系统.md similarity index 94% rename from hzh/MS/04-可观测性/日志系统/README.md rename to hzh/MS/04-可观测性/02-日志系统.md index 8eb443c..d272d27 100644 --- a/hzh/MS/04-可观测性/日志系统/README.md +++ b/hzh/MS/04-可观测性/02-日志系统.md @@ -144,6 +144,6 @@ DB 慢查询 → 100% 全量采集 → 重点关注 ## 关联笔记 -- [[04-可观测性/Metrics监控/README]] — Metrics + Logging = 完整的问题定位能力 -- [[04-可观测性/链路追踪/README]] — trace_id 是日志与追踪的桥梁 -- [[04-可观测性/告警管理/README]] — 日志可以触发基于模式的告警 +- [[04-可观测性/01-Metrics监控]] — Metrics + Logging = 完整的问题定位能力 +- [[04-可观测性/03-链路追踪]] — trace_id 是日志与追踪的桥梁 +- [[04-可观测性/04-告警管理]] — 日志可以触发基于模式的告警 diff --git a/hzh/MS/04-可观测性/链路追踪/README.md b/hzh/MS/04-可观测性/03-链路追踪.md similarity index 95% rename from hzh/MS/04-可观测性/链路追踪/README.md rename to hzh/MS/04-可观测性/03-链路追踪.md index 5492fec..9aed60b 100644 --- a/hzh/MS/04-可观测性/链路追踪/README.md +++ b/hzh/MS/04-可观测性/03-链路追踪.md @@ -161,6 +161,6 @@ flowchart TD ## 关联笔记 -- [[04-可观测性/Metrics监控/README]] — Tracing 与 Metrics 互补 -- [[04-可观测性/日志系统/README]] — trace_id 串联日志和追踪 -- [[04-可观测性/告警管理/README]] — 基于 Trace 数据的异常检测告警 +- [[04-可观测性/01-Metrics监控]] — Tracing 与 Metrics 互补 +- [[04-可观测性/02-日志系统]] — trace_id 串联日志和追踪 +- [[04-可观测性/04-告警管理]] — 基于 Trace 数据的异常检测告警 diff --git a/hzh/MS/04-可观测性/告警管理/README.md b/hzh/MS/04-可观测性/04-告警管理.md similarity index 96% rename from hzh/MS/04-可观测性/告警管理/README.md rename to hzh/MS/04-可观测性/04-告警管理.md index 56babf8..356c7f4 100644 --- a/hzh/MS/04-可观测性/告警管理/README.md +++ b/hzh/MS/04-可观测性/04-告警管理.md @@ -181,6 +181,6 @@ flowchart LR ## 关联笔记 -- [[04-可观测性/Metrics监控/README]] — Metrics 是告警的数据来源 -- [[05-部署运维/SRE实践/README]] — SLO/Error Budget 的详细方法论 -- [[02-服务治理/容错模式/README]] — 熔断器状态可以作为告警信号 +- [[04-可观测性/01-Metrics监控]] — Metrics 是告警的数据来源 +- [[05-部署运维/04-SRE实践]] — SLO/Error Budget 的详细方法论 +- [[02-服务治理/06-容错模式]] — 熔断器状态可以作为告警信号 diff --git a/hzh/MS/04-可观测性/README.md b/hzh/MS/04-可观测性/README.md index 8c12aef..92d9448 100644 --- a/hzh/MS/04-可观测性/README.md +++ b/hzh/MS/04-可观测性/README.md @@ -25,10 +25,10 @@ graph LR | # | 主题 | 核心问题 | |---|------|----------| -| 1 | [[04-可观测性/Metrics监控/README]] | 怎么量化系统的健康度？RED/USE 方法怎么用？ | -| 2 | [[04-可观测性/日志系统/README]] | 日志怎么集中收集？结构化日志的最佳实践是什么？ | -| 3 | [[04-可观测性/链路追踪/README]] | trace_id 如何贯穿跨服务调用链？OpenTelemetry 怎么用？ | -| 4 | [[04-可观测性/告警管理/README]] | 如何设计告警避免疲劳？SLO/Error Budget 怎么做？ | +| 1 | [[04-可观测性/01-Metrics监控]] | 怎么量化系统的健康度？RED/USE 方法怎么用？ | +| 2 | [[04-可观测性/02-日志系统]] | 日志怎么集中收集？结构化日志的最佳实践是什么？ | +| 3 | [[04-可观测性/03-链路追踪]] | trace_id 如何贯穿跨服务调用链？OpenTelemetry 怎么用？ | +| 4 | [[04-可观测性/04-告警管理]] | 如何设计告警避免疲劳？SLO/Error Budget 怎么做？ | ### 为什么需要独立的"可观测性"体系？ @@ -74,5 +74,5 @@ flowchart LR ### 关联笔记 - [[02-服务治理]] — 熔断器可以触发告警，与监控系统联动 -- [[05-部署运维/Kubernetes/README]] — K8s Liveness/Readiness Probe 是可观测性的基础 +- [[05-部署运维/02-Kubernetes]] — K8s Liveness/Readiness Probe 是可观测性的基础 - [[hzh/MS/README.md]] — 完整微服务知识索引 diff --git a/hzh/MS/05-部署运维/容器化/README.md b/hzh/MS/05-部署运维/01-容器化.md similarity index 95% rename from hzh/MS/05-部署运维/容器化/README.md rename to hzh/MS/05-部署运维/01-容器化.md index f735b7c..e8014d0 100644 --- a/hzh/MS/05-部署运维/容器化/README.md +++ b/hzh/MS/05-部署运维/01-容器化.md @@ -151,5 +151,5 @@ flowchart LR ## 关联笔记 -- [[05-部署运维/Kubernetes/README]] — K8s 以 Pod 为部署单元，镜像来自 Docker -- [[05-部署运维/CI-CD与GitOps/README]] — CI/CD 流水线中的镜像构建环节 +- [[05-部署运维/02-Kubernetes]] — K8s 以 Pod 为部署单元，镜像来自 Docker +- [[05-部署运维/03-CICD与GitOps]] — CI/CD 流水线中的镜像构建环节 diff --git a/hzh/MS/05-部署运维/Kubernetes/README.md b/hzh/MS/05-部署运维/02-Kubernetes.md similarity index 96% rename from hzh/MS/05-部署运维/Kubernetes/README.md rename to hzh/MS/05-部署运维/02-Kubernetes.md index e45b5a0..4e1d4cb 100644 --- a/hzh/MS/05-部署运维/Kubernetes/README.md +++ b/hzh/MS/05-部署运维/02-Kubernetes.md @@ -261,6 +261,6 @@ spec: ## 关联笔记 -- [[02-服务治理/服务发现/README]] — K8s Service 是服务端发现模式的代表 -- [[02-服务治理/流量治理/README]] — Istio VirtualService 在 K8s 上的高级路由 -- [[05-部署运维/SRE实践/README]] — SLO/Error Budget 在 K8s 中的落地 +- [[02-服务治理/04-服务发现]] — K8s Service 是服务端发现模式的代表 +- [[02-服务治理/08-流量治理]] — Istio VirtualService 在 K8s 上的高级路由 +- [[05-部署运维/04-SRE实践]] — SLO/Error Budget 在 K8s 中的落地 diff --git a/hzh/MS/05-部署运维/CI-CD与GitOps/README.md b/hzh/MS/05-部署运维/03-CICD与GitOps.md similarity index 95% rename from hzh/MS/05-部署运维/CI-CD与GitOps/README.md rename to hzh/MS/05-部署运维/03-CICD与GitOps.md index 9f10bd1..7bedec1 100644 --- a/hzh/MS/05-部署运维/CI-CD与GitOps/README.md +++ b/hzh/MS/05-部署运维/03-CICD与GitOps.md @@ -171,6 +171,6 @@ helm upgrade --install order-service ./charts/order-service \ ## 关联笔记 -- [[05-部署运维/容器化/README]] — Docker 镜像构建是 CI/CD 的第一步 -- [[05-部署运维/Kubernetes/README]] — K8s 是部署的目标平台 -- [[05-部署运维/SRE实践/README]] — 错误预算影响发布策略 +- [[05-部署运维/01-容器化]] — Docker 镜像构建是 CI/CD 的第一步 +- [[05-部署运维/02-Kubernetes]] — K8s 是部署的目标平台 +- [[05-部署运维/04-SRE实践]] — 错误预算影响发布策略 diff --git a/hzh/MS/05-部署运维/SRE实践/README.md b/hzh/MS/05-部署运维/04-SRE实践.md similarity index 95% rename from hzh/MS/05-部署运维/SRE实践/README.md rename to hzh/MS/05-部署运维/04-SRE实践.md index 920736f..1f78689 100644 --- a/hzh/MS/05-部署运维/SRE实践/README.md +++ b/hzh/MS/05-部署运维/04-SRE实践.md @@ -155,6 +155,6 @@ groups: ## 关联笔记 -- [[04-可观测性/告警管理/README]] — SLO/Error Budget 与告警体系的联动 -- [[05-部署运维/Kubernetes/README]] — K8s HPA 弹性伸缩支撑 SLO 保障 -- [[05-部署运维/CI-CD与GitOps/README]] — GitOps 支持安全的持续交付 +- [[04-可观测性/04-告警管理]] — SLO/Error Budget 与告警体系的联动 +- [[05-部署运维/02-Kubernetes]] — K8s HPA 弹性伸缩支撑 SLO 保障 +- [[05-部署运维/03-CICD与GitOps]] — GitOps 支持安全的持续交付 diff --git a/hzh/MS/05-部署运维/README.md b/hzh/MS/05-部署运维/README.md index 873aef6..4490150 100644 --- a/hzh/MS/05-部署运维/README.md +++ b/hzh/MS/05-部署运维/README.md @@ -25,10 +25,10 @@ graph LR | # | 主题 | 核心问题 | |---|------|----------| -| 1 | [[05-部署运维/容器化/README]] | Docker 镜像怎么优化？最佳实践有哪些？ | -| 2 | [[05-部署运维/Kubernetes/README]] | K8s 核心概念和资源管理怎么做？ | -| 3 | [[05-部署运维/CI-CD与GitOps/README]] | 自动化流水线怎么设计？GitOps 流程怎么走？ | -| 4 | [[05-部署运维/SRE实践/README]] | SLI/SLO/Error Budget 如何落地？ | +| 1 | [[05-部署运维/01-容器化]] | Docker 镜像怎么优化？最佳实践有哪些？ | +| 2 | [[05-部署运维/02-Kubernetes]] | K8s 核心概念和资源管理怎么做？ | +| 3 | [[05-部署运维/03-CICD与GitOps]] | 自动化流水线怎么设计？GitOps 流程怎么走？ | +| 4 | [[05-部署运维/04-SRE实践]] | SLI/SLO/Error Budget 如何落地？ | ### 学习建议 diff --git a/hzh/MS/06-gRPC/01-协议与架构.md b/hzh/MS/06-gRPC/01-协议与架构.md index 32ec369..a4be0fa 100644 --- a/hzh/MS/06-gRPC/01-协议与架构.md +++ b/hzh/MS/06-gRPC/01-协议与架构.md @@ -150,12 +150,12 @@ graph LR > > 既然 gRPC 这么多优势，是不是所有场景都应该用 gRPC？什么情况下 HTTP/JSON 仍然更合适？ -答案见 [[02-服务治理/服务间通信]]。对外暴露 API 时，HTTP/JSON 仍然不可替代——因为浏览器的 Native Fetch 无法直接调用 gRPC，第三方接入者也不想安装 Proto 编译器。 +答案见 [[02-服务治理/05-服务间通信]]。对外暴露 API 时，HTTP/JSON 仍然不可替代——因为浏览器的 Native Fetch 无法直接调用 gRPC，第三方接入者也不想安装 Proto 编译器。 ## 关联笔记 -- [[02-服务治理/服务间通信]] — gRPC 与 REST 的基础对比及选型建议 -- [[02-服务治理/容错模式/README]] — 基于此架构的重试、熔断等治理机制 +- [[02-服务治理/05-服务间通信]] — gRPC 与 REST 的基础对比及选型建议 +- [[02-服务治理/06-容错模式]] — 基于此架构的重试、熔断等治理机制 - [[02-Proto设计]] — Proto 文件设计的进阶实践 - [[03-RPC模式]] — 四种 RPC 模式的深度用法 - [[04-拦截器]] — 切面编程和上下文传播 diff --git a/hzh/MS/06-gRPC/02-Proto设计.md b/hzh/MS/06-gRPC/02-Proto设计.md index d344104..924127d 100644 --- a/hzh/MS/06-gRPC/02-Proto设计.md +++ b/hzh/MS/06-gRPC/02-Proto设计.md @@ -279,4 +279,4 @@ proto/ - [[01-协议与架构]] — Proto 文件最终服务于协议栈中的 Generated Stub 层 - [[07-最佳实践]] — Buf 代码生成流程和生产配置 -- [[02-服务治理/服务间通信]] — 不同序列化方案的性能对比 +- [[02-服务治理/05-服务间通信]] — 不同序列化方案的性能对比 diff --git a/hzh/MS/06-gRPC/04-拦截器.md b/hzh/MS/06-gRPC/04-拦截器.md index 5f4c12d..0bb67b2 100644 --- a/hzh/MS/06-gRPC/04-拦截器.md +++ b/hzh/MS/06-gRPC/04-拦截器.md @@ -156,7 +156,7 @@ conn, _ := grpc.Dial(target, > [!keypoint] 为什么需要上下文传播 > -> 当一个请求穿越 5 个微服务时，如果没有上下文传播，你在日志系统中看到的是 5 条孤立的记录。有了 W3C Trace Context，每层服务自动将 `traceparent` 透传给下一跳——最终汇聚成一条完整的调用链路，这就是 [[02-服务治理/分布式追踪]] 的核心能力。 +> 当一个请求穿越 5 个微服务时，如果没有上下文传播，你在日志系统中看到的是 5 条孤立的记录。有了 W3C Trace Context，每层服务自动将 `traceparent` 透传给下一跳——最终汇聚成一条完整的调用链路，这就是 [[02-服务治理/03-分布式追踪]] 的核心能力。 ## 拦截器最佳实践 @@ -172,5 +172,5 @@ conn, _ := grpc.Dial(target, - [[01-协议与架构]] — 拦截器位于 gRPC Framework 层，在 HTTP/2 之前处理请求 - [[05-错误处理]] — 拦截器经常需要根据错误码决定重试或降级策略 -- [[02-服务治理/分布式追踪]] — Context 传播是实现分布式追踪的前提 -- [[02-服务治理/安全机制]] — 鉴权拦截器是安全机制在代码层的落地形式 +- [[02-服务治理/03-分布式追踪]] — Context 传播是实现分布式追踪的前提 +- [[02-服务治理/02-安全机制]] — 鉴权拦截器是安全机制在代码层的落地形式 diff --git a/hzh/MS/06-gRPC/05-错误处理.md b/hzh/MS/06-gRPC/05-错误处理.md index f355fe0..394dd21 100644 --- a/hzh/MS/06-gRPC/05-错误处理.md +++ b/hzh/MS/06-gRPC/05-错误处理.md @@ -174,5 +174,5 @@ default: - [[04-拦截器]] — 拦截器根据错误码决定是否触发自动重试 - [[07-最佳实践]] — 重试策略中与错误状态的配合配置 -- [[02-服务治理/容错模式]] — 熔断器在收到特定错误码后触发熔断 -- [[02-服务治理/分布式追踪]] — 错误链路在追踪系统中的标注方式 +- [[02-服务治理/06-容错模式]] — 熔断器在收到特定错误码后触发熔断 +- [[02-服务治理/03-分布式追踪]] — 错误链路在追踪系统中的标注方式 diff --git a/hzh/MS/06-gRPC/06-连接管理.md b/hzh/MS/06-gRPC/06-连接管理.md index ca94a1f..9054e8a 100644 --- a/hzh/MS/06-gRPC/06-连接管理.md +++ b/hzh/MS/06-gRPC/06-连接管理.md @@ -151,5 +151,5 @@ Kubernetes 的 DNS 控制器会自动将 Service 的 Endpoints 更新到 DNS 记 - [[01-协议与架构]] — Name Resolver 是架构图中连接管理层的第一环 - [[07-最佳实践]] — Keepalive、负载均衡在生产环境的配合配置 -- [[02-服务治理/服务发现/README]] — 更深度的服务发现机制对比（Nacos / Consul / K8s） -- [[02-服务治理/容错模式/README]] — 负载均衡 + 熔断的组合效果 +- [[02-服务治理/04-服务发现]] — 更深度的服务发现机制对比（Nacos / Consul / K8s） +- [[02-服务治理/06-容错模式]] — 负载均衡 + 熔断的组合效果 diff --git a/hzh/MS/06-gRPC/07-最佳实践.md b/hzh/MS/06-gRPC/07-最佳实践.md index f4726f1..9d29968 100644 --- a/hzh/MS/06-gRPC/07-最佳实践.md +++ b/hzh/MS/06-gRPC/07-最佳实践.md @@ -216,5 +216,5 @@ resp, err := client.GetBigData( - [[04-拦截器]] — 重试策略可以通过 interceptor 实现更复杂的逻辑 - [[05-错误处理]] — 重试策略根据错误状态码来决定是否重试 - [[06-连接管理]] — Keepalive、负载均衡、Name Resolver 的详细配置 -- [[02-服务治理/安全机制]] — mTLS 与服务间身份认证的更深内容 -- [[02-服务治理/容错模式]] — 熔断器、限流器与重试策略的组合配置 +- [[02-服务治理/02-安全机制]] — mTLS 与服务间身份认证的更深内容 +- [[02-服务治理/06-容错模式]] — 熔断器、限流器与重试策略的组合配置 diff --git a/hzh/MS/06-gRPC/README.md b/hzh/MS/06-gRPC/README.md index 4df98a6..1a8bb6f 100644 --- a/hzh/MS/06-gRPC/README.md +++ b/hzh/MS/06-gRPC/README.md @@ -7,7 +7,7 @@ create time: 2026-05-07 16:30 ## 概述 -本目录系统整理 **gRPC** 的核心知识点，从底层协议到生产实践，由浅入深覆盖 gRPC 的每一个关键领域。与 [[02-服务治理/服务间通信]] 中的入门对比不同，这里聚焦于「用了 gRPC 之后」—— 如何设计 Proto、如何编写拦截器、如何处理流式调用、连接怎么管、出错怎么查。 +本目录系统整理 **gRPC** 的核心知识点，从底层协议到生产实践，由浅入深覆盖 gRPC 的每一个关键领域。与 [[02-服务治理/05-服务间通信]] 中的入门对比不同，这里聚焦于「用了 gRPC 之后」—— 如何设计 Proto、如何编写拦截器、如何处理流式调用、连接怎么管、出错怎么查。 ```mermaid graph LR @@ -126,8 +126,8 @@ graph LR ## 关联笔记 -- [[02-服务治理/服务间通信]] — gRPC 与 REST 的基础对比及混合通信模式 -- [[02-服务治理/服务发现/README]] — Nacos / Consul / K8s Service 深度对比 -- [[02-服务治理/容错模式/README]] — 重试、熔断、限流、降级的完整治理 -- [[02-服务治理/分布式追踪/README]] — OpenTelemetry 链路追踪 -- [[02-服务治理/安全机制/README]] — mTLS、JWT、RBAC +- [[02-服务治理/05-服务间通信]] — gRPC 与 REST 的基础对比及混合通信模式 +- [[02-服务治理/04-服务发现]] — Nacos / Consul / K8s Service 深度对比 +- [[02-服务治理/06-容错模式]] — 重试、熔断、限流、降级的完整治理 +- [[02-服务治理/03-分布式追踪]] — OpenTelemetry 链路追踪 +- [[02-服务治理/02-安全机制]] — mTLS、JWT、RBAC diff --git a/hzh/MS/README.md b/hzh/MS/README.md index c4c3155..0c4853a 100644 --- a/hzh/MS/README.md +++ b/hzh/MS/README.md @@ -39,40 +39,40 @@ graph LR | 子主题 | 核心内容 | |--------|---------| -| [[02-服务治理/服务发现/README]] | Nacos / Consul / K8s Service，客户端 vs 服务端发现模式 | -| [[02-服务治理/API网关/README]] | 统一入口的职责边界、路由策略、插件体系 | -| [[02-服务治理/服务间通信/README]] | gRPC vs REST，同步 vs 异步组合拳 | -| [[02-服务治理/容错模式/README]] | 超时 / 重试 / 熔断 / 限流 / 舱壁隔离 / 降级 | -| [[02-服务治理/配置管理/README]] | Nacos Config / Apollo，动态刷新与版本管理 | -| [[02-服务治理/分布式追踪/README]] | OpenTelemetry，trace/span 概念，采样策略 | -| [[02-服务治理/流量治理/README]] | 灰度发布策略，蓝绿 vs 金丝雀，Istio VirtualService | -| [[02-服务治理/安全机制/README]] | mTLS, JWT, RBAC/ABAC, 输入防护 | +| [[02-服务治理/04-服务发现]] | Nacos / Consul / K8s Service，客户端 vs 服务端发现模式 | +| [[02-服务治理/01-API网关]] | 统一入口的职责边界、路由策略、插件体系 | +| [[02-服务治理/05-服务间通信]] | gRPC vs REST，同步 vs 异步组合拳 | +| [[02-服务治理/06-容错模式]] | 超时 / 重试 / 熔断 / 限流 / 舱壁隔离 / 降级 | +| [[02-服务治理/07-配置管理]] | Nacos Config / Apollo，动态刷新与版本管理 | +| [[02-服务治理/03-分布式追踪]] | OpenTelemetry，trace/span 概念，采样策略 | +| [[02-服务治理/08-流量治理]] | 灰度发布策略，蓝绿 vs 金丝雀，Istio VirtualService | +| [[02-服务治理/02-安全机制]] | mTLS, JWT, RBAC/ABAC, 输入防护 | ### 3. [[03-数据一致性]] — 跨服务数据一致性怎么保证？ | 子主题 | 核心内容 | |--------|---------| -| [[03-数据一致性/数据库拆分/README]] | 垂直拆分 / 水平分片，ShardingSphere，跨库查询方案 | -| [[03-数据一致性/分布式事务/README]] | Outbox 模式，Saga，TCC，AT 模式，幂等设计 | -| [[03-数据一致性/ID生成/README]] | Snowflake, UUID v7, 号段模式 | +| [[03-数据一致性/01-数据库拆分]] | 垂直拆分 / 水平分片，ShardingSphere，跨库查询方案 | +| [[03-数据一致性/02-分布式事务]] | Outbox 模式，Saga，TCC，AT 模式，幂等设计 | +| [[03-数据一致性/03-ID生成]] | Snowflake, UUID v7, 号段模式 | ### 4. [[04-可观测性]] — 请求穿越多个服务后如何排查问题？ | 子主题 | 核心内容 | |--------|---------| -| [[04-可观测性/Metrics监控/README]] | Prometheus, RED/USE 方法, Counter/Gauge/Histogram | -| [[04-可观测性/日志系统/README]] | JSON 结构化日志, ELK vs Loki, 采集管线, 采样策略 | -| [[04-可观测性/链路追踪/README]] | OpenTelemetry, W3C Trace Context, 上下文传播, 采样 | -| [[04-可观测性/告警管理/README]] | SLO/Error Budget 告警, 分级降噪, On-Call 最佳实践 | +| [[04-可观测性/01-Metrics监控]] | Prometheus, RED/USE 方法, Counter/Gauge/Histogram | +| [[04-可观测性/02-日志系统]] | JSON 结构化日志, ELK vs Loki, 采集管线, 采样策略 | +| [[04-可观测性/03-链路追踪]] | OpenTelemetry, W3C Trace Context, 上下文传播, 采样 | +| [[04-可观测性/04-告警管理]] | SLO/Error Budget 告警, 分级降噪, On-Call 最佳实践 | ### 5. [[05-部署运维]] — 上百个服务如何容器化编排与发布？ | 子主题 | 核心内容 | |--------|---------| -| [[05-部署运维/容器化/README]] | Dockerfile 最佳实践, 镜像安全, distroless | -| [[05-部署运维/Kubernetes/README]] | Pod/Deployment/Service/Ingress, Probe, HPA, 资源配置 | -| [[05-部署运维/CI-CD与GitOps/README]] | GitHub Actions Pipeline, GitOps (ArgoCD), Helm | -| [[05-部署运维/SRE实践/README]] | SLI/SLO/SLA, Error Budget, Blameless Postmortem, DORA Metrics | +| [[05-部署运维/01-容器化]] | Dockerfile 最佳实践, 镜像安全, distroless | +| [[05-部署运维/02-Kubernetes]] | Pod/Deployment/Service/Ingress, Probe, HPA, 资源配置 | +| [[05-部署运维/03-CICD与GitOps]] | GitHub Actions Pipeline, GitOps (ArgoCD), Helm | +| [[05-部署运维/04-SRE实践]] | SLI/SLO/SLA, Error Budget, Blameless Postmortem, DORA Metrics | ## 学习建议