公众号迁移 on roseduan

OPC 时代，如何最小成本构建一个产品

Sun, 10 May 2026 14:22:34 +0000

1. 什么是 OPC

OPC (One Person Company)，一人公司，听起来好像也不是什么新鲜词，毕竟单干的、自由职业的、独立开发者一直都有，每个时代都不缺这种人。

但今天我们说的 OPC，跟以前的"个体户"其实不太一样。

我自己的感受是，它其实是 AI 时代催生出来的新东西。

2. 为什么是现在

云这件事其实很多年前就成熟了。

服务器、负载均衡、TLS、CDN、对象存储、数据库，这些过去要专门请一个 SRE 团队维护的东西，现在点几下就能开通，还便宜。

但光有云其实不够，因为一个人除了写代码，还要做设计、写文案、回邮件、跑增长、看数据。

这些事一个人全揽下来，再有云加持，也是会累到崩溃的。

真正让 OPC 变得现实的，其实是 AI。

写代码有 Codex、Claude Code，一个人的工程产能能放大到接近一个小团队。
做设计有 v0、Lovable、Figma AI，懂审美比会画图更重要了。
写文案、邮件、SEO 描述这种事，AI 能给你 80% 的初稿。常见的客服问题，一个 chatbot 也能挡掉大部分。
数据分析以前要写一堆 SQL，现在自然语言问一下就行。

云解决了"东西在哪儿跑"，AI 解决了"东西谁来做"，两件事一起被外包出去之后，一个人撑起一家公司就不再是什么传奇故事了。

国外这两年也确实出现了不少这样的例子：Sahil Lavingia 用一支极小的远程团队，让 Gumroad 持续盈利了很多年，Pieter Levels 一个人独立开发并运营了好几款产品，加在一起年收入有几百万美金。

还有越来越多的独立开发者，一个 Twitter 账号 + 一个 Stripe 账号 + 一个 Vercel 项目，做出了过去要 A 轮融资才能撑起来的东西。

3. 以 codepie 为例

下面想以我自己最近在做的 codepie （codepie.roseduan.cn）为例，讲讲一个人是怎么把这件事跑起来的。

codepie 是一个我独自运营的在线课程平台，目前所有的事情都是我一个人在做：写代码、做设计、跑营销、回用户消息。

下面就从技术选型和成本两个方面来聊一下。

技术选型

我选技术其实没什么花哨的标准，就一条：能干活的前提下，挑维护成本最低、心智负担最小、上限又不会被锁死的那个。

前端

前端用的是 Next.js 16 + React 19 + TypeScript。一个框架把路由、SSR、SEO、API、中间件全包了。

课程详情页要 SEO，付费校验要后端逻辑，App Router 把这两件事统一在一棵树里，挺省心。

样式直接用 Tailwind CSS，没有上任何组件库。

一个人维护 UI，最怕的就是组件库版本一升级把样式打乱，原子化 class 让样式归属于页面本身，比较稳。

数据库

主数据库主要靠 Supabase，Postgres + Auth + Storage 一起搞定。

我不需要自己搭 OAuth、不需要管数据库备份、不需要写注册登录页。

用户、订单、解锁状态几张表就解决了。

限流和缓存用了 Upstash Redis，serverless 形态，按请求计费，闲的时候几乎不花钱。

登录用 NextAuth v5，跟 Supabase 配合处理 GitHub / Google 登录。

部署 / 运维

部署直接用 Vercel，git push 上去就部署完了，预览环境、TLS、CDN 都自带。

数据看 Vercel Analytics 和 Speed Insights 的免费版，前期足够用。

域名在 Cloudflare 注册的，一年 80 块左右。

开发工具

日常开发我用 Claude Code 和 Codex 比较多，重构、调试、SQL 调优都靠它们。

CI 用 GitHub Actions 跑测试，保证主分支随时可以发布。

整套技术栈背后的想法很简单：把所有非核心的事情都交给云，自己只写"只有我能写"的那部分。

成本

成本其实是这件事里最让我意外的一部分，下面是上线 codepie 产品的大致成本：

项目	月成本	说明
Vercel	$0	Hobby 免费版，前期流量够用
Supabase	$0	Free 计划，500MB 数据库 + 1GB 存储
Upstash Redis	$0	免费 10000 请求/天
域名	≈ ¥7 / 月	Cloudflare，一年 ¥80
Claude / Codex 订阅	$20	核心生产力工具
邮件服务 (Resend)	$0	免费 3000 封/月
其他（图床、监控）	$0	Vercel 自带或 Supabase Storage
合计	≈ $27 / 月

只有等 DAU 真的涨起来之后，Vercel 和 Supabase 才会跨过免费门槛。

到那时候，Vercel Pro 月、25/月，加起来也就 $80 不到，而那个时候产品大概率已经能自己养活自己了。

对比一下传统创业，买服务器、雇前后端 + 设计、买协作软件，一个月烧几万块是很正常的。

几万块跟两百块，差的其实不只是钱，而是试错的次数，几万块烧错了你要痛三个月，两百块烧错了下个礼拜你又能开一个新项目。

4. 几点经验

上线一个产品，有几个当初没多想、回头看挺重要的决定，也算是一点感悟吧。

不上"大而全"的东西。不上 Strapi，不上自部署的 Prisma + PG，不上 Kubernetes。每多一个组件，都是一份维护成本，一份心智负担。
内容比 UI 重要。UI 越无聊越好，把时间花在产品本身的内容和体验上，比花在做酷炫首页和复杂动效上回报高 10 倍。用户不会因为你的 hover 动画就掏钱。
早一点上线，晚一点优化。免费部分早早放出去收反馈，比闭门 3 个月做完美再发布要强。前者让你知道方向对不对，后者只是让你的代码看起来更"漂亮"一点。
AI 是放大器，不是替代品。AI 替不了你的判断和品味，但能把你的判断翻倍交付。把它用在重复劳动上，重构、对齐、写测试、调样式，然后把判断力留给真正要紧的事。
不要拒绝免费 tier。很多独立开发者觉得"免费的不专业"，但其实 Vercel / Supabase / Upstash 的免费额度足够撑到产品验证完成。在没有验证之前付钱，纯属浪费。

5. 写在最后

折腾下来最大的感受是，OPC 这件事的本质，其实是杠杆的换挡。

以前做产品要钱，要服务器、要团队、要授权；现在做产品要的是判断力，在一堆云服务、AI 工具、开源框架里挑出几个"够用又不绑架你"的组合，剩下的精力压在内容和用户体验上就行。

codepie 现在每月不到 $30 的成本就能稳定跑着，一个人能干完过去十几个人才能干的事。

这件事本身比产品还让我兴奋，它意味着，任何一个有手艺、有判断的人，今天都可以把自己的能力直接做成产品交到用户手里，不需要谁来许可你。

AI 时代真正的红利，可能不是"AI 替你做了什么"，而是"AI 让一个人能做什么"。

前者是工具，后者才是杠杆。

如果你也在想"要不要试试做点什么"，结论其实挺简单的，现在的门槛已经低到没有什么借口了，剩下的就是动不动手而已。

从零实现 AI Coding Agent

Fri, 08 May 2026 09:15:41 +0000

到 2026 年，对于绝大多数开发来说，应该都离不开 Cursor、Claude Code 或 Codex 这类 Vibe Coding 工具了。

我自己也是 Claude Code 的重度用户，几乎每天都在用，但每次用着它，心里总会有些疑问，或者说好奇心，这玩意儿到底是怎么做到的？

例如它是如何与 LLM 交互的，如何存储短期记忆的，如何调用不同的工具？

去年开始，我决定动手写一个简单的 Coding Agent 来帮助我理解其原理，断断续续花了几个月的时间，写出一个能在终端跑、能读代码改代码跑测试的 Coding Agent，核心代码 3000 行左右。

写完之后发现也不算是很难，只要循序渐进的拆解，按照不同的模块逐个击破，就基本能够自己写一个出来了。

目前网上的教程大多偏理论，所以我把过去这几个月的实现过程，整理成了一个 20 章的实战教程：《从零实现 AI Coding Agent》。

教程地址：codepie.roseduan.cn

Coding Agent 的核心

AI Coding Agent 的内核就是：LLM（大脑）+ Tools（手脚）+ Loop（循环）。

LLM 负责思考，读懂你说的话、决定下一步干什么、解析报错。

Tools 是它的手脚，读文件、写文件、执行 Bash、搜索代码。

Loop 是节奏，LLM 想一步、调用一个工具、看工具输出、再想下一步，直到任务搞定。

像 Cursor、Claude Code、Codex、Windsurf、Devin 等等这些工具，剥开外壳，骨架基本都是这样的。

真正难的是细节

当然，原理听起来很简单，但是在实现的时候，还是有很多魔鬼细节的，我随便列几个：

流式响应怎么处理？LLM 一边吐 token，中间可能夹一个 tool_use 块，怎么解析？
工具协议怎么实现？JSON Schema 长什么样、tool_result 怎么返回、出错的时候怎么告诉模型？
模型一次返回 5 个工具调用，并行执行还是串行？怎么聚合？
用着用着上下文长到 200k token 了，怎么压缩？哪些消息保留，哪些用摘要替换？
LLM 在那一通操作之后，Token 算超了怎么办？怎么提前预警？
用户输入里夹了恶意指令怎么办？Prompt Injection 怎么挡？
Bash 命令卡住了，子进程超时怎么办？

这些都不是高大上的算法问题，而是一些工程细节，但你不亲手写一遍，你只是知道"有这么回事"，自己亲手写过一遍之后，你脑子里才会有一张 Coding Agent 的解剖图。

课程目录：4 大模块 / 20 章

**模块一｜基础：与 LLM 对话（Ch 1-4）**项目搭建、API 调用、流式响应、多轮对话、Tool Use 协议。打通和 LLM 打交道的所有基础设施。

**模块二｜工具：文件与命令（Ch 5-8）**Read、Write、Bash、Search 四件套，Agent 之所以能"干活"，全靠这些基础工具。

**模块三｜引擎：Agent Loop（Ch 9-12）**课程的核心。核心循环、并发工具调用、规划与任务分解、错误处理。把这块写明白，你就真正理解 Agent 是什么。

**模块四｜上下文与体验（Ch 13-20）**System Prompt 设计、Token 管理、上下文压缩、CLI 体验、Prompt Injection 防护、项目感知。从"能跑"到"能用"的最后一段。

完整课程目录如下：

课程特点

不依赖任何 Agent 框架。 每一行代码你自己写（延续之前课程的一贯风格），框架接口会变，但底层原理不会，你学的是后者。

TypeScript + Python 双语言。 每一章都有两种语言实现，跟自己熟悉的语言就行。

每章一个可运行 git commit。 clone 下来 checkout 到任何一章，立刻能跑测试验证。

讲的是真实产品的核心技术。 课程里讲的 Agent Loop、Tool Use 协议、上下文压缩、System Prompt 等，就是 Cursor、Claude Code 等工具的核心基础。不是玩具，是你能直接拿去面试讲、拿去工作里改的真东西。

学完你能获得什么

一个能跑起来的 Coding Agent。装到自己电脑上，给它一个项目，让它读代码、改代码、跑测试，功能上是 Claude Code 的 mini 精简版。
20 个干净的 git commits。结构清晰、每个 commit 对应一个章节的 git 历史，学完之后这就是你简历里的项目。
对 Codex / Claude Code 内部的深度理解。下次同事问"这个 Agent 是怎么工作的"，你能上白板从原理讲清楚，而不是只会说"我看过 Claude Code 文档"。
AI Infra / Agent 工程方向的简历素材。一个手写的、20 章完整清晰 commits 可查的真实项目，比任何"我用过 XX 框架"都管用。

课程适合谁

每天在用 Cursor / Claude Code / Codex，但说不清它到底怎么工作，想搞懂它内部的工程而不是只会用
试过 LangChain 写 Agent，demo 跑通了，但完全不理解底层的 Tool Use、Loop、上下文管理，框架接口一变就懵
写过几年 Web 后端，想往 AI 方向转，但找不到一个能放进简历、被面试官深挖的真实项目
在校学生，想找一个有深度的毕设 / 课题方向，让导师眼前一亮
准备 AI / Agent 方向求职面试，不想只会复述论文和八股，想能上白板从 Tool Use 协议讲到 Token 管理
已经掌握 TypeScript 或 Python 基础，缺一个能拿出手、能解剖、能讨论的工程实践项目
对 Cursor / Claude Code 内部充满好奇，喜欢"动手做出来"远胜过"读完一篇综述"

免费试看

前 3 章免费，不用登录，可以直接阅读，课程主页如下（或点击文章底部阅读原文）：

codepie.roseduan.cn

读完前 3 章可以了解课程的风格、深度、节奏合不合你的胃口，觉得值再往下走。

这个课程不会让你"看完就会"，马上成为 AI 大师，但我能保证：

这 20 章一行行写过来，Claude Code 不再是黑盒，Cursor 不再是魔法。下一次你再用它，你眼里看到的是工程、是循环、是 Tool Use 协议，是对一个 AI Agent 设计的基本掌握。

动物本能

Sun, 26 Apr 2026 03:14:46 +0000

临近三十岁时，越活越迷茫，焦虑得凌晨两三点睡不着觉，那就码字打发时间吧，顺便整理下思绪。

仔细想想，以前的我迷茫吗，好像没有，每天在按部就班的做着自己的事情，当然这些事情谈不上是热爱还是纯粹习惯了，亦或是被逼的，甚至是被身边的人影响到了，还是无聊的时候，无所事事，给自己找点活干，或许都有可能。

但回过头来看看，那时候真的不迷茫吗，我现在才发觉，那时候的头脑，仅仅是因为充斥了其他的事情，而无暇顾及我现在思索的一些东西，才会有一种不迷茫的假象。

现在愈发觉得，我不知道自己想要成为什么样子，想要过什么样的生活，甚至不认识自己究竟是谁，想要去到哪里。

亡命天涯的峰哥好像说，一切心理问题都是性压抑，果真是这样吗？或许性确实能够带来一时的欢愉，像毒品一样，麻醉人的神经，产生一种短暂的快感，忘记烦恼。

但是如果你恢复了理智之后，会发现焦虑和困惑从来就不会凭空消失，它们又会让人陷入下一个精神危机的循环之中。

我当然也想过，及时行乐，只专注于当下的快乐，但是脑子里的思想又不停地在转动。

我是谁，我从哪里来，我要到哪里去。

针对这个问题，我暂时想到了一个能够说服我自己的答案。

那就是，这个问题本身可能并没有答案。

我们无法在三十岁，五十岁，甚至七十岁的时候想明白，只有当我们即将死去的时候，回顾一生，才能够有那么一丝的想法和总结。

只不过最有意思的是，我们无法将自己的人生重新来一遍，也就是说，这个困惑所有人的问题，只能在死去的时候才能够清晰，并且只存在于那一刹那，便会永远消失不见。

从动物本能的角度来说，开心能够让人愉悦，伤心会让人沮丧，追求幸福和开心是人的本能，所以，我觉得，还是应该顺应我们的动物本能，去做一些让自己能够开心的事情。

上下文管理：Agent 的“记忆”难题

Mon, 20 Apr 2026 09:22:23 +0000

前面四篇，我们搞清楚了 Agent 的完整工作原理：LLM 负责思考，Tool Use 负责执行，Agent Loop 把它们串成循环，System Prompt 定义行为规则。

但如果你真的跑过一个 Agent，你一定会遇到一个非常现实的问题：跑着跑着，它就“失忆”了，或者直接报错说 token 超限了。

这就是今天要聊的主题，上下文管理。

先搞清楚一个概念：上下文窗口

LLM 不是一个有记忆的东西。前面第三篇我们说过，它是无状态的，每次调用都要把完整的消息历史发给它，它才能知道之前发生了什么。

而这个“完整的消息历史”，不能无限长。每个 LLM 都有一个上下文窗口（Context Window），就是它一次能处理的信息总量上限，单位是 token。

现在主流模型的上下文窗口大概是这样的：

Claude：1M token
GPT-5：1M token

听起来挺大的？别急，我们算算 Agent 跑起来会消耗多少。

上下文是怎么被吃掉的

一个 Agent 每跑一轮循环，消息历史里就会多出这些东西：

LLM 的回复（包含思考过程和 tool_use）
工具执行的结果（tool_result）

关键是工具返回的结果往往很大。你让 Agent 读一个文件，tool_result 就是整个文件的内容，随便一个代码文件就可能几百行。你让它执行一个命令，输出也可能是一大片日志。

我们来算一笔账。假设 Agent 处理一个中等复杂度的任务，跑了 20 轮循环：

内容	大小估算
System Prompt	~3000 token
用户消息	~200 token
20 轮 LLM 回复	~10000 token
20 轮工具结果	~40000 token
总计	~53000 token

这还只是一个中等任务。如果是复杂任务，跑个五六十轮，再读几个大文件，轻轻松松就奔着几十万 token 去了。

而且别忘了，上下文窗口是输入和输出共享的。你输入占了 180K，留给 LLM 生成回复的空间就只剩 20K 了。

这就是上下文管理的核心矛盾：Agent 跑的轮次越多，积累的信息越多，但能装信息的容器就那么大。

为什么不能简单地丢掉旧消息

你可能会想：既然装不下了，把早期的消息删掉不就行了？

没那么简单。

假设 Agent 在第 3 轮读了一个配置文件，到第 25 轮的时候需要根据这个配置来修改代码。如果你把第 3 轮的内容删了，LLM 就不知道配置文件里写了什么，它要么瞎猜，要么重新去读一遍（浪费一轮循环）。

消息历史是 Agent 的“工作记忆”。随便删东西，就像一个人突然忘掉了之前的调查结果，轻则重复劳动，重则做出错误判断。

所以上下文管理的难点在于：怎么在有限的空间里，保留最重要的信息，丢掉不重要的。

常见的管理策略

实际的 Agent 产品会用几种策略来应对这个问题：

1. 对话摘要压缩

这是最常用的策略。当消息历史快要超限的时候，把早期的对话内容“压缩”成一段摘要。

比如前 10 轮的完整对话可能有 30000 token，压缩成一段摘要可能只需要 2000 token：

“用户让我修复 login 接口的 bug。我读了 src/auth/login.ts 和 src/utils/token.ts，发现 token 生成逻辑有问题，已经修复并更新了测试。”

这段摘要保留了关键信息（做了什么、改了哪些文件、结论是什么），但体积只有原来的十分之一不到。

谁来做这个压缩？还是 LLM 自己。你把早期的对话内容发给 LLM，让它生成一段摘要，然后用这段摘要替换掉原来的详细内容。

Claude Code 就用了这种方式，它叫 auto-compact。当上下文快满的时候，自动触发一次压缩，把早期对话浓缩成摘要，腾出空间给后续的工作。

2. 工具结果截断

工具返回的结果往往是上下文膨胀的最大元凶。一个文件内容可能有几千行，但 LLM 真正需要的可能只是其中几十行。

所以可以在返回 tool_result 的时候就做限制：

文件太长？只返回前 N 行，或者只返回与当前任务相关的部分
命令输出太多？截断，只保留最后 N 行（通常错误信息在末尾）
搜索结果太多？只返回 Top N 条最相关的

这种策略的好处是从源头控制输入量，坏处是可能丢掉了 LLM 需要的信息。所以截断要有策略，不能一刀切。

3. 滑动窗口

最简单粗暴的方式：只保留最近 N 轮的消息，更早的直接丢掉。

这种方式实现简单，但效果一般。因为 Agent 的工作往往是有连贯性的，第 5 轮做的事情可能在第 30 轮还有用。单纯按时间丢弃，很容易丢掉关键信息。

所以在实际产品中，滑动窗口通常不会单独使用，而是和摘要压缩配合：超出窗口的部分不是直接删掉，而是先压缩成摘要再保留。

4. 按需重新获取

既然旧的工具结果可以丢掉，那 LLM 需要的时候再重新获取不就行了？

比如第 3 轮读过的配置文件，到第 25 轮如果还需要，LLM 可以再调一次 read_file 重新读。反正工具还在，随时都能用。

这种方式的代价是多消耗一轮循环和一次工具调用，但好处是信息始终是最新的（文件可能在中间被修改过），而且不需要一直把内容留在上下文里占空间。

上下文管理的核心权衡

你会发现，所有策略都在做一个权衡：信息完整性 vs 空间效率。

保留的信息越完整，LLM 做决策的质量越高，但空间消耗也越大。压缩得越狠，空间越充裕，但 LLM 可能因为缺少关键信息而犯错。

没有完美的方案，只有适合当前场景的方案。好的 Agent 产品会组合使用多种策略，并且根据实际情况动态调整。

比如 Claude Code 的做法大致是这样的：

默认保留完整的消息历史
当上下文接近上限时，自动触发 compact（摘要压缩）
压缩时保留最近几轮的完整内容，更早的部分生成摘要
用户也可以手动触发压缩

这种方式在大多数场景下都能工作得不错。

为什么上下文管理是“能跑”到“能用”的关键

一个不做上下文管理的 Agent，跑个三五轮没问题，但稍微复杂一点的任务（需要十几轮甚至几十轮）就会撞墙。要么 token 超限直接报错，要么上下文太长导致 LLM 注意力分散，开始忽略早期的重要信息。

这也是为什么很多人自己写的 demo Agent 看起来能跑，但真正用起来很快就不行了。差别不在 Agent Loop 的实现上，而在这些“看不见的细节”上。

上下文管理就是这样一个看不见但极其重要的模块。它不决定 Agent 能不能工作，但决定了 Agent 能不能持续、稳定、可靠地工作。

一句话总结

上下文管理就是在有限的空间里，保留最重要的信息，让 Agent 能持续工作。核心策略是摘要压缩、结果截断、滑动窗口和按需重新获取，本质上都是在信息完整性和空间效率之间做权衡。

到这里，AI Agent 的五个核心概念我们就全部聊完了：LLM、Tool Use、Agent Loop、System Prompt、上下文管理。这五个东西组合在一起，就是 Cursor、Claude Code 这些 AI 编程助手背后的完整原理。

理解了这些，你就真正搞懂了 Agent 是怎么工作的。

System Prompt：Agent 的”出厂设置”

Wed, 15 Apr 2026 09:21:41 +0000

前三篇我们把 AI Agent 的核心原理拆完了：LLM 负责思考，Tool Use 负责执行，Agent Loop 把它们串成循环。

但你有没有想过一个问题：同样是 Claude 模型，为什么你可以让它变成一个严格的代码审查员，也可以让它变成一个自主干活的编程助手？模型没变，工具也没变，凭什么表现完全不一样？

答案就是今天要聊的东西，System Prompt。

什么是 System Prompt

System Prompt，直译叫"系统提示词"，但我更喜欢叫它 Agent 的"出厂设置"。

你可以把它理解为一段写给 LLM 的"内部指令"。用户看不到它，但它在每次对话中都会被发给 LLM，默默地影响着 LLM 的一切行为。

Anthropic 在 Claude 的 API 中，专门提供了一个 system 参数来设置它：

1
2
3
4
5


{
  "model": "claude-sonnet-4-20250514",
  "system": "你是一个专业的代码审查助手，专注于发现 bug 和安全漏洞。回复要简洁直接，不要废话。",
  "messages": [...]
}

就这么一段话，就能让同一个 Claude 模型表现得完全不同。加上这段 system prompt，它就变成了一个严肃的代码审查员；换一段，它又能变成一个耐心的编程导师。

在 Agent 的整体架构中，System Prompt 的位置大概是这样的：

1
2
3
4
5
6
7


System Prompt（定义身份和规则）
       ↓
      LLM（根据规则进行思考和决策）
     ↙   ↘
Tool Use   输出结果
     ↘   ↙
   Agent Loop（循环驱动）

System Prompt 是所有行为的起点。LLM 每次思考之前，都会先"读"一遍这个出厂设置，然后再决定怎么做。

System Prompt 到底管什么

一个好的 System Prompt 通常定义以下几件事：

1. 身份和角色

告诉 LLM “你是谁”。这不是闲聊，而是在设定它的行为基调。

比如 Claude Code 的 System Prompt 开头就会告诉 Claude：你是一个终端环境下的 AI 编程助手，你的任务是帮助用户完成软件工程任务。

这一句话就决定了 LLM 后续的所有行为倾向，它会倾向于读代码、写代码、执行命令，而不是跟你聊天侃大山。

2. 行为规则

告诉 LLM “该做什么、不该做什么”。

比如：

修改文件之前必须先读取文件内容
不要在没有用户确认的情况下执行危险命令（比如 rm -rf）
回复要简洁，不要输出多余的解释
优先使用专用工具而非 Bash 命令

这些规则就像公司给新员工发的行为手册。LLM 会尽量遵守这些规则来完成任务。

3. 工具使用策略

虽然工具定义告诉了 LLM “有哪些工具可以用”，但 System Prompt 可以进一步指导 LLM “什么时候该用哪个”。

比如 Claude Code 的 System Prompt 里，有大量类似这样的指导：

搜索文件用 Glob 工具，搜索文件内容用 Grep 工具

简单的代码搜索直接用工具，复杂的探索性搜索交给子 Agent

修改文件优先用 Edit 工具而不是完整重写

读文件用 Read 工具，不要用 Bash 执行 cat 命令

没有这些策略，LLM 虽然也能用工具，但可能用得不够好。就像一个新手虽然知道厨房里有哪些工具，但不知道切肉该用什么刀。

4. 输出格式

告诉 LLM 用什么方式说话，用 Markdown 还是纯文本？要不要加 emoji？代码块要不要标注语言？回复该长还是该短？

这些细节决定了用户体验，你可能觉得无所谓，但如果一个终端工具的 Agent 每次回复都输出一大堆 HTML 格式的内容，用起来会很难受。

为什么 System Prompt 这么重要

我打个比方。

LLM 就像一个能力很强但什么都不知道的新人。它脑子聪明、学东西快，但刚来公司什么情况都不了解。

Tool Use 是给它发了一套工具箱，Agent Loop 是让它可以自己干活。

System Prompt 是什么？是入职第一天，老板坐下来跟它说的那番话：

“你是我们团队的后端开发，主要负责 API 模块。我们的代码规范是这样的，git 提交格式是那样的，遇到不确定的事情先问我，不要自己乱搞。对了，生产环境的数据库别乱动。”

有了这番话，这个新人就知道自己该干嘛、不该干嘛、怎么干。没有这番话，它可能也能干活，但大概率会踩坑。

这就是 System Prompt 的价值，它不改变 LLM 的能力上限，但决定了 LLM 在具体场景下能发挥出多少。

同一个模型，不同的 Prompt，完全不同的表现

我们来做一个简单的实验。同一个 Claude 模型，给它两段不同的 System Prompt：

A：代码审查助手

“你是一个专业的代码审查员。用户会给你一段代码，你需要逐行审查，指出潜在的 bug、安全漏洞和性能问题。回复要严谨、有条理，每个问题都要给出修复建议。”

B：终端编程助手

“你是一个终端环境下的 AI 编程助手。用户给你任务，你自己去完成。你可以读文件、写文件、执行命令。回复要简洁高效，优先行动，少说废话。”

同样是让它们处理一个"login 接口有 bug"的问题：

A（审查员） 会等你把代码贴给它，然后逐行分析，列出问题清单，给出修改建议。它不会主动去读文件、改代码，因为它的角色定位就是"审查"，不是"动手"。
B（编程助手） 会自己去搜索 login 相关的文件，读源码，定位 bug，改代码，跑测试，测试不过还会自己 debug。整个过程不需要你引导。

同一个 Claude 模型，因为 System Prompt 不同，表现出了完全不同的行为模式。一个像严谨的审查员，一个像独立干活的开发者。

System Prompt 就是 Agent 产品的"灵魂"。 工具和循环是骨架，System Prompt 才是让 Agent 有个性、有风格、有专业性的东西。

System Prompt 的层级结构

在实际的 Agent 产品中，System Prompt 并不只是一段话，而是分成了好几层：

第一层：产品级 System Prompt。 这是 Agent 产品的开发者写死的，用户看不到也改不了。它定义了 Agent 最基础的行为模式，比如 Claude Code 的那几万字 System Prompt，涵盖了身份定义、工具使用策略、输出格式、安全规则等方方面面。

第二层：用户级自定义。 这是 Agent 产品提供给用户的定制入口。比如 Claude Code 的 CLAUDE.md 文件，Cursor 的 Rules 配置。你可以在这里写上你的项目规范、技术栈、代码风格偏好，Agent 每次启动都会把它加到上下文里。

第三层：对话级上下文。 每次对话时动态注入的信息，比如当前打开的文件、项目的目录结构、之前对话的摘要等。这些不是你写的，而是 Agent 程序自动收集并注入的。

这三层叠加在一起，就构成了 LLM 在每次对话中看到的完整"指令集"。产品级 Prompt 定义了基础行为，用户级定制做个性化调整，对话级上下文提供实时信息。

这也是为什么同一个 Claude Code，在不同项目里表现可能不一样，因为每个项目的 CLAUDE.md 不一样，对话级上下文也不一样，等于给 Agent 做了不同的"岗前培训"。

System Prompt 的局限性

说了这么多 System Prompt 的价值，也得说说它的局限，别把它神化了。

第一，LLM 不是 100% 遵守 System Prompt 的。 它只是"倾向于"遵守。你在 System Prompt 里写"回复不要超过 100 字"，它大多数时候会听，但偶尔还是会写一大段。特别是当用户的指令和 System Prompt 有冲突时，LLM 有时候会优先响应用户，毕竟它的本能是"尽可能满足用户的需求"。

第二，Prompt 越长，后面的指令越容易被忽略。 Claude Code 的 System Prompt 有几万字，要把所有规则都遵守得完美无缺是不现实的。这就是为什么 Agent 产品需要不断调优 Prompt，哪些规则放在前面、哪些用粗体强调、措辞怎么写更有效，都是需要反复实验的。

第三，System Prompt 解决不了模型能力本身的问题。 你不能靠一段 Prompt 让一个小模型去做它能力范围外的事情。Prompt 能做的是在模型能力范围内，引导它表现得更好，但不能把天花板抬高。

理解这些局限，你就能更理性地看待 System Prompt 的价值：它很重要，但不是万能的。

一句话总结

System Prompt 就是 Agent 的"出厂设置"，它定义了 LLM 的身份、行为规则、工具使用策略和输出格式。不改变模型的能力上限，但决定了实际表现。

下一篇，我们来聊另一个非常实际的问题，上下文管理。

Agent 跑了几十轮循环之后，消息历史越来越长，token 要爆了怎么办？LLM 的上下文窗口就像一个容量有限的工作台，东西堆多了就放不下了。

怎么在有限的空间里让 Agent 持续高效地工作？这是从"能跑"到"能用"的关键一步。

Agent Loop：让 Agent 自己跑起来

Tue, 07 Apr 2026 09:06:59 +0000

上篇文章我们聊了 Tool Use——LLM 通过结构化的方式"点菜"，Agent 程序负责"上菜"。

但光有工具还不够，LLM 调了一次工具、拿到了结果，然后呢？如果任务还没完成，它还得继续调其他工具，对吧？

这个"继续"的过程，就是今天要聊的核心——Agent Loop。

Anthropic 怎么说的

Anthropic 在他们那篇很有影响力的文章《Building effective agents》中，对 Agent 有一个非常精辟的定义：

Agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop.

Agent 可以处理复杂的任务，但它们的实现往往很简单。本质上就是 LLM 在一个循环中，根据环境反馈来使用工具。

注意这句话里的关键词：in a loop（在一个循环中）。

这就是 Agent 和普通 LLM 应用最本质的区别。普通的 LLM 应用是你问一句它答一句，流程是预先写死的。

而 Agent 是把控制权交给 LLM，由模型自己决定下一步做什么、调什么工具、什么时候停下来。

Anthropic 在文章中还特别强调了一点：Agent 的核心循环结构非常简单，关键在于模型的能力和工具的设计，而不是复杂的编排逻辑。

Claude Code 就是这个理念的直接产物。如果你用过 Claude Code，你应该能感受到：你给它一个任务，它会自己去读代码、改文件、跑命令，一步步推进，直到搞定。

背后驱动这一切的，就是 Agent Loop。

从一个真实场景说起

假设你在用 Claude Code 写代码，然后你说了一句：

“帮我在项目里找到所有 TODO 注释，整理成一个清单。”

这个任务对人来说很简单：打开搜索，输入 TODO，看看结果，整理一下。但对 Agent 来说，它需要经历一个完整的循环。

我们一步一步来看。

循环的每一步

第一轮：搜索 src 目录

你的任务发给 LLM 之后，LLM 会思考：要找 TODO 注释，我应该先用搜索工具在项目里搜一下。

于是它返回了一个 tool_use：

1
2
3
4
5


{
  "type": "tool_use",
  "name": "search",
  "input": { "pattern": "TODO", "path": "./src" }
}

Agent 执行搜索，拿到结果：

1
2
3


src/auth.js:42  // TODO: add token refresh logic
src/api.js:18   // TODO: handle timeout errors
src/utils.js:7  // TODO: refactor this function

Agent 把结果作为 tool_result 返回给 LLM。

第二轮：还要不要继续搜？

LLM 拿到搜索结果后，不是直接就给你答案了。

它会再想一下：找到了 3 个 TODO，但我只搜了 src 目录，是不是还应该看看测试目录？

于是它又返回一个 tool_use：

1
2
3
4
5


{
  "type": "tool_use",
  "name": "search",
  "input": { "pattern": "TODO", "path": "./tests" }
}

Agent 执行，发现测试目录里没有 TODO，把空结果返回给 LLM。

第三轮：够了，生成回答

这时候 LLM 判断信息已经足够了，不再调用工具，而是直接输出一段文字：

“项目中共有 3 处 TODO 注释：

src/auth.js 第 42 行：需要添加 token 刷新逻辑

src/api.js 第 18 行：需要处理超时错误

src/utils.js 第 7 行：需要重构该函数”

此时 stop_reason 变成 "end_turn"，循环结束。

整个流程画出来

你再回头看一遍，其实就是一个循环：

用户输入 → LLM 思考 → 需要工具？→ 是 → 执行工具 → 结果返回 LLM → LLM 再想 → 需要工具？→ 是 → …… → 不需要了 → 输出最终结果

这就是所谓的 Agent Loop（智能体循环）。

用代码来表达的话，核心逻辑就是一个 while 循环：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


while true:
    response = 调用 LLM(消息历史)

    if response 包含 tool_use:
        result = 执行工具(tool_use)
        把 tool_result 加入消息历史
        continue  // 继续循环
    else:
        输出最终回答
        break     // 退出循环

没错，就这么简单。正如 Anthropic 说的：Agent 可以处理复杂的任务，但它的实现往往很简单。整个 Agent 最核心的调度逻辑，就是这几行伪代码。

为什么这个循环这么重要

没有这个循环，LLM 就只能做一问一答的事情。你问它一个问题，它凭自己脑子里的知识回答你，完事了。

但有了这个循环，事情就完全不一样了。LLM 可以根据中间结果动态决定下一步做什么。搜完代码发现有个文件可疑，那就再读一下这个文件；读完发现还需要看看 git 历史，那就再调一个命令；命令执行发现报错了，分析一下原因再试一次。

Anthropic 把这种模式叫做 autonomous agent（自主智能体），和那些流程写死的 workflow 做了明确区分。workflow 是你提前规定好第一步做什么、第二步做什么；而 agent 是让模型自己决定该怎么走。这种灵活性，正是 Agent Loop 带来的。

这也是为什么 Claude Code 处理一个稍微复杂点的任务，可能要跑几十轮循环。它不是一步到位的，而是像人一样，边做边想，一步步推进。

循环中的关键细节

看上去简单的循环，实际跑起来有几个重要的细节：

消息历史是关键

每一轮循环，LLM 的回复（包含 tool_use）和工具的执行结果（tool_result）都要追加到消息历史里。下一轮调用 LLM 时，要把完整的历史都带上。

为什么？因为 LLM 本身是无状态的，它不记得上一次说了什么、做了什么。只有你把历史消息全部喂给它，它才能知道：“哦，我之前已经搜过 src 目录了，现在应该搜 tests 目录。”

消息历史就是 Agent 的"记忆"。

stop_reason 决定循环走向

上篇文章我们提到过，LLM 的返回里有一个 stop_reason 字段：

"tool_use"：LLM 想调工具，循环继续
"end_turn"：LLM 觉得完事了，循环结束

Agent 程序就是靠这个信号来决定：是继续跑，还是停下来把结果给用户。

循环不能无限跑

LLM 有时候会陷入奇怪的状态，比如反复调用同一个工具，或者在两个工具之间来回跳。所以实际的 Agent 都会设一个最大循环次数，超过了就强制停止。

这不是什么高深的技术，就是一个计数器加一个 if 判断。但不加的话，你的 Agent 可能会一直跑下去，token 费用也跟着蹭蹭涨。

一个更复杂的例子

上面找 TODO 的例子比较简单，只跑了两三轮。

来看一个更贴近真实场景的例子。

你跟 Claude Code 说：“帮我修一下 login 接口的那个 bug，用户登录后 token 没有正确返回。”

Claude Code 可能会这样跑：

轮次	LLM 决策	工具调用	结果
1	先找到 login 接口在哪	`search("login")`	找到 src/auth/login.ts
2	读一下这个文件	`read_file("src/auth/login.ts")`	拿到源码
3	看看 token 生成逻辑	`read_file("src/utils/token.ts")`	发现 generateToken 函数
4	找到 bug 了，改代码	`write_file("src/auth/login.ts")`	修复完成
5	跑一下测试确认	`bash("npm test")`	2 个测试失败
6	看看测试为什么挂了	`read_file("tests/auth.test.ts")`	发现测试也需要更新
7	更新测试代码	`write_file("tests/auth.test.ts")`	修改完成
8	再跑一次测试	`bash("npm test")`	全部通过 ✅
9	任务完成，汇报结果	无（end_turn）	输出修复总结

9 轮循环，用了 4 种不同的工具，中间还经历了一次测试失败后的自我纠正。

这就是 Agent 的威力：它不是按固定脚本执行的，而是根据每一步的实际结果，动态调整下一步该做什么。

就像一个真正的开发者在工作一样：遇到问题就分析，分析完就动手，动手后验证，验证不通过就再来。

一句话总结

Agent Loop 就是一个 while 循环：不断调 LLM、执行工具、喂回结果，直到任务完成。

它是整个 Agent 的调度核心，把 LLM 的"思考能力"和工具的"执行能力"串成了一条完整的工作链。没有这个循环，LLM 就只是一个聊天机器人；有了它，LLM 才真正变成一个能干活的 Agent。

到这里，AI Agent 的三大核心概念：LLM、Tool Use、Agent Loop，我们就全部讲完了，你已经理解了一个 Agent 到底是怎么工作的。

Tool Use：给 LLM 装上手脚

Wed, 01 Apr 2026 09:16:29 +0000

上篇文章我们说了，AI Agent 的本质就是三样东西：LLM + 工具 + 循环。

LLM 负责思考，这个好理解，循环我们后面再聊，今天先说中间那个——工具。

为什么要先说工具？因为它是 Agent 和普通聊天机器人之间最关键的分水岭。没有工具，LLM 再聪明也只是一个"嘴强王者"——说得头头是道，但啥也干不了。

LLM 的困境

你有没有想过，LLM 为什么不能直接帮你干活？

原因很简单：LLM 本质上就是一个文本生成器。

你给它一段话，它给你回一段话，仅此而已。它不能读你电脑上的文件，不能执行命令，不能访问互联网，更不能帮你改代码然后保存——它和你的电脑之间，隔着一道墙。

你跟 ChatGPT 说"帮我把 main.py 第 42 行的 bug 修一下"，它可以告诉你怎么改，但它没办法真的打开你的文件改掉它。就像一个被关在玻璃房里的天才，看得见外面，但摸不到。

所以问题来了：怎么让 LLM 能够和外部世界交互？

答案就是 Tool Use（工具使用）。

什么是 Tool Use

Anthropic 在 Claude 的官方文档中对 Tool Use 的描述非常清晰，我直接借用他们的说法：

Tool Use 允许 Claude 与外部工具和 API 进行交互。你在 API 请求中定义工具，Claude 会在合适的时候决定调用哪个工具、传什么参数，你的代码负责执行工具并返回结果。

说白了就是四个角色的协作：你（用户）提需求，Agent 程序做中间人，LLM 做决策，工具来执行。

具体怎么运作？按照 Anthropic 官方的说法，整个流程分成四步：

第一步：定义工具，发送请求

在你调用 LLM API 的时候，除了发送用户的消息，你还需要在请求里带上一个 tools 数组，告诉 LLM：“你现在有这些工具可以用。”

每个工具的定义包含三个要素：name（名字）、description（描述）、input_schema（参数定义，用 JSON Schema 格式）。

比如定义一个读文件的工具：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
  "name": "read_file",
"description": "Read the contents of a file at the given path.",
"input_schema": {
    "type": "object",
    "properties": {
      "file_path": {
        "type": "string",
        "description": "The absolute path to the file to read"
      }
    },
    "required": ["file_path"]
  }
}

这就是在给 LLM 一份"菜单"：你有一个能力叫 read_file，作用是读文件，需要一个参数 file_path。

这里的 description 特别重要。LLM 就是靠这个描述来判断什么时候该用这个工具的。描述写得越清晰，LLM 的调用就越准确。

第二步：LLM 返回 tool_use

LLM 拿到用户的任务和工具列表后，会思考：这个任务我自己能回答吗？还是需要借助工具？

如果它决定要用工具，返回的内容里会包含一个类型为 tool_use 的内容块。

这是 Anthropic API 里的专有概念——LLM 的回复不再只是纯文本，而是一个结构化的工具调用请求：

1
2
3
4
5
6
7
8


{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq",
  "name": "read_file",
  "input": {
    "file_path": "src/main.py"
  }
}

注意这里有个 id 字段，每次工具调用都有一个唯一标识，后面返回结果的时候要用到它。

这里最关键的一点——LLM 并没有真的去读文件。它只是"说"了一句话：我想读 src/main.py 这个文件。

就像你在餐厅点菜，你说"来一份宫保鸡丁"，但你不会自己跑到厨房去炒，LLM 就是那个点菜的人。

同时，API 响应里的 stop_reason 会变成 “tool_use”，而不是正常回复时的 “end_turn”。

Agent 程序就是靠这个标志来判断：LLM 还没说完，它想调工具，我得帮它执行。

第三步：执行工具，返回 tool_result

真正干活的是你写的 Agent 程序。它解析出 LLM 想调的工具和参数后，去执行对应的操作——比如真的去读那个文件，拿到文件内容。

然后，把结果用 tool_result 的格式返回给 LLM：

1
2
3
4
5


{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq",
  "content": "def main():\n    print('hello world')\n..."
}

看到那个 tool_use_id 了吗？它和前面第二步的 id 是对应的，这样 LLM 就知道这是哪次工具调用的结果。

如果工具执行出错了呢？你可以在返回时加上 “is_error”: true，告诉 LLM：这个工具调用失败了，你得换个思路。

第四步：LLM 拿到结果，继续思考

LLM 拿到 tool_result 后，就可以基于这些信息继续思考。它可能直接生成最终回复，也可能决定再调用其他工具——比如读完文件后觉得还要搜一下某个函数的引用。

这就自然引出了下一篇要讲的 Agent Loop：工具调用可以反复进行，形成一个循环，直到 LLM 觉得任务完成了为止。

用一个例子串起来

我们来看一个具体的例子，把四步完整走一遍。假设你对 Agent 说：

“帮我看看 config.json 里数据库的端口配置是多少。”

你 → Agent：“帮我看看 config.json 里数据库的端口配置是多少。”

Agent → LLM：把你的消息 + tools 工具列表一起发给 Claude API。

Claude 思考：用户想知道 config.json 的内容，我需要先读这个文件。我有 read_file 这个工具可以用。

Claude → Agent：返回 tool_use 内容块，stop_reason: “tool_use”

1
2
3
4
5
6


{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "read_file",
  "input": { "file_path": "config.json" }
}

Agent 执行：真的去读 config.json，拿到内容。

Agent → Claude：返回 tool_result

1
2
3
4
5


{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "{\"database\": {\"host\": \"localhost\", \"port\": 5432}}"
}

Claude 思考：拿到了，端口是 5432，可以直接回答用户了。

Claude → Agent → 你：“config.json 中数据库端口配置为 5432。“此时 stop_reason: “end_turn”，Agent 知道 LLM 说完了，循环结束。

看，整个过程中 LLM 做的事情就是两件：判断该用什么工具，以及根据工具返回的结果生成回答。它自己不执行任何操作，所有的"脏活累活"都是 Agent 程序在干。

以前不是这样的

你可能觉得这套机制很自然，但其实 Tool Use 是最近两年才成熟起来的。

早期的 LLM 根本没有原生的工具调用能力。那时候想让 LLM 调工具，靠的是什么？Prompt hack。

什么意思呢？就是你在 System Prompt 里写一大段话，告诉 LLM：

“如果你需要搜索，请按以下格式输出：

关键词*，我会帮你执行搜索并返回结果。”*

然后你的程序去解析 LLM 输出的文本，看有没有这个特定格式的标签，有的话就提取出来执行。

这种方式问题很大。LLM 生成的文本格式经常不对，漏个引号、多个换行就解析失败了。而且不同的工具要定义不同的格式，维护起来很痛苦。

现在不一样了，Anthropic 和 OpenAI 都在 API 层面原生支持了 Tool Use。工具定义用标准的 JSON Schema，LLM 返回结构化的 tool_use 内容块，格式稳定、解析简单。不再需要任何文本解析的 hack。

这一步的进化看起来不起眼，但它让 Agent 的可靠性提升了一个量级。可以说，没有原生 Tool Use 支持，就没有今天的 Agent 生态。

Coding Agent 需要哪些工具

工具这个概念很通用，不同场景的 Agent 用的工具完全不同。做客服的 Agent 可能需要查订单、查库存的工具，做数据分析的 Agent 可能需要查数据库、画图表的工具。

对于 Coding Agent——也就是帮你写代码的 Agent——核心工具其实就那么几个：

Read File：读取文件内容。Agent 要改你的代码，总得先看看现在长什么样吧。

Write File：写入或修改文件。看完了，想好了，得能动手改。

Bash：执行终端命令。跑测试、装依赖、查看 git 状态，都靠它。

Search：搜索代码。在大型项目里快速定位某个函数、某个变量在哪里用到了。

就这四个，一个 Coding Agent 的基本能力就全了。Cursor、Claude Code 这些产品，核心工具也就是这些，只不过在此基础上做了更多的细节优化和体验打磨。

你可能会觉得：就这？对，就这。工具不需要多复杂，关键是 LLM 要知道什么时候该用哪个、怎么用。而现在的模型，在这方面已经做得非常好了。

一句话总结

Tool Use 就是给 LLM 一份工具菜单，让它来点菜，Agent 程序负责上菜。LLM 不直接执行任何操作，它只负责决策。

理解了这一点，你就掌握了 Agent 的第二个核心概念。

下一篇，我们来聊最后一个核心——Agent Loop。有了工具，怎么把它们串成一个自动化的工作流，让 Agent 能一步步把任务搞定？这就是循环的魅力了。

AI Agent 到底是什么？别被那些花哨的概念唬住了

Mon, 30 Mar 2026 09:12:24 +0000

AI Agent 到底是什么？别被那些花哨的概念唬住了

AI Agent 到底是什么？别被那些花哨的概念唬住了

最近 AI Agent 这个词真的是铺天盖地，打开技术社区到处都在聊，什么"自主智能体"、“多模态协作”、“认知架构”……说实话，很多文章我看完之后的感受就是：说了一堆，但好像什么也没说。

今天我想用最大白话的方式，把 AI Agent 这个事儿讲清楚。如果你之前对 Agent 一无所知，没关系，看完这篇你就能有一个非常清晰的认知了。

先说结论

AI Agent，说白了就是三样东西：

LLM + 工具 + 循环

LLM 负责思考和决策，工具负责干活（读文件、写代码、搜索网页、执行命令等），循环是让它不断重复"思考—行动—观察"这个过程，直到任务完成。

你可能会说，这也太简单了吧？对，核心原理就是这么简单。那些高大上的概念，本质上都是在这三个东西上做文章。

打一个比方你就明白了。

想象你刚入职一家公司，老板跟你说：“把这个项目的用户模块重构一下。“你会怎么做？

你不会傻站着吧？你会先去看现有的代码，了解项目结构，然后想一个重构方案，接着动手改代码，改完跑一下测试，发现有个地方报错了，再回去看看哪里有问题，修一下，再测试……如此循环，直到搞定。

AI Agent 干的就是这个事，流程和你一模一样。只不过它的"脑子"是 LLM，它的"手"是各种工具，而那个"不断尝试直到搞定"的过程，就是循环。

和 ChatGPT 聊天有什么区别

这是很多人最困惑的一点：我平时用 ChatGPT 不也挺智能的吗？它和 Agent 到底差在哪？

差别非常大。我们平时用 ChatGPT，基本上是这样的：

你问一个问题 → 它回答 → 结束。

这是一个单轮或多轮的对话，但本质上 LLM 只是在回答问题，它不会主动去做任何事情。你让它写一段代码，它写完了就贴在那儿，至于这段代码能不能跑、文件该放哪里、要不要执行一下测试看看——它一概不管。

这就像你问一个特别聪明的朋友：“这个 bug 怎么修？“他给你分析得头头是道，方案讲得很清楚，但他说完就走了，不会帮你打开编辑器去改代码。

Agent 不一样。

你给 Agent 一个任务，比如"帮我在项目里加一个用户注册的接口”，它会：

先去读你的项目代码，看看现有的目录结构和代码风格

看看其他接口是怎么写的，学一下你的项目规范

找到合适的位置，写一个新的接口文件

把代码写入到对应的文件里

跑一下测试看看有没有问题

如果测试挂了，它会看报错信息，分析原因，修改代码，再跑一次

直到测试全部通过

看出来区别了吗？ChatGPT 是被动回答，Agent 是主动干活。

再打个比方。ChatGPT 像一个百科全书式的顾问，你问什么它答什么，知识渊博但手不动。Agent 更像一个实习生，虽然可能没那么老练，但你把任务交给它，它会自己去想办法完成——找资料、写东西、试错、返工，全程不用你盯着。

你其实已经在用 Agent 了

如果你用过下面这些工具，那你已经在和 Agent 打交道了，只是你可能没意识到：

Cursor / Windsurf：你在编辑器里说"帮我重构这个函数”，它会自动去读你的代码，理解上下文，然后修改多个文件，甚至帮你处理相关的引用。这就是一个 Coding Agent，只不过套了一个编辑器的壳。

Claude Code：Anthropic 出的终端 AI 编程助手，你在命令行里给它一个任务，它就自己开始干了——读文件、写文件、执行命令、跑测试，一步步把活干完。我自己现在日常开发基本离不开它了。

Devin：号称"第一个 AI 软件工程师”，能独立完成从需求分析到代码提交的整个流程。虽然实际效果还有不少争议，但方向是对的。

Manus：前段时间非常火爆的一个通用 Agent，它能操作浏览器、写代码、处理文件，自动化完成各种复杂任务。比如你让它"帮我调研一下竞品的定价策略”，它会自己打开浏览器一个个去看，然后整理成报告给你。

这些产品形态各异，有的在编辑器里，有的在终端里，有的在浏览器里，但底层逻辑都一样——LLM 做大脑，工具做手脚，循环做驱动。

为什么现在 Agent 突然火了

Agent 这个概念其实不新，学术界很早就在研究了。但以前为什么一直停留在"概念"阶段？因为 LLM 不够聪明。

你想想，如果你招了一个实习生，但他连你说的话都理解不了，你给他工具他也不会用，或者用得乱七八糟——那你还不如自己干呢。以前的 LLM 就是这个状态。

转折点在 2024 年前后，几个关键条件同时到位了：

第一，模型能力飙升。 Claude 3.5 Sonnet、GPT-4o、以及后面的 Claude Sonnet 4 等模型，推理能力有了质的飞跃。它们是真的能理解你的意图，分析复杂的上下文，然后做出合理的决策。就像那个实习生突然开窍了，一点就通。

第二，Tool Use 协议成熟。 Anthropic 和 OpenAI 都推出了标准化的工具调用协议。什么意思呢？以前你想让 LLM 调工具，得靠各种 prompt hack，让它输出特定格式的文本，然后你去解析——非常不可靠。现在不一样了，LLM 可以结构化地告诉你"我想调用哪个工具、参数是什么"，这让 Agent 的实现变得简单且可靠。

第三，上下文窗口变大。 以前的模型只能处理几千个 token，你连一个文件都塞不完整。现在动不动就是 100K、200K 的上下文窗口，一个 Agent 可以把整个项目的关键代码都读进去，理解能力自然就上来了。这就好比那个实习生以前只能看一页纸的需求文档，现在能把整个项目的设计文档全部看完再动手。

这三个条件一到位，Agent 就从"学术概念"变成了"真能干活的产品"。所以你会发现，2024 年到 2025 年，Agent 相关的产品井喷式爆发，不是巧合，是技术成熟到了这个节点。

Agent 的门槛其实没那么高

很多人觉得 AI Agent 是一个很高深的东西，离自己很远。但说实话，如果你是一个有基本编程能力的开发者，理解 Agent 的原理甚至自己写一个，真的没那么难。

核心代码量其实并不大。一个最简单的 Agent，可能就几百行代码——调 LLM API、定义几个工具、写一个循环，就跑起来了。当然，要做到像 Cursor、Claude Code 那样好用，还有很多细节要打磨，比如上下文管理、错误处理、用户体验等等。但起步的门槛，真的比你想象的低很多。

一句话总结

AI Agent = 一个能自己想、自己做、做完还能自己检查和纠正的 LLM 应用。

核心就是 LLM + 工具 + 循环，不要被各种花哨的术语吓到。它的本质就是给 LLM 装上手脚，让它从"只能说"变成"能说也能做"。

如果你理解了这一点，恭喜你，你已经比大多数人看得更清楚了。下一篇文章，我会拆开那个"循环"给你看——一个 Agent 从接到任务到完成任务，中间到底经历了什么，每一步都在干嘛。

Vibe Coding 时代的开发者

Mon, 02 Mar 2026 19:25:53 +0000

vibe coding 浪潮下，每个开发者都会毋庸置疑的受到影响，分享一下自己近期的一些想法。

传统的分工模式

在以前，对于一家公司，尤其是初创公司，最常见的做法就是按照产品的不同维度来进行职能划分，比如前端、后端、客户端、测试、运维等等。

之所以要这样划分，原因其实很简单，很难找到一个人，能够精通所有的东西，把全部的工作链路都打通。

这种分工模式当然有好的一面，那就是各司其职，每个人专注于自己擅长的领域，效率很高。在大厂中更是如此，每个人都只是一个螺丝钉，共同拼凑出一个完整的产品。

当然这种模式也带来了不少弊端：沟通成本高、协作链路长、个人视野容易被局限在自己那一小块领域里。

我自己就有过这种感受，有时候你只盯着自己负责的模块，对整个产品的全貌反而越来越模糊。

AI 加持下，个人的能力边界被打开了

但是有了 AI 的加持之后，事情开始变得不一样了。

个人的能力会得到显著的增强，之前无法拓展的边界，无法掌握的全栈和深度知识，现在变得容易很多。

以前你想从后端去写前端页面，可能需要花好几个月去系统学习，踩无数的坑。

但现在呢？借助 AI，可以快速地搭建一个可用的系统，虽然可能不够完美，但至少能把整条链路跑通。

不过目前来看 AI 也不是万能的。

我自己平时做数据库内核相关的工作，涉及到复杂的系统设计、性能调优、底层数据结构这些领域，AI 生成的代码很多时候是不够可靠的，甚至可能埋下一些隐蔽的坑。

越是底层的、对正确性要求高的场景，越需要人去把关，所以 AI 打开的是能力边界，但一个人的核心的深度思考和判断力，依然是不可替代的。

开发者的工作模式会被重新定义

对个人来说，以往的工作模式可能会被彻底颠覆。

以前我们做开发，会比较专注于某个产品功能的 coding，写完代码之后进行小范围的自测，然后和前端、测试、产品等各个角色进行对接，一个功能在不同的人之间流转，最终才能上线。

但是现在，coding 的部分正在被 AI 逐步接管。

开发者的角色会慢慢转变，你不再只是一个写代码的人，而是要专注于对功能本身的把关，负责整体的调研、方案设计、测试验证，总体来说，就是需要对全局有一个掌控能力。

这一点其实挺关键的，如果只是简单地使用 AI 生成代码，然后直接提交，说实话，这种技能将会变得无比廉价，没有任何门槛，谁都能干的事情，那就没有什么竞争力可言了。

但换个角度来看，真正廉价的不是 AI 本身，而是不加思考地使用 AI。

会用 AI 和善用 AI 之间的差距，可能比会写代码和不会写代码之间的差距还要大，你能不能在 AI 输出的基础上做出准确的判断，能不能识别出哪些地方是对的、哪些地方有问题，这才是真正的核心竞争力。

所以对我们个人来说，综合素质的要求将会变得更高，未来的趋势可能是：一个个"超级个体"，每个人负责一个功能的全方位流程，coding、测试、发布、前后端，一个人就能够全部搞定。

当然，成为"超级个体"是有前提的，你需要对产品有判断力，对技术有全局视野，对质量有把控能力。

说白了，门槛不是变低了，而是从"写代码"转移到了"做判断"，以前你可能只需要把某个模块的代码写好就行，但现在你需要能够站在更高的维度去思考问题，有能力和有想法的人，越来越有有机会成为一个真正独当一面的人。

信息获取的密度被拉满了

AI 对个人的影响，还有一个很重要的点，那便是信息获取的密度会变得非常高。

之前我们学习和探索一个新的知识点，这个过程可能是缓慢的。你需要不断地去搜索、去翻文档、去看源码，甚至去各种论坛上找相关的内容进行整理总结，有时候一个问题折腾一天都不一定能搞明白。

但是现在，对于一个项目里面任何不懂的地方，直接问 AI 就能够得到一个大致正确的答案，这个过程甚至要不了 5 分钟。

我自己就有过一个挺明显的感受：之前在研究一个不太熟悉的模块的时候，按照以往的方式，可能需要花好几天去翻代码、查资料，才能理清其中的脉络。但现在让 AI 先帮我梳理一遍整体的架构和关键逻辑，我再带着这些信息去看源码，效率直接翻了好几倍。

大脑对于信息的摄入变得前所未有地快速和密集，这对我们来说既是好事，也是挑战，它要求我们具备不断接纳新知识、快速消化理解的能力。

久而久之，那些善于提问、善于整合信息的人，会和其他人拉开越来越大的差距。

以人为本，主动拥抱变化

我始终秉持一个观点：AI 的使用应该以人为本。

AI 说到底只是一个工具，在短期内它无法取代人，它不会帮你做决策，不会帮你判断产品方向，也不会帮你处理那些复杂的、需要人与人之间沟通协调的事情。

但是，我们确实应该主动去拥抱这种变化，因为 AI 对生产效率的提升的确是有目共睹的，这一点没什么好争论的。与其去焦虑它会不会取代自己，不如想想怎么最大化地利用它的优势，然后去激发自身的潜能。

毕竟，工具越强大，使用工具的人就越重要。

使用 Claude Code 几天后的感受和经验

Tue, 10 Feb 2026 18:42:02 +0000

最近在做数据库优化器的并行查询支持，需要新增好几个算子。

这几个算子的开发，我开始尝试用 Claude Code 辅助完成，两天时间，三个算子基本完整实现，每个涉及 30 多个文件、1500 行以上的代码改动。

使用几天之后有一些真实的感受和经验，这里聊聊，也给想尝试 AI 编程工具的同学一些参考。

先说背景

我们项目中用的优化器叫 ORCA，是一个 C++ 写的独立查询优化器，代码量大概 90 多万行。给这种大型 C++ 项目加功能，最大的挑战不是某个算法有多难，而是流程太长、涉及的模块太多。

加一个算子，需要改十几个文件：算子定义、转换规则、中间表示、序列化、反序列化、代价模型、最终翻译……每一步都有自己的规范和约束，漏掉任何一步都会编译失败或者运行时出问题。

如果纯手写，一个算子少说得两三天起步，还得反复翻已有的代码做参照，并且不断学习新的概念。

这是我想尝试 Claude Code 的原因——看看它能不能在这种"大项目、长流程"的场景里真正帮上忙。

它实际帮了哪些忙

快速理解陌生代码

这个优化器的代码我之前只看过一部分，很多模块并不熟悉。

以前碰到不熟悉的模块，我的做法是 grep 关键词、顺着调用链一个文件一个文件地看，90 万行代码里找上下文，经常花很长时间。

现在我直接问 Claude Code：“这个 Class 是做什么的”、“这个方法的调用链是怎样的”，它能直接读源码、定位到关键代码位置给出解释。

**这是我觉得 Claude Code 最有价值的能力之一，**它不是凭记忆回答（那样大概率会编），而是实时去读你项目的代码，基于实际代码来回答，这一点和在网页端使用 ChatGPT 这种 AI 工具有本质区别。

参照已有模式生成代码

我的功能实现场景有一个好处——已经有一个类似的算子作为参考模式。

所以我告诉 Claude Code"参照这个已有算子的模式，新增一个类似的算子"，它能把整条链路的代码都生成出来：新文件、新类、注册逻辑、序列化代码、构建文件修改，一次性覆盖完整流程。

当然不是说生成完就直接能用，新算子和参考算子之间有不少差异，Claude Code 生成的第一版代码，有些差异处理得不完全正确，我需要逐个文件 review 然后修正。

但即便如此，它帮我省掉了大量"脚手架"代码的编写——那些模式固定、但写起来繁琐且容易遗漏的部分。毫不隐瞒地说，如果纯手写这十几个文件，我大概率会在某个环节漏掉什么，然后花半天 debug。

而 Claude Code 至少把完整流程都覆盖到了，我只需要集中精力在核心逻辑的正确性上。

编译报错直接扔给它

C++ 大项目的编译错误有时候信息量很大，一个错误刷出几十行。直接把报错信息扔给 Claude Code，大部分情况它能准确定位问题并修复——类型不匹配、头文件缺失、虚函数没实现等等。

有一次遇到一个运行时断言失败，报错位置和我改的代码完全没关系，我自己看了半天没头绪。把报错信息给 Claude Code，它分析后判断是构建缓存导致的问题，建议 clean rebuild，果然就好了。

更有意思的是，它会记住这种经验。后面我再做类似修改的时候，它主动提醒我"这种改动需要先 clean 再 rebuild"，不用我再踩同样的坑。

辅助学习和梳理架构

除了写代码，我还用 Claude Code 来学习和理解系统架构。

它的做法是直接去读源码，然后结合我的问题给出结构化的解释。比如我问某个概念是什么意思，它会去找到对应的基类和几个典型子类的实现，用真实代码来解释，而不是给一段泛泛而谈的定义。

这种**“基于实际代码的学习”**效率非常高，尤其适合那些文档不完善、设计细节都藏在代码里的项目。

我甚至让它帮我生成了一份完整的学习计划，按阶段组织，每个阶段标注对应的源码文件和学习重点。这个对后面新人上手很有帮助。

几个可以复用的使用技巧

用了一段时间之后，我总结了一些自己觉得比较有效的使用方式，供大家参考。

1. 人来设计，AI 来实现

这是我觉得最重要的一条。不要指望 AI 替你做设计决策，而是你想清楚要做什么、核心逻辑是什么，然后让它来写具体代码。

具体来说就是：我自己想清楚新算子的语义、和已有算子的差异点、需要修改哪些模块，然后给 Claude Code 一个明确的指令，指令越清晰，生成的代码质量越高。

反过来，如果你说"帮我实现一个 xxx 功能"但自己都没想清楚要怎么做，生成的代码大概率不能用。

2. 给它一个参照物

如果你的项目里已经有类似的代码，一定要指明参考哪个文件、哪个类。比如"参照 A 类的模式来写 B 类"，这比从头描述需求要高效得多。AI 很擅长"照葫芦画瓢"，它能精确复制已有代码的风格、命名规范和架构模式。

这也是大型项目用 Claude Code 的天然优势——项目越大，可参照的模式越多，AI 能发挥的空间越大。

3. 逐文件 review，不要一把梭

生成完代码不要直接提交。我的做法是每个文件过一遍，重点看：

核心逻辑是否正确（这是 AI 最容易出错的地方）
边界条件有没有漏处理
和已有代码有没有冲突

模板化的代码（序列化、注册、构建文件等）一般问题不大，重点盯核心逻辑就行。

4. 善用它的记忆能力

Claude Code 有一个持久化的 memory 机制——它会把关键经验、项目约束记录下来，后续对话自动参考。

你也可以主动让它记住一些东西，比如"我们项目用的是 Autotools 构建系统，不是 CMake"、“修改枚举头文件后必须 clean rebuild”。记住一次，后面就不用反复提醒了。

这一点是 Claude Code 相比网页端 ChatGPT/Claude 最大的区别之一——它是有"项目记忆"的，不是每次对话从零开始。

5. 当成代码搜索引擎和学习助手

除了写代码，Claude Code 作为代码阅读工具的价值可能被低估了。

想了解某个模块怎么工作的？直接问它，比自己 grep 来 grep 去快得多。想搞清楚一个复杂的调用链？让它帮你追踪。想快速上手一个不熟悉的代码库？让它帮你梳理架构、生成学习路线。

在大型项目中，这种"随时可问的代码助手"能显著降低认知负担。

6. 复杂任务先让它做计划

对于涉及多个文件、多个步骤的复杂任务，不要上来就让它开始写代码。可以先让它分析需要改哪些文件、每个文件改什么，确认计划没问题后再动手。

这样做的好处是：你能在动手之前就发现遗漏或者方向性错误，避免写了一半发现思路不对。

什么场景下效果最好

用下来的感受是，Claude Code 在以下场景效果最明显：

代码量大的项目：上下文越多，人越难全局掌控，AI 的辅助价值越大
有模式可循的开发：参照已有代码做变体，这是 AI 最擅长的
跨文件、跨模块的改动：一个需求涉及十几个文件，人很容易遗漏，AI 能帮你保证完整性
流程化/脚手架代码：序列化、反序列化、注册、配置文件这类机械性代码

相对来说，以下场景它帮助有限：

从零设计全新架构：这需要对系统有深入理解和全局思考，AI 目前做不到
性能调优：需要 profiling 数据和对硬件特性的理解
需要深入理解业务语义的 bug 修复：AI 能帮你定位代码位置，但理解为什么这样做是错的，还是得靠人

写在最后

工具终究是工具，它不会替代你对系统的理解和设计能力。但不得不说，对于大型 C/C++ 项目这种代码量大、模式化程度高的开发场景，Claude Code 确实能帮不少忙。

我之前折腾过不少 AI 编程工具，包括 GitHub Copilot、Cursor 等等。

Claude Code 给我最大的不同感受是——它不只是补全几行代码，而是能理解整个项目的上下文，真正参与到跨文件、跨模块的开发任务中来。加上记忆能力和命令行的工作方式，它更像一个能读懂你项目的"结对编程"搭档，而不只是一个代码补全工具。

当然了，前提是你自己得清楚自己在做什么。AI 最擅长的是加速执行，而不是替你思考。

如果你也在做系统级的开发工作，不妨试试，可能会有惊喜，后续我也会分享更多的 vibe coding 的相关经验。

北漂三年

Sun, 17 Aug 2025 00:05:07 +0000

不知不觉在北京已经三年了。

作为一个南方人，对北方总是有一种莫名的抵触，我内心曾想过永远也不会到北方去，因为害怕漫长的冬季，我甚至一直希望生活在一个永远没有冬天的地方。

但事与愿违，人生中的很多事情并不是那么顺心意的。

当初来北京只是计划待半年，后来由于工作和生活中的一些因素，一直在北京未能离开，于是就这样三年过去了。

三年之间有太多的变化，当初前后脚入职的同事有很多也已经跳槽了。我也从一个职场小白，持续的在这个行业里摸爬打滚，慢慢的有了一些积累。

工作这几年的持续输出和个人影响力构建，也让我开始获得了一些实际的成果和回报，可以说，是在北京这个地方，我才开始感受到在工作方面的第一次质变。

所以有时候命运就是这么捉弄人，尽管不喜欢北方，但偏偏却是在这个地方收获到了更多。

公司附近的商场，比起我当初看到的模样也改变了许多，经历了一次重新装修，有了新的名字，有了更豪华的装饰，以及更多的商家。

这里秋天的天空特别蓝，万里无云，还有令人沉醉的微风，当然春天的柳絮，雾霾，沙尘暴会让人觉得很不舒适，冬天没有我想象的那么难熬，尽管室外有时寒风彻骨，但室内的暖气确实是南方人从未体验过的。

扪心自问，尽管待了几年，但是我对北京这座城市是无感的，谈不上喜欢，也谈不上讨厌。

只不过，我这种自由散漫的性格，有时候无法在一个高压的城市环境中长久生存，这意味着注定会离开。但是又何去何从呢，仍然没有答案，只有迷茫。

今年感觉整个人的状态不一样了，工作前几年里，我几乎每天都会坚持学习，做很多事情也比较有干劲，脑子里也会有比较多新奇的想法和创意，乐于分享。

但是 2025 年到现在，突然一下子感觉到累了，每天下班之后都昏昏欲睡，很难集中注意力。甚至，我根本不知道自己想要什么，不知道自己喜欢什么，不知道想要追求什么样的生活。

有时候也会在一些论坛贴子里看到类似“人生的意义”之类的话题，但也都是泛泛而谈，虽然能够理解，也觉得有道理，但是对目前的我好像并不能起到实际的帮助。

有时候内心也会骂自己，可能就是闲的，无车无房无女朋友，感受不到什么压力，容易胡思乱想。现在有一份工作，有自己的业余爱好，无病无灾的，还有什么不知足呢。

但我内心清楚，一些迷茫与无奈确实是客观存在的，比如自己的一些打算迫于一些客观条件无法在短期内得到实现，甚至可能永远无法实现；比如内心所追求的，却怎么也得不到；比如我总是秉持着一个理想主义者的心态，却总是在残酷的现实中四处碰壁。

如此种种都让我觉得，好像没有什么是可以追求的，对很多事情也失去了兴趣，好像生活真的没有什么意义。

不知道这种状态会持续多久，也不知道我能否找到答案。

或许，我们痛苦、迷茫、努力，忙碌半生，只是让我们知道自己是一个普通人，如沧海一粟，泛不起一点涟漪，改变不了别人，甚至改变不了自己。

近期的生活和工作状态

Wed, 14 May 2025 19:09:08 +0000

生活

今年初更新完《rosedb 源码剖析》的系列文章和视频之后，好久没更新文章了，主要是在生活其他方面花费了更多一些的精力。

一是前段时间房子到期了，看房和搬家花了一些时间。

我租房子还是本着不折腾的心态，尽量给自己减少通勤的负担，所以毕业几年以来，基本上都是租公司附近的小区，然后是走路 15 分钟左右上下班，几乎没怎么去挤过上下班高峰期的地铁。

这样的好处是能够有更多的时间用于自主学习，自媒体运营，以及其他副业的拓展。

不得不吐槽一下，一线城市租房子实在是太贵了，我是在五环边上，一个 70 平左右的一居室，租金是 7000+ 一个月。

尽管嫌弃贵，但咬咬牙还是租了，一个人住，空间大点也是挺有生活幸福感的。

二是，业余时间打网球更多了。

去年七月份开始，重拾了网球，这是我唯一喜欢的运动。大学的时候打网球比较多，但是工作几年之后基本荒废了。

最近这几个月打网球比较多，是因为感觉到自己技术比较菜，总是恼怒自己为什么不能更好，心理非常不服气。

于是花了一些时间去练习，然后也参与了一些业余比赛。

然后过了今年的这几个月，还是觉得高手太多了，就算自己再怎么努力，也只能是一个业余水平，永远也不可能和专业学网球的人较量高低。

于是心态放平和了很多，现在只把它当做是一个日常锻炼身体的活动，我需要将精力放到自己擅长的事情上来。

工作

工作方面中规中矩，在目前这家数据库初创公司快三年了，这是我毕业后第一次在一家公司待这么长的时间，之前都是大概一年半跳槽一次。

工作内容方面依然围绕数据库内核展开，边做边学，目前能够自己去设计一些 feature，独立做一些事情。

但是整体对数据库内核的知识掌握仍然是比较零散的，暂时没有形成一个比较系统的框架，这是我需要加强的地方。

最近其实也对工作产生了很多的情绪，有时候会觉得非常的累，一眼望不到尽头。

但是我内心也劝诫自己，现在这环境下，能有一份工作都不错了，好多人还找不到工作呢，还要啥自行车？

仔细想了一下，对工作感到厌倦的主要原因是，无法在短期内达到自己理想的状态，比如能够创业，或者是做出很酷的产品，赚更多的钱。

但其实又是太正常不过了，想要真正在行业内做出好的产品，亦或是顶尖的产品，一定是需要在行业内有十年如一日的积累，加上对行业有深刻的理解，并且集成了人脉、资本，或者是其他资源，才有可能迈出这一步。而我的状态才哪到哪呢，仅仅学习数据库三年而已。

最近几个月的创作时间变少了，向各位读者说声抱歉。

确实在这方面有些懈怠，但是最近业余时间应该会重新向写文章&做视频倾斜，慢慢恢复更新的频率。

因为我自己本身还是属于爱创作，爱分享的人，长期不和读者粉丝互动，不向大家提供有价值的分享，我自己也会觉得非常的不适应。

最后，打个小广告，我的个人付费课程长期营业中，目前有《从零实现 KV 存储》、《从零实现 SQL 数据库》、《从零实现分布式 KV》三门实战课程，

帮助了很多同学实现技能提升、丰富简历、求职转行、以及升职加薪。

感兴趣可以进入课程主页了解：

**https://roseduan.cn/course**

掌握 Rust 语言的终极秘籍

Mon, 24 Feb 2025 08:47:37 +0000

我自己接触 Rust 挺长时间了，非常看好这门语言，也很喜欢 Rust。

Rust 语言近年来也在系统开发领域逐渐崭露头角，凭借独特的性能与内存管理优势，成为了众多开发者青睐的编程语言。

无论你是后端开发、数据库设计，还是分布式系统，Rust 都有很好的性能优势，并且 Rust 的整个生态也在日渐完善了。

如果你对 Rust 语言充满兴趣，或是想深入学习如何用 Rust 构建底层系统，下面这两门我亲自设计和编码的课程将是你学习路上的宝贵资源，再次给大家推荐一下！

《从零实现 KV 存储》

这门课程的核心在于通过实现一个简易的 KV 存储引擎，帮助大家了解和掌握 Rust 在存储系统开发中的应用。

课程完整目录如下：

我们会从最基础的 Bitcask 模型入手，逐步构建出一个高效、可靠的 Key-Value 存储引擎。在这一过程中，大家将深入了解数据的存储、索引、编码、持久化等基本概念。

对于 KV 存储来说，如何高效存储和检索数据是最基本的需求，Bitcask 模型通过顺序追加日志来实现高效的写入与读取，并且能够提供简单的错误恢复机制。课程中的实践让你能够亲手构建一个简洁而高效的 KV 存储系统，为后续的复杂应用打下坚实的基础。

课程内容还扩展到了 Redis 数据结构与协议的支持。你将学习如何在 KV 存储引擎上实现一些常见的数据结构，例如字符串、哈希表、列表等，并通过实现 Redis 协议，掌握如何处理客户端请求。

为了便于开发和测试，课程还涉及到 HTTP 接口访问的实现，让你可以通过 HTTP 请求与 KV 存储引擎进行交互。

通过这门课程，你不仅可以掌握 Rust 语言的基本语法，还能学习到如何运用 Rust 开发高性能、可靠的存储系统。课程内容全面且具有实践性，非常适合对底层系统开发感兴趣的 Rust 初学者。

《从零实现 SQL 数据库》

这门课程更进一步，带着大家从零开始实现一个简单的 SQL 数据库。

课程完整目录如下：

在实际项目中，SQL 数据库是非常核心的组件，学习如何实现一个简易的 SQL 数据库，能够让你更好地理解数据库内部的工作原理，并且为未来开发复杂系统打下坚实基础。

在这门课程中，会实现一个 SQL 数据库内部的完整构造，比如解析器、执行计划、执行器、存储引擎等等。

为了支持数据的持久化与事务性操作，课程还设计了基于内存和磁盘的存储引擎。在内存引擎中，我们将使用简单的 BTreeMap 索引结构，以优化数据检索效率。而在磁盘引擎中，我们将设计数据存储和磁盘文件的管理方式，从而保证数据的可靠存储。

另外，ACID（原子性、一致性、隔离性、持久性）事务是 SQL 数据库设计的核心内容。课程将详细介绍如何实现事务机制，确保数据库操作的一致性与可靠性。

最后，为了提高开发效率与用户体验，我们还设计了一个简单的可视化命令行界面，帮助用户更加直观地与数据库交互。

通过这门课程，你将获得关于 SQL 数据库设计的全面理解，从底层原理到代码实现的每一个环节。对于想要深度了解数据库内部机制的开发者来说，这门课程无疑是一把开启数据库知识大门的钥匙。课程的代码总量在 6500 行左右（包含注释），全部从零手写，相信通过这样一个硬核的课程，能够对 Rust 有一个全面的理解。

如果大家想入门并且上手实践 Rust 的话，这两门课程无疑是非常好的入门教程，不仅可以帮助你理解 Rust 语言的核心特性（如内存管理、并发模型和性能优化），更重要的是，通过实际的项目，带你走进系统编程和数据库开发的世界。

通过这两门课程的学习，你将能够更加深入地理解 Rust 的精髓与应用。这不仅仅是学习语言，更是一个走向高效系统开发的过程。如果你也想挑战自我，提升编程技能，走上成为 Rust 系统开发专家的道路，那就从这两门课程开始吧。

关于课程详情，大家可以查看以下链接：

**https://roseduan.cn/course**

想要购买的话，可以加我，或者有其他任何疑问都可以咨询。

Go 实战项目 rosedb 源码剖析 8—迭代器、过期时间

Sat, 22 Feb 2025 09:23:58 +0000

1、迭代器

由于全内存索引的缘故，rosedb 的迭代器实现起来相对简单，因为在内存中已经维护了全量的 key 和索引信息，并且前面提到过 rosedb 中使用了一个 btree 数据结构，btree 本身是有序的，所以在迭代数据的时候只需要根据 key 的信息取出索引，然后从数据文件中读到对应的 Value 即可。

在迭代数据的时候，rosedb 提供了两种方式，分别是调用 Ascend、Descend 这种方法，可以直接传入一个自定义的方法处理 Key 和 Value，定义大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// Ascend calls handleFn for each key/value pair in the db in ascending order. 
func (db *DB) Ascend(handleFn func(k []byte, v []byte) (bool, error)) {
    db.mu.RLock()
    defer db.mu.RUnlock()

    db.index.Ascend(func(key []byte, pos *wal.ChunkPosition) (bool, error) {
        chunk, err := db.dataFiles.Read(pos)
        if err != nil {
            return false, err
        }
        if value := db.checkValue(chunk); value != nil {
            return handleFn(key, value)
        }
        return true, nil
    })
}

还有一种方式是使用更常见的 Iterator 迭代器，这种迭代器可以更加灵活的控制，比如可以进行 Seek、可以手动调用 Next 跳转到下一个 Value，大致使用方法如下：

1
2
3
4
5
6
7
8
9


iter := db.NewIterator(iterOpts)
defer iter.Close()

for iter.Rewind(); iter.Valid(); iter.Next() {
    item := iter.Item()
    if item != nil {
        fmt.Printf("key = %s, value = %s\n", string(item.Key), string(item.Value))
    }
}

在创建 Iterator 的时候可以传入一个参数配置，目前有如下三个配置项：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// IteratorOptions defines configuration options for creating a new iterator. 
type IteratorOptions struct {
    // Prefix specifies a key prefix for filtering. If set, the iterator will only 
    // traverse keys that start with this prefix. Default is empty (no filtering). 
    Prefix []byte

    // Reverse determines the traversal order. If true, the iterator will traverse 
    // in descending order. Default is false (ascending order). 
    Reverse bool

    // ContinueOnError determines how the iterator handles errors during iteration. 
    // If true, the iterator will log errors and continue to the next entry. 
    // If false, the iterator will stop and become invalid when an error occurs. 
    ContinueOnError bool
}

Prefix：指定扫描的 key 前缀，只有前缀匹配才会输出对应的数据
Reverse：控制是否进行迭代反转，false 为正向迭代，true 为反向迭代
ContinueOnError：在遇到某个 value 读取错误的时候，是否继续读取下一条数据

索引迭代器

面向外层调用者的迭代器接口，在 rosedb 内部，实际上是基于索引迭代器进行实现的，所以先来介绍下索引迭代器。

索引迭代器的方法名和外层的方法基本类似，大致的区别是索引返回的 Value 是 ChunkPosition，而外层 DB 的迭代器，需要根据 ChunkPosition 从 wal 当中读取 Value。

索引层面的迭代器也是分为了两种，一种是 Ascend 和 Descend 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// Ascend iterates over items in ascending order and invokes the handler function for each item. 
// If the handler function returns false, iteration stops. 
Ascend(handleFn func(key []byte, position *wal.ChunkPosition) (bool, error))

// AscendRange iterates in ascending order within [startKey, endKey], invoking handleFn. 
// Stops if handleFn returns false. 
AscendRange(startKey, endKey []byte, handleFn func(key []byte, position *wal.ChunkPosition) (bool, error))

// AscendGreaterOrEqual iterates in ascending order, starting from key >= given key, 
// invoking handleFn. Stops if handleFn returns false. 
AscendGreaterOrEqual(key []byte, handleFn func(key []byte, position *wal.ChunkPosition) (bool, error))

// Descend iterates over items in descending order and invokes the handler function for each item. 
// If the handler function returns false, iteration stops. 
Descend(handleFn func(key []byte, pos *wal.ChunkPosition) (bool, error))

// DescendRange iterates in descending order within [startKey, endKey], invoking handleFn. 
// Stops if handleFn returns false. 
DescendRange(startKey, endKey []byte, handleFn func(key []byte, position *wal.ChunkPosition) (bool, error))

// DescendLessOrEqual iterates in descending order, starting from key <= given key, 
// invoking handleFn. Stops if handleFn returns false. 
DescendLessOrEqual(key []byte, handleFn func(key []byte, position *wal.ChunkPosition) (bool, error))

这种方法，直接调用了 BTree 提供的方法进行遍历，以 Ascend 为例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func (mt *MemoryBTree) Ascend(handleFn func(key []byte, position *wal.ChunkPosition) (bool, error)) {
    mt.lock.RLock()
    defer mt.lock.RUnlock()

    mt.tree.Ascend(func(i btree.Item) bool {
        cont, err := handleFn(i.(*item).key, i.(*item).pos)
        if err != nil {
            return false
        }
        return cont
    })
}

另一种是 Iterator 迭代器接口，定义如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// IndexIterator represents a generic index iterator interface. 
type IndexIterator interface {
    // Rewind resets the iterator to its initial position. 
    Rewind()

    // Seek positions the cursor to the element with the specified key. 
    Seek(key []byte)

    // Next moves the cursor to the next element. 
    Next()

    // Valid checks if the iterator is still valid for reading. 
    Valid() bool

    // Key returns the key of the current element. 
    Key() []byte

    // Value returns the value (chunk position) of the current element. 
    Value() *wal.ChunkPosition

    // Close releases the resources associated with the iterator. 
    Close()
}

Rewind：迭代器指针重新回到初始位置
Seek：跳转到第一个大于等于（或小于等于）给定值的位置
Next：跳转到下一个值
Valid：是否有效，用于表示遍历是否已经结束
Key：用户实际的 key
Value：内存中的 Value，返回值是 ChunkPosition
Close：关闭迭代器，清理资源

这种 Iterator 迭代器实际上底层的 BTree 并没有直接提供类似的接口，我们进行了一层封装，利用 BTree 已有的方法去实现了迭代器中的接口，例如 Rewind 方法让迭代器指针重新回到初始位置，调用了 Btree 提供的 Min 或 Max 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func (it *memoryBTreeIterator) Rewind() {
    if it.tree == nil || it.tree.Len() == 0 {
        return
    }

    if it.reverse {
        it.current = it.tree.Max().(*item)
    } else {
        it.current = it.tree.Min().(*item)
    }
    it.valid = true
}

例如 Next 方法，直接找到比当前值更大（或更小）的值即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


it.valid = false
if it.reverse {
    it.tree.DescendLessOrEqual(it.current, func(i btree.Item) bool {
        if !i.(*item).Less(it.current) {
            return true
        }
        it.current = i.(*item)
        it.valid = true
        return false
    })
} else {
    it.tree.AscendGreaterOrEqual(it.current, func(i btree.Item) bool {
        if !it.current.Less(i.(*item)) {
            return true
        }
        it.current = i.(*item)
        it.valid = true
        return false
    })
}

DB 迭代器接口

在索引迭代器的基础之上，DB 迭代器的接口就是面向实际用户的了，实现上也比较简单，直接对索引迭代器进行封装。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// Iterator represents a database-level iterator that 
// provides methods to traverse over the key/value pairs in the database. 
// It wraps the index iterator and adds functionality to 
// retrieve the actual values from the database. 
type Iterator struct {
    indexIter index.IndexIterator // index iterator for traversing keys 
    db        *DB                 // database instance for retrieving values 
    options   IteratorOptions     // user-defined configuration options 
    lastError error               // stores the last error encountered during iteration 
}

提供的方法是类似的，唯一的区别是索引迭代器的返回值是内存索引 ChunkPosition，这里需要根据 ChunkPosition 从 wal 文件中读取实际的 Value。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


position := it.indexIter.Value()
if position == nil {
    it.indexIter.Next()
    continue
}

// read the record from data file 
chunk, err := it.db.dataFiles.Read(position)
if err != nil {
    it.lastError = err
    if !it.options.ContinueOnError {
        it.Close()
        return nil
    }
    log.Printf("Error reading data file at key %q: %v", key, err)
    it.indexIter.Next()
    continue
}

2、过期时间

rosedb 支持过期时间，也就是说一个 key 可以存活一段时间，然后自动失效。

在实现上，主要是对 LogRecord 加上一个额外的字段 expire，表示其过期时间，然后在写入的时候将这个信息存储起来，并且在读取的时候，需要结合这个字段进行判断，如果 expire 时间已经超过了当前时间，那么就认为 key 是无效的。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// LogRecord is the log record of the key/value pair. 
// It contains the key, the value, the record type and the batch id 
// It will be encoded to byte slice and written to the wal. 
type LogRecord struct {
    Key     []byte
    Value   []byte
    Type    LogRecordType
    BatchId uint64
    Expire  int64
}

PutWithTTL

PutWithTTL 和 Put 方法类似，但是可以额外指定一个 ttl，表示 key 的存活时间。

在填充 LogRecord 的时候，只需要结合 ttl 和当前时间就能够计算得到 expire 信息。

1
2
3
4
5
6
7
8
9


// PutWithTTL adds a key-value pair with ttl to the batch for writing. 
func (b *Batch) PutWithTTL(key []byte, value []byte, ttl time.Duration) error {
    // 其他代码省略..... 
    record.Key, record.Value = key, value
    record.Type, record.Expire = LogRecordNormal, time.Now().Add(ttl).UnixNano()
    b.mu.Unlock()

    return nil
}

在读取的时候，从 wal 中拿到的是 chunk 信息，也就是一个字节数组，然后我们需要解码得到 LogRecord 的信息。

这时候需要判断 expire 是否已经超过了当前时间，如果 key 已经过期了，那么直接将其从索引中删除，并且返回 Key 不存在的错误。

1
2
3
4
5
6
7
8
9


    // check if the record is deleted or expired 
    record = decodeLogRecord(chunk)
    if record.Type == LogRecordDeleted {
        panic("Deleted data cannot exist in the index")
    }
    if record.IsExpired(now) {
        b.db.index.Delete(record.Key)
        return nil, ErrKeyNotFound
    }

Expire

Expire 方法主要是对一个已经存在的 key 设置过期时间。

如果针对的是已经存在于 pendingWrites 临时数组中的数据，那么可以直接更新其过期时间，并且在 Commit 阶段再写入到 wal 文件中。

1
2
3
4
5
6
7
8
9


    // if the key exists in pendingWrites, update the expiry time directly 
    if record != nil {
        // return key not found if the record is deleted or expired 
        if record.Type == LogRecordDeleted || record.IsExpired(time.Now().UnixNano()) {
            return ErrKeyNotFound
        }
        record.Expire = time.Now().Add(ttl).UnixNano()
        return nil
    }

否则的话，则需要从 wal 文件中读取数据，如果 key 不存在的话直接返回错误，否则更新数据的过期时间。

然后写入到 pendingWrites 中，待 Commit 时进行写入。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


    now := time.Now()
    record = decodeLogRecord(chunk)
    // if the record is deleted or expired, we can assume that the key does not exist, 
    // and delete the key from the index 
    if record.Type == LogRecordDeleted || record.IsExpired(now.UnixNano()) {
        b.db.index.Delete(key)
        return ErrKeyNotFound
    }
    // now we get the value from wal, update the expiry time 
    // and rewrite the record to pendingWrites 
    record.Expire = now.Add(ttl).UnixNano()
    b.appendPendingWrites(key, record)

TTL

TTL 方法返回一个 key 的存活时间。

具体逻辑也比较简单，首先还是从 pendingWrites 中获取，如果能拿到数据的话，则直接根据 expire 信息得到 tll 值。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


    var record = b.lookupPendingWrites(key)
    if record != nil {
        if record.Expire == 0 {
            return -1, nil
        }
        // return key not found if the record is deleted or expired 
        if record.Type == LogRecordDeleted || record.IsExpired(now.UnixNano()) {
            return -1, ErrKeyNotFound
        }
        // now we get the valid expiry time, we can calculate the ttl 
        return time.Duration(record.Expire - now.UnixNano()), nil
    }

否则需要从 wal 文件中获取数据，并且解码得到 LogRecord，并且判断其是否已经过期了，然后计算得到 ttl。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


    chunk, err := b.db.dataFiles.Read(position)
    if err != nil {
        return-1, err
    }

    // return key not found if the record is deleted or expired 
    record = decodeLogRecord(chunk)
    if record.Type == LogRecordDeleted {
        return-1, ErrKeyNotFound
    }
    if record.IsExpired(now.UnixNano()) {
        b.db.index.Delete(key)
        return-1, ErrKeyNotFound
    }

    // now we get the valid expiry time, we can calculate the ttl 
    if record.Expire > 0 {
        return time.Duration(record.Expire - now.UnixNano()), nil
    }

Persist

Persist 方法主要用于移除一个 key 的过期时间，这样 key 就能够永久存活了。

首先还是从 pendingWrites 中获取，如果存在的话则直接将 expire 信息设置为 0。

1
2
3
4
5
6
7
8
9


    // if the key exists in pendingWrites, update the expiry time directly 
    var record = b.lookupPendingWrites(key)
    if record != nil {
        if record.Type == LogRecordDeleted && record.IsExpired(time.Now().UnixNano()) {
            return ErrKeyNotFound
        }
        record.Expire = 0
        return nil
    }

否则从 wal 文件中读取数据，解码得到 LogRecord，然后将 expire 设置为 0，并且存到临时数组中，待 Commit 时写入。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


    chunk, err := b.db.dataFiles.Read(position)
    if err != nil {
        return err
    }

    record = decodeLogRecord(chunk)
    now := time.Now().UnixNano()
    // check if the record is deleted or expired 
    if record.Type == LogRecordDeleted || record.IsExpired(now) {
        b.db.index.Delete(record.Key)
        return ErrKeyNotFound
    }
    // if the expiration time is 0, it means that the key has no expiration time, 
    // so we can return directly 
    if record.Expire == 0 {
        return nil
    }

    // set the expiration time to 0, and rewrite the record to wal 
    record.Expire = 0
    b.appendPendingWrites(key, record)

DB 过期时间接口

前面提到的几个方法都是 Batch 中的，在 DB 实例中也有一个同样的方法，其实和上一节提到的关于 Put、Delete、Get 方法类似，都是对 Batch 接口做了一层简单的封装，类似只有单个操作的 Batch。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// PutWithTTL a key-value pair into the database, with a ttl. 
// Actually, it will open a new batch and commit it. 
// You can think the batch has only one PutWithTTL operation. 
func (db *DB) PutWithTTL(key []byte, value []byte, ttl time.Duration) error {
    batch := db.batchPool.Get().(*Batch)
    deferfunc() {
        batch.reset()
        db.batchPool.Put(batch)
    }()
    // This is a single put operation, we can set Sync to false. 
    // Because the data will be written to the WAL, 
    // and the WAL file will be synced to disk according to the DB options. 
    batch.init(false, false, db)
    if err := batch.PutWithTTL(key, value, ttl); err != nil {
        _ = batch.Rollback()
        return err
    }
    return batch.Commit()
}

过期 key 清理

如果过期的 key 没有及时清理的话，key 和索引都会残留在内存中，造成不必要的空间浪费。

在 rosedb 当中，有两种方式可以对过期的 key 进行清理。

一种是自动的，比如在调用 Get 或者 Exist 的时候，如果判断到 key 是存在的，但是已经过期了，那么会直接删除掉索引中对应的 key。

1
2
3
4


    if record.IsExpired(now) {
        b.db.index.Delete(record.Key)
        return nil, ErrKeyNotFound
    }

第二种方式是调用者手动进行清理，rosedb 当中提供了方法 DeleteExpiredKeys ，这个方法主要是扫描索引中的数据，并且判断是否已经过期了，如果是的话则从索引中将其删除。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// delete from index if the key is expired. 
for _, pos := range positions {
    chunk, err := db.dataFiles.Read(pos)
    if err != nil {
        innerErr = err
        done <- struct{}{}
        return
    }
    record := decodeLogRecord(chunk)
    if record.IsExpired(now) {
        db.index.Delete(record.Key)
    }
    db.expiredCursorKey = record.Key
}

调用者可以在外层封装一个定时任务，实现自动清理过期 key 的功能。

Go 实战项目 rosedb 源码剖析 7—启动流程

Thu, 20 Feb 2025 08:42:48 +0000

理解了前面的 rosedb 数据写入、读取、merge 流程之后，再来看看数据库启动的流程。

Bitcask 模型需要在启动的时候去执行全量数据扫描，并且加载索引，在 rosedb 当中，主要涉及到加载 merge 文件，并且如果有 HINT 文件的话，可以直接从 HINT 文件中加载索引，否则从数据文件中加载索引。

rosedb 在启动的时候通过 Open 方法，启动的时候可以传递参数配置，目前有如下配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


// Options specifies the options for opening a database. 
type Options struct {
    // DirPath specifies the directory path where the WAL segment files will be stored. 
    DirPath string

    // SegmentSize specifies the maximum size of each segment file in bytes. 
    SegmentSize int64

    // Sync is whether to synchronize writes through os buffer cache and down onto the actual disk. 
    // Setting sync is required for durability of a single write operation, but also results in slower writes. 
    //
    // If false, and the machine crashes, then some recent writes may be lost. 
    // Note that if it is just the process that crashes (machine does not) then no writes will be lost. 
    //
    // In other words, Sync being false has the same semantics as a write 
    // system call. Sync being true means write followed by fsync. 
    Sync bool

    // BytesPerSync specifies the number of bytes to write before calling fsync. 
    BytesPerSync uint32

    // WatchQueueSize the cache length of the watch queue. 
    // if the size greater than 0, which means enable the watch. 
    WatchQueueSize uint64

    // AutoMergeEnable enable the auto merge. 
    // auto merge will be triggered when cron expr is satisfied. 
    // cron expression follows the standard cron expression. 
    // e.g. "0 0 * * *" means merge at 00:00:00 every day. 
    // it also supports seconds optionally. 
    // when enable the second field, the cron expression will be like this: "0/10 * * * * *" (every 10 seconds). 
    // when auto merge is enabled, the db will be closed and reopened after merge done. 
    // do not set this shecule too frequently, it will affect the performance. 
    // refer to https://en.wikipedia.org/wiki/Cron 
    AutoMergeCronExpr string
}

DirPath：表示文件的存放目录，不存在的话会自动创建
SegmentSize：表示一个 wal 数据文件的最大容量
Sync：是否每次写入都将操作系统缓存的数据刷到磁盘中
BytesPerSync：累计写入多少字节后调用 Sync
WatchQueueSize：这个参数主要是支持 watch 功能，即 key 对应的值有变化之后通知调用方
AutoMergeCronExpr：此参数启用自动 merge 功能，填写一个 cron 表达式，后台线程自动进行 merge

在 Open 方法的具体代码中，首先会检查参数配置是否有效，如果传递的目录不存在的话，则会创建这个目录。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


    // check options 
    if err := checkOptions(options); err != nil {
        return nil, err
    }

    // create data directory if not exist 
    if _, err := os.Stat(options.DirPath); err != nil {
        if err := os.MkdirAll(options.DirPath, os.ModePerm); err != nil {
            return nil, err
        }
    }

然后会使用文件锁机制，确保一个目录中只能有一个进程，即一个目录之上只能运行一个 rosedb 实例，确保数据安全。

1
2
3
4
5
6
7
8
9


    // create file lock, prevent multiple processes from using the same database directory 
    fileLock := flock.New(filepath.Join(options.DirPath, fileLockName))
    hold, err := fileLock.TryLock()
    if err != nil {
        return nil, err
    }
    if !hold {
        return nil, ErrDatabaseIsUsing
    }

然后是加载 merge 文件。

1
2
3
4


    // load merge files if exists 
    if err = loadMergeFiles(options.DirPath); err != nil {
        return nil, err
    }

在前面讲解 merge 的流程当中，提到过 merge 完成之后，如果没有立即清理文件的话，merge 之后的文件和旧的数据文件都存在，这时候需要进行替换，将旧的数据文件删除，将 merge 的文件作为新的数据文件。

在 loadMergeFiles 方法中，会加载上一次 merge 终止的 SegmentID。因为我们为了检查 merge 操作是否已经完成，会在 merge 结束之后写一个文件，这个文件是以 .MERGEFIN 后缀结尾的。

这个文件中记录了上一次 merge 操作完成的 SegmentID，例如上一次 merge 操作的文件是 0-5，那么这个文件中记录的就是 5。

1
2
3
4
5


    // get the merge finished segment id 
    mergeFinSegmentId, err := getMergeFinSegmentId(mergeDirPath)
    if err != nil {
        return err
    }

如果这个文件并不存在，或者读取的时候失败了，那么说明 merge 操作并没有成功完成，只需要删除掉 merge 目录即可。

然后读取到了这个 mergeFinSegmentId，只需要将这些文件移动到原数据目录当中，这样原来的文件就被删除，merge 目录中的文件就成了新的数据文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


    // now we get the merge finished segment id, so all the segment id less than the merge finished segment id 
    // should be moved to the original data directory, and the original data files should be deleted. 
    for fileId := uint32(1); fileId <= mergeFinSegmentId; fileId++ {
        destFile := wal.SegmentFileName(dirPath, dataFileNameSuffix, fileId)

        // remove the original data file 
        if _, err = os.Stat(destFile); err == nil {
            if err = os.Remove(destFile); err != nil {
                return err
            }
        }
        // move the merge data file to the original data directory 
        copyFile(dataFileNameSuffix, fileId, false)
    }

Merge 文件加载完成之后，数据文件的状态已经全部准备好了，这时候通过 wal 打开这些文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


func (db *DB) openWalFiles() (*wal.WAL, error) {
    // open data files from WAL 
    walFiles, err := wal.Open(wal.Options{
        DirPath:        db.options.DirPath,
        SegmentSize:    db.options.SegmentSize,
        SegmentFileExt: dataFileNameSuffix,
        Sync:           db.options.Sync,
        BytesPerSync:   db.options.BytesPerSync,
    })
    if err != nil {
        return nil, err
    }
    return walFiles, nil
}

打开数据文件之后，就能够加载索引了，主要的逻辑在 loadIndex 方法中，加载索引主要是分为了两部分，第一是如果存在 HINT 文件的话，则直接从 HINT 文件中加载，然后再从数据文件中加载。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


func (db *DB) loadIndex() error {
    // load index frm hint file 
    if err := db.loadIndexFromHintFile(); err != nil {
        return err
    }
    // load index from data files 
    if err := db.loadIndexFromWAL(); err != nil {
        return err
    }
    return nil
}

HINT 文件是在 merge 的过程中生成的，存储的是 key+position 信息，position 就是 value 在 wal 文件中的位置。需要注意 HINT 文件中的位置索引信息肯定是最新的，因为 merge 的时候是直接写入的最新的 value，所以得到的索引信息肯定也是最新的状态，这时候直接插入到索引当中即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


    for {
        chunk, _, err := reader.Next()
        if err != nil {
            if err == io.EOF {
                break
            }
            return err
        }

        key, position := decodeHintRecord(chunk)
        // All the hint records are valid because it is generated by the merge operation. 
        // So just put them into the index without checking. 
        db.index.Put(key, position)
    }

HINT 文件其实也是通过 wal 组件打开的，所以可以直接调用 wal 的遍历方法，加载其中的数据，这时候加载的并不是之前数据文件中提到的 LogRecord，而是只包含 key 和索引信息的 hint 文件的 record 信息，这里并没有使用一个专门的结构体来表示，而是直接对这两个信息进行编码，读出来之后按照同样的方式进行解码。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


func encodeHintRecord(key []byte, pos *wal.ChunkPosition) []byte {
    // SegmentId BlockNumber ChunkOffset ChunkSize 
    //    5          5           10          5      =    25 
    // see binary.MaxVarintLen64 and binary.MaxVarintLen32 
    buf := make([]byte, 25)
    var idx = 0

    // SegmentId 
    idx += binary.PutUvarint(buf[idx:], uint64(pos.SegmentId))
    // BlockNumber 
    idx += binary.PutUvarint(buf[idx:], uint64(pos.BlockNumber))
    // ChunkOffset 
    idx += binary.PutUvarint(buf[idx:], uint64(pos.ChunkOffset))
    // ChunkSize 
    idx += binary.PutUvarint(buf[idx:], uint64(pos.ChunkSize))

    // key 
    result := make([]byte, idx+len(key))
    copy(result, buf[:idx])
    copy(result[idx:], key)
    return result
}

从 HINT 文件中加载索引之后，还需要从数据文件中加载索引。

试想这样一种情况，文件 0-5 是参与了 merge 过程的文件，但是在 merge 的过程当中，有可能有新的数据写入，所以可能生成了数据文件 6，甚至 7，这时候这些新的没有参与 merge 的文件是没有对应的 HINT 索引文件信息的，只能从数据文件本身去加载索引，这部分的逻辑在 loadIndexFromWAL 中。

在遍历数据文件加载索引的过程中，需要判断如果已经是从 HINT 文件中加载过索引了，则直接跳过。

1
2
3
4
5
6
7


// if the current segment id is less than the mergeFinSegmentId, 
// we can skip this segment because it has been merged, 
// and we can load index from the hint file directly. 
if reader.CurrentSegmentId() <= mergeFinSegmentId {
    reader.SkipCurrentSegment()
    continue
}

然后是从数据文件中加载 LogRecord 信息，需要判断如果类型是 LogRecordDeleted，则表示从索引中删除对应的数据。

并且如果一个 Batch 中的数据并没有对应的特殊的标识 Batch 结束的数据的话，则说明这个 Batch 是无效的，直接丢弃这些数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


// if we get the end of a batch, 
// all records in this batch are ready to be indexed. 
if record.Type == LogRecordBatchFinished {
    batchId, err := snowflake.ParseBytes(record.Key)
    if err != nil {
        return err
    }
    for _, idxRecord := range indexRecords[uint64(batchId)] {
        if idxRecord.recordType == LogRecordNormal {
            db.index.Put(idxRecord.key, idxRecord.position)
        }
        if idxRecord.recordType == LogRecordDeleted {
            db.index.Delete(idxRecord.key)
        }
    }
    // delete indexRecords according to batchId after indexing 
    delete(indexRecords, uint64(batchId))
} elseif record.Type == LogRecordNormal && record.BatchId == mergeFinishedBatchID {
    // if the record is a normal record and the batch id is 0, 
    // it means that the record is involved in the merge operation. 
    // so put the record into index directly. 
    db.index.Put(record.Key, position)
} else {
    // expired records should not be indexed 
    if record.IsExpired(now) {
        db.index.Delete(record.Key)
        continue
    }
    // put the record into the temporary indexRecords 
    indexRecords[record.BatchId] = append(indexRecords[record.BatchId],
        &IndexRecord{
            key:        record.Key,
            recordType: record.Type,
            position:   position,
        })
}

索引加载完成之后，DB 启动的流程就基本完成了。

随后有一些额外的处理，第一个是如果开启了 watch 功能的话，会启动一个后台 goroutine 去处理 key 变化通知的事件信息。

1
2
3
4
5
6
7


    // enable watch 
    if options.WatchQueueSize > 0 {
        db.watchCh = make(chan *Event, 100)
        db.watcher = NewWatcher(options.WatchQueueSize)
        // run a goroutine to synchronize event information 
        go db.watcher.sendEvent(db.watchCh)
    }

第二个是如果传递的参数 AutoMergeCronExpr 是有效的话，则也启动一个后台 goroutine 去定时周期性的去调用 merge 进行数据文件的清理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


    // enable auto merge task 
    iflen(options.AutoMergeCronExpr) > 0 {
        db.cronScheduler = cron.New(
            cron.WithParser(
                cron.NewParser(cron.SecondOptional | cron.Minute | cron.Hour |
                    cron.Dom | cron.Month | cron.Dow | cron.Descriptor),
            ),
        )
        _, err = db.cronScheduler.AddFunc(options.AutoMergeCronExpr, func() {
            // maybe we should deal with different errors with different logic, but a background task can't omit its error. 
            // after auto merge, we should close and reopen the db. 
            _ = db.Merge(true)
        })
        if err != nil {
            return nil, err
        }
        db.cronScheduler.Start()
    }

广告区：

《从零实现 KV 存储》，使用 Rust 和 Go 两种语言实现，手把手教学，只需要基础的语法知识，即可学会一个硬核实战项目！

《从零实现 SQL 数据库》，使用 Rust 手写一个数据库系统，超级硬核，Rust 实战项目首选！

课程详情：https://roseduan.cn/course/

Go 实战项目 rosedb 源码剖析 6—Merge 操作

Wed, 19 Feb 2025 08:34:22 +0000

Merge 操作是 bitcask 模型中描述的清理文件中的无效数据，rosedb 中的 Merge 操作基本按照 bitcask 模型的流程进行处理。

首先需要理解为什么会有无效数据存在，前面说过 rosedb 中的数据文件的写入、删除都是 append-only 的，也就是说永远不会去修改旧的数据。那么在数据库运行的过程中，如果发生了数据的覆盖，或者是删除等，都会导致一些无效的数据残留在文件中。

例如我们先后依次写入了 k = 100，k= 200，k = 300，并且写入了 x = 100，然后执行了删除 x 的操作。

这时候文件中已经存在了 5 条 LogRecord 信息，但是实际上 k 的最新的值是 300，那么其旧值就没有必要存在了，可以进行清理。并且 x 已经被删除了，但是仍然有两个 LogRecord 记录在了文件中，这也是可以清理掉的。

所以 Merge 的过程实际上就是将有效的数据进行重写，这样就能够保证文件中写入的数据一定是最新的，然后删除掉旧的文件，这时候就完成了无效数据清理的流程。

在 Merge 的过程中，还会生成一个 HINT 文件，这个文件中只包含 key+索引信息，而不包含 value 信息，这样可以在启动的时候加载 HINT 文件直接加载索引，而不需要读取整个 value，是为了启动加速而做的优化。

具体到代码实现，首先会打开一个新的 Segment 文件用于写入，例如原来的 Segment 文件列表是 0-5，这时候打开新的文件 6 作为活跃文件，那么 0-5 文件都是能够进行 Merge 操作的了。

1
2
3
4
5
6
7


    prevActiveSegId := db.dataFiles.ActiveSegmentID()
    // rotate the write-ahead log, create a new active segment file. 
    // so all the older segment files will be merged. 
    if err := db.dataFiles.OpenNewActiveSegment(); err != nil {
        db.mu.Unlock()
        return err
    }

然后会打开一个新的 DB 实例，如果当前 DB 实例的路径是 /tmp/db/rosedb_merge_test，那么会在同级之下建立一个新的临时目录，目录名称是在原有的目录上以 -merge 结尾，例如下面这样：

打开的 DB 实例就在这个 -merge 的临时目录打开，这里叫做 mergeDB：

1
2
3
4
5
6
7
8
9


    // open a merge db to write the data to the new data file. 
    // delete the merge directory if it exists and create a new one. 
    mergeDB, err := db.openMergeDB()
    if err != nil {
        return err
    }
    defer func() {
        _ = mergeDB.Close()
    }()

然后遍历当前 DB 实例的所有数据文件，这里调用了 wal 组件的遍历方法。

1
2
3
4
5
6
7


chunk, position, err := reader.Next()
if err != nil {
    if err == io.EOF {
        break
    }
    return err
}

从 wal 文件中读取每一条数据，并且取出其中的 key，然后和内存索引中进行对比，如果是相等的，则说明是一条有效的数据，则进行重写。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


if indexPos != nil && positionEquals(indexPos, position) {
    // clear the batch id of the record, 
    // all data after merge will be valid data, so the batch id should be 0. 
    record.BatchId = mergeFinishedBatchID
    // Since the mergeDB will never be used for any read or write operations, 
    // it is not necessary to update the index. 
    newPosition, err := mergeDB.dataFiles.Write(encodeLogRecord(record, mergeDB.encodeHeader, buf))
    if err != nil {
        return err
    }
    // And now we should write the new position to the write-ahead log, 
    // which is so-called HINT FILE in bitcask paper. 
    // The HINT FILE will be used to rebuild the index quickly when the database is restarted. 
    _, err = mergeDB.hintFile.Write(encodeHintRecord(record.Key, newPosition))
    if err != nil {
        return err
    }

需要注意这里如果 LogRecord 类型不是 LogRecordNormal 的话，例如是被删除的数据，或者是已经过期的数据，那么也会直接过滤掉。

这里在写入的时候，是写入到了临时的 mergeDB 当中，并且将索引数据写入到了 HINT 文件当中。

1
2
3
4


    // And now we should write the new position to the write-ahead log, 
    // which is so-called HINT FILE in bitcask paper. 
    // The HINT FILE will be used to rebuild the index quickly when the database is restarted. 
    _, err = mergeDB.hintFile.Write(encodeHintRecord(record.Key, newPosition))

还需要注意一个问题是，如果在数据量较大的情况下，merge 操作可能是很漫长的，如果中途发生了错误，我们有什么办法可以判断呢？

还是和 Batch 的处理类似，我们可以在 merge 操作结束之后，再写入一个新的文件，这个文件的内容可以写最大的参与 merge 的文件 ID，假如这次 merge 操作的文件 id 是 0-5 ，那么就可以记录 5。

merge 过程中，新插入的数据，例如可能是 6-7，这样可以在启动的时候帮助我们过滤哪些文件是 merge 过的，这样可以直接从 HINT 文件加载索引，否则就从数据文件中加载索引。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// After rewrite all the data, we should add a file to indicate that the merge operation is completed. 
// So when we restart the database, we can know that the merge is completed if the file exists, 
// otherwise, we will delete the merge directory and redo the merge operation again. 
mergeFinFile, err := mergeDB.openMergeFinishedFile()
if err != nil {
    return err
}
_, err = mergeFinFile.Write(encodeMergeFinRecord(prevActiveSegId))
if err != nil {
    return err
}
// close the merge finished file 
if err := mergeFinFile.Close(); err != nil {
    return err
}

这个文件记录完成之后，整个 merge 操作就结束了。

大家可能还会注意到一个问题，那就是我们只重写了数据，临时的目录还在，旧的文件并没有删除掉，什么时候才会去做这一步的清理呢？

其实有两种办法，第一种是在 DB 启动的时候，会加载 merge 相关的文件，然后去做旧文件删除和替换。

另一种是，如果 merge 结束之后，想要立即清理旧的文件，那么可以在 Merge 方法中传入参数 reopenAfterDone 为 true，这样就会 merge 之后立即清理文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


func (db *DB) Merge(reopenAfterDone bool) error {
    if err := db.doMerge(); err != nil {
        return err
    }
    if !reopenAfterDone {
        return nil
    }

    db.mu.Lock()
    defer db.mu.Unlock()

    // close current files 
    _ = db.closeFiles()

    // replace original file 
    err := loadMergeFiles(db.options.DirPath)
    if err != nil {
        return err
    }

    // open data files 
    if db.dataFiles, err = db.openWalFiles(); err != nil {
        return err
    }

    // discard the old index first. 
    db.index = index.NewIndexer()
    // rebuild index 
    if err = db.loadIndex(); err != nil {
        return err
    }

    return nil
}

只不过立即清理的话会带来一个副作用，那就是立即清理文件的话，会扫描新的文件去重建索引，如果是数据量较大的情况，可能会消耗较长的时间。

Go 实战项目 rosedb 源码剖析 5—内存索引

Tue, 18 Feb 2025 08:41:59 +0000

在 bitcask 论文当中，索引使用了一个哈希表来存储，这样做的好处是插入、查找、删除操作的时间复杂度都是接近于 O(1) 的，点查的速度很快。

但是具体实现的时候，内存索引的选择可以是多样化的，任意能够存储 key/value 对，并且可以根据 key 取出 value 的内存数据结构都是可以的，例如 BTree、自适应基数树（ART）、红黑树、哈希表等等。所以在实现的过程当中，可以根据不同的需要去进行选择。

例如如果想要性能更好，并且对 key 顺序扫描没有要求，那么可以使用哈希表；如果想要 key 有序进行扫描，可以使用一些天然支持排序的数据结构，比如 BTree；如果想要更加的节省内存空间，那么可以使用自适应基数树。

在 rosedb 当中，最开始的 V1 版本中使用了自适应基数树（ART）作为内存索引，目前在 V2 的版本中，使用 BTree 作为内存索引。

Google 开源的 Go 语言实现的 BTree(https://github.com/google/btree)是一个使用广泛、性能优异、接口功能丰富的库，并且能够天然的支持 key 有序排列，对顺序扫描，以及范围扫描都能够很好的支持。

并且 BTree 的插入、删除、查询操作的时间复杂度接近 O(logN)，速度也非常的快。

rosedb 当中的索引接口是一个 interface，这样方便在代码实现层面去接人不同的索引数据结构，索引接口的定义如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// Indexer is an interface for indexing key and position. 
// It is used to store the key and the position of the data in the WAL. 
// The index will be rebuilt when the database is opened. 
// You can implement your own indexer by implementing this interface. 
type Indexer interface {
    // Put key and position into the index. 
    Put(key []byte, position *wal.ChunkPosition) *wal.ChunkPosition

    // Get the position of the key in the index. 
    Get(key []byte) *wal.ChunkPosition

    // Delete the index of the key. 
    Delete(key []byte) (*wal.ChunkPosition, bool)

    // Size represents the number of keys in the index. 
    Size() int
}

当然除了基础的增删改查的方法之外还有一些数据遍历的方法。

开发者可以在这个基础之上去做其他的延伸，比如去实现其他的数据结构，只需要实现这个 interface 即可，其他的上下层代码都不需要进行修改。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Change the index type as you implement. 
var indexType = BTree

func NewIndexer() Indexer {
    switch indexType {
    case BTree:
        return newBTree()
    default:
        panic("unexpected index type")
    }
}

目前在 rosedb 当中只实现了 Google 的 BTree，对 btree 做了一个简单的封装，使用了 Mutex 做为读写互斥锁。

1
2
3
4
5
6


// MemoryBTree is a memory based btree implementation of the Index interface 
// It is a wrapper around the google/btree package: github.com/google/btree 
type MemoryBTree struct {
    tree *btree.BTree
    lock *sync.RWMutex
}

一些简单的 Put、Get、Delete 的方法都调用了btree 的方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


func (mt *MemoryBTree) Put(key []byte, position *wal.ChunkPosition) *wal.ChunkPosition {
    mt.lock.Lock()
    defer mt.lock.Unlock()

    oldValue := mt.tree.ReplaceOrInsert(&item{key: key, pos: position})
    if oldValue != nil {
        return oldValue.(*item).pos
    }
    return nil
}

func (mt *MemoryBTree) Get(key []byte) *wal.ChunkPosition {
    mt.lock.RLock()
    defer mt.lock.RUnlock()
    value := mt.tree.Get(&item{key: key})
    if value != nil {
        return value.(*item).pos
    }
    return nil
}

func (mt *MemoryBTree) Delete(key []byte) (*wal.ChunkPosition, bool) {
    mt.lock.Lock()
    defer mt.lock.Unlock()

    value := mt.tree.Delete(&item{key: key})
    if value != nil {
        return value.(*item).pos, true
    }
    return nil, false
}

rosedb 的索引是可以自定义实现的，开发者如果感兴趣的话，可以去按照各自的需求进行实现，这里推荐一些开源的库，可以作为一些不错的候选，感兴趣的同学可以自己去实现。

https://github.com/armon/go-radix：基数树实现
https://github.com/plar/go-adaptive-radix-tree：自适应基数树实现
https://github.com/emirpasic/gods：包含红黑树、AVL 树等数据结构的实现
https://github.com/derekparker/trie：Go 语言的字典树实现

广告区：

《从零实现 KV 存储》，使用 Rust 和 Go 两种语言实现，手把手教学，只需要基础的语法知识，即可学会一个硬核实战项目！

《从零实现 SQL 数据库》，使用 Rust 手写一个数据库系统，超级硬核，Rust 实战项目首选！

课程详情：https://roseduan.cn/course/

Go 实战项目 rosedb 源码剖析 4—数据写入、删除、读取

Mon, 17 Feb 2025 08:35:56 +0000

前面讲完了 wal 的核心设计原理和代码实现，这个组件是 rosedb 的重要组成部分，所以在学习或者使用 rosedb 的时候，对这个组件都需要能够融会贯通。

在 wal 组件之上，我们就可以向 wal 写入数据或者读取数据，这一节就来看看 rosedb 在写入、删除和读取数据时的核心流程以及代码实现。

Batch 概述

需要说明的是 rosedb 在写入数据的时候，实际是建立在 Batch 接口之上，Batch 可以理解是一个批量写入接口，所以我们可以先来看一下 Batch 接口的实现。

Batch 其实有点类似于事务，但是并没有提供事务的隔离性，只不过 Batch 中写入的数据能够保证原子性，也就是说一个 Batch 的数据要么全部写入成功，要么全部失败回滚，不会停留在某个中间状态。

写入数据的时候，可能前后会有多个 Batch，每个 Batch 的数据怎么各自区分呢？

我们使用了一个 batchId 进行区分，batchId 是全局唯一的，每个批量的数据在写入的时候都会有一个对应的 batchId（可以认为 batchId 类似事务版本号）。

例如我们写入了两个 Batch 的数据，batchId 分别是 101 和 102，那么写入到 wal 文件中的数据就会按照同样的顺序来进行组织。

例如这里 batch 101 写入了三条数据，分别是 key1、key2、key3，batch 102 写入了两条数据，分别是 key4 和 key5。

注意这里我们在每个 batch 的最后还多写了一条特殊的数据，用于表示 batch 的结束。

这样做的目的是为了保证 batch 数据的原子性，例如我们向 batch 中写入了 10 条数据，但是在向磁盘写到第 5 条的数据出现了异常，那么我们在重启的时候，并没有一种方式能够知道哪些数据是成功写入的。

所以在 batch 的末尾加上一条特殊数据，数据库启动建立索引的时候，需要对这些数据进行遍历，只有读取到这一条标识 Batch 完成的特殊数据的时候，才认为整个 batch 是有效的，否则认为这个 Batch 的数据是无效的，则直接全部丢弃。

初始化 Batch

初始化 Batch 可以传递参数配置，目前有两个配置：

1
2
3
4
5
6
7


// BatchOptions specifies the options for creating a batch. 
type BatchOptions struct {
    // Sync has the same semantics as Options.Sync. 
    Sync bool
    // ReadOnly specifies whether the batch is read only. 
    ReadOnly bool
}

ReadOnly 表示 Batch 是否是只读的，如果是的话，则 Batch 中只能进行类似 Get 的读取数据的操作，Put、Delete 这种增删数据操作是不允许的。

Sync 表示是否每次操作都将操作系统缓冲区的内容刷到磁盘。

1
2
3
4
5
6
7
8
9


// Sync is whether to synchronize writes through os buffer cache and down onto the actual disk. 
// Setting sync is required for durability of a single write operation, but also results in slower writes. 
//
// If false, and the machine crashes, then some recent writes may be lost. 
// Note that if it is just the process that crashes (machine does not) then no writes will be lost. 
//
// In other words, Sync being false has the same semantics as a write 
// system call. Sync being true means write followed by fsync. 
Sync bool

然后会初始化 batchId 的生成器，这里使用到了一个第三方库 snowflake https://github.com/bwmarrin/snowflake

，实际上实现了 Twitter 的雪花算法，能够生成唯一的 ID 标识。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// NewBatch creates a new Batch instance. 
func (db *DB) NewBatch(options BatchOptions) *Batch {
    batch := &Batch{
        db:         db,
        options:    options,
        committed:  false,
        rollbacked: false,
    }
    if !options.ReadOnly {
        node, err := snowflake.NewNode(1)
        if err != nil {
            panic(fmt.Sprintf("snowflake.NewNode(1) failed: %v", err))
        }
        batch.batchId = node
    }
    batch.lock()
    return batch
}

Batch 写入

初始化一个 Batch 之后，就可以调用其中的方法对数据进行读写了。

顾名思义 Batch 数据写入的时候，可以写入多条数据（批量），因此每次 Put 数据的时候，实际上只是将其存放到一个临时的数组当中，这里叫做 pendingWrites。

1
2
3
4
5
6
7
8


    // write to pendingWrites 
    var record = b.lookupPendingWrites(key)
    if record == nil {
        // if the key does not exist in pendingWrites, write a new record 
        // the record will be put back to the pool when the batch is committed or rollbacked 
        record = b.db.recordPool.Get().(*LogRecord)
        b.appendPendingWrites(key, record)
    }

这里首先会根据 key 从数组中查找，如果已经包含了同名的 key 数据，则直接覆盖原来的值即可。例如在一个 Batch 中，先写入了 k1 = v1，然后又写入了 k1 = v2，那么我们只需要保留数据的最新值 v2 即可，不用重复写入两条数据。

如果不存在的话则会 append 一条新的数据到数组中。

这里写入的数据用结构体 LogRecord 表示，分别包含数据的 key、value、type 类型、batchId、expire 过期时间。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// LogRecord is the log record of the key/value pair. 
// It contains the key, the value, the record type and the batch id 
// It will be encoded to byte slice and written to the wal. 
type LogRecord struct {
    Key     []byte
    Value   []byte
    Type    LogRecordType
    BatchId uint64
    Expire  int64
}

这里的类型主要分为了三种，分别是：

LogRecordNormal：表示 Put 的数据
LogRecordDeleted：表示被 Delete 的数据（类似论文中提到的墓碑值）
LogRecordBatchFinished：表示 batch 结束的特殊数据

1
2
3
4
5
6
7
8


const (
    // LogRecordNormal is the normal log record type. 
    LogRecordNormal LogRecordType = iota
    // LogRecordDeleted is the deleted log record type. 
    LogRecordDeleted
    // LogRecordBatchFinished is the batch finished log record type. 
    LogRecordBatchFinished
)

Batch 删除

删除数据的逻辑和 Put 基本类似，因为我们知道 bitcask 模型的文件是 append-only 的，也就是说不能去更新文件中的数据，而是只能追加写入。所以删除实际上就是写入一条新的数据，并且标识类型是 LogRecordDeleted。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


    var exist bool
    var record = b.lookupPendingWrites(key)
    if record != nil {
        record.Type = LogRecordDeleted
        record.Value = nil
        record.Expire = 0
        exist = true
    }
    if !exist {
        record = &LogRecord{
            Key:  key,
            Type: LogRecordDeleted,
        }
        b.appendPendingWrites(key, record)
    }

Batch 读取

再来看一下读取数据。

在 Batch 中读取数据，首先会读取临时数组 pendingWrites 中的内容。比如我们在一个 Batch 中新写入了 k1 = 100，但是并没有提交，也就是说还没有写入到 wal 文件当中，但是在当前 Batch 中来读取这条数据，也依然能够读取得到。

如果没有获取到的话，则会根据 key 从索引中进行读取，索引中存放到的是数据在 wal 文件中的位置，也就是上一节内容中提到的 wal 组件里的 ChunkPosition。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ChunkPosition represents the position of a chunk in a segment file. 
// Used to read the data from the segment file. 
type ChunkPosition struct {
    SegmentId SegmentID
    // BlockNumber The block number of the chunk in the segment file. 
    BlockNumber uint32
    // ChunkOffset The start offset of the chunk in the segment file. 
    ChunkOffset int64
    // ChunkSize How many bytes the chunk data takes up in the segment file. 
    ChunkSize uint32
}

拿到索引之后便能够从 wal 中读取数据了：

1
2
3
4
5
6
7
8
9


    // get key/value from data file 
    chunkPosition := b.db.index.Get(key)
    if chunkPosition == nil {
        return nil, ErrKeyNotFound
    }
    chunk, err := b.db.dataFiles.Read(chunkPosition)
    if err != nil {
        return nil, err
    }

Batch 提交

Batch 提交数据，实际上就是将临时数组中的内容写入到 wal 文件中，然后更新内存索引，主要逻辑在方法 Commit 中。

首先会遍历 pendingWrites 数组中的内容，填充 BatchId，然后进行编码，调用 wal 的方法 PendingWrites 写入。

不要忘记最后我们写入了一条特殊的数据用于表示 Batch 的结束，这个 LogRecord 的类型是 LogRecordBatchFinished。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


    batchId := b.batchId.Generate()
    now := time.Now().UnixNano()
    // write to wal buffer 
    for _, record := range b.pendingWrites {
        buf := bytebufferpool.Get()
        b.buffers = append(b.buffers, buf)
        record.BatchId = uint64(batchId)
        encRecord := encodeLogRecord(record, b.db.encodeHeader, buf)
        b.db.dataFiles.PendingWrites(encRecord)
    }

    // write a record to indicate the end of the batch 
    buf := bytebufferpool.Get()
    b.buffers = append(b.buffers, buf)
    endRecord := encodeLogRecord(&LogRecord{
        Key:  batchId.Bytes(),
        Type: LogRecordBatchFinished,
    }, b.db.encodeHeader, buf)
    b.db.dataFiles.PendingWrites(endRecord)

    // write to wal file 
    chunkPositions, err := b.db.dataFiles.WriteAll()

在这段逻辑中我们需要注意几个点。

一是对数据进行编码，我们知道 pendingWrites 中缓存的数据实际上是 LogRecord 结构体，但是在写入数据到 wal 的时候，需要传递字节数组类型，所以这里需要对数据进行二进制编码。

大致的编码逻辑如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// +-------------+-------------+-------------+--------------+---------------+---------+--------------+ 
// |    type     |  batch id   |   key size  |   value size |     expire    |  key    |      value   | 
// +-------------+-------------+-------------+--------------+---------------+--------+--------------+ 
//
//  1 byte        varint(max 10) varint(max 5)  varint(max 5) varint(max 10)  varint      varint 
func encodeLogRecord(logRecord *LogRecord, header []byte, buf *bytebufferpool.ByteBuffer) []byte {
    header[0] = logRecord.Type
    var index = 1

    // batch id 
    index += binary.PutUvarint(header[index:], logRecord.BatchId)
    // key size 
    index += binary.PutVarint(header[index:], int64(len(logRecord.Key)))
    // value size 
    index += binary.PutVarint(header[index:], int64(len(logRecord.Value)))
    // expire 
    index += binary.PutVarint(header[index:], logRecord.Expire)

    // copy header 
    _, _ = buf.Write(header[:index])
    // copy key 
    _, _ = buf.Write(logRecord.Key)
    // copy value 
    _, _ = buf.Write(logRecord.Value)

    return buf.Bytes()
}

主要是借助了 Go 自带的 binary 包进行编码，编码后的数据分为了几个部分，分别是

type：类型，占 1 字节
Batch Id：uint64 类型，在编码的时候为了节省空间使用变长类型（如果使用固定的 8 字节当然也可以表示，但是假如 BatchID 是 1，那么实际上只需要 1 个字节就能表示，使用 8 字节就是空间浪费，在 Go 语言中为了这种特殊的变长编码，会存储一些额外的辅助信息，所以最大的 uint64 变长编码占据的长度是 10 字节）
key size：key 的长度，uint32 类型，也是变长编码
value size：value 的长度，uint32 类型，变长编码
expire：过期时间，int64 类型，变长编码
key：实际用户存储的 key 数据
value：实际用户存储的 value 数据

第二个注意的点是，我们这里使用了 wal 的批量写入接口，这样只需要执行一次写入操作就能够将数据全部写入（通过方法 WriteAll）。

通过 wal 写入之后，就拿到了索引数据，就是 chunkPositions 中的内容。

1
2
3
4
5
6


    // write to wal file 
    chunkPositions, err := b.db.dataFiles.WriteAll()
    if err != nil {
        b.db.dataFiles.ClearPendingWrites()
        return err
    }

然后就需要更新索引，rosedb 中的索引使用的是 Google 开源的 BTree，https://github.com/google/btree 。

1
2
3
4
5
6
7


    // write to index 
    for i, record := range b.pendingWrites {
        if record.Type == LogRecordDeleted || record.IsExpired(now) {
            b.db.index.Delete(record.Key)
        } else {
            b.db.index.Put(record.Key, chunkPositions[i])
        }

更新索引实际上就是根据 LogRecord 的操作类型，如果是普通类型则使用 Put 方法插入（或更新）key 对应的索引，如果是删除操作则调用索引的 Delete 方法删除 key 对应的数据。

Batch 回滚

当在 Batch 中写入一些数据之后，可以选择不提交，而是直接丢弃，那么所有的数据都不会写入到 wal 文件中。

这是通过回滚方法实现的，大致逻辑在 Rollback 方法中，主要就是清理掉临时数组 pendingWrites 中的内容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


    if !b.options.ReadOnly {
        // clear pendingWrites 
        for _, record := range b.pendingWrites {
            b.db.recordPool.Put(record)
        }
        b.pendingWrites = b.pendingWrites[:0]
        for key := range b.pendingWritesMap {
            delete(b.pendingWritesMap, key)
        }
    }

DB 数据操作接口

如果在操作数据的时候，并不想使用 Batch 接口，其实也可以直接调用 DB 实例的方法，这些方法名和 Batch 中的一样，只是对 Batch 做了一个简单的封装，以 Put 为例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// Put a key-value pair into the database. 
// Actually, it will open a new batch and commit it. 
// You can think the batch has only one Put operation. 
func (db *DB) Put(key []byte, value []byte) error {
    batch := db.batchPool.Get().(*Batch)
    deferfunc() {
        batch.reset()
        db.batchPool.Put(batch)
    }()
    // This is a single put operation, we can set Sync to false. 
    // Because the data will be written to the WAL, 
    // and the WAL file will be synced to disk according to the DB options. 
    batch.init(false, false, db)
    if err := batch.Put(key, value); err != nil {
        _ = batch.Rollback()
        return err
    }
    return batch.Commit()
}

实际上相当于是打开一个 Batch 然后只写入了一条数据。

这里做了一个简单的优化，那就是 Batch 结构体实际上可以进行复用，因为打开 Batch 还需要初始化一些结构体，如果频繁调用的情况下，可能会导致内存分配频繁，我们可以借助池化的概念将 Batch 进行缓存，这样每次都能够从 Batch Pool 中获取。

只不过需要注意的是每次 Batch 使用完之后，都需要进行 reset，也就是将一些临时数据进行清理，这样不会对下次使用造成影响。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func (b *Batch) reset() {
    b.db = nil
    b.pendingWrites = b.pendingWrites[:0]
    b.pendingWritesMap = nil
    b.committed = false
    b.rollbacked = false
    // put all buffers back to the pool 
    for _, buf := range b.buffers {
        bytebufferpool.Put(buf)
    }
    b.buffers = b.buffers[:0]
}

广告区：

《从零实现 KV 存储》，使用 Rust 和 Go 两种语言实现，手把手教学，只需要基础的语法知识，即可学会一个硬核实战项目！

《从零实现 SQL 数据库》，使用 Rust 手写一个数据库系统，超级硬核，Rust 实战项目首选！

课程详情：https://roseduan.cn/course/

Go 实战项目 rosedb 源码剖析 3—wal 代码解读

Wed, 12 Feb 2025 08:41:43 +0000

前面一节主要是在理论和设计层面讲解了预写日志 wal 组件，但是在代码实现当中，其实还蕴含着更多的细节。

rosedb 中的 wal 预写日志，既像传统关系型数据库一样保证了数据崩溃恢复和数据完整性，而且较为特殊的一点是，wal 预写日志本身又是实际存储数据的文件，这也是 bitcask 模型最大的特点。

wal 组件代码是开源的：https://github.com/rosedblabs/wal

wal 定义

wal 实际上是由多个文件组成的，每个文件叫做一个 Segment，下面是对 wal 结构体的定义：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type WAL struct {
    activeSegment     *segment               // active segment file, used for new incoming writes. 
    olderSegments     map[SegmentID]*segment // older segment files, only used for read. 
    options           Options
    mu                sync.RWMutex
    bytesWrite        uint32
    renameIds         []SegmentID
    pendingWrites     [][]byte
    pendingSize       int64
    pendingWritesLock sync.Mutex
}

其中最主要的是 activeSegment，表示当前活跃的 Segment 文件，用于新的写入（也可以读取）；以及 olderSegments 表示旧的 Segment，这些文件都是被写满了的，不能写入，只能用于读取数据。

注意 olderSegments 是一个 map 结构，key 是文件对应的唯一标识，文件在命名的时候是连续递增的，如下图：

因此 Segment 文件的 id 就是文件名中的数字。

针对每个 Segment 文件，定义了一个 segment 结构体表示，主要包含 SegmentID、实际的文件描述符，以及当前的 block 信息，block 号和 block 大小。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type segment struct {
    id                 SegmentID
    fd                 *os.File
    currentBlockNumber uint32
    currentBlockSize   uint32
    closed             bool
    header             []byte
    startupBlock       *startupBlock
    isStartupTraversal bool
}

打开 wal

打开 wal 其实主要是打开对应目录中的所有 Segment 文件，这里会读取对应的目录，找到所有符合 Segment 文件后缀的文件，解析得到 SegmentID。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


entries, err := os.ReadDir(options.DirPath)
if err != nil {
    return nil, err
}

// get all segment file ids. 
var segmentIDs []int
for _, entry := range entries {
    if entry.IsDir() {
       continue
    }
    var id int
    _, err := fmt.Sscanf(entry.Name(), "%d"+options.SegmentFileExt, &id)
    if err != nil {
       continue
    }
    segmentIDs = append(segmentIDs, id)
}

如果这个目录是空的，也就是说没有获取到任何的 Segment 文件信息，那么只需要在这里初始化一个空的 Segment 文件即可，这个文件是目前的唯一一个 Segment，自然也就是当前活跃的 Segment 了。

否则，则说明存在 Segment 文件，需要将其按照 SegmentID 排序，id 最大的那个文件便是当前活跃文件，其他的文件就是 olderSegments。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// empty directory, just initialize a new segment file. 
iflen(segmentIDs) == 0 {
    segment, err := openSegmentFile(options.DirPath, options.SegmentFileExt,
       initialSegmentFileID)
    if err != nil {
       return nil, err
    }
    wal.activeSegment = segment
} else {
    // open the segment files in order, get the max one as the active segment file. 
    sort.Ints(segmentIDs)

    for i, segId := range segmentIDs {
       segment, err := openSegmentFile(options.DirPath, options.SegmentFileExt,
          uint32(segId))
       if err != nil {
          return nil, err
       }
       if i == len(segmentIDs)-1 {
          wal.activeSegment = segment
       } else {
          wal.olderSegments[segment.id] = segment
       }
    }
}

打开一个 Segment 文件的主要逻辑在方法 openSegmentFile 中，这里主要是调用系统函数，打开文件并得到一个文件句柄。

然后获取文件的大小，并且计算填充 currentBlockNumber 和 currentBlockSize，例如如果当前文件的大小是 100KB，那么当前的 block 号就是 100 ``/ 32 = 3，block 号是从 0 开始的；当前的 block size 就是 100 % 32 = 4，这两个属性主要是用在写入数据时候的开始位置。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


// openSegmentFile a new segment file. 
func openSegmentFile(dirPath, extName string, id uint32) (*segment, error) {
    fd, err := os.OpenFile(
       SegmentFileName(dirPath, extName, id),
       os.O_CREATE|os.O_RDWR|os.O_APPEND,
       fileModePerm,
    )

    if err != nil {
       return nil, err
    }

    // set the current block number and block size. 
    offset, err := fd.Seek(0, io.SeekEnd)
    if err != nil {
       return nil, fmt.Errorf("seek to the end of segment file %d%s failed: %v", id, extName, err)
    }

    return &segment{
       id:                 id,
       fd:                 fd,
       header:             make([]byte, chunkHeaderSize),
       currentBlockNumber: uint32(offset / blockSize),
       currentBlockSize:   uint32(offset % blockSize),
       startupBlock: &startupBlock{
          block:       make([]byte, blockSize),
          blockNumber: -1,
       },
       isStartupTraversal: false,
    }, nil
}

wal 写入

接下来看看如何向 wal 写入一条新的数据，写入一条数据的逻辑在方法 Write 中。

首先会判断当前文件是否已经到了写入的阈值，如果已经到了，需要打开一个新的活跃文件用于写入。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func (wal *WAL) Write(data []byte) (*ChunkPosition, error) {
    wal.mu.Lock()
    defer wal.mu.Unlock()
    if int64(len(data))+chunkHeaderSize > wal.options.SegmentSize {
       return nil, ErrValueTooLarge
    }
    // if the active segment file is full, sync it and create a new one. 
    if wal.isFull(int64(len(data))) {
       if err := wal.rotateActiveSegment(); err != nil {
          return nil, err
       }
    }

方法 rotateActiveSegment 中会打开新的活跃文件，这里会将 Segment ID 递增，然后将之前的活跃文件放到 olderSegments 中，注意这里还调用了 Sync 方法将缓冲区的内容进行持久化，保证数据安全存储到磁盘中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// rotateActiveSegment create a new segment file and replace the activeSegment. 
func (wal *WAL) rotateActiveSegment() error {
    if err := wal.activeSegment.Sync(); err != nil {
       return err
    }
    wal.bytesWrite = 0
    segment, err := openSegmentFile(wal.options.DirPath, wal.options.SegmentFileExt,
       wal.activeSegment.id+1)
    if err != nil {
       return err
    }
    wal.olderSegments[wal.activeSegment.id] = wal.activeSegment
    wal.activeSegment = segment
    return nil
}

这些前置操作完成之后，才会真正向当前活跃 Segment 文件中写入数据，这里调用的是 Segment 的 Write 方法。

1
2
3
4
5


// write the data to the active segment file. 
position, err := wal.activeSegment.Write(data)
if err != nil {
    return nil, err
}

再进入到 Segment 结构体的 Write 方法中，大致的写入流程分为了两步，一是写入到 buffer 当中，组织当前 chunk 的数据格式，填充 header 部分的内容，然后再调用文件的 write 方法写入数据。

1
2
3
4
5
6
7
8
9


// write all data to the chunk buffer 
pos, err = seg.writeToBuffer(data, chunkBuffer)
if err != nil {
    return
}
// write the chunk buffer to the segment file 
if err = seg.writeChunkBuffer(chunkBuffer); err != nil {
    return
}

再展开说明这里为什么会使用到一个 byte buffer 呢，因为用户写入的 data 数据是一个字节数组，但是我们实际写入到磁盘的数据，需要加上 header 部分，如果 data 较大的话，还会将其拆分为多个 chunk 进行写入，每个 chunk 都会有对应的 header。

如果这里每次都重新去 make 一个新的字节数组的话，那么会造成内存的频繁分配和释放，但这完全是没有必要的，我们可以复用这些字节数组的内存空间，所以可以使用到 Go 语言中的 sync.Pool 进行资源的池化，具体是使用到了一个开源的第三方库 https://github.com/valyala/bytebufferpool。

回到我们的写入逻辑，实际上就是将数据按照固定的格式进行组织，并缓存到 byte buffer 中。

首先会判断如果当前 block 的容量已经很小了，小到不能够容纳一个 chunkHeader（7 字节），那么当前 block 就不能够使用了，直接对齐填充，然后开启一个新的 block。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// if the left block size can not hold the chunk header, padding the block 
if seg.currentBlockSize+chunkHeaderSize >= blockSize {
    // padding if necessary 
    if seg.currentBlockSize < blockSize {
       p := make([]byte, blockSize-seg.currentBlockSize)
       chunkBuffer.B = append(chunkBuffer.B, p...)
       padding += blockSize - seg.currentBlockSize

       // a new block 
       seg.currentBlockNumber += 1
       seg.currentBlockSize = 0
    }
}

然后到了一个关键的步骤，如果写入的 chunk 是能够完全容纳到当前 block 当中，那么 chunk 的类型就是 FULL，对其进行填充，然后存储到 byte buffer 中。

1
2
3
4


// The entire chunk can fit into the block. 
if seg.currentBlockSize+dataSize+chunkHeaderSize <= blockSize {
    seg.appendChunkBuffer(chunkBuffer, data, ChunkTypeFull)
    position.ChunkSize = dataSize + chunkHeaderSize

appendChunkBuffer 方法主要是填充 header 部分，分别是 CRC 校验和、数据长度、Chunk 类型，然后将 header 部分和数据部分都存储到 buffer 当中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


func (seg *segment) appendChunkBuffer(buf *bytebufferpool.ByteBuffer, data []byte, chunkType ChunkType) {
    // Length  2 Bytes    index:4-5 
    binary.LittleEndian.PutUint16(seg.header[4:6], uint16(len(data)))
    // Type    1 Byte index:6 
    seg.header[6] = chunkType
    // Checksum    4 Bytes index:0-3 
    sum := crc32.ChecksumIEEE(seg.header[4:])
    sum = crc32.Update(sum, crc32.IEEETable, data)
    binary.LittleEndian.PutUint32(seg.header[:4], sum)

    // append the header and data to segment chunk buffer 
    buf.B = append(buf.B, seg.header...)
    buf.B = append(buf.B, data...)
}

然后是写入的另一种情况，如果当前的 block 不能够容纳 Chunk，则需要对 Chunk 进行拆分，这里是在一个 for 循环当中处理的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


for leftSize > 0 {
    chunkSize := blockSize - currBlockSize - chunkHeaderSize
    if chunkSize > leftSize {
       chunkSize = leftSize
    }

    var end = dataSize - leftSize + chunkSize
    if end > dataSize {
       end = dataSize
    }

    // append the chunks to the buffer 
    var chunkType ChunkType
    switch leftSize {
    case dataSize: // First chunk 
       chunkType = ChunkTypeFirst
    case chunkSize: // Last chunk 
       chunkType = ChunkTypeLast
    default: // Middle chunk 
       chunkType = ChunkTypeMiddle
    }
    seg.appendChunkBuffer(chunkBuffer, data[dataSize-leftSize:end], chunkType)

    leftSize -= chunkSize
    blockCount += 1
    currBlockSize = (currBlockSize + chunkSize + chunkHeaderSize) % blockSize
}

chunkSize 表示当前写入的 Chunk 的大小，如果是第一个，则类型是 FIRST，如果是最后一个，则类型是 LAST，否则则是 MIDDLE 类型。

每次循环 leftSize 会逐渐递减，直到全部拆分完毕，则原插入的数据就分拆完成，并且完全按照 Chunk 缓存到了 buffer 中。

这里大家可以按照代码举一个具体的示例进行分析。

前面的解析、拆分、填充 header 完成后，需要写入的数据都已经按照固定的格式缓存到了 buffer 当中，这时候只需要调用文件的写入方法，写入这些数据就可以了。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// write the pending chunk buffer to the segment file 
func (seg *segment) writeChunkBuffer(buf *bytebufferpool.ByteBuffer) error {
    if seg.currentBlockSize > blockSize {
       return errors.New("the current block size exceeds the maximum block size")
    }

    // write the data into underlying file 
    if _, err := seg.fd.Write(buf.Bytes()); err != nil {
       return err
    }

    // the cached block can not be reused again after writes. 
    seg.startupBlock.blockNumber = -1
    return nil
}

wal 读取

再来看一下如何从 wal 中读取数据。

其实在写入的时候，我们的数据写入到了哪个位置，已经是明确的了，并且我们也将这个信息作为参数返回给了调用者，调用者可以将这个位置信息保存起来，或者进行其他处理都是可以的。

这个位置信息主要包含写入到了哪个 Segment 文件当中，以及写入到了哪个 block，并且 block 的偏移是多少，这些信息使用 ChunkPosition 结构体表示。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ChunkPosition represents the position of a chunk in a segment file. 
// Used to read the data from the segment file. 
type ChunkPosition struct {
    SegmentId SegmentID
    // BlockNumber The block number of the chunk in the segment file. 
    BlockNumber uint32
    // ChunkOffset The start offset of the chunk in the segment file. 
    ChunkOffset int64
    // ChunkSize How many bytes the chunk data takes up in the segment file. 
    ChunkSize uint32
}

因此我们从 wal 中读取数据的时候，需要将这个 ChunkPosition 作为参数传递进来，我们才能够知道应该读哪个文件，并且从文件的哪个位置开始读取。

下面是 Read 方法的入口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// Read reads the data from the WAL according to the given position. 
func (wal *WAL) Read(pos *ChunkPosition) ([]byte, error) {
    wal.mu.RLock()
    defer wal.mu.RUnlock()

    // find the segment file according to the position. 
    var segment *segment
    if pos.SegmentId == wal.activeSegment.id {
       segment = wal.activeSegment
    } else {
       segment = wal.olderSegments[pos.SegmentId]
    }

    if segment == nil {
       return nil, fmt.Errorf("segment file %d%s not found", pos.SegmentId, wal.options.SegmentFileExt)
    }

    // read the data from the segment file. 
    return segment.Read(pos.BlockNumber, pos.ChunkOffset)
}

首先会根据 Segment ID 查找对应的文件，如果没有找到的话则报错。

然后进入到 Segment 的 Read 方法中。

在 read 文件内容的时候，以 block 为单位进行读取，读取的起始位置就是 blockNumber * blockSize，然后数据的起始位置就是传递进来的参数 chunkOffset，这样就能够知道 Chunk 的 header 内容了，由于 header 占据的是固定的 7 字节，所以对其进行解析，得到数据长度以及 Chunk 类型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// header 
header := block[chunkOffset : chunkOffset+chunkHeaderSize]

// length 
length := binary.LittleEndian.Uint16(header[4:6])

// copy data 
start := chunkOffset + chunkHeaderSize
result = append(result, block[start:start+int64(length)]...)

// check sum 
checksumEnd := chunkOffset + chunkHeaderSize + int64(length)
checksum := crc32.ChecksumIEEE(block[chunkOffset+4 : checksumEnd])
savedSum := binary.LittleEndian.Uint32(header[:4])
if savedSum != checksum {
    return nil, nil, ErrInvalidCRC
}

// type 
chunkType := header[6]

如果 Chunk 的类型是 FULL 或者 LAST，则说明已经读取到了完整的数据，则跳出外层的循环。

否则，跳转到下一个 block 继续读取。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


if chunkType == ChunkTypeFull || chunkType == ChunkTypeLast {
    nextChunk.BlockNumber = blockNumber
    nextChunk.ChunkOffset = checksumEnd
    // If this is the last chunk in the block, and the left block 
    // space are paddings, the next chunk should be in the next block. 
    if checksumEnd+chunkHeaderSize >= blockSize {
       nextChunk.BlockNumber += 1
       nextChunk.ChunkOffset = 0
    }
    break
}
blockNumber += 1
chunkOffset = 0

wal 批量写入

前面介绍的写入数据的方法，只写入了一条数据，如果调用者有多条数据的话，希望能够在一个批次中一次性全部写入，那么可以采用 wal 的批量写入方法。

批量写入能够大幅度提升多条数据写入的性能，因为能够减少系统调用次数，将多次磁盘 IO 转化为一次。

具体的实现方法比较简单，首先会调用 PendingWrites 方法将需要写入的数据进行缓存，这里我们使用了一个数组对这些数据进行暂存。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// PendingWrites add data to wal.pendingWrites and wait for batch write. 
// If the data in pendingWrites exceeds the size of one segment, 
// it will return a 'ErrPendingSizeTooLarge' error and clear the pendingWrites. 
func (wal *WAL) PendingWrites(data []byte) {
    wal.pendingWritesLock.Lock()
    defer wal.pendingWritesLock.Unlock()

    size := wal.maxDataWriteSize(int64(len(data)))
    wal.pendingSize += size
    wal.pendingWrites = append(wal.pendingWrites, data)
}

多条数据暂存完成后，需要写入的数据都维护在变量 pendingWrites 中了，这时候可以调用 WriteAll 方法一次性将这些数据全部写入。

需要注意这里和之前一样，还是会判断如果文件已经到了阈值，那么会打开一个新的活跃文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// if the active segment file is full, sync it and create a new one. 
if wal.activeSegment.Size()+wal.pendingSize > wal.options.SegmentSize {
    if err := wal.rotateActiveSegment(); err != nil {
       return nil, err
    }
}

// write all data to the active segment file. 
positions, err := wal.activeSegment.writeAll(wal.pendingWrites)
if err != nil {
    return nil, err
}

然后进入到 Segment 的 writeAll 方法当中，执行实际的写入逻辑。

这里和之前的单条数据写入类似，会将所有的数据缓存到 buffer 当中，这个时候需要计算得到最终的返回值 ChunkPosition，因为写入的时候是一次性将所有的字节内容写到文件了，到这个时候并不能获取到每个 Chunk 的位置信息。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// write all data to the chunk buffer 
var pos *ChunkPosition
positions = make([]*ChunkPosition, len(data))
for i := 0; i < len(positions); i++ {
    pos, err = seg.writeToBuffer(data[i], chunkBuffer)
    if err != nil {
       return
    }
    positions[i] = pos
}

然后调用 writeChunkBuffer 方法写入到文件当中，这里和之前是一样的。

需要注意，如果批量写入失败的话，我们需要回滚状态，因为为了提前拿到 ChunkPosition 的信息，在缓存到 buffer 中的时候，就将 currentBlockNumber 和 currentBlockSize 进行了修改。如果写入失败的话，就将这些信息还原到之前的状态。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// if any error occurs, restore the segment status 
originBlockNumber := seg.currentBlockNumber
originBlockSize := seg.currentBlockSize

// init chunk buffer 
chunkBuffer := bytebufferpool.Get()
chunkBuffer.Reset()
defer func() {
    if err != nil {
       seg.currentBlockNumber = originBlockNumber
       seg.currentBlockSize = originBlockSize
    }
    bytebufferpool.Put(chunkBuffer)
}()

wal 全量读取

前面的读取方法，都是根据 ChunkPosition 获取一条数据，有时候需要遍历 wal 中所有的 Segment 文件，并且获取到所有的数据。例如在 rosedb 当中，会在启动的时候遍历所有的数据去构建索引。

因此我们需要一种方式来遍历读取 wal 所有的数据，实际上就是对每个 Segment 文件中的数据进行读取。

这里定义了一个 Reader 结构体，来记录遍历的状态。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// Reader represents a reader for the WAL. 
// It consists of segmentReaders, which is a slice of segmentReader 
// structures sorted by segment id, 
// and currentReader, which is the index of the current segmentReader in the slice. 
//
// The currentReader field is used to iterate over the segmentReaders slice. 
type Reader struct {
    segmentReaders []*segmentReader
    currentReader  int
}

结构体 segmentReader 主要记录了一个 Segment 在遍历时的状态：

1
2
3
4
5
6
7
8


// segmentReader is used to iterate all the data from the segment file. 
// You can call Next to get the next chunk data, 
// and io.EOF will be returned when there is no data. 
type segmentReader struct {
    segment     *segment
    blockNumber uint32
    chunkOffset int64
}

首先会通过 NewReader 方法获取到一个 Reader 结构，这个方法其实就是将所有的 Segment 文件按照从小到大排序，并且放到 segmentReaders 数组当中。

1
2
3
4
5
6
7
8


// get all segment readers. 
var segmentReaders []*segmentReader
for _, segment := range wal.olderSegments {
    if segId == 0 || segment.id <= segId {
       reader := segment.NewReader()
       segmentReaders = append(segmentReaders, reader)
    }
}

拿到 Reader 之后，可以调用 Next 方法一直获取下一条数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func (r *Reader) Next() ([]byte, *ChunkPosition, error) {
    if r.currentReader >= len(r.segmentReaders) {
       return nil, nil, io.EOF
    }

    data, position, err := r.segmentReaders[r.currentReader].Next()
    if err == io.EOF {
       r.currentReader++
       return r.Next()
    }
    return data, position, err
}

注意到这里是一个递归，因为当前 Segment 文件如果遍历完的话，就会开始遍历下一个文件，每个文件的读取方法都是一样的。

然后是 segmentReader 的 Next 方法，这里就是在单个 Segment 文件中获取一条实际的数据。

1
2
3
4
5
6
7


value, nextChunk, err := segReader.segment.readInternal(
    segReader.blockNumber,
    segReader.chunkOffset,
)
if err != nil {
    return nil, nil, err
}

读取数据调用的方法和前面单条数据的读取逻辑是一样的，这里需要返回 nextChunk 的信息，表示下一条数据的起始位置。这样就可以循环调用 Next 方法从文件中获取数据，直到遍历完成。

广告区：

《从零实现 KV 存储》，使用 Rust 和 Go 两种语言实现，手把手教学，只需要基础的语法知识，即可学会一个硬核实战项目！

《从零实现 SQL 数据库》，使用 Rust 手写一个数据库系统，超级硬核，Rust 实战项目首选！

课程详情：https://roseduan.cn/course/

Go 实战项目 rosedb 源码剖析 2—预写日志原理

Mon, 10 Feb 2025 08:49:40 +0000

预写日志，即 Write Ahead Log（wal），是一种数据库系统中常见的用于崩溃恢复的技术保障。例如在 Postgres 中，也有对应的 wal 实现，主要是为了防止系统崩溃时数据丢失，因为在 Postgres 中，为了写入效率，数据一般会先写入到内存中的 shared buffer 中。

如果 buffer 中的数据还没有来得及刷到磁盘，此时发生了系统崩溃等其他严重错误，那么会导致数据丢失。所以常见的解决方式是在写入到 buffer 之前，会先将数据写入到 wal 中，这样就能够保证数据的可靠性。

并且在数据库系统中，wal 也被用作事务完整性的技术保证，确保事务的原子性（A），以及持久性（D），只有事务的修改完全写入到 wal 文件中才能够被正确的提交，如果事务中发生了一些错误，那么在重启的时候，会通过重放日志的方式来让数据库达到一致的状态。

有一篇论文专门讲述了 wal 在数据库系统中对事务的保障，感兴趣可以参考：https://cs.stanford.edu/people/chrismre/cs345/rl/aries.pdf

wal 文件是采用 append only 的方式进行写入，也就是说这个文件的写入永远只能追加写入，而不会去修改其中的某一部分数据。这样做的目的的是利用顺序 IO 的性能优势，特别是在传统的 HDD 磁盘上，顺序 IO 和随机 IO 存在较大的性能差异。

具体到 rosedb 中的 WAL 预写日志，其实设计上也比较的简单。

rosedb 中的 wal 作为一个单独的组件，独立于 rosedb 之外，并且也是开源的

https://github.com/rosedblabs/wal

rosedb 的 wal 设计和实现基本参考了 RocksDB 中预写日志的实现，文件组织格式基本一致。

可以参考 RocksDB 的对应文档：https://github.com/facebook/rocksdb/wiki/Write-Ahead-Log-File-Format

在 wal 当中将每个文件叫做一个 Segment，一个 Segment 文件一般会有一个阈值，比如 512MB、1G、2G 等等，可以在打开时根据 Option 参数进行配置。

写到了阈值之后，就会关闭旧的文件然后打开一个新的文件，文件名也一般是递增的，大致如下：

每一个 Segment 文件的内部，实际上是切分成了 N 个 32 KB 的连续 Block。

这时候大家可能会有一个疑问，为什么需要将文件切分成 32 KB 的 block 呢？

一个最主要的原因是提升文件读写的效率，例如在读数据的时候，如果不分 block，那么写入了 10 条数据，在读取的时候，需要通过十次系统调用 read 才能够将数据读取出来。我们知道系统调用需要从用户态切换到内核态，这存在一定的性能开销。

如果是分 block 的方式，一次性将 32 KB 的数据全部读取出来，效率会得到大幅提升。这里对 block 取值是 32KB 其实也是参考了 RocksDB 的做法，其实 16KB 或者是 64KB 理论上也是可以的。

向 wal 文件中写入的一条日志数据，一般叫做 Chunk，chunk 数据是有固定格式的：

前 7 个字节是固定的 header 部分，主要是

CRC 校验和，占 4 字节
实际存储的数据长度，占 2 字节
Chunk 类型，分为了 FULL、FIRST、MIDDLE、LAST，占 1 字节

最后的 payload 部分就是实际存储的数据，当然这是变长的，实际的长度记录在前面固定的 header 当中。

在写入 Chunk 的时候，根据当前 block 的容量和 chunk 的大小，分为了两种情况：

Chunk 能够完全容纳到当前 block 中，那么这个 Chunk 类型是 FULL
Chunk 不能够完全容纳到 block 中，则需要将 Chunk 进行切分，第一部分是 FIRST，中间的部分是 MIDDLE、最后的一部分是 LAST

下面举几个具体的例子：

假如当前 block 还剩余 10 KB 的空间，当前 chunk 的大小是 1 KB，那么能够完全容纳到这个 block 中，那么写入的时候会标识这个 chunk 的类型是 FULL。

如果 chunk 的大小是 15 KB，那么需要将 10KB 存储到当前 block，标识其类型是 FIRST，剩余的 5 KB 存储到下一个 block 中，类型是 LAST。

当然还有一种情况是，chunk 更大，例如是 128 KB，那么 10 KB 会存储到当前 block 中，类型是 FIRST，剩余的 118 KB仍然无法存储到一个 block 中，所以需要继续切分，将其切分为 4 个 chunk，前 3 个 chunk 占据一个完整的 block 大小，3 * 32 = 96 KB，这三个 chunk 的类型就是 MIDDLE。

最后还剩 118 - 96 = 22 KB，再将其存储到一个 block 中，这是完整数据的最后一部分，所以类型是 LAST。

在读取的时候，如果 chunk 的类型是 FULL，则说明是一条完整的数据。

如果 chunk 的类型是 FIRST，那么需要继续读取下一个 chunk，直到读到类型为 LAST 的 chunk，将这一部分数据组合起来，才是最终完整的数据。

能够搞懂这几个示例，其实理解 wal 就非常的容易了，wal 的设计是 rosedb 最核心的一个部分，是学习和理解 rosedb 最重要的前置内容，下一节将详细讲解 wal 的代码，帮助理解这个组件在代码实现上的细节。

广告区：

《从零实现 KV 存储》，使用 Rust 和 Go 两种语言实现，手把手教学，只需要基础的语法知识，即可学会一个硬核实战项目！

《从零实现 SQL 数据库》，使用 Rust 手写一个数据库系统，超级硬核，Rust 实战项目首选！

课程详情：https://roseduan.cn/course/

Go 实战项目 rosedb 源码剖析 1—架构原理

Sat, 08 Feb 2025 09:23:17 +0000

rosedb 是一个轻量级、快速、稳定可靠的单机磁盘 KV 存储引擎，基于一种日志追加型的文件组织方式。

https://github.com/rosedblabs/rosedb

它足够的简单，每个人都能够轻松理解其运行的原理，它也足够的小巧精悍，能够满足基本的数据存储需求。

无论你是数据库的爱好者、开发者，甚至是基础架构相关的开发，都能够从这个项目中学习到数据库这类系统级项目的基本设计原理和实现细节。

rosedb 基于 bitcask 存储模型，这是由一家数据库商业化公司 Riak 在 2010 年提出来的，相关文章介绍如下：

https://riak.com/assets/bitcask-intro.pdf

Riak 主要是想打造一个全新的存储引擎，在最理想的情况下，满足下面的这些条件：

读写低延迟
高吞吐，特别是对大量的随机写入
能够处理超过内存容量的数据
崩溃恢复友好，能够保证快速恢复，不丢数据
简单的备份和恢复策略
相对简单、易懂的代码结构和数据存储格式
在大数据量下，性能有保障
能够有自由的授权使用在 Riak 的系统中

在当时已有的存储引擎中，没有一个能够很好的满足这些条件（LevelDB 和 RocksDB 虽然成熟强大，但是过于复杂），于是 Riak 团队重新设计了一个简单、高效的存储引擎 bitcask。

一个 bitcask 实例就是系统上的一个目录，并且限制同一时刻只能有一个进程打开这个目录。目录中有多个文件，同一时刻只有一个活跃的文件用于写入。

当活跃文件写到满足一个阈值之后，就会被关闭，成为旧的数据文件，并且打开一个新的文件用于写入。

所以这个目录中就是一个活跃文件和多个旧的数据文件的集合。

当前活跃文件的写入是只能追加的（append only），这意味着可以利用顺序 IO，不会有多余的磁盘寻址，最大限度保证了吞吐。

写入到文件的数据，具有固定的格式，大致有这些信息：

crc：数据校验和，防止数据被破坏、篡改等
timestamp：写入数据的时间戳
ksz：key size，key 的大小
value_sz：value size，value 的大小
key：用户实际存储的 key
value：用户实际存储的 value

每次写入都是追加写到活跃文件当中，删除操作实际上也是一次追加写入，只不过写入的是一个特殊的墓碑值，用于标记一条记录的删除，也就是说不会实际去删除某条数据。当执行 merge 操作的时候，才会将这种无效的数据清理掉。

所以 bitcask 模型中，一个文件中的数据，实际上就是多个具有固定格式的数据集合的排列：

在追加写入磁盘文件完成后，就会更新内存中的数据结构，论文中叫做 keydir，实际上就是全部 key 的一个集合，存储的是 key 到一条磁盘文件数据的位置，这里论文中说的是使用一个哈希表来存储。

keydir 一定会存储一条数据在磁盘中最新的位置，这样数据更新之后，文件中旧的数据仍然存在，等待 merge 的时候被清理。

所以读取数据就会变得很简单，首先根据 key 从内存中找到对应的记录，这个记录存储的是数据在磁盘中的位置，然后根据这个位置，找到磁盘上对应的数据文件，以及文件中的具体偏移，这样就能够获取到完整的数据了。

由于旧的数据实际上一直存在于磁盘文件中，因为我们并没有将旧的数据删掉，而是新追加了一条标识其被删除的记录。

所以随着 bitcask 存储的数据越来越多，旧的数据也可能会越来越多。论文中提出了一个 merge 的过程来清理所有无效的数据。

merge 会遍历所有不可变的旧数据文件，将所有有效的数据重新写到新的数据文件中，并且将旧的数据文件删除掉。

merge 完成后，还会为每个数据文件生成一个 hint 文件，hint 文件可以看做是全部数据的索引，它和数据文件唯一的区别是，它不会存储实际的 value。

它的作用是在 bitcask 启动的时候，直接加载 hint 文件中的数据，快速构建索引，而不用去全部重新加载数据文件，换句话说，就是在启动的时候加载更少的数据去构建索引，因为 hint 文件不存储 value，它的容量会比数据文件更小。

和 LSM Tree 的联系与区别

Bitcask 和 LSM Tree 都采用了日志追加写入的方式，只不过在实现上，bitcask 更像是简化版的 LSM Tree。

LSM Tree 的主要的结构有 WAL 预写日志、Memory Table、SSTable，预写日志也是追加进行写入，其复杂度主要在于对 SSTable 的维护以及 Compaction。

Bitcask 大致相当于 LSM Tree 中的 wal+memtable，只不过有一个很关键的区别： LSM Tree 的 memtable 存储的是还没有来得及刷到 SSTable 中的 key/value 数据，而 bitcask 中的 memtable 存储的是全量的 key+索引信息；而且 LSM Tree 的 memtable 存在多个，而 bitcask 可以认为只有一个。

LSM Tree 的优势是什么？

LSM Tree 的写入快速，能够处理远超内存容量的数据，但是如果刷 SSTable 的后台任务不及时，可能会造成写限速（Write Stall），并且在读取的时候，在 SSTable 中可能会存在多次磁盘 IO 寻址。

Bitcask 的优势是什么？

Bitcask 最大的优势在简单、易维护、读写稳定快速，读写不受数据量的限制，无论数据量大小，写永远都是一次追加写文件和一次更新内存索引，读也永远都是从内存中读取索引，然后直接一次磁盘文件寻址。

这种优势是维护全量内存索引带来的，但这同时带来了一个弊端，那就是在重启的时候必须加载全量数据去构建索引，数据集大的情况下，重启时间可能会很长，这种情况下 bitcask 模型适合处理较小规模的数据集。

bitcask 的文件清理主要通过扫描数据并重写来完成，这比 LSM Tree 的 Compaction 流程简单得多。

以上就是 bitcask 存储模型的基本原理，也是 rosedb 的基本架构。

但是在具体的实现当中，也有两点关键的区别。

第一点是，bitcask 论文中提到使用一个哈希表作为内存索引数据结构，但目前在 rosedb 当中使用的是 Google 开源的 BTree 实现。其实这里使用任意一个内存数据结构都是可以的，可以根据实际的需求和场景来确定或者进行扩展。

第二点是，针对数据文件的内部组织结构，rosedb 的 wal 实现采用了 block 分块的方式，这是原 bitcask 论文中未提及到的。

当然还有一些其他具体实现时候的魔鬼细节，将会在后续的文章中为大家一一揭晓。

广告区：

《从零实现 KV 存储》，使用 Rust 和 Go 两种语言实现，手把手教学，只需要基础的语法知识，即可学会一个硬核实战项目！

《从零实现 SQL 数据库》，使用 Rust 手写一个数据库系统，超级硬核，Rust 实战项目首选！

课程详情：https://roseduan.cn/course/

手写 SQL 数据库，吊打面试官！

Wed, 05 Feb 2025 08:49:42 +0000

本文是《从零实现 SQL 数据库》课程的加餐文章，描述如何在简历中写这个项目，以及一些可能的面试问题&答案，对课程感兴趣的同学可以查看课程主页： https://roseduan.cn/course/

一、简历上如何写这个项目？

**项目名称：**sqldb: 极简关系型 SQL 数据库

**项目概述：**sqldb 是使用 Rust 实现的简易关系型 SQL 数据库，支持常见的表管理、SQL 数据查询与存储等功能，支持 ACID 的事务特性，帮助理解生产级关系型数据库的架构原理和设计细节，以及代码层面的具体实现。

**项目架构：**主要分为了计算层和存储层，存储层支持基于磁盘和内存的存储引擎，并且在存储之上，使用快照隔离的方法实现了 ACID 事务。计算层按照标准的 SQL 数据库架构实现，主要有 SQL 解析、执行计划和执行器。执行器和存储事务层的读写接口进行交互，实现数据的具体存储和查询。

设计细节：

SQL 的词法和语法解析器
执行计划节点构建
执行引擎的执行逻辑
基于内存和磁盘的存储设计
ACID 事务的设计
表达式计算
可视化命令行

**项目功能：**支持了常见的 SQL 语法，包含：

创建和删除表：Create Table、Drop Table 语法，并且支持 Integer、String 等常见数据类型，支持 (Not) Null、Default、Index 等建表约束
DML：数据插入 Insert Into、数据删除 Delete From、数据更新 Update，数据查询 Select，select 支持投影、排序、分组、limit/offset、where 过滤、agg 聚集函数、join 子句
事务：支持 Begin、Commit、Rollback 语句
其他语句：比如 Show Tables 查看表结构，Explain 语句输出 SQL 执行计划

二、常见面试问题

1. 请简单介绍一下这个项目

结合上面的项目概述、架构、功能中的描述回答即可。

2. 为什么使用 Rust 来实现？

选择 Rust 主要是因为 Rust 具有出色的性能和内存管理能力。作为系统级编程语言，Rust 提供了安全性和高效性，Rust 的所有权模型和内存管理可以帮助避免传统 C/C++ 编程中的内存泄漏和数据竞争问题。此外，Rust 还具有现代化的工具链，支持高效的编译和静态分析，这对构建高性能数据库是非常重要的。

3. 项目中的存储引擎具体是怎么设计的？

存储引擎主要是有内存和磁盘，对外提供统一的读写接口。

内存使用 BTree，主要是使用了 Rust 标准库中的 BtreeMap。

磁盘存储基于简单的日志追加式的 bitcask 存储模型，bitcask 模型是一个高效、简洁的存储引擎，数据以日志的方式写到磁盘文件中，内存中维护了 key 和对应的索引信息。读取的时候直根据 key 从内存中获取到对应的索引，然后根据索引读取磁盘文件中的数据即可。

4. ACID 的事务具体是怎么实现的？

sqldb 中的事务基于快照隔离实现，主要有以下具体的设计细节：

数据快照：每个事务在开始时会获得一个快照。这意味着事务只会看到在事务开始时已提交的数据，不会看到其他事务的未提交修改。即使其他事务修改了数据，当前事务仍然只看到自己开始时的数据版本。

多版本并发控制（MVCC）：每个数据项维护多个版本（即多版本并发控制）。每次数据修改都会创建一个新的版本，事务通过其开始时的快照读取相应的版本，每个版本会关联一个全局唯一的事务版本号。

读写冲突检测：快照隔离会防止并发冲突（如脏读、不可重复读、幻读）。当一个事务修改了数据并提交后，其他事务无法看到其未提交的修改。如果两个事务同时读取相同的数据项并尝试修改它们，会检测到冲突并使其中一个事务回滚，避免不一致的结果。

5. 这种设计是怎么保证 ACID 特性的？

**A 原子性：**通过事务写入数据，只有调用 Commit 之后，才会生效，否则已经写入的中间数据是无效的。要么调用 Rollback 进行回滚，所以一个事务中的数据要么提交，要么回滚，保证了原子性。
**C 一致性：**一致性保证数据库从一个有效的状态转换到另一个有效的状态，在原子性和隔离性都满足的情况下，一致性也能够得到保证。
**I 隔离性：**主要是快照隔离，通过 MVCC 多版本并发控制，以及数据冲突检测机制，能够避免脏读，不可重复读，幻读的问题。是一种介于传统的串行化和可重复读之间的隔离级别。

脏读：事务在开始的时候获取了一个全局快照，只能读到对当前事务可见的数据，其他未提交的事务不能读到，避免了脏读。
不可重复读：通过全局快照，其他事务的修改就算提交了，也不会对当前事务可见，也就是说事务在运行的过程中，始终只能看到其开始时的状态，解决了不可重复读问题。
幻读：事务在读取的时候，如果事务版本号比当面版本号更大，说明是更加新的事务提交的数据，也不可见，解决了幻读的问题。

**D 持久性：**通过磁盘存储引擎，数据写入之后，能够安全的保存到持久化存储中。

6. SQL 语句是怎么解析并执行的？

SQL 解析：首先使用词法分析器（Lexer）和语法分析器（Parser）将 SQL 查询转换成一个抽象语法树（AST）。词法分析器将 SQL 语句分割成各个语法单元（例如关键字、标识符 Token、运算符），语法分析器 Parser 则检查 SQL 语句是否符合 SQL 语法规范，并生成抽象语法树 AST。

执行计划生成：根据 AST 构建执行计划。执行计划定义了如何访问和处理数据库中的数据。数据的增删改都对应了具体的执行节点，例如 Select 会决定使用索引还是全表扫描，或者如何使用 JOIN、Group By 等操作。

执行器：执行器根据执行计划访问数据库中的数据，执行相应的操作。执行器会与存储引擎交互，从内存或磁盘中读取数据，并根据操作修改数据。

7. SQL 解析时，如何处理不同类型的 SQL 语法？

SQL 解析主要在词法分析和语法分析阶段完成，在 Lexer 中将 SQL 拆分为不同各个语法单元，例如关键字、Token、运算法等。在 Parser 阶段会根据预定义的语法规则进行解析，如果不符合预期的话，则直接报出对应的语法错误。如果是一个有效的 SQL 语句则生成对应的抽象语法树。

8. 如何保证数据的崩溃恢复？

sqldb 中实现了基于磁盘的存储引擎，数据写入的时候会首先写入到磁盘存储引擎中，这能够保证持久性。如果在写入的过程中发生了异常，由于事务原子性机制的保证，中间状态的数据并不会生效，因此能够有效的保证数据库恢复到正确的状态。

9. 如何处理表达式计算？

sqldb 中使用了基于运算符优先级的算法 Precedence Climbing 来进行表达式计算，它本质上是一种递归下降解析表达式的方法，通过递归地处理运算符和操作数来解析表达式，并根据运算符的优先级和结合性来确定表达式的计算顺序。

这种算法的核心思想是利用运算符的优先级进行“爬升”（Climbing），以决定表达式的结构和计算顺序。

在 sqldb 当中，由于运算符众多，支持了几种最常用的运算符加减乘除。

如果面试官要求代码演示，可以参考：https://github.com/rosedblabs/rust-practice/tree/main/expr-eval

10. 如何支持 SQL 语法中的聚合函数和 Join 操作？

聚合函数（如 SUM、AVG、COUNT）在执行引擎中通过遍历结果集并进行相应的计算来实现。在执行查询时，执行引擎会根据执行计划确定是否需要对结果集进行分组，并计算聚合结果。

对于 JOIN 操作，执行引擎会根据查询类型选择合适的连接算法（如 Nested Loop Join 或 Hash Join）来完成数据表的连接操作。

11. 建表时既然支持 Index，那么索引是如何实现的？

sqldb 中的索引实现比较简单，借助 KV 存储引擎的底层结构，实现了类似哈希索引的功能。在实现上，主要是针对索引列，单独存储了一个 Key/Value 对，key 就是表名+索引列数据，value 是主键 id。这样在通过索引列进行查询的时候，能够快速定位到具体的数据，并且取出其中的主键 id 信息，然后再根据主键 id 获取数据。

并且在数据进行增删改的时候，如果索引列也进行了更新，那么也需要对索引的数据进行维护。

12. 如果要将这个数据库扩展成一个生产级别的数据库，你会考虑哪些方面？

要将这个数据库扩展成生产级别的数据库，可以从以下几个方面进行改进：

完善 SQL **语法：**增加更多样化的 SQL 语法，支持更加复杂的查询场景
性能优化：增加查询缓存、优化索引结构、增加并行查询处理等，以提高性能。
高可用性和容错：实现数据的自动备份、故障恢复和数据复制机制，确保高可用性。
安全性：增加访问控制、加密、审计日志等功能，确保数据安全性。
易用性：完善命令行工具，提供图形化界面，增强用户友好性。

我不停地学习，完全是被“同行”逼的

Wed, 25 Dec 2024 13:01:10 +0000

在很多人眼中，我还算是一个比较励志的人，从自学编程，文科转码，后来折腾各种开源项目，从业务开发转到数据库内核。

但是我折腾这么多东西，仅仅因为我是一个很上进的人吗，并不是，其实完全是被“同行”逼的。

且先分享下关于我的三个小故事。

我刚上大学的时候，遇到了一个学长，那个时候他已经快毕业了，由于在同一个社团，我们之间有了一些交集，对他也有了更多的了解。

他学历不算太好，但是对计算机有着非常浓厚的兴趣，后来凭借自己的能力找到了非常不错的工作。

我那时候凭自己的兴趣参加了学校的计算机社团和一个在图书馆的社团，让我非常震惊的是，这个学长竟然同时是这两个社团的社长，立即对这位学长产生了一些崇拜和佩服的心理。

在他的影响下，我也坚定了自学计算机的路径，并且在两个社团中，也渐渐站稳了脚跟，毕竟这两个社团都是我所喜欢的。在大三的时候，我也顺理成章的成为了这两个社团的社长，算是步了这位学长的后尘，取得了当时对于我来说觉得非常自豪的成就。

还是在大学，我大三开始系统性的自学 Java 的时候，其实非常的痛苦，经历过这种自学阶段的同学其实应该都能懂。主要并没有一个学习的氛围，并且自己也比较菜，遇到了一些问题的话不知道怎么去解决。

在这个非常难熬的阶段，我在知乎上看到了一篇文章，讲述的也是一个同学，本身学的是物理，但是呢，因为各种原因，打算自学计算机。

然后他做了各种明确的规划，列出了自己的学习路径，以及学习目标等等，并且在毕业的时候拿到了很好的 offer。

我当时看完这篇文章之后，也是挺惊讶的，我觉得别人都能够做到的事情，我为什么做不到呢？

于是我将他的这篇知乎文章专门复制出来，整理到了一个文档中。在后来的学习过程中，无论我遇到了什么问题，亦或是我坚持不下去的时候，总是会打开这篇文章看看，当做是一种自我激励。

后来，我毕业的时候，虽然还是没有足够的实力拿到很好的 offer，但也找到了让自己还算满意的工作，并且去了自己大学时候向往的城市，多少也算是完成了当初开始自学的目标。

第三个故事是关于我的开源项目 rosedb 的，之前写过一些关于如何开始写这个开源项目，以及一些推广和运营等相关的文章。

我最开始写这个项目的契机，其实非常的简单，那就是我看到别人写出了类似这样的项目。

当初我学习 Go 语言的过程当中，看到了两个项目，分别是 boltdb 和 nutsdb，boltdb 也是一个国外作者自己写的，并且已经相当的成熟，nutsdb 是国人写的一个项目。

当时看完这两个项目之后，我也挺受震撼，因为平时业务方面的东西都写腻了，突然看到这种面向底层基础的项目，让我觉得眼前一亮。

于是我也有了自己尝试去开始做的念头，并且暗自提示和鼓励自己，别人都能够做到，我为什么不可以呢？

后来的事大家都知道了，rosedb 在我的维护之下，虽然算不上多么的成功，但对于个人开发者来说，已经算是挺不错的了吧，并且后来我又在自己的一些创新想法之上开源了另一个项目 lotusdb。

通过这几个小故事，相信你也看到了，我不停地学习，不停的逼着自己进步，并不是因为我是一个主观上很上进的人，而是在每个成长的阶段，我都能找到一个标杆或榜样，不服输的性格让我觉得，别人都能做到，那么我也能行！

公众号迁移 on roseduan

OPC 时代，如何最小成本构建一个产品

1. 什么是 OPC

2. 为什么是现在

3. 以 codepie 为例

技术选型

前端

数据库

部署 / 运维

开发工具

成本

4. 几点经验

5. 写在最后

从零实现 AI Coding Agent

Coding Agent 的核心

真正难的是细节

课程目录：4 大模块 / 20 章

课程特点

学完你能获得什么

课程适合谁

免费试看

动物本能

上下文管理：Agent 的“记忆”难题

先搞清楚一个概念：上下文窗口

上下文是怎么被吃掉的

为什么不能简单地丢掉旧消息

常见的管理策略

1. 对话摘要压缩

2. 工具结果截断

3. 滑动窗口

4. 按需重新获取

上下文管理的核心权衡

为什么上下文管理是“能跑”到“能用”的关键

一句话总结

System Prompt：Agent 的”出厂设置”

什么是 System Prompt

System Prompt 到底管什么

1. 身份和角色

2. 行为规则

3. 工具使用策略

4. 输出格式

为什么 System Prompt 这么重要

同一个模型，不同的 Prompt，完全不同的表现

System Prompt 的层级结构

System Prompt 的局限性

一句话总结

Agent Loop：让 Agent 自己跑起来

Tool Use：给 LLM 装上手脚

AI Agent 到底是什么？别被那些花哨的概念唬住了

Vibe Coding 时代的开发者

传统的分工模式

AI 加持下，个人的能力边界被打开了

开发者的工作模式会被重新定义

信息获取的密度被拉满了

以人为本，主动拥抱变化

使用 Claude Code 几天后的感受和经验

先说背景

它实际帮了哪些忙

快速理解陌生代码

参照已有模式生成代码

编译报错直接扔给它

辅助学习和梳理架构

几个可以复用的使用技巧

1. 人来设计，AI 来实现

2. 给它一个参照物

3. 逐文件 review，不要一把梭

4. 善用它的记忆能力

5. 当成代码搜索引擎和学习助手

6. 复杂任务先让它做计划

什么场景下效果最好

写在最后

北漂三年

推荐一本 Rust 实战项目书籍

近期的生活和工作状态

生活

工作

掌握 Rust 语言的终极秘籍

《从零实现 KV 存储》

《从零实现 SQL 数据库》

Go 实战项目 rosedb 源码剖析 8—迭代器、过期时间