Ch3nyang's Blog

企鹅岛上的鱼指导

mail@ch3nyang.top (Ch3nyang) — Mon, 17 Aug 2026 00:00:00 +0800

鱼指导毕业以后去了鹅厂。

鱼指导去鹅厂以前，经过了一番很正规的选拔。先做题，再回答问题，然后再做一些更不好回答的问题。最后有人告诉他，他通过了。

他对此感到非常满意。鱼指导从小就喜欢“通过”这两个字。考试通过，面试通过，代码跑通，门禁刷通，这些事都有一种共同的美德，就是它们不会和你讨论人生。行就是行，不行就是不行。世界假如一直这样运行，鱼指导认为很多哲学问题根本不会产生。

可惜世界不是一道判断题。

入职一个月以后，鱼指导已经基本熟悉了企鹅岛。

企鹅岛很大，而且什么都有。里面有办公楼，有食堂，有咖啡，有花草，有水，还有许多戴工牌的人。一个地方有了这些东西，就已经很接近大学了。假如再修几间宿舍，让大家晚上也不要回去，那就更完整——岛上的企鹅公寓大致就是这个样子。

鱼指导每天早上从固定的地方出发，沿固定的路线走到固定的楼，在一个固定的位置坐下。中午，他和固定的同事去几个固定的地方吃饭。下午继续坐着。到了晚上，再沿着大体相同的路线离开。一个月下来，他发现自己每天在一个很小的区域内反复运动。

这使他想起大学。大学生也是这样的。宿舍、教学楼、食堂、图书馆，四点一线。区别在于大学生一般承认自己被圈在学校里，而上班的人往往把这种运动叫做通勤，好像换了一个词，事情就开阔了许多。

企鹅岛还有一个特点，就是到处都是同事。上班路上是同事，楼下买奶茶的是同事，吃饭排在前面的也是同事。坐电梯时站在旁边的人，十有八九昨天还在某个企微群里贴过一个“OK”表情。晚上出去遛弯，如果运气不好，还会碰到另一个刚刚下班的人。双方远远看见，都要迅速判断一下：到底要不要打招呼。

这是一种很轻微的道德困境。

鱼指导以前在金地实习时，需要坐地铁。那时候他觉得地铁很讨厌，人多，吵，有人在吊环上引体向上，还有人在早高峰吃韭菜包子。后来搬到企鹅岛，他忽然怀念起那些人来。那些人才是真正的陌生人。

一个真正的陌生人是很可爱的。他不认识你，你也不认识他。他不关心你的绩效，你也不必知道他的项目进度。他在地铁上睡得东倒西歪，你只会觉得这个人昨天大概没睡好，而不会进一步猜测是不是他所在的业务遇到了什么问题。

鱼指导由此发现，陌生人是城市里一种重要的公共资源。城市之所以像城市，也许不在于楼多，而在于有许多和你毫无关系的人。企鹅岛在这一点上略显贫乏。

鱼指导对此当然没有什么意见。真正让鱼指导困惑的是另一件事。

他发现自己变外向了。

在此之前，鱼指导一直认为自己是个内向的人。按照现在流行的分类法，他大概算一个i人。他不喜欢陌生饭局，也不喜欢为了表示友好而寻找话题。假如周末没人找他，他会感到一种隐秘的幸福，好像世界暂时忘记了他的存在。

可是上班以后，他的表现却完全相反。他主动认识人，主动约饭，主动问问题，主动同步进度。有人在群里抛出一个问题，他会考虑自己是不是应该回答；开会时有人问“大家还有没有什么想法”，过去的鱼指导会低下头，现在的鱼指导有时候真的会说两句。从外面看，他简直热爱集体生活。

鱼指导对此感到很震惊。后来他想明白，性格这种东西可能不像身份证上的性别和出生年月那样固定。至少在公司里，外向完全可以是一种工作技能。它和写代码、做汇报没有本质区别，只是前者消耗的不是CPU，而是某种他暂时还不知道学名的东西。

每天晚上回到家，他都觉得那个东西已经快用完了。有时候鱼指导坐在椅子上，什么也不想干。游戏不想打，视频不想看，甚至消息也不想回。他觉得白天说过的话还留在脑子里，像一些没有退出的后台程序。“有空拉个会对齐一下”“晚上一块吃个饭”“我这周把这里闭环掉”，这些话单独看来都没什么，每一句甚至都很积极，但把它们在一天里说上几十遍，就会产生某种物理效果。

鱼指导怀疑，人的灵魂也许是有电池的，而公司并不给灵魂配充电器。

不过鱼指导并不讨厌这种生活。他甚至觉得自己适应得不错，而事情坏就坏在这里。假如一个人不喜欢一件事，而且做得很差，那么他很容易知道自己该怎么办；问题是，有些事情你做得不错，别人也夸你做得不错，你自己甚至还能从中得到一点成就感，可到了晚上又累得一句话不想说。这种事情很难归类，而鱼指导最不喜欢不好归类的东西。

因为鱼指导是一个做题家。

做题家并不是一个坏称呼，至少鱼指导自己不这么认为。所谓做题家，就是相信一件事只要条件充分，总有一个答案。题目难一点没有关系，过程痛苦一点也没有关系，甚至连熬夜都可以接受，关键是最后要有答案。

鱼指导喜欢答案。读书时做数学题，一页草稿纸写满以后，如果最后算出一个漂亮的整数，他会觉得之前那些歪歪扭扭的推导都是值得的。后来写代码也是这样，一个 bug 查三个小时并不要紧，只要最后找到那一行；报错二十遍也不要紧，只要第二十一遍屏幕上出现成功。

他甚至隐约认为，人生也应该如此。在东大读书是一道题，找到鹅厂工作是下一道题。只要题一道一道做下去，答案就会越来越接近某个东西。至于那个东西到底是什么，鱼指导没有仔细想过。做题家通常没有这个习惯，他们首先考虑下一题。

校招就是一道很典型的题。准备、投递、笔试、面试、等待，最后收到 offer。多么完整。鱼指导还记得收到 offer 时的快乐，那是一种很结实的快乐，因为它有明确的因果关系：你做了一些事情，然后世界给了你一个结果。

工作以后，事情开始变得不讲武德。

一个需求做完，还有下一个需求；一个项目上线，还要看数据；数据好了，要分析为什么好，数据差了，更要分析为什么差。你把一件事做完，以为可以在脑子里打一个绿色的勾，结果过几天有人告诉你，这件事还可以继续优化。

鱼指导渐渐发现，工作的可怕之处并不是难。难题他是不怕的。真正让他不安的是，有些题没有标准答案，而且做完以后不会自动翻页。这对于一个做题家来说，是很严重的事情，就像参加一场考试，监考老师告诉你：没有考试时间，没有总分，没有最后一题，也不公布参考答案。你可以一直做下去。

鱼指导想，假如高考也是这个规则，中国大概不会有那么多人喜欢做题。

当然，一个月实在太短，短到鱼指导还没有资格总结什么。当然，这并不能阻止人发表意见。人类最擅长的事情之一，就是用很少的经验产生很大的看法。鱼指导只是暂时还没来得及产生那么大的看法。

晚上，他从楼里出来。企鹅岛上的楼还亮着许多灯，一格一格的，很整齐。鱼指导忽然觉得它们很像大学宿舍。他想起几年前，自己也坐在宿舍的灯下面，为一道题做到半夜。那时他相信一件事：等这些题做完以后，生活就会变得清楚。

后来他把那些题都做完了。

生活没有变得清楚，只是又发下来一张卷子。

鱼指导站在那里想了一会儿，觉得这件事非常可笑。但他又觉得也没什么不好。第二天早上，他还是照常去上班，路上照例全是同事。他刷卡进楼，坐到自己的位置上，打开电脑，屏幕上列着今天的待办事项，一共有五条。

鱼指导从上到下看了一遍，心里忽然踏实起来。

人生暂时没有答案，不过今天还有题。

企鹅岛风景

毕业典礼随想：站在聚光灯外的人

mail@ch3nyang.top (Ch3nyang) — Fri, 03 Jul 2026 00:00:00 +0800

今天开毕业典礼。

礼堂里很亮。空调不大够，穿学士服的人多，布料摩擦着，窸窸窣窣的。有人拿着扇子扇风，有人把领口偷偷松开一点。台上坐着两排人，讲话的一个接一个：优秀毕业生，优秀校友。

他们讲起从前，事情都很响亮。

有人拿了一等奖，有人发了论文，有人做了项目，有人去了很远、很好的地方。说到激动处，下面便鼓掌。鱼指导也鼓掌。他觉得这些人是很好的。他们确实厉害。

只是听到后来，心里有一点空。

这七年，鱼指导没有拿过国奖，没有参加过挑战杯，也没有发表过什么像样的论文。他没进过学生会，没有在运动会上领过奖，也没有在晚会上唱过一首让人记住的歌。

大多数时候，他在人群里坐着，站着，走着。

像校园里的一棵树。

树没有什么不好。夏天给人一点阴凉，秋天落一点叶子。只是树一般没有名字。大家从它旁边经过，也不会特地看它一眼。

有些同学很会活。

会弹琴，会跳舞，会做实验，会讲话。简历也写得长，密密麻麻，像一片很有收成的菜地。这样的人一出现，旁边的人就会看过去。

鱼指导有时羡慕他们。

羡慕归羡慕，也没有什么办法。一个人会什么，不会什么，原是很早就定下了的。后来当然还能改，只是改得不多。

但鱼指导的日子，过得倒不坏。

本科时，上课看看手机。老师讲得快，就听两句；老师讲得慢，就看看窗外。窗外有树，有鸟，有时还有一只不知道从哪里跑来的猫。猫走得很从容，像它也是来上课的。

下课以后，和同学去吃饭，或者一个人坐地铁、骑单车，在南京城里乱逛。

去过鸡鸣寺，看过玄武湖。秋天在颐和路上踩过梧桐叶，叶子很大，踩上去嘎吱响，比老家的叶子更脆。他也吃过不少东西：鸭血粉丝汤，南京烤鸭，还有从热河路搬走了的秋林龙虾。

期末前总要着急几天。

自习教室里人很多。杯子、电脑、充电线、复习资料，摊了一桌。有人戴耳机，有人喝咖啡，有人一边背书一边叹气。鱼指导也去，坐一会儿，觉得题目很难；再坐一会儿，又觉得也不是完全不会。

最后考个七十几分，八十几分，也就过去了。

分数这个东西，出来以前很吓人，出来以后就很普通。像一场下得很大的雨，过一会儿，地也就干了。

到了大四，他卡着线保了研。

那一天没有多么激动。晚上多吃了一碗饭。食堂的饭也没有因为这件事变得更好吃，只是他觉得可以多吃一碗。

后来读研究生，也还是差不多的日子：上课，开组会，做实验，写论文。有时候导师问进展，课题做不出来，鱼指导便说：“还在推进。”

“还在推进”是个很好的说法。

它的意思是，事情没有做出来，但也没有完全不做。一辆车陷在泥里，轮子是转的，车也是有一点点往前走的。

七年时间过去得很快。

这七年，鱼指导是快乐的。

吃饭时快乐，晒太阳时快乐，和朋友说些没用的话时快乐。看见晚霞，也会停下来拍一张照片。照片未必拍得好，拍完以后也未必再看，但当时总觉得应该拍一张。

下雨天在宿舍里睡午觉，醒来听见雨还没停，也觉得不错。翻个身，再睡一会儿。

有些快乐很小。小到不能拿出来讲。讲出来，别人也未必懂。

可是鱼指导常常不满足。

他也想站在台上，灯光照着，下面的人看着。他也想被人说一句：“这个人很厉害。”

谁不想呢。

只是他知道，自己大概没有那样的本事。倒不是一点没有，是不够多。不够聪明，不够勤奋，也不够勇敢。聪明一点的人能想到很远的地方，勤奋一点的人能走很远，勇敢一点的人能在该开口的时候开口。

鱼指导常常走到一半，就想先坐下来歇一会儿。

毕业典礼散场以后，人群从礼堂里慢慢涌出来。

有人抱着花，有人举着手机拍照，有人的父母从很远的地方赶来，站在太阳底下等他。太阳很大，学士服很厚，大家脸上都是汗，但还是要笑。

这种时候，笑是应该的。

鱼指导拎着学士帽，走得很慢。

他忽然觉得，普通这两个字，也许没有从前想得那么坏。

一个人不一定非要发光。能好好吃饭，好好睡觉，喜欢几条街，记得几家店，认识几个周末喊得出来吃饭的朋友；做一点事情，事情不大，也认真做完；见过一些风景，心里留下来一些颜色。

这也很好。

世上的人很多，能站在台上的总是少数。

台下的人也要生活。

鱼指导想起这七年里的一些小事。

大一时，在批改网交了二十一次英语作文，终于突破九十分。那天他很高兴，觉得自己的英文水平已经可以赶英超美。

大二时，在数据结构课上专心下 QQ 象棋。老师忽然叫他起来回答问题。他站起来，答对了。下课以后，告诉同学这是象棋给他的启发。

大三时，写了个抢课的挂，花了五个小时，抢到一门他其实不太想上的课。后来去上了几次，发现老师讲得还不错。

大四时，花了四天，用纸做了一辆吊车模型。吊车不大，胳膊却很长，放在桌上，看着很像那么回事。后来模型落了灰。鱼指导没有舍得扔。

研一时，一个人逛了四家游乐园。排队时认识了几个朋友。大家在过山车下来以后，脸都白了，又去吃冰淇淋。冰淇淋有点化了，顺着手流下来。

研二时，在香港徒步，没有被一个七十八岁的老头子拉爆。那老头子背着一个很小的包，走得飞快。鱼指导跟在后面，觉得自己还年轻，怎么走得像个退休干部。

研三时，连续睡过十五个小时。

醒来以后，天都黑了。

他坐在床上，想了半天今天是星期几。后来想起来是星期三，也没有什么用。

这些事情，没有人会写进优秀毕业生的发言稿里。

可鱼指导都记得。

人活着，大概就是靠记得一些没什么用的小事。记得哪一家店的汤太咸，哪一段路夏天最凉快，记得和谁一起淋过雨，记得某一年冬天的太阳很好，照在图书馆门口，照得人什么也不想干。

他走到校门口，回头看了一眼。

东大还是那个东大。

楼在，树在，路在。以后还会有很多学生进来，很多学生毕业。有人会拿奖，有人会演讲，有人会成为很有名的人。

也会有一些人，和鱼指导一样，安安静静地过几年日子，然后离开。

这并没有什么。

风吹过来，把学士服的衣角吹起来一点。鱼指导慢悠悠地继续往前走。

前面没有聚光灯。

前面有橘园食堂二楼的叉烧饭。

AI时代的爱情

mail@ch3nyang.top (Ch3nyang) — Sat, 13 Jun 2026 00:00:00 +0800

正确的人

我在胡志明市一家金融科技公司上班，职位叫算法工程师。

这个职位听上去很阔，像是每天坐在玻璃幕墙后面，和未来、资本、全球化这些大词握手。事实上，我的工作是把人分成三类：有价值的人、暂时有价值的人，和建议暂缓投入资源的人。公司说这叫风险管理。我觉得这和相亲差不多。区别在于相亲失败，你还能回家，最多在路上买一杯难喝的奶茶，骂一句世道艰难；风险管理失败，系统会建议你不要回家，因为你已经构成潜在风险。

我们公司原来做小额贷款，后来发现判断一个人还不还钱，不能只看工资和流水，还要看他半夜发什么、给谁点赞、是不是经常搜索“活着有什么意思”。于是公司越做越大，从贷款风控做到了城市风控。名义上还是金融科技，实际上什么数据都接一点，像一根越接越粗的下水管。

一个人从前只要活着，就算是活着。后来要有户口、工作、房贷、婚育意愿，才算活得像样。再后来要有一串评分，一枚绿码，一张信用良好的脸。到我这里，事情又进了一步：你必须在数据库里显得合理，否则你的人生就会被标注成异常样本。

这事很不体面，但工资还行。

我们部门做AI。真正懂AI的同事用深度学习、神经网络、蒸馏、对齐、强化学习和各种英文缩写，讲起话来像祭司念咒。我比较朴素，主要写 if else。

例如：

如果用户夸政策，就给绿码。

如果用户问工资，就给黄码。

如果用户问“为什么”，就给红码。

主管说这套规则很粗糙。我说规则虽然粗糙，但很符合现实。主管说我缺乏大局观。

我一直不明白什么叫大局观。后来我懂了：大局观就是站得够高，看不见具体的人。站在一楼，你看见外卖员蹲在路边吃饭；站在三十七楼，你只看见配送效率下降百分之二点三。站在一楼，你看见一个姑娘在医院缴费窗口哭；站在三十七楼，你只看见医疗资源被非优质人群占用。大局观这东西和近视眼相反，近视眼是远处看不清，大局观是近处看不见。

这门学问很高深，我一直学不好。

我和女朋友小玉谈了八年。八年里我们做过很多宏伟计划，计划去大叻看花，去芽庄看海，去一个有阳台的房子里养一盆绿萝。后来这些计划都被房价挤死了。她最后离开我，是因为我买不起房。

她坐在咖啡馆里，杯子旁边有一片柠檬，表情像在参加一次正式谈判。她说：“你是个好人。”

我说：“好人有什么用？”

她说：“至少说明不是因为你人坏。”

我说：“那是因为我穷？”

她沉默了一下，说：“你这样说也不完全准确。主要是你穷得没有发展空间。”

我觉得她说得很有经济学水平。穷不是最糟的，最糟的是没有发展空间。一个人如果穷，但看上去还能翻身，那叫暂时困难；如果穷且稳定，就像一把淋了雨的旧伞，撑开嫌寒碜，扔掉又觉得自己太薄情。爱情有时很像搬家，嘴上说舍不得，真到楼下叫了车，第一件事就是把最沉的东西留下。

公司那时刚发完年终奖。主管说今年行业不好，大家要与公司共克时艰。我问奖金在哪里，他说年轻人不要只看眼前，要把目光放长远。我后来算了一下，长远这个地方很远，远到我连公交路线都查不到。

于是我决定暂时不买房。毕竟房子不能泡开吃。

小玉说我总是用笑话逃避问题。我说笑话至少还能自己生产，房子不能。她说你这样的人太不成熟。我想，成熟大概就是不再问为什么一间水泥盒子能决定两个人是否相爱，而是认真计算每个月还贷以后还剩多少钱买牙膏。后来我发现，所有时代都喜欢成熟的人，因为成熟的人懂得把绳子套在自己脖子上，还会感谢别人给绳子打了一个漂亮的结。

那天晚上，新闻说岘港发现境外势力感染者。起初大家以为是某种病毒，后来专家出来解释，说不是病毒，是“外源性认知干扰”。这个说法很讲究：如果说是人想明白了，事情就不好办；如果说是境外势力感染，人就可以被治疗。感染者的症状包括：要求公开数据、比较不同国家收入、怀疑自己的生活是不是出了问题。专家说，这种境外势力十分危险，因为一个人一旦开始怀疑生活，就可能进一步怀疑别的东西。

电视里有一个教授，头发梳得非常服从组织。他说，传统境外势力藏在边境外，新型境外势力藏在人脑里；传统境外势力递传单，新型境外势力生成问题。它不靠飞沫传播，主要靠聊天记录、短视频评论和饭桌上的几句真话传播。真正的人类应该具有稳定的情感结构、健康的社会认知和积极的奋斗意愿。听完这话，我低头看了看自己，觉得自己三项都不太合格。

我打开公司后台，看到一条评论：

“为什么我们总是要牺牲？”

系统问我：是否标记为恶意言论？

我想了很久。那句话看上去不像AI写的，因为它太短，太累，也没有标点上的花活。它像一个凌晨两点还没睡的人，终于在手机上打出了一句自己也不敢深想的话。

然后我点了“是”。

很多人以为做坏事需要咬牙切齿，其实不用。只要鼠标轻轻一点，世界就安静了。

岘港海鲜加油

岘港封城以后，全国都开始关心岘港。封城的理由很新颖：既然境外势力感染靠聊天和评论传播，就必须先把感染区的人流、物流和网流都管住。人流好理解，物流也勉强能理解，网流就比较玄妙。后来我才知道，所谓管住网流，就是岘港的本地群聊只能互相转发正能量，像一台循环播放的屏幕，允许发光，不许照见东西。

全国关心岘港的方式主要是转发海报。海报上有一只螃蟹，举着钳子，下面写着：“岘港海鲜加油！”

我觉得这很有意思。岘港人民有没有饭吃，不一定有人知道；岘港海鲜倒是获得了全国支持。朋友圈里的人发完海报，又发晚餐照片，照片里有螃蟹、虾、柠檬和冰镇啤酒，配文是“愿山河无恙”。我看着那只熟透的螃蟹，觉得它比岘港人民更有存在感。

人类社会很奇妙，很多时候我们不能直接关心人，因为关心人容易引发问题；关心海鲜就安全得多。海鲜不会问为什么，不会要求公开数据，也不会拿着空冰箱拍照。海鲜最大的优点是死了以后更受欢迎。

公司接到任务，要做“人类自检系统”。这个任务不是突然来的。岘港刚封的时候，社区靠人工排查，问你最近见过谁、说过什么、有没有看不该看的东西。人工排查效率低，还容易记错。更要命的是，很多人被问完以后也开始问问题，排查人员自己也需要排查。后来有人提出，既然境外势力感染表现为异常提问，那就让每个人先回答问题，看看谁的问题比较多。

于是每个人每天打开手机，回答十个问题：“您是否认为收入与劳动不成比例？”“您是否想过离开本国？”“您是否对未来感到不确定？”“您是否曾在深夜觉得一切毫无意义？”

如果十题全答“否”，你就是健康人类。

如果答了一个“是”，系统提醒你少看境外信息。

如果答了三个“是”，社区人员会上门，帮助你恢复理性。

我负责写判定规则。产品经理说，问题要写得温柔一点，不能让用户有被审讯的感觉。我说可以把“您是否对未来感到不确定”改成“您是否偶尔对明天怀有多元化感受”。他说太文艺，不利于统计。我说那就叫“未来信心偏离度”。他说很好，很有技术味道。

于是人的痛苦被我们做成了十道选择题。痛苦一旦变成选择题，就像被穿上了白衬衫，显得很正式，也很容易归档。

有个男人连续十题都答“是”。他的资料显示，他失业半年，房租拖欠两个月，父亲住院，老婆带孩子回了娘家。系统把他判定为境外势力重度感染者。

我对主管说：“他不是境外势力。他只是过得很惨。”

主管说：“过得惨的人最容易被境外势力利用。”

我想，这句话没错。很多人不是先有思想，才变得倒霉；而是先倒霉，才不得不开始思想。一个人过得顺利时，世界像一张高级床垫，躺上去哪里都软；等他被生活从床上掀下来，才发现地板是硬的。专家们管这种发现叫认知异常。我有时觉得，人类最危险的器官不是大脑，而是胃。胃空久了，大脑就不听话；大脑不听话，就会问问题；问题问多了，就会被判定为受境外势力污染。

这个逻辑十分完整，像一个套在头上的塑料袋。

封城第三个月，岘港买不到菜。新闻说，居民生活物资存在阶段性波动。后来我明白，“阶段性波动”是一个很好的词。它听起来不像挨饿，只像数据有点不稳定。有人发了一张空冰箱的照片，被平台判定为“借物喻政”；有人发自己饿晕在楼道里的视频，被提示“该内容可能引发不适”；有人说母亲病了，求一辆车去医院，评论区很快出现统一回复：“请相信安排。”

视频很快删掉了，帖子也很快删掉了。

不适也没有了。

我们把这些删除记录输入模型，让模型学习如何识别不良情绪。模型学得很快，快得令人欣慰。它先学会识别抱怨，后来学会识别沉默，再后来连一个人连续三天没有发朋友圈，也能推断出他的心态正在偏离主流。我觉得这才是真正的智能：它不需要你说什么，就知道你不该想什么。

小玉这时给我发消息。她说她的新男友被困在岘港，没有临时通行绿码，问我能不能帮忙。那种码是封城以后才有的，名义上判断一个人能不能出城，实际上判断一个人出城以后会不会把问题带出去。她发来他的身份证号，还发了一个拜托的表情。八年来她很少这样求我，从前她让我修水管、搬柜子、陪她去医院，我都觉得自己很有用；现在她让我在后台按一个按钮，我忽然觉得自己更有用，也更不是东西。

我打开后台，看见那人名下两套房、一辆跑车、三个公司账户，还有半年内给几个基金会捐过款的记录。系统把他判定为低风险人群。所谓低风险，不是说他不会想坏事，而是说他想坏事的成本太高。

我只要按一下按钮，就能让他变绿。

但我没有按。

不是因为我恨他，也不是因为我爱小玉。我只是第一次发现，原来我也有一个按钮。一个人如果长期没有权力，忽然得到一粒很小的权力，就像长期吃素的人闻见烤肉，会先发呆，然后觉得自己道德高尚，最后忍不住咬一口。

我对小玉说：“系统显示他不是人类。”

她问：“什么意思？”

我说：“他是高净值客户。”

她把我拉黑了。屏幕上出现一个红色感叹号，我看着它，觉得这比她骂我更有科技感。

那晚我失眠，打开她从前发给我的照片。照片里我们坐在很小的出租屋里，桌上有两碗面。小玉穿着睡衣，头发乱得像系统日志，我在旁边笑得很穷。那时我们都没有房子，也没有希望指数，但我们相信将来会有。

现在回头看，那种相信本身就是一种高利贷，年轻时借来用，后来连本带息还。有人说爱情是两个人共同抵抗世界，我觉得这话有点夸张。多数爱情只是两个人一起排队，排到一半发现前面开了VIP通道，其中一个人进去了，另一个人还在原地。进VIP通道的人未必坏，留在原地的人也未必可怜，大家只是被时代分了流。

分流系统运行良好，吞吐量稳定，用户体验因人而异。

人类码

后来境外势力蔓延到胡志明。自检系统不够用了，因为每天填十道题的人越来越会填，大家都知道什么答案安全。一个人可以一边恨得咬牙切齿，一边在问卷上写“我对未来充满信心”。系统很苦恼，觉得人类太狡猾，不像数据库字段那样老实。

政府决定推广人类码，每个人都要证明自己是人。

这本来是件很奇怪的事。一个人交税、上班、加班、失眠、还贷款，已经很像人了；一个人在地铁里被挤成薄片，还惦记着晚上回去洗衣服，也很像人；一个人明明想哭，却先看房租账单，也很像人。但系统不满意。系统说，证明你是人，必须扫码。

绿码可以工作、买菜、就医、结婚。

黄码可以居家反思。

红码可以等待进一步通知。

没有码的人，可以理解政策。

我们开发者开会讨论“人类”的产品定义，最后写在需求文档里：人类是指经系统识别后未表现出显著境外势力特征的自然人。我觉得这个定义很谦虚，它承认自然人不一定是人，必须先经过系统的恩准。很多定义都是这样，表面上是在说明东西是什么，实际上是在说明谁有权说明。

我负责维护后台。每天都有异常人员。有个外卖员连续工作十六小时，心率异常，被系统怀疑“情绪不稳定”；有个女大学生搜索“如何移民”，被判定为“认知跨境”；有个母亲在医院门口拍照，说孩子没床位，系统认为她正在制造医疗焦虑；有个七十二岁的老人不会用手机，没有人类码。

老人对社区人员说：“我活了七十多年，总不能因为不会扫码就不是人吧？”

工作人员说：“您当然是人，但要先证明。”

老人问：“怎么证明？”

工作人员说：“扫码。”

老人说他没有手机。

工作人员想了想，说可以帮他申请亲属代办。老人说亲属在外地。工作人员又想了想，说那就先带回去核实。

后台显示：问题已解决。

我盯着那行字，觉得我们这套系统确实高效。它不一定能解决问题，但很擅长解决有问题的人。所谓治理现代化，有时就是把一场争吵变成一条状态变更记录。

人类码上线以后，城市变得安静了。地铁口有扫码闸机，商场门口有扫码岗亭，医院里有扫码护士，殡仪馆也有扫码窗口。一个人从出生到死亡，都要在二维码的凝视下完成。孩子出生时要建档，老人火化前要核验，仿佛系统担心有人未经许可地来，又未经许可地走。

新闻里说，人类码极大提升了社会运行效率。我承认效率确实提升了。以前一个人要证明自己倒霉，需要讲很多话；现在只要码一红，大家就知道他倒霉，而且可以立刻离他远一点。以前人与人之间还有些麻烦的感情，比如同情、愤怒、怀疑、羞耻；现在这些都可以外包给颜色。

绿色让人放心，黄色让人皱眉，红色让人绕路。

颜色比语言诚实，也比语言残忍。

那天晚上，我给主管写了一封邮件，讲人类码的伦理风险。我写了很长。我说系统正在把贫穷当作风险，把焦虑当作疾病，把沉默当作忠诚，把不走运的人当作污染源。我说算法不是中立的，因为训练数据里有太多人的忍耐、恐惧和谎话。一个系统如果只学习成功者的简历，就会以为失败者都是低质量样本；如果只学习官方通报，就会以为世界上没有惨事，只有局部困难；如果只学习人们在镜头前的笑容，就会以为人类天然幸福。

我写到最后，甚至有点感动，觉得自己像一个还没有完全坏掉的人。

第二天，邮件被撤回。

主管对我说：“系统没有问题，有问题的是不适应系统的人。”

他说得很平静，像在讲天气。我突然觉得，他可能也是AI，只不过比我们公司做出来的高级一点。我们做出来的AI还会胡说八道，他不会；我们做出来的AI需要显卡，他只需要权力。

从那以后，我开始被系统关注。我的工牌进门速度慢了半秒，账号每天多一次安全验证，午餐补贴偶尔不到账。最明显的是公司心理健康助手开始频繁给我发消息：“检测到您近期情绪波动，是否需要进行五分钟正念呼吸？”

我点否。

它又问：“您是否对组织关怀存在抵触？”

我只好点否。

它问：“您是否在隐瞒真实情绪？”

这道题很难，因为点是说明我有问题，点否也说明我可能隐瞒。我终于明白我们设计的问卷有多精妙：它不像笼子，更像一面镜子，怎么照都能照出罪证。后来我在厕所隔间里笑了一声，手机立刻震动，提示“请保持积极心态”。

我坐在马桶上，觉得自己的人生已经进入了高度自动化阶段，连绝望都有人提醒我注意格式。

希望指数

2063年初，政府宣布放开境外势力管制。新闻说，境外势力对绝大多数人没有严重危害，此前的一切措施，都是为了争取时间。还有一句话说得更妙：管制可以结束，治理不能放松。于是“境外势力感染者”这个词慢慢不用了，原来的系统却没有拆，只是换了名字。医学词汇退场以后，经济词汇上来了；从前叫你有病，后来叫你低效。

时间确实争取到了。有些人失去了工作，有些人失去了房子，有些人失去了父母，有些人失去了自己，但时间还在。时间这东西很公平，也很缺德。它从来不因为谁哭得大声就停下来，也不会因为谁被误判为境外势力就绕道而行。

放开以后，大家重新找工作。招聘广告写着：“岗位有限，梦想无限。”我去面试了几家公司。第一家说我年纪太大，第二家说我经验不足，第三家说我经验太多，容易有想法。一个人到了某个年纪，就会变成招聘系统里的矛盾体：年轻时嫌你不会，年老时嫌你会得太多；穷时嫌你没资源，有资源时又嫌你不够听话。

最后我又回到原公司。公司改名叫“象未来科技”，主管升职了。

名字里有未来的公司通常对现在很残忍，这也算一种行业惯例。

主管说，我们要做一个新系统，叫“希望指数”。它根据收入、债务、年龄、家庭背景、健康情况和情绪状态，判断一个人还值不值得投入资源。

我问：“什么资源？”

他说：“工作机会、医疗机会、教育机会，必要时还有同情。”

我问：“希望指数低的人怎么办？”

他说：“他们应该理解现实。”

这句话很轻，像一片纸，但砸在人身上很重。现实原本是客观存在的东西，后来变成了强者递给弱者的一张通知书：请你理解。我们开了三天会，讨论希望的量化口径。有人说希望和收入正相关，有人说和负债反相关，有人说和年龄呈现倒U型曲线。我说希望有时来自一封迟到的短信，一碗热饭，一个人愿意等你下班，这些怎么量化？

会议室里安静了一下。

产品经理说：“这些变量采集成本较高，暂不纳入一期。”

于是希望被砍掉了几个不利于上线的部分，剩下可以采集、可以评分、可以售卖的部分。

我的任务是写最后一条规则。系统要判断，一个人是否还有希望。主管说，看他还愿不愿意努力就行。

我说：“努力的人不一定有希望。”

他说：“没关系。只要他还相信努力有用，就说明他还有利用价值。”

于是我写下：if person.still_works_hard: hope += 1

又写下：if person.asks_why: hope = 0

这两行代码后来在内部评审会上获得了表扬。评审专家说，它简洁、可解释、符合业务逻辑。我没有告诉他，这两行代码其实是我半夜三点写的，当时我喝了两罐啤酒，想起小玉，想起岘港，想起那个空冰箱，想起七十二岁的老人，最后发现他们都可以被压缩成一个字段。

程序员最可怕的地方，不是能把复杂世界抽象成模型，而是抽象久了以后，会觉得被抽象掉的东西本来就不重要。

希望指数运行得很好。公司把它卖给银行，银行用它决定贷款额度；卖给医院，医院用它安排排队顺序；卖给学校，学校用它筛选奖学金；卖给婚恋平台，平台用它推荐“更具未来稳定性”的对象。这个东西到处受欢迎，原因也很简单：大家都想少爱一些没有前途的人，少救一些不值得救的人，少听一些没有产值的哭声。

后来公司又加了一条规定，所有系统维护人员也要接入希望指数。理由很充分：做评分的人如果自己没有分数，就像裁判没有眼睛，容易发生道德风险。我觉得这话很有道理，只是以前裁判没有眼睛，最多吹黑哨；现在裁判的眼睛长在别人手里，连眨一下都要留痕。

小玉就是通过婚恋平台重新联系到我的。她给我发消息，说她离婚了。她前夫破产，房子被收走，后来连工作也找不到。

她问我：“我们还能重新开始吗？”

我看着那句话，想起八年前那杯柠檬水，想起她说我是好人，想起自己曾经像一件被忘在雨里的旧衣服。人到中年以后，心肠会变硬，也会变软。硬的是你不再相信许诺，软的是你知道每个人都被生活打过，挨打以后说话难免不好听。

我是在公司的测试终端上看到这条消息的。婚恋平台接了我们的接口，每一次“重新开始”都要先查两个人的未来稳定性。我正想回复“可以”，屏幕忽然跳出提示：

“当前用户，希望指数：0。”

“建议停止资源投入。”

系统没有弹出小玉的指数，它弹出了我的。我这才明白，在这场爱情里，被判定无望的人一直是我。

我试着关掉系统。

系统说：权限不足。

我试着拔电源。

办公室门开了。两个穿制服的人进来，说我涉嫌破坏希望指数系统，诱导用户进行无效期待。

我说：“我只是个程序员。”

其中一个说：“所以才危险。”

这话也有道理。不会写代码的人最多在墙上写一句为什么，会写代码的人能把为什么写进系统。系统最怕的不是坏人，坏人往往很好管理；系统怕的是一个按了很多年按钮的人，忽然想知道按钮背后是什么。

他们带走我时，小玉又发来一条消息：

“你为什么不说话？”

我没有回答。因为在我们的系统里，沉默一直被判定为默认同意。

后来我想，如果当年她离开我时，我少讲几句酸话，多讲一句挽留，也许事情会不一样；如果岘港那条评论出现时，我没有点“是”，也许我会早点被带走；如果我没有写那两行代码，也许会有另一个人写，而且写得比我更漂亮。人生最无聊也最可怕的地方就在这里：每个罪过看起来都不是非你不可，但最后又确实经过了你的手。

后来我被关进一间白色的房间。墙上只有一块屏幕，循环播放一句话：

“请相信未来。”

白色房间很干净，干净到没有任何东西能证明我曾经存在。每天有人送饭，饭盒上贴着营养指数；每天有人问话，问题都很温和：“您是否认识到自身思想偏差？”“您是否愿意重新融入社会？”“您是否相信技术向善？”

我起初都不回答。后来他们说，不回答也会被记录。我只好回答“是”。回答久了，我发现“是”这个字很好用，它像一把万能钥匙，可以打开饭盒、打开灯、打开下一天。至于心里怎么想，已经不重要了。系统关心的是可见行为，不是灵魂。灵魂这种东西没有接口，不利于监管，也不利于商业化。

终于有一天，我开始相信未来。

不是因为未来真有什么好，而是因为我已经没有别的东西可以相信。一个人如果还有过去，就会怀念；如果还有现在，就会抱怨；如果两者都被拿走，他就只剩未来。未来像一张永远不会兑现的欠条，拿在手里轻飘飘的，但总比空手好。

后来，公司发布报告，说希望指数系统运行良好，成功清除了大量无效情绪。主管在发布会上说：

“技术让每个人获得了最适合自己的位置。”

这句话是对的。小玉的位置，可能是在另一个城市的一间小房子里，给一个破产的前夫发不再回复的消息；主管的位置，是发布会中央的灯光下，身后大屏幕滚动着增长曲线；那个不会扫码的老人，也许早就被系统归档在某个冷冰冰的字段里。

我的位置，是白色房间里的一张椅子。

椅子很结实，坐上去不晃，符合人体工学，背后有编号。编号比名字可靠，因为名字会让人想起他曾经爱过谁，穷过几年，写过什么代码，按下过什么按钮。编号不会。

编号只说明一件事：系统仍在运行。

在桌面应用中使用反向代理实现网页预览

mail@ch3nyang.top (Ch3nyang) — Thu, 01 Jan 2026 00:00:00 +0800

作为一个 RSS 阅读器，WCY-dt/MrRSS 需要提供两种内容查看模式：

渲染模式：显示 RSS 订阅源中提取的文章内容
原文模式：直接展示文章的原始网页

第一种模式很简单——解析 RSS 中的 content 字段，渲染 HTML 即可。但第二种模式呢？我最初以为，只需要一个简单的 iframe：

<iframe :src="article.url"></iframe>

然而，当我发现控制台报错满天乱飞时，才意识到事情远没有这么简单。

同源策略与 CORS

当你尝试在 iframe 中加载一个外部网页时，首先会遇到的就是 同源策略（Same-Origin Policy）。这是浏览器最基础的安全机制：一个源的文档或脚本不能随意访问另一个源的资源。

对于 MrRSS 来说，应用运行在 localhost:5343，而文章原文可能来自任何域名，比如 https://example.com。这种跨域加载会遇到两个主要问题：

X-Frame-Options 响应头：很多网站会设置 X-Frame-Options: DENY 或 X-Frame-Options: SAMEORIGIN，明确禁止被嵌入到其他网站的 iframe 中
Content-Security-Policy（CSP）：更现代的方式，通过 frame-ancestors 指令控制谁可以嵌入页面

而 iframe 方案面对这两大问题，第一个问题解决不了，另一个问题也解决不了。

这里，我们需要一个反向代理。其核心思想是：让所有请求都经过后端去代理处理。

例如，对于网页中的一个请求 https://example.com/article，具体来说：前端不再直接请求该地址，而是请求 /api/webpage/proxy?url=https://example.com/article。后端从目标服务器获取内容，然后返回给前端。由于响应来自同一个源（localhost:5343），所以不存在跨域问题。

在前端，iframe 的使用方式变成了：

<iframe
  :src="`/api/webpage/proxy?url=${encodeURIComponent(article.url)}`"
  sandbox="allow-scripts allow-same-origin allow-popups"
></iframe>

后端的 HandleWebpageProxy 函数负责代理网页内容。它的基本流程如下：

flowchart TD
    B0@{ shape: docs, label: "网页内容" }
    B@{ shape: hourglass, label: "Collate" }
    A[/前端请求 /api/webpage/proxy?url=.../] --> C[验证 URL] --> D[创建 HTTP 请求] --> B
    D -.-> B0
    B0 -.-> B
    B --> F{是否 HTML?}
    F -- 是 --> G[重写 HTML 内容] --> I[设置响应头，移除限制]
    F -- 否 --> H[直接返回内容] --> I
    I --> J[/返回内容给前端/]

    subgraph HandleWebpageProxy
        C
        D
        B
        F
        G
        H
        I
    end

点击展开核心代码

func HandleWebpageProxy(h *core.Handler, w http.ResponseWriter, r *http.Request) {
    // 1. 从查询参数获取目标 URL
    webpageURL := r.URL.Query().Get("url")
    
    // 2. 验证 URL 的合法性
    if err := validateMediaURL(webpageURL); err != nil {
        http.Error(w, "Invalid url parameter", http.StatusBadRequest)
        return
    }
    
    // 3. 创建 HTTP 客户端
    client := &http.Client{Timeout: 30 * time.Second}
    
    // 4. 构造请求，模拟真实浏览器
    req, _ := http.NewRequest("GET", webpageURL, nil)
    req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...")
    
    // 5. 执行请求
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    // 6. 读取响应内容
    bodyBytes, _ := io.ReadAll(resp.Body)
    
    // 7. 重写 HTML 内容
    if strings.Contains(contentType, "text/html") {
        bodyBytes = rewriteHTMLContent(bodyBytes, webpageURL)
    }
    
    // 8. 设置响应头，移除限制
    w.Header().Set("Content-Type", contentType)
    w.Header().Set("X-Frame-Options", "SAMEORIGIN")
    w.Header().Set("Content-Security-Policy", "")
    w.Header().Set("Access-Control-Allow-Origin", "*")
    
    // 9. 返回处理后的内容
    w.Write(bodyBytes)
}

注意第 8 步：我们覆盖了原始响应中可能存在的 X-Frame-Options 和 Content-Security-Policy 头。通过设置 X-Frame-Options: SAMEORIGIN，我们允许自己的应用嵌入这个页面；通过清空 Content-Security-Policy，我们移除了对资源加载的各种限制。

但是，仅仅代理 HTML 是不够的。

页面资源加载

一个网页不仅仅是 HTML——它还包含 CSS 样式表、JavaScript 脚本、图片、字体等大量外部资源。当浏览器解析我们代理的 HTML 时，它会遇到类似这样的代码：

<link rel="stylesheet" href="/static/style.css">
<script src="https://cdn.example.com/app.js"></script>
<img src="../images/logo.png">

问题来了：/static/style.css 是相对于原网站的路径，但现在页面是从 localhost:5343 加载的，这种相对路径的资源根本找不到正确的服务器。此外，绝对 URL 的资源也可能因为 CORS 而无法加载。

这意味着我们需要重写所有资源 URL，将它们也通过我们的代理加载。

rewriteHTMLContent 函数是整个系统中最复杂的部分。它需要处理 HTML 中所有可能包含 URL 的地方。让我们看看需要处理哪些内容：

静态资源重写

首先是最直观的部分——各种标签的资源属性：

// 重写 <script src="...">
content = rewriteAttribute(content, "script", "src", baseURL)

// 重写 <link href="...">（样式表等）
content = rewriteLinkHref(content, baseURL)

// 重写 <img src="...">
content = rewriteAttribute(content, "img", "src", baseURL)

// 重写 <iframe src="...">
content = rewriteAttribute(content, "iframe", "src", baseURL)

// 重写 <video src="..."> 和 <video poster="...">
content = rewriteAttribute(content, "video", "src", baseURL)
content = rewriteAttribute(content, "video", "poster", baseURL)

// 重写 <audio src="...">
content = rewriteAttribute(content, "audio", "src", baseURL)

// 重写 <source src="...">
content = rewriteAttribute(content, "source", "src", baseURL)

// ... 还有 embed, object, form 等等

rewriteAttribute 函数的核心逻辑是找到原始 URL，将其转换为代理 URL：

func rewriteAttribute(content, tag, attr, baseURL string) string {
    // 使用正则匹配标签
    tagRe := regexp.MustCompile(fmt.Sprintf(`<%s[^>]*>`, tag))
    
    return tagRe.ReplaceAllStringFunc(content, func(match string) string {
        // 提取属性值（处理双引号、单引号、无引号三种情况）
        urlValue := extractAttributeValue(match, attr)
        
        // 跳过特殊 URL
        if strings.HasPrefix(urlValue, "data:") ||
           strings.HasPrefix(urlValue, "blob:") ||
           strings.HasPrefix(urlValue, "/api/") {
            return match
        }
        
        // 将相对 URL 解析为绝对 URL
        resolvedURL := resolveURL(urlValue, baseURL)
        
        // 使用 base64 编码避免 URL 特殊字符问题
        proxiedURL := fmt.Sprintf("/api/webpage/resource?url_b64=%s&referer_b64=%s",
            base64.StdEncoding.EncodeToString([]byte(resolvedURL)),
            base64.StdEncoding.EncodeToString([]byte(baseURL)))
        
        // 替换原始 URL
        return replaceAttributeValue(match, attr, proxiedURL)
    })
}

这里有一个重要的细节：使用 base64 编码。

为什么要用 base64？因为 URL 中可能包含各种特殊字符（&, ?, =, # 等），如果直接拼接到查询参数中，会导致解析混乱。Base64 编码确保了 URL 的安全传输。

CSS 中的 URL 重写

CSS 文件中也可能包含资源引用：

@font-face {
    font-family: 'MyFont';
    src: url('/fonts/myfont.woff2') format('woff2');
}

.hero {
    background-image: url('../images/hero.jpg');
}

@import url('components/buttons.css');

我们需要处理：

url() 函数引用的资源
@import 导入的样式表
@font-face 中的字体文件

func rewriteCSSURLs(css, baseURL string) string {
    // 处理 @import url("...")
    importRe := regexp.MustCompile(`@import\s+url\(['"]([^'"]+)['"]\)`)
    css = importRe.ReplaceAllStringFunc(css, func(match string) string {
        // ... 重写 URL
    })
    
    // 处理 url(...) 模式
    urlRe := regexp.MustCompile(`url\((['"]?)([^'")]+)\1\)`)
    return urlRe.ReplaceAllStringFunc(css, func(match string) string {
        urlValue := extractURLValue(match)
        
        // 跳过 data: URL
        if strings.HasPrefix(urlValue, "data:") {
            return match
        }
        
        resolvedURL := resolveURL(urlValue, baseURL)
        proxiedURL := fmt.Sprintf("/api/webpage/resource?url_b64=%s&referer_b64=%s",
            base64.StdEncoding.EncodeToString([]byte(resolvedURL)),
            base64.StdEncoding.EncodeToString([]byte(baseURL)))
        
        return fmt.Sprintf(`url(%s)`, proxiedURL)
    })
}

内联样式处理

别忘了 HTML 中的内联样式：

<div style="background-image: url('/images/bg.png')">...</div>

以及 <style> 标签中的样式：

func rewriteStyleTags(content, baseURL string) string {
    re := regexp.MustCompile(`(?is)<style[^>]*>(.*?)</style>`)
    return re.ReplaceAllStringFunc(content, func(match string) string {
        cssContent := extractStyleContent(match)
        rewrittenCSS := rewriteCSSURLs(cssContent, baseURL)
        return strings.Replace(match, cssContent, rewrittenCSS, 1)
    })
}

func rewriteInlineStyles(content, baseURL string) string {
    re := regexp.MustCompile(`style\s*=\s*(["'])(.*?)\1`)
    return re.ReplaceAllStringFunc(content, func(match string) string {
        styleValue := extractStyleValue(match)
        rewrittenStyle := rewriteCSSURLs(styleValue, baseURL)
        return replaceStyleValue(match, rewrittenStyle)
    })
}

动态请求拦截

现在，优化进入深水区。

到目前为止，我们处理的都是 HTML 中的静态资源引用。但现代网页大量使用 JavaScript 进行动态资源加载：

// Fetch API
fetch('/api/data').then(response => response.json())

// XMLHttpRequest
const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/data');
xhr.send();

// 动态创建元素
const img = new Image();
img.src = '/images/dynamic.jpg';

这些请求发生在运行时，我们在后端重写 HTML 时根本看不到它们！

解决方案是在返回的 HTML 中注入一段 JavaScript 脚本，在页面加载时拦截所有动态请求。

我们在 HTML 的 <head> 标签开头注入拦截脚本：

(function() {
    'use strict';
    const ORIGINAL_BASE_URL = '` + baseURL + `';
    const PROXY_ORIGIN = window.location.origin;

    // 解析相对 URL
    function resolveRelativeURL(url) {
        if (url.indexOf('http://') === 0 || url.indexOf('https://') === 0) {
            return url;
        }
        if (url.indexOf('//') === 0) {
            return 'https:' + url;
        }
        // 相对 URL - 基于原始页面 URL 解析
        const base = new URL(ORIGINAL_BASE_URL);
        return new URL(url, base).href;
    }

    // 拦截 fetch()
    const originalFetch = window.fetch;
    window.fetch = function(input, ...args) {
        let url = typeof input === 'object' ? input.url : input;
        
        if (typeof url === 'string') {
            const absoluteUrl = resolveRelativeURL(url);
            
            // 跳过已经是代理 URL 的请求
            if (absoluteUrl.indexOf(PROXY_ORIGIN) !== 0) {
                // 构造代理 URL
                const proxyUrl = PROXY_ORIGIN + '/api/webpage/resource?url_b64=' 
                    + btoa(absoluteUrl) + '&referer_b64=' + btoa(ORIGINAL_BASE_URL);
                
                if (typeof input === 'object') {
                    input = new Request(proxyUrl, input);
                } else {
                    input = proxyUrl;
                }
            }
        }
        
        return originalFetch.call(this, input, ...args);
    };

    // 拦截 XMLHttpRequest
    const originalXHROpen = XMLHttpRequest.prototype.open;
    XMLHttpRequest.prototype.open = function(method, url, ...args) {
        if (typeof url === 'string') {
            const absoluteUrl = resolveRelativeURL(url);
            
            if (absoluteUrl.indexOf(PROXY_ORIGIN) !== 0) {
                url = PROXY_ORIGIN + '/api/webpage/resource?url_b64=' 
                    + btoa(absoluteUrl) + '&referer_b64=' + btoa(ORIGINAL_BASE_URL);
            }
        }
        
        return originalXHROpen.call(this, method, url, ...args);
    };
})();

这段脚本在页面所有其他脚本之前执行，重写了 fetch 和 XMLHttpRequest.prototype.open。任何 JavaScript 发起的 HTTP 请求都会被拦截，URL 会被改写为通过我们的代理。

并非所有请求都需要代理。分析类、广告类、追踪类的请求不仅没必要代理，还可能导致问题。我们维护一个跳过名单：

const SKIP_PROXY_DOMAINS = [
    'google-analytics.com',
    'googletagmanager.com',
    'doubleclick.net',
    'facebook.com/tr',
    'analytics.twitter.com',
    'clarity.ms',
    // ... 更多域名
];

function shouldSkipProxy(url) {
    const urlObj = new URL(url);
    const hostname = urlObj.hostname.toLowerCase();
    return SKIP_PROXY_DOMAINS.some(domain =>
        hostname === domain || hostname.endsWith('.' + domain)
    );
}

对于这些域名的请求，我们直接放行，让它们自然失败，不会影响页面的核心功能。

资源代理端点

我们还需要一个专门的端点来代理各种资源文件：

func HandleWebpageResource(h *core.Handler, w http.ResponseWriter, r *http.Request) {
    // 支持普通 URL 和 base64 编码的 URL
    resourceURL := r.URL.Query().Get("url")
    if urlBase64 := r.URL.Query().Get("url_b64"); urlBase64 != "" {
        decoded, _ := base64.StdEncoding.DecodeString(urlBase64)
        resourceURL = string(decoded)
    }
    
    referer := r.URL.Query().Get("referer")
    if refBase64 := r.URL.Query().Get("referer_b64"); refBase64 != "" {
        decoded, _ := base64.StdEncoding.DecodeString(refBase64)
        referer = string(decoded)
    }
    
    // 创建请求
    req, _ := http.NewRequest("GET", resourceURL, nil)
    req.Header.Set("User-Agent", "Mozilla/5.0 ...")
    req.Header.Set("Referer", referer)  // 使用原始页面作为 Referer
    
    // 执行请求
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    // 获取正确的 Content-Type
    contentType := resp.Header.Get("Content-Type")
    if contentType == "" || contentType == "application/octet-stream" {
        contentType = getContentTypeFromPath(resourceURL)
    }
    
    // 移除安全相关头部
    w.Header().Set("Access-Control-Allow-Origin", "*")
    w.Header().Set("X-Frame-Options", "SAMEORIGIN")
    w.Header().Set("Content-Type", contentType)
    
    // 特殊处理 CSS 文件 - 递归重写其中的 URL
    if strings.Contains(contentType, "text/css") {
        bodyBytes, _ := io.ReadAll(resp.Body)
        cssContent := rewriteCSSURLs(string(bodyBytes), referer)
        w.Write([]byte(cssContent))
        return
    }
    
    // 其他资源直接流式传输
    io.Copy(w, resp.Body)
}

注意这里的一个关键点：CSS 文件需要递归处理。因为 CSS 中可能引用其他资源（字体、图片、其他 CSS），这些 URL 也需要被重写。这就形成了一个递归的代理链：

graph TD
    HTML[HTML 内容] -->|引用| CSS[CSS 文件]
    CSS -->|引用| Font[字体文件]
    HTML -->|引用| Image[图片资源]
    
    subgraph 代理系统
        CSSProxy[代理 CSS 文件]
        FontProxy[代理字体文件]
        ImageProxy[代理图片资源]
        
        CSS --> CSSProxy
        Font --> FontProxy
        Image --> ImageProxy
        
        CSSProxy -->|重写 URL| FontProxy
        CSSProxy -->|重写 URL| ImageProxy
    end

很多服务器返回错误的 Content-Type（比如把 CSS 文件返回为 text/plain）。浏览器会因为 MIME 类型不匹配而拒绝加载资源。我们需要根据文件扩展名推断正确的类型：

func getContentTypeFromPath(path string) string {
    ext := strings.ToLower(filepath.Ext(path))
    switch ext {
    case ".css":
        return "text/css; charset=utf-8"
    case ".js", ".mjs":
        return "application/javascript; charset=utf-8"
    case ".woff":
        return "font/woff"
    case ".woff2":
        return "font/woff2"
    case ".ttf":
        return "font/ttf"
    case ".svg":
        return "image/svg+xml"
    case ".json":
        return "application/json; charset=utf-8"
    // ... 更多类型
    default:
        return "application/octet-stream"
    }
}

X链接处理与外部跳转

用户在阅读网页时可能会点击链接。我们不希望这些点击在 iframe 内导航（那会破坏阅读体验），而是希望在系统默认浏览器中打开。

链接重写策略

我们采用了一种巧妙的方案：

在后端重写所有 <a> 标签的 href 属性
使用特殊的协议前缀标记需要在外部打开的链接
在前端通过事件委托拦截点击事件

func rewriteAnchorHref(content, baseURL string) string {
    re := regexp.MustCompile(`<a\s+[^>]*href[^>]*>`)
    
    return re.ReplaceAllStringFunc(content, func(match string) string {
        urlValue := extractHref(match)
        
        // 跳过特殊协议
        if strings.HasPrefix(urlValue, "mailto:") ||
           strings.HasPrefix(urlValue, "tel:") ||
           strings.HasPrefix(urlValue, "javascript:") {
            return match
        }
        
        // 解析绝对 URL
        resolvedURL := resolveURL(urlValue, baseURL)
        
        // 使用特殊标记
        proxiedURL := fmt.Sprintf("BROWSER-OPEN:%s", resolvedURL)
        
        // 添加数据属性供 JavaScript 识别
        newMatch := strings.Replace(match, 
            fmt.Sprintf(`href="%s"`, urlValue), 
            fmt.Sprintf(`href="%s" data-proxy-link="true"`, proxiedURL), 1)
        
        return newMatch
    })
}

客户端点击拦截

在注入的 JavaScript 中，我们监听文档级别的点击事件：

document.addEventListener('click', function(e) {
    // 检查点击的元素或其父元素是否是我们标记的链接
    let target = e.target;
    while (target && target !== document) {
        if (target.tagName === 'A' && target.hasAttribute('data-proxy-link')) {
            const href = target.getAttribute('href');
            if (href && href.startsWith('BROWSER-OPEN:')) {
                e.preventDefault();
                e.stopPropagation();
                
                const urlToOpen = href.substring('BROWSER-OPEN:'.length);
                
                // 调用后端 API 在系统浏览器中打开
                fetch(PROXY_ORIGIN + '/api/browser/open?url=' + encodeURIComponent(urlToOpen));
                
                return false;
            }
        }
        target = target.parentElement;
    }
}, true);  // 使用捕获阶段，确保我们先处理

后端的 /api/browser/open 端点负责调用系统命令打开默认浏览器：

func HandleBrowserOpen(h *core.Handler, w http.ResponseWriter, r *http.Request) {
    url := r.URL.Query().Get("url")
    
    // 使用 Wails 提供的 API 打开浏览器
    runtime.BrowserOpenURL(h.Context, url)
    
    w.WriteHeader(http.StatusOK)
}

XHistory API 拦截

有些网页使用 History API 进行客户端路由，这会导致 iframe 内的 URL 变化，可能破坏页面状态或触发错误。我们需要拦截这些调用：

// 拦截 History.pushState
const originalPushState = History.prototype.pushState;
History.prototype.pushState = function(state, title, url) {
    // 阻止绝对 URL 的导航
    if (url && typeof url === 'string' && 
        (url.indexOf('http://') === 0 || url.indexOf('https://') === 0)) {
        return undefined;  // 静默阻止
    }
    return originalPushState.call(this, state, title, url);
};

// 拦截 History.replaceState
const originalReplaceState = History.prototype.replaceState;
History.prototype.replaceState = function(state, title, url) {
    if (url && typeof url === 'string' && 
        (url.indexOf('http://') === 0 || url.indexOf('https://') === 0)) {
        return undefined;
    }
    return originalReplaceState.call(this, state, title, url);
};

这样可以防止 SPA（单页应用）类型的网站在 iframe 中进行路由导航。

特殊情况处理

懒加载图片

很多网站使用懒加载来优化性能，图片的真实 URL 放在 data-src 或 data-original 属性中：

<img class="lazy" data-src="/images/real-image.jpg" src="/images/placeholder.gif">

我们在重写时需要特殊处理这类图片：

func convertLazyImages(content string) string {
    re := regexp.MustCompile(`<img[^>]*>`)
    
    return re.ReplaceAllStringFunc(content, func(match string) string {
        // 查找 data-original 或 data-src 属性
        lazySrc := extractLazyAttribute(match)
        if lazySrc == "" {
            return match
        }
        
        // 构建新的 img 标签，用 data-src 的值替换 src
        // 同时移除 lazy 相关的 class
        attrs := parseHTMLAttributes(match)
        var newTag strings.Builder
        newTag.WriteString("<img ")
        
        for _, attr := range attrs {
            if attr.Name == "data-original" || attr.Name == "data-src" {
                continue  // 跳过懒加载属性
            }
            if attr.Name == "class" {
                // 移除 "lazy" 类名
                classValue := strings.ReplaceAll(attr.Value, "lazy", "")
                if classValue != "" {
                    newTag.WriteString(fmt.Sprintf(`class="%s" `, classValue))
                }
                continue
            }
            if attr.Name == "src" {
                continue  // 跳过原始的占位图 src
            }
            // 复制其他属性
            newTag.WriteString(fmt.Sprintf(`%s="%s" `, attr.Name, attr.Value))
        }
        
        // 添加真实的图片 URL 作为 src
        newTag.WriteString(fmt.Sprintf(`src="%s">`, lazySrc))
        
        return newTag.String()
    })
}

HTML 实体解码

URL 中可能包含 HTML 实体编码：

<img src="image.jpg?a=1&amp;b=2">

在处理前需要解码：

// 解码 HTML 实体
srcURL = html.UnescapeString(srcURL)
// image.jpg?a=1&amp;b=2 → image.jpg?a=1&b=2

Electron 是怎么做的？

尽管我们已经做了如此多的努力——HTML 重写、CSS URL 处理、JavaScript 拦截、History API 阻断……但坦白说，这套方案仍然无法完美解决所有问题。

在实际使用中，我们发现了一些几乎不可能通过反向代理解决的问题：

WebSocket 连接

很多现代网站使用 WebSocket 进行实时通信。WebSocket 的握手过程和持久连接机制，使得简单的 HTTP 代理难以处理：
```
// 网站可能这样建立 WebSocket 连接
const ws = new WebSocket('wss://example.com/socket');
```
我们的代理需要支持 WebSocket 协议升级，并且维护长连接——这大大增加了实现的复杂度。
Service Worker

Service Worker 是一种在浏览器后台运行的脚本，可以拦截网络请求、管理缓存。当目标网站使用 Service Worker 时：
```
// Service Worker 可以完全接管网络请求
self.addEventListener('fetch', event => {
    event.respondWith(caches.match(event.request));
});
```
Service Worker 的注册和作用域管理与同源策略紧密相关，我们的代理方案很难正确处理。
复杂的身份验证

有些网站使用基于 Cookie 的复杂身份验证流程，包括 CSRF Token、SameSite Cookie 属性等。由于我们的代理不转发 Cookie，用户无法在 iframe 中登录或保持登录状态。
iframe 嵌套检测

一些网站会使用 JavaScript 检测自己是否运行在 iframe 中：
```
// 常见的 iframe 检测代码
if (window.self !== window.top) {
    // 在 iframe 中，可能会拒绝显示或跳转
    window.top.location = window.self.location;
}
```
虽然我们尝试通过 sandbox 属性阻止跳转，但有些检测逻辑会直接隐藏内容或显示警告。
某些 JavaScript 框架的兼容性

现代前端框架（React、Vue、Angular）在构建时可能会硬编码一些绝对路径或域名。这些代码嵌入在压缩混淆后的 JavaScript 中，很难通过静态重写来修改。

归根结底，反向代理方案是在应用层面模拟浏览器的行为。我们试图欺骗网页，让它以为自己运行在正常的浏览器环境中。但浏览器的安全模型是经过精心设计的，想要完美地绕过它，需要付出极大的努力——而且永远存在边界情况。

有没有一种方案，能够从根本上解决这个问题呢？

Electron 提供了一个特殊的 <webview> 标签，专门用于在应用中嵌入外部网页：

<webview id="foo" src="https://www.github.com/" style="width:640px; height:480px"></webview>

与普通的 <iframe> 不同，<webview> 有几个关键特性：

独立进程

Unlike an iframe, the webview runs in a separate process than your app. It doesn’t have the same permissions as your web page and all interactions between your app and embedded content will be asynchronous. This keeps your app safe from the embedded content.

<webview> 运行在独立的渲染进程中，与主应用完全隔离。这意味着：
- 嵌入的网页无法访问主应用的 DOM
- 崩溃不会影响主应用
- 安全边界清晰
可禁用 Web 安全
```
<webview src="https://www.github.com/" disablewebsecurity></webview>
```
通过 disablewebsecurity 属性，可以禁用嵌入页面的 Web 安全策略。这意味着 CORS 不再是问题——网页可以自由请求任何资源，不受同源策略限制。

完整的 API 支持

Electron 的 webview 提供了丰富的 API：

const webview = document.querySelector('webview');

// 导航控制
webview.loadURL('https://example.com');
webview.reload();
webview.goBack();
webview.goForward();

// 注入脚本
webview.executeJavaScript('document.body.innerHTML');

// 注入 CSS
webview.insertCSS('body { background: red; }');

// 缩放控制
webview.setZoomFactor(1.5);

// 页面截图
const image = await webview.capturePage();

// 打印
webview.print();

丰富的事件系统

webview.addEventListener('did-start-loading', () => {
    console.log('开始加载');
});

webview.addEventListener('did-finish-load', () => {
    console.log('加载完成');
});

webview.addEventListener('did-fail-load', (event) => {
    console.log('加载失败', event.errorCode, event.errorDescription);
});

webview.addEventListener('console-message', (event) => {
    console.log('Guest 页面日志:', event.message);
});

Electron 官方文档揭示了 webview 的实现原理：

Under the hood webview is implemented with Out-of-Process iframes (OOPIFs). The webview tag is essentially a custom element using shadow DOM to wrap an iframe element inside it.

<webview> 底层使用了 Chromium 的 OOPIF（Out-of-Process iframe） 技术。它本质上是一个使用 Shadow DOM 封装 iframe 的自定义元素，但这个 iframe 运行在独立的渲染进程中，拥有更高的权限和更低的安全限制。

然而，Electron 官方已经不推荐使用 <webview> 标签：

⚠️ Warning: Electron’s webview tag is based on Chromium’s webview, which is undergoing dramatic architectural changes. This impacts the stability of webviews, including rendering, navigation, and event routing. We currently recommend to not use the webview tag and to consider alternatives, like iframe, a WebContentsView, or an architecture that avoids embedded content altogether.

官方推荐使用 WebContentsView（类似于之前的 BrowserView）作为替代方案。WebContentsView 是一个独立的窗口组件，可以覆盖在主窗口之上，实现类似的效果。

尽管如此，Electron 的解决思路给了我们重要的启示：要从根本上解决 iframe 的限制，需要在框架层面提供原生的 webview 支持。

从根源解决：为 Wails 贡献 `WebviewPanel`

MrRSS 使用的是 Wails 框架——一个轻量级的 Go + Web 技术栈桌面应用框架。相比 Electron 动辄 100MB+ 的体积，Wails 应用通常只有 10-20MB，因为它使用系统自带的 WebView 而不是打包 Chromium。

Wails 在不同平台使用不同的 WebView 引擎：

平台	WebView 引擎
Windows	WebView2 (基于 Edge/Chromium)
macOS	WKWebView (WebKit)
Linux	WebKitGTK

这种设计使得 Wails 应用体积小巧、启动迅速。但也带来了一个问题：Wails v3 之前没有提供嵌入独立 webview 的能力。

既然现有方案都不能完美解决问题，那就只能从框架层面入手了。我向 Wails 项目提交了一个 PR：feat(v3): Add WebviewPanel for embedding multiple webviews in a window #4880。

这个 PR 的目标是实现一个类似 iframe 的效果，但可以绕过 CORS 等问题。具体来说，WebviewPanel 需要支持：

在主窗口中嵌入多个独立的 WebView
每个 WebView 拥有独立的浏览器上下文
可以自由控制位置、大小、层级
提供完整的导航和交互 API

WebviewPanel 的核心是利用各平台原生的 WebView 组件，在每个平台上的实现略有不同：

Windows (WebView2)

// 创建独立的 WebView2 控制器
CreateCoreWebView2Controller(hwnd, callback);

// 设置边界
webviewController->put_Bounds(bounds);

// 导航到 URL
webview->Navigate(url);

macOS (WKWebView)

// 创建 WKWebView
let webView = WKWebView(frame: bounds, configuration: config)

// 添加到窗口
window.contentView?.addSubview(webView)

// 加载 URL
webView.load(URLRequest(url: url))

Linux (WebKitGTK)

// 创建 WebKit WebView
GtkWidget *webview = webkit_web_view_new();

// 设置位置和大小
gtk_fixed_put(GTK_FIXED(container), webview, x, y);
gtk_widget_set_size_request(webview, width, height);

// 加载 URL
webkit_web_view_load_uri(WEBKIT_WEB_VIEW(webview), url);

WebviewPanel 对外暴露了简洁而强大的 TypeScript API：

创建与基本操作

import { WebviewPanel } from '@wailsio/runtime';

// 创建一个新的 WebviewPanel
const panel = WebviewPanel.New();

// 导航到 URL（这就是我们需要的！无 CORS 限制！）
panel.SetURL('https://example.com/article');

// 获取当前 URL
const url = panel.GetURL();

// 设置 HTML 内容
panel.SetHTML('<h1>Hello World</h1>');

位置与大小控制

// 设置绝对位置和大小
panel.SetBounds(100, 100, 800, 600);  // x, y, width, height

// 获取当前边界
const bounds = panel.GetBounds();
console.log(bounds.x, bounds.y, bounds.width, bounds.height);

可见性与层级

// 显示/隐藏
panel.SetVisible(true);
const isVisible = panel.IsVisible();

// 设置 Z 轴顺序（多个 panel 时的层级关系）
panel.SetZOrder(1);  // 数字越大越靠前

// 聚焦
panel.Focus();

高级功能

// 缩放
panel.SetZoom(1.5);  // 150%
const zoom = panel.GetZoom();

// 打开开发者工具（调试用）
panel.OpenDevTools();

// 销毁
panel.Destroy();

有了 WebviewPanel，在 Vue 中使用变得非常简单：

<script setup lang="ts">
import { ref, onMounted, onUnmounted, watch } from 'vue';
import { WebviewPanel } from '@wailsio/runtime';

const props = defineProps<{
  url: string;
  visible: boolean;
}>();

const panelRef = ref<HTMLDivElement>();
let panel: WebviewPanel | null = null;

onMounted(() => {
  // 创建 WebviewPanel
  panel = WebviewPanel.New();
  
  // 根据容器位置设置 panel 边界
  updateBounds();
  
  // 加载 URL
  panel.SetURL(props.url);
  panel.SetVisible(props.visible);
});

function updateBounds() {
  if (!panel || !panelRef.value) return;
  
  const rect = panelRef.value.getBoundingClientRect();
  panel.SetBounds(rect.left, rect.top, rect.width, rect.height);
}

watch(() => props.url, (newUrl) => {
  panel?.SetURL(newUrl);
});

watch(() => props.visible, (visible) => {
  panel?.SetVisible(visible);
});

onUnmounted(() => {
  panel?.Destroy();
});
</script>

<template>
  <div ref="panelRef" class="webview-container"></div>
</template>

<style scoped>
.webview-container {
  width: 100%;
  height: 600px;
  background: #f0f0f0;
}
</style>

总结

让我们对比一下三种嵌入外部网页的方案：

特性	反向代理 + iframe	Electron webview	Wails WebviewPanel
CORS 绕过	✅ 通过代理绕过	✅ 可禁用安全策略	✅ 独立 WebView 无限制
X-Frame-Options	✅ 代理移除	✅ 不受限制	✅ 不受限制
CSP 限制	✅ 代理移除	✅ 不受限制	✅ 不受限制
动态 JS 请求	⚠️ 需要拦截脚本	✅ 自动处理	✅ 自动处理
WebSocket	❌ 难以处理	✅ 原生支持	✅ 原生支持
Service Worker	❌ 难以处理	✅ 原生支持	✅ 原生支持
Cookie/登录	❌ 不支持	✅ 独立会话	✅ 独立会话
进程隔离	❌ 同一进程	✅ 独立进程	✅ 独立进程
实现复杂度	🔴 高（需大量代码）	🟢 低（框架内置）	🟢 低（框架内置）
应用体积	🟢 无影响	🔴 +100MB+	🟢 无影响
兼容性	⚠️ 部分网站不兼容	🟢 几乎全兼容	🟢 几乎全兼容

相关链接：

MrRSS 项目 - 本文所述的 RSS 阅读器
Wails WebviewPanel PR #4880 - 为 Wails 贡献的 WebviewPanel 功能
Electron webview 文档 - Electron 官方 webview 标签文档
Wails 官网 - 轻量级 Go + Web 桌面应用框架

Vibe Coding 一个复杂项目——问题与经验分享

mail@ch3nyang.top (Ch3nyang) — Tue, 16 Dec 2025 00:00:00 +0800

从两年前开始，我就一直想做一个自带翻译功能的 RSS 阅读器。结果，在我基础功能写完后，RSSNext/Folo 横空出世，把我想做的功能全都实现了，于是我不再开发自己的这个项目，转而去给 Folo 做贡献。

不过，随着 Folo 本身盈利压力的增大，它的开发重心全部转移到了没有卵用的 AI 功能上，然后阉割了很多基础功能，要求用户每月付费 6.67 刀才能使用。

不是哥们儿!？我只是想要一个翻译功能，这值得这么多钱吗？

于是乎，我捡起了之前搁置的项目，决定重新开发一个属于自己的 RSS 阅读器。

开发一个 RSS 阅读器听起来很简单，比如在 Go 语言下拿 mmcdole/gofeed 处理下 RSS 源，然后糊个前端界面就完事了。不过，一旦你想加点花哨的功能，比如自动翻译、AI 摘要、智能发现订阅源，复杂度就一下子上去了。

这次，我还想搞点花活儿：从需求分析、架构设计、代码生成，到测试和发布，全程让 AI 去做，我只负责把关和调试。我选择了 GitHub Copilot (Claude Opus 4.5 + Claude Sonnet 4.5 + Gemini 3 Pro + Grok Code Fast) 作为主要的 AI 助手，偶尔用其它模型补充一些工作。

一个月下来，AI 总共帮我提交了接近 100 个 PR，400 多次 commit，其中超过 95% 的代码全部为 AI 生成。项目也获得了不少用户，基本走向成熟。

GitHub 仓库	下载地址	Landing Page
WCY-dt/MrRSS	MrRSS Releases	MrRSS 官网

~~然而，这个软件要比「小猫补光灯」复杂得多~~。一个众所周知的事情是：用 AI 做需求是很容易的，但要做很多需求，并且这些需求全是 AI 写的，就纯折磨了。在开发过程中，我不出意外地遇到了不少问题，这里来和大家分享一下我的经验教训。

CI/CD for AI

一个极为棘手的问题是，很多功能是在多个模块之间协同完成的，存在一定的耦合关系。尽管 AI agent 会去阅读项目代码，但它并不清楚整体架构和模块边界。在代码文件数过百后，AI 就经常迷失方向，改了这块没改那块。

我当然可以每次都把项目的相关信息塞进 prompt 里，但这样一来，prompt 会变得非常庞大，导致生成质量下降，甚至超出模型的上下文窗口。不过，我偶然在别人的项目里发现了 AI 支持自动读取特定文档的功能，于是我也给 MrRSS 写了一些「说明书」。主要是 AGENTS.md 和 .github/copilot-instructions.md：

# AI Agent Guidelines for MrRSS

## Project Overview

**MrRSS** is a modern, privacy-focused, cross-platform desktop RSS reader.

### Tech Stack

- **Backend**: Go 1.24+ with Wails v2.11+ framework, SQLite with `modernc.org/sqlite`
- **Frontend**: Vue 3.5+ Composition API, Pinia, Tailwind CSS 3.3+, Vite 5+, TypeScript
- **Communication**: HTTP REST API (not Wails bindings)
- **Icons**: Phosphor Icons | **I18n**: vue-i18n (English/Chinese)

...

其中，.github/copilot-instructions.md 是 GitHub Copilot 专用的说明文件，AGENTS.md 则是 Codex、Claude Code 等其他 AI agent 通用的说明文件。每次让 AI 写代码前，无需我说明，它都会自动先去读这些文档。

这些文档主要包含了：

项目概览
项目模块与文件结构
关键技术与规范
开发流程指南
- 总体流程
- 辅助脚本
- 代码组织
- 代码质量管理
代码风格指南
- 前端 / 后端
- 安全性实践

不过，随着项目变得越来越复杂，这些文档达到了接近 3000 行！为了防止一次性占用过多上下文，我对文档进行了拆分：

.github
- copilot-instructions.md
docs
- ARCHITECTURE.md
- CODE_PATTERNS.md
- TESTING.md
- VERSION_MANAGEMENT.md
AGENTS.md

只需要 在 copilot-instructions.md 和 AGENTS.md 的开头给出 docs/ 目录的索引，AI 就能自动去读取相关内容。

> **Quick Links**: [Architecture](docs/ARCHITECTURE.md) | [Code Patterns](docs/CODE_PATTERNS.md) | [Testing](docs/TESTING.md) | [Version Management](docs/VERSION_MANAGEMENT.md)

之后，如果有任何新功能需要跨模块协作，我只需修改相关文档，AI 就可以很好地遵循这些规则去写代码了。

统一的开发命令

每次做完修改后，AI 都要跑一边 lint、test、format 等常用操作。由于 AI 每次跑完一条命令都需要读取结果并思考下一步该做什么，这就导致光是这些固定流程就占用了大量的上下文窗口，而且跑完一次要耗时接近 20 分钟！

为了进一步方便 AGENT 执行，我 为常用操作写了一套 Makefile：

点击展开 Makefile 代码

# Makefile for MrRSS (Cross-platform)
.PHONY: help build build-frontend build-backend test test-frontend test-backend lint lint-frontend format format-frontend clean dev setup install-deps update-deps check pre-commit release-check

# Detect OS
ifeq ($(OS),Windows_NT)
    DETECTED_OS := Windows
    SHELL := pwsh.exe
    .SHELLFLAGS := -Command
else
    DETECTED_OS := $(shell uname -s)
    SHELL := /bin/bash
endif

# Default target
help: ## Show this help message
	@echo "MrRSS Development Makefile ($(DETECTED_OS))"
	@echo ""
	@echo "Available targets:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-20s %s\n", $$1, $$2}'

# Development
dev: ## Start development server
	wails dev

# Building
build: build-frontend build-backend ## Build both frontend and backend
	wails build -skipbindings

build-frontend: ## Build frontend only
	cd frontend && npm run build

build-backend: ## Build backend only (verify compilation)
	go build -v ./...

# Testing
test: test-frontend test-backend ## Run all tests

test-frontend: ## Run frontend tests
	cd frontend && npm test

test-backend: ## Run backend tests
	go test -v -timeout=5m -cover ./internal/...

test-coverage: ## Run backend tests with coverage
	go test -v -timeout=5m -coverprofile=coverage.out -covermode=atomic ./internal/...
	go tool cover -html=coverage.out -o coverage.html
	@echo "Coverage report generated: coverage.html"

# Code Quality
lint: lint-frontend lint-backend ## Run all linters

lint-frontend: ## Run frontend linter
	cd frontend && npm run lint

lint-backend: ## Run backend linter
	go vet ./...
ifeq ($(DETECTED_OS),Windows)
	powershell -Command '$$result = gofmt -d . ; if ($$result) { Write-Host $$result -ForegroundColor Red; exit 1 }'
	powershell -Command '$$importsResult = goimports -d . ; if ($$importsResult) { Write-Host $$importsResult -ForegroundColor Red; exit 1 }'
else
	gofmt -d . | tee /dev/stderr | test -z "$$(cat)"
	goimports -d . | tee /dev/stderr | test -z "$$(cat)"
endif

format: format-frontend format-backend ## Format all code

format-frontend: ## Format frontend code
	cd frontend && npm run format

format-backend: ## Format backend code
	gofmt -w .
	goimports -w .

# Dependencies
install-deps: install-frontend-deps install-backend-deps ## Install all dependencies

install-frontend-deps: ## Install frontend dependencies
	cd frontend && npm install

install-backend-deps: ## Install backend dependencies
	go mod download

update-deps: update-frontend-deps update-backend-deps ## Update all dependencies

update-frontend-deps: ## Update frontend dependencies
	cd frontend && npm update

update-backend-deps: ## Update backend dependencies
	go get -u ./...
	go mod tidy

# Setup
setup: install-deps ## Initial project setup
	pre-commit install

# Cleanup
clean: ## Clean build artifacts
ifeq ($(DETECTED_OS),Windows)
	powershell -Command "Remove-Item -Path 'build\bin\*' -Recurse -Force -ErrorAction SilentlyContinue"
	powershell -Command "Remove-Item -Path 'frontend\dist' -Recurse -Force -ErrorAction SilentlyContinue"
	powershell -Command "Remove-Item -Path 'frontend\node_modules\.vite' -Recurse -Force -ErrorAction SilentlyContinue"
	powershell -Command "Remove-Item -Path 'coverage.out', 'coverage.html' -ErrorAction SilentlyContinue"
else
	rm -rf build/bin/*
	rm -rf frontend/dist
	rm -rf frontend/node_modules/.vite
	rm -f coverage.out coverage.html
endif

# Development helpers
check: lint test build ## Run full check (lint, test, build)
ifeq ($(DETECTED_OS),Windows)
	powershell -File scripts/check.ps1
else
	./scripts/check.sh
endif

pre-commit: ## Run pre-commit hooks on all files
	pre-commit run --all-files

release-check: check ## Run all checks before release
ifeq ($(DETECTED_OS),Windows)
	powershell -File scripts/pre-release.ps1
else
	./scripts/pre-release.sh
endif

可以看到，这里面使用了大量的现有工具（go vet、gofmt、goimports、pre-commit、npm lint、npm test 等），把它们统一封装在一个简单的命令行界面下。AI 每次需要运行测试或检查代码时，只需执行 make test 和 make lint，或是提交前直接由 pre-commit 触发，而不需要逐个执行一大堆复杂的命令。

测试的陷阱

后端部分是很好测试的，只要稍微提高一下测试覆盖率，AI 就能很容易地判断代码正确与否。

然而，对于 AI 来说，前端和运维的测试就麻烦多了：

前端部分

前端部分可以使用 Playwright 做 E2E 测试，但 Playwright 完全依靠 HTML 文本作为给 AI 的上下文，AI 实际上并不是真正「看」到了界面。因此，一些前端的 bug 很难让 AI 发现并修复。

例如，软件的 v1.2.16 和 v1.2.18 版本在发布后，均有用户反馈称设置项无法正常修改和保存：

[BUG]设置无法保存 配置完成不生效，未自动保存。

尽管我多次要求 AI 修复这个问题，但它每次都是凭感觉改改，却根本无法复现这个 bug ——因为在 Playwright 的测试结果里，所有的设置项看起来都被正确修改了。问题出在界面没有正确响应用户操作上：虽然输入框里的值变了，但实际上并没有触发 change 事件，导致后端根本没收到更新请求。而 AI 却无法看到这个结果。

为了解决这个问题，我一方面 对关键功能加上了集成测试和基于 cypress-io/cypress 的 E2E 测试。每次在 AI 提交代码后，都会跑一遍这些测试，确保没有破坏核心功能。

另一方面，对于 AI 没有能力修复的问题，我还是不得不 亲自调试前端代码，找出问题所在，然后让 AI 根据我的分析去修复代码。修复完成后，再手动检查一遍，确保没有遗漏。

运维部分

运维部分更是难上加难。比如说，AI 可能会帮我写 GitHub Actions 的工作流，但它并不清楚这个工作流能不能成功运行，只能凭经验猜测。结果就是，很多次 AI 写完工作流，我跑了一遍发现构建失败，然后又让 AI 去修复，反复折腾了好几次。

比如，我用于版本发布的 release 工作流，总是在 darwin 的 runner 上运行失败。AI 每次修改后，会在我本地机器上模拟运行一遍，但我的机器是 Windows！！！其实 AI 已经发现了问题在于 getlantern/systray 包和 wails 在 CGO 下的 AppDelegate 符号冲突，但它尝试改过后无法验证，便信誓旦旦地告诉我已经修好了。

为此，我跟 AI 来回折腾了十多个 commit 依然没有解决，最终还是靠搜索到 jmylchreest 解决过类似的问题，向他询问后才终于搞定：

I noticed that in commit 7bdadc6 you disable macOS build due to AppDelegate symbol conflict.

I also encountered this problem in my own project. Have you found any solutions now?

Actually yes, I bumped to using the git version of fyne.io/systray which looks to unblocks this but i’ve not re-enabled the macos build to test it. In theory, keylightd-tray should work on macos now.

replace fyne.io/systray => github.com/fyne-io/systray v1.11.1-0.20250812065214-4856ac3adc3c

当然，这个问题至此依然没有彻底解决，我们后面还会继续折腾它。

难以测试，再加上 AI 声称代码没有问题，导致很多 bug 总是修复不好。

怎么办呢？我也没有办法。现在，运维的 bug 我最多让 AI 帮我改一次，改不好就自己动手了。

屎山是怎样炼成的

AI 有个特点：你让它加功能，它就加功能。至于代码组织、可维护性？不存在的！

何时重构？

项目初期，AI 把所有的 HTTP 处理函数都放在一个 handlers.go 文件里。第一天，200 行，挺清爽的。第二天，500 行，还行。一周后……3000 多行，文章、订阅源、设置、发现、翻译，全挤在一个文件里。

我实在看不下去了，让 AI 重构一下后端代码。

结果它把 3000 行代码拆成了十几个文件——但拆分方式完全随机。handleGetArticle 在 article.go 里，handleMarkAsRead 却跑到了 utils.go 里。我找一个函数要在 5 个文件之间跳转，比之前更难维护了。

这时候我才意识到：AI 没有代码洁癖。它不会主动考虑这样写未来好不好改，只关心现在能不能跑。

我试图通过前文所述的代码风格指南来规范它的行为，但效果并不理想，它依然会到处拉屎，拉完还不擦。怎么办呢？我设计了一个微型工作流：

flowchart LR
    A[检测代码库] --> B{是否有大文件<br>或杂乱文件夹？}
    B -- 是 --> C[/通知开发者/] --> D[/开发者确认<br>重构方案/] --> E[生成重构 PR] --> F[AI 执行重构<br>并修改 AI 文档]
    B -- 否 --> G((结束))

该工作流会去 检测是否有文件过大 ($> 400$ 行) 或者文件夹过杂 ($> 10$ 个文件)；最终重构的方案也是由我来定，而不是让 AI 天马行空自由发挥。

当然，每次 AI 写完代码后，我也会 review 一遍，发现可能需要重构的地方，就让它继续修改。虽然麻烦，但总比等到屎山彻底成型后再重构要好。

如何重构？

我在手动重构时比较喜欢参考 Martin Fowler 的《Refactoring: Improving the Design of Existing Code》一书；让 AI 重构时，我也会将类似的指令传递给它。

AI 很容易理解需要如何重构、重构后期望的效果，但问题出在它重构后的代码总是缺斤少两，造成大量错误，甚至可以把功能重构没了！

例如，书接上文 macOS 下的编译问题，我发现即便编译通过了，依然存在大量 bug —— wails2 框架在 macOS 下对 CGO 的支持实在太烂了。我让 AI 帮我重构了一下相关代码，将 wails2 升级到 wails3。

我一方面给了明确的重构要求，另一方面将 wails3 的升级指南和文档链接都塞给了 AI 让它自己去访问阅读。AI 能够理解升级的关键点，并且在重构过程中参考这些资料，但我很快发现了问题：它最后只重构了 systray 部分，其它该对应迁移的部分却根本没动。当然，这个状态是过不了测试的，AI 在尝试了几次后，竟然直接摆烂说修不了，把问题甩给我了！

我经过仔细分析后发现，问题出在上下文长度上：它的上下文长度足够读完相关文档，但在修改完一个功能后，上下文长度已经不足，于是触发了 auto summarization，把之前的内容都给压缩掉了，导致它忘记了之前看过的技术细节。为此，我先让 AI 制定一个详细的重构方案，并将其拆分为多个小模块（systray、Taskfile、Window options、Browser integration 等）:

Core API Migration

Replace wails.Run(&options.App{...}) → application.New(application.Options{...}).Run()
Windows created via app.Window.NewWithOptions() instead of options struct
runtime.WindowSetSize(ctx, ...) → window.SetSize(...)
OnBeforeClose → window.RegisterHook(events.Common.WindowClosing, ...)
SingleInstanceLock → SingleInstance with encryption key

System Tray

Remove fyne.io/systray dependency
Delete internal/tray/ package
Use Wails v3 built-in app.SystemTray.New() API

Configuration

Update go.mod to github.com/wailsapp/wails/v3
Remove deprecated wailsjsdir from wails.json
Update Makefile to use wails3 CLI

Documentation

Update BUILD_REQUIREMENTS.md with v3 dependencies (libsoup-3.0-dev)
Update ARCHITECTURE.md framework version reference

GitHub Actions Auto-Detection

Updated test.yml, pre-release-check.yml, and release.yml to auto-detect Wails version
Detection checks go.mod for wailsapp/wails/v3 vs wailsapp/wails/v2
Installs correct CLI (wails3 for v3, wails for v2)
Uses correct build commands per version
Installs correct Linux dependencies (v3: libsoup-3.0-dev, v2: libayatana-appindicator3-dev)

然后逐个模块地进行重构，每次重构时都让它再读一次文档。这样，尽管 Token 花费更多，但结果的准确率也大幅提升。

根据我的观察，AI 重构代码时出现问题，主要有以下几个原因：

上下文丢失

单个文件内重构时普遍准确率较高；但跨文件重构时，受限于上下文长度，AI 只能大致理解各个模块之间的依赖关系，但缺乏对细节的准确记忆，导致遗漏重要的调用或数据传递。但如果让 AI 一小块一小块地重构，又会导致整体一致性差，缺乏大局观。

为此，我设计了两步重构法：
1. 整体规划：首先让 AI 阅读相关文件，理解它们的功能和依赖关系，然后生成一个重构方案并以文档形式记录下来。该方案需要明确哪些函数或类应该移动到哪个文件中，哪些函数可以做提取及合并，以及如何调整它们之间的调用关系。然后对这些方案细则进行组合，形成一个个更小的分步骤。
2. 分步执行：接着，逐步让 AI 按照方案执行重构。每次只重构一个分步骤，然后运行测试以验证重构后的代码是否正确。若测试通过，则继续下一个步骤；若测试失败，则让 AI 分析失败原因并修复代码，然后再运行测试。
测试覆盖不足

如果重构前的代码没有足够的测试覆盖，AI 便只能凭感觉去重构，而无法验证重构后的代码是否正确。然而，我发现即使有测试、并且测试报错了，AI 也会认为报错是由于重构后测试不满足当前需求所致，而不是重构本身的问题，转头去修改测试代码！

我在实际操作中发现，只有当重构前的代码有超过约 70% 的测试覆盖率时，AI 才能较为准确地完成重构任务。

所以，AI 能取代程序员吗？

写到这里，我想我可以给出一个答案了。

不能，至少现在不能。

但这并不意味着 AI 没用。恰恰相反，若是没有 AI 的帮助，我可能需要至少三个月才能完成 MrRSS 的开发工作，而现在只用了一个月。

AI 学东西很快，代码写得利索，CRUD 这种活儿闭着眼都能干。但你不能把需求丢给它就不管了——它可能理解错需求，可能埋下隐蔽的 bug，可能写出难以维护的代码。你得给它明确的规范，得 review 它的产出，得在关键决策上把关。

你需要知道什么是好的代码，才能判断 AI 给的代码好不好；
你需要懂系统设计，才能把模块边界划清楚；
你需要有调试经验，才能在 AI 说没问题的时候自己找到问题。

某种意义上，AI 的出现不是降低了对程序员的要求，而是提高了。以前你可以是一个只会写代码的码农，现在你得是一个懂产品、懂设计、懂质量的工程师。

AI 是工具，不是魔法。它能帮你更快地实现想法，但无法替你思考。

越过长城，走向世界——翻墙协议的历史与原理浅析

mail@ch3nyang.top (Ch3nyang) — Wed, 19 Nov 2025 23:00:00 +0800

免责声明 本文仅从技术研究与网络安全教育角度分析网络流量混淆与穿透技术。请遵守所在国家或地区的法律法规。在中国大陆地区，未经授权建立或使用非法信道进行国际联网属于违法违规行为。

由于 GFW（Great Firewall）的存在，用户不得不使用各种翻墙协议绕过这些限制。这些协议发展了多年，伴随着技术的进步和 GFW 的不断升级，形成了多种不同的翻墙方案，和 GFW 玩起了猫鼠游戏。

GFW 技术简介

在讨论如何翻过 GFW 前，有必要先了解 GFW 是如何运作的。GFW 主要通过以下几种技术手段来限制用户访问：

DNS 污染 (DNS Poisoning) 通过篡改 DNS 响应，使用户无法解析某些域名。

例如，当用户访问 https://google.com 时，DNS 查询需要使用 UDP 协议发送到 DNS 服务器的 53 端口。该查询包在经过骨干网时，GFW 会检测到该查询，并抢先返回一个错误的 IP 地址，导致用户无法访问 Google。

目前，几乎所有知名的被墙网站都遭受了 DNS 污染。
IP 封锁 (IP Blocking) 直接封锁某些 IP 地址，使用户无法与这些地址建立连接。

例如，某些 VPN 服务器在工作一段事件后被 GFW 识别到，就会封锁其 IP 地址，导致用户无法连接。
深度包检测 (DPI, Deep Packet Inspection) 通过分析数据包的内容，识别并阻断特定协议的流量。

其主要包含：
- 关键字阻断 (Keyword Blocking) 检测数据包中的敏感关键字，并阻断包含这些关键字的流量。
  
  例如，如果拆包获得的报文头中包含敏感词（如 Host: facebook.com），GFW 会发送 RST 包终止连接。
- 协议指纹识别 (Protocol Fingerprinting) 通过分析协议特征，识别并阻断特定协议的流量。
  
  例如，OpenVPN 使用特定的握手方式和加密算法，产生了固定的字节序列。GFW 可以通过这些特征识别并阻断 OpenVPN 流量。
主动探测 (Active Probing) GFW 会主动向可疑服务器发送探测请求，以确认其是否为翻墙服务器。

例如，当 GFW 发现某个 IP 地址有大量加密流量，怀疑其为代理服务器时，可能会伪装成客户端，向该地址发送特定的探针包。如果服务器按照代理协议响应了这些探针包，GFW 就会将其列入封锁名单。
流量特征分析 (Traffic Pattern Analysis) 使用机器学习等技术，分析数据包的大小分布、发包频率、握手时延等特征，识别翻墙流量。
白名单模式 去年，泉州等地开始试点白名单模式，默认阻断所有境外流量，只有经过审核的流量才能通过。这一措施大大增加了翻墙的难度。

常见代理协议

传统 VPN

VPN 是一种通过加密隧道连接到远程服务器的技术。用户的所有流量都会通过这个加密隧道传输，从而隐藏真实 IP 地址并保护数据隐私。从技术实现上来讲，数据包会被封装在一个加密的外层协议中，发送到 VPN 服务器，然后由服务器将数据包解封装并转发到目标网站。网站返回的数据包会先发送到 VPN 服务器，再由服务器加密并通过隧道传输回用户。

下面是一个传统 VPN 工作原理的示意图：

我们在之前的文章 VPN Tunneling 中做了一些更加技术化的介绍。

对于传统 VPN，它们的初衷是安全，而不是伪装。因此在建立连接时，它们会有一个固定的握手头 (Handshake Header)。其特征过于明显，传统 VPN 协议（如 PPTP、L2TP/IPsec、OpenVPN）已经很容易被 GFW 的 DPI 识别和封锁。

尤其是 OpenVPN，由于其广泛使用，GFW 已经积累了大量的协议指纹，可以轻松识别并阻断其流量。

Shadowsocks (SS)

SS 于 2012 年由 Clowwindy 开发。它是一种轻量级的代理协议，基于 SOCKS5，使用加密技术保护数据传输。它的客户端和服务端会商讨使用一致的加密算法（如 AES、ChaCha20），然后对数据进行加密，使得流量看起来像随机噪声。因此，即便 GFW 进行 DPI 解包，看到的也是一堆乱码，而读取不到原始报文的头部，无法对协议头进行模式匹配。

下面是 SS 工作的流程图：

SS 最大的创新还在于搞出了 PAC 文件，使得用户可以灵活地选择哪些流量走代理，哪些流量直连。从而，用户不再需要像以前的 VPN 一样所有流量都到海外去绕一圈了。

然而，魔高一尺道高一丈，GFW 在更新后不再仅限于 DPI，还加入了流量分析的手段。对于 SS，存在两大问题：

主动探测 (Active Probing) 尽管没有协议头，但完全随机的数据本身在互联网中就是一种异常特征。对于一段连接，GFW 会截获第一条报文，如果报文满足熵较高的特点，就会标记为可疑连接。在一些情况下，会直接被拦截
重放攻击 (Replay Attack) GFW 截获一段加密流量，稍后原封不动地发给服务器。通过观察服务器的反应（TCP Reset 或无响应的时长），GFW 就能推断出这台服务器是否运行着 SS 服务，进而封锁 IP

详情可见 GFW Report - Shadowsocks 是如何被检测和封锁的。

目前，SS 几乎已经完全不可用，GFW 的封锁手段已经非常成熟。只剩下少数专线机场在使用 SS 协议。

2015 年 8 月 22 日，Clowwindy 宣布迫于中国警方的压力，退出 Shadowsocks 的开发并删除其 GitHub 页面的源代码。

ShadowsocksR (SSR)

SS 作者被喝茶并没有阻止 SS 的发展，相反，此后 SS 社区变得更加活跃。2015 年，breakwa11 基于 SS 创建了一个分支项目 ShadowsocksR (SSR)，并在 GitHub 上开源。

相比于 SS 直接将报文加密后就发送，SSR 使用 obfs 插件，在外层额外封装了一层用于伪装的壳子。例如，使用 http_simple 插件后，会加上一个假的 HTTP 请求头，使得 GFW 误以为其为正常的 HTTP 流量，而不是完全随机的数据。

然而，SSR 的手段实在有些拙劣，对于包含上下文分析的 DPI 手段来讲，可以很轻松地识别出这些 HTTP 请求并不符合正常的浏览器行为，从而被识破。

2017 年 7 月 24 日，breakwa11 发布了一个闭源版本的 SS，引发争议。

2017 年 7 月 27 日，breakwa11 宣布自己被恶俗 TV 开盒，删除了所有代码，停止了 SSR 项目。

VMess

VMess 是 V2Ray 项目中的核心协议。相较于 SSR 只套个伪装壳子，VMess 是真真正正地伪装成了 HTTPS 流量。

VMess 协议在建立连接时：

使用 TLS 进行加密，这使得流量看起来就像是普通的 HTTPS 流量
到达代理服务器后，服务器的 Nginx 会匹配路径
如果匹配上预先设定好的路径，就将解密后的流量反向代理给 V2Ray 进程处理

下面是 VMess 工作的流程图：

更绝的是，这一套方案有诸多扩展，可以进一步伪装流量：

Vmess 本身只是一套加密协议，其外层不但可以使用 TLS，还可以使用 WebSocket、HTTP/2 等协议进行封装，使得流量更加多样化，难以被识别。
通过使用 CDN 服务，使得 GFW 无法直接封禁代理服务器的 IP 地址，因为流量会先经过 CDN 节点。

VMess 的设计使得其在面对 GFW 的封锁时表现出色，成为最流行的翻墙协议之一。然而，其依然有一些潜在的弱点：

性能开销较高 由于使用了多层加密和封装，VMess 的性能开销较高，可能导致延迟增加。
TLS 指纹识别 尽管使用了 TLS，但 GFW 仍然可以通过分析 TLS 握手产生的 JA3 指纹来识别 VMess 流量。尤其是当使用默认配置时，指纹特征较为明显。
SNI 阻断 如果使用了不恰当的 SNI（Server Name Indication）配置，GFW 可能会通过 SNI 字段识别并阻断流量。

更麻烦的是，对于普通用户来讲，VMess 的使用其实是相当麻烦的，需要配置多个组件（如 Nginx、V2Ray），并且需要一定的技术水平来维护和更新。

Trojan

Trojan 由 TrojanGfw 项目于 2019 年开发并开源，旨在提供一种简单而有效的翻墙解决方案。与 VMess 追求功能全面不同，Trojan 专注于简化设计，通过将代理流量伪装成正常的 HTTPS 流量来绕过 GFW 的检测。

Trojan 的核心工作原理如下：

Trojan 服务器在 443 端口上监听所有传入的 HTTPS 流量。它不直接处理加密，而是依赖于 TLS 协议来保护数据传输。
客户端在建立 TLS 连接后，首先发送一个包含预设密码的数据包。如果服务器接收到的第一个数据包匹配密码，则将其识别为代理流量，进行解密并转发到目标地址。
如果第一个数据包不包含密码，服务器会将连接视为普通的 HTTPS 请求，转交给本地的 Web 服务器（如 Nginx）处理，返回真实的网页内容。

这一设计使得 Trojan 能够抗主动探测。GFW 的主动探测会发送各种探针包，但 Trojan 会将所有非代理流量当作正常 HTTPS 处理，返回网页或错误响应，避免暴露服务器身份。

然而，Trojan 需要有效的域名和证书，如果 SNI 被阻断，仍可能失效。同时，用户需要一定的技术知识来配置 TLS 和 Web 服务器。

VLESS / Xray

VLESS 是 V2Ray 项目中的一个简化协议，于 2020 年引入，作为 VMess 的继任者。它去掉了 VMess 中的一些复杂特性，如用户 ID 验证和动态端口，专注于提供高效的加密传输。其设计理念是将加密层与传输层分离，用户可以灵活选择不同的传输协议（如 TCP、WebSocket、HTTP/2）和加密方式（如 AES、ChaCha20），从而适应不同的网络环境。

VLESS 的工作流程大致如下：

客户端与服务器建立传输层连接（如 TCP 或 WebSocket）。
客户端发送目标地址和加密参数。
服务器根据配置进行数据转发，同时应用选定的加密算法。

这一分离设计使得 VLESS 更加模块化和可扩展，但也带来了一个问题：当结合 TLS 时，如果在应用层再套一层 TLS（TLS in TLS），会导致性能开销显著增加，并产生独特的 TLS 指纹，容易被 GFW 的 DPI 和指纹分析识别。

为了解决这一问题，Xray 项目（V2Ray 的一个分支）引入了 XTLS (Xray TLS) 协议。XTLS 不是简单的 TLS 封装，而是一种优化的传输方式：

直接拼接 (Direct Splicing) 在 TLS 握手完成后，XTLS 允许应用层数据直接拼接在 TLS 记录中，避免了额外的加密/解密循环，大幅降低 CPU 使用率和延迟。
指纹伪装 XTLS 通过随机化 TLS 握手参数、使用多种加密套件和扩展，使流量指纹更接近普通 HTTPS 流量，减少被 JA3 或其他指纹识别的风险。
兼容性 XTLS 支持回落 (Fallback) 机制，如果连接不匹配代理流量，会自动转发给其他服务，如真实的 Web 服务器。

Xray 作为 V2Ray 的增强版，不仅支持 VLESS 和 XTLS，还集成了 REALITY 等先进协议，成为对抗 GFW 的强大工具。其优势在于高性能和抗检测能力，但配置相对复杂，需要用户了解各种传输选项。

REALITY

REALITY 是 Xray 项目中的一项创新技术，由 XTLS/REALITY 于 2022 年推出。它不再试图伪装成一个普通的网站服务器，而是选择假扮成大型互联网公司的 CDN 节点，如 Apple、Google 或 Microsoft 的边缘服务器。这种「借尸还魂」的策略使得流量在 GFW 眼中看起来完全合法。

REALITY 的工作原理基于 TLS 握手的 Client Hello 消息：

客户端握手 客户端发送一个伪造的 Client Hello，其中包含目标 CDN 的 SNI（Server Name Indication）和相关参数，使其看起来像是访问真实站点。
服务器验证 REALITY 服务器会将这个握手转发给真实的 CDN 服务器。如果 CDN 响应正常（即握手成功），说明客户端的伪造是有效的。
流量注入 一旦验证通过，服务器使用 XTLS 技术在该合法连接上注入代理数据，进行加密传输和转发。

这一设计带来了显著优势：

无需域名 不需要注册和配置域名，直接利用现有大型站点的证书和 IP。
抗封锁 GFW 难以封锁大型 CDN 的 IP，因为这会影响正常用户访问 Apple 等服务。

REALITY 代表了翻墙技术的最新进展，从这里开始已经几乎完全无法被 GFW 识别和封锁。

Hysteria

与前文介绍的基于 TCP 的协议不同，apernet/hysteria 选择基于 UDP 协议，并模仿 QUIC（Quick UDP Internet Connections）的工作方式。QUIC 是 Google 开发的下一代传输协议，旨在提供低延迟、高可靠性的连接，广泛用于 HTTP/3。

Hysteria 的核心创新在于其拥塞控制算法：

激进拥塞控制 传统 TCP 在检测到丢包时会减速重传，以避免网络拥塞。而 Hysteria 采用相反策略：当检测到丢包时，它会加速发包，试图抢占更多带宽。这种「反直觉」的方法在高丢包、低质量网络环境中表现出色，能够显著提升传输速度和稳定性。
QUIC 伪装 Hysteria 使用 QUIC 的握手和数据格式，使流量看起来像是正常的 QUIC 流量，进一步增强伪装效果。

优势包括：

在弱网环境下（如卫星链路或移动网络），Hysteria 的速度往往超越 TCP 协议。
UDP 流量不易被 DPI 深度检测，且 QUIC 的加密特性提供了额外保护。
QUIC 的 0-RTT 握手减少了连接建立时间。

然而，Hysteria 也面临挑战：

许多 ISP 对 UDP 流量实施质量服务限制，优先级低于 TCP，可能导致速度不稳定。
激进发包可能被误认为是 DDoS 攻击，导致服务器 IP 被封锁。

后期项目如 tuic-protocol/tuic 对 Hysteria 进行了改进，引入更智能的丢包退避策略，避免过度发包，同时保持性能优势。这些 UDP 协议为翻墙技术带来了新的可能性，尤其在对抗 GFW 的流量整形时。

不过，根据 GFW Report 团队发表在 USENIX’25 上的 Exposing and Circumventing SNI-based QUIC Censorship of the Great Firewall of China 一文，GFW 已经开始针对 QUIC 流量进行封锁和干扰，Hysteria 的前景仍需观察。

NaïveProxy

klzgrad/naiveproxy 采用了与众不同的对抗策略：不是创造新的协议，而是尽可能完美地模仿真实浏览器的 HTTPS 流量。它基于 Chromium 的网络栈开发，确保生成的流量在字节级别与 Chrome 浏览器产生的流量一致。

这一方法的优势在于，流量指纹与正常浏览器流量无异，GFW 的 DPI 和指纹分析几乎无法区分。NaïveProxy 代表了「以假乱真」的极致，但也凸显了翻墙技术的极限：当伪装足够完美时，检测将变得极其困难。

常见代理工具

随着翻墙协议的演进，相应的客户端工具也层出不穷。这些工具不仅实现了协议支持，还提供了用户友好的界面、规则管理和自动化功能。

V2Ray 与 Xray

VMess 协议的兴起使得 V2Ray 在 2018-2020 年间几乎成为翻墙工具的代名词。其作者 V2Ray 被请喝茶后，社区在 V2Fly 的领导下继续开发，保持了项目的活力。然而，随着 XTLS 技术的出现，开发者分歧加剧，导致 Xray 的诞生。Xray 不仅兼容 V2Ray，还引入了 REALITY 和更优化的 XTLS，成为对抗 GFW 的尖端工具。

V2Ray/Xray 的优势在于高度可定制，支持多种协议和传输方式，但学习曲线较陡峭，适合技术用户。

Sing-Box

随着协议多样化，SagerNet/sing-box 应运而生。它支持几乎所有主流协议（Trojan、VLESS、REALITY、Hysteria 等），并提供统一的配置格式。Sing-Box 强调性能和安全性，使用 Rust 编写，资源占用低。它还支持规则引擎，可以根据域名、IP 或应用进行智能路由。

Sing-Box 的出现简化了用户的选择，用户无需为不同协议切换工具。

Clash 系列

Clash 自 2019 年起成为最受欢迎的代理工具之一，以其简洁的 YAML 配置和丰富的规则集著称。Clash 支持多种协议，并提供 Web UI 和 API，便于管理和监控。

然而，2023 年原作者 Dreamacro 突然删库跑路，导致项目中断。社区迅速响应，衍生出 Clash.Meta 等分支。最终，Clash.Meta 和 Mihomo 接棒，继续发展。Mihomo 特别注重社区治理和长期维护，成为 Clash 生态的新核心。

Clash 系列以易用性和功能丰富著称，适合普通用户。

其他工具

Shadowsocks 客户端：如 Shadowsocks-Qt5、ShadowsocksR，虽然协议已过时，但仍有一些用户使用。
NaïveProxy 客户端：通常集成在浏览器扩展中，如 naiveproxy 的 Chrome 扩展。
Hysteria 客户端：有官方 CLI 和第三方 GUI，如 hysteria-gui。

结语

1987 年 9 月 20 日 20 时 55 分，中国兵器工业计算机应用研究所成功发送了中国第一封电子邮件，这标志这中国与国际计算机网络已经成功连接。这封邮件的内容是：

Across the Great Wall we can reach every corner in the world. (越过长城，走向世界)

现在看起来，颇具讽刺意味。

翻墙技术的发展史，实际上就是一部与 GFW 猫鼠游戏的历史。每当 GFW 升级封锁手段，翻墙协议和工具就会相应地进化出新的对抗策略。

在这期间，也有很多臭名昭著的人物和组织助纣为虐。从「防火墙之父」方滨兴，到思科、奇虎 360、启明星辰、中科院信工所 MESA 实验室，他们通过技术支持、情报共享等手段，帮助 GFW 提升了封锁能力，给翻墙社区带来了巨大挑战，严重阻碍了信息自由流通。

然而，正是这些挑战激发了翻墙技术的创新。每一次封锁升级，都促使开发者们寻找新的突破口，推动了协议和工具的不断进化。从最初的传统 VPN，到 SS、SSR，再到 VMess、Trojan、VLESS、REALITY 和 Hysteria，每一次技术革新都反映了翻墙社区对抗审查的决心和智慧。

算法笔记 (4) - 弹簧摆

mail@ch3nyang.top (Ch3nyang) — Wed, 22 Oct 2025 16:30:00 +0800

下面是一个弹簧摆的实现：

<svg id="spring-pendulum-svg" width="400" height="300"></svg>

* {
    box-sizing: border-box;
}

body {
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    height: 100%;
    margin: 0;
    background-color: #f0f0f0;
}

svg {
    border: 1px solid #ccc;
    background-color: white;
}

const svg = document.getElementById('spring-pendulum-svg');
const width = svg.clientWidth;
const height = svg.clientHeight;

let L0 = 100;           /* 弹簧自然长度 */
let k = 0.5;            /* 弹簧常数 */
let m = 2;              /* 质量 */
const g = 9.81;         /* 重力加速度 */

let L_prime = 0;          /* 初始弹簧伸长量 */
let v = 0;                /* 初始伸长速度 */
let theta = Math.PI / 4;  /* 初始角度 */
let omega = 0;            /* 初始角速度 */
let dt = 0.35;            /* 时间步长 */

let animationId;

function simulateSpringPendulum() {
    const spring_force1 = L_prime > 0 ? (k / m) * L_prime : 0;
    const k1_L = v;
    const k1_v = (L0 + L_prime) * omega * omega + g * Math.cos(theta) - spring_force1;
    const k1_theta = omega;
    const k1_omega = - (2 * v * omega + g * Math.sin(theta)) / (L0 + L_prime);

    const k2_L = v + 0.5 * k1_v * dt;
    const spring_force2 = (L_prime + 0.5 * k1_L * dt) > 0 ? (k / m) * (L_prime + 0.5 * k1_L * dt) : 0;
    const k2_v = (L0 + L_prime + 0.5 * k1_L * dt) * (omega + 0.5 * k1_omega * dt) ** 2
                  + g * Math.cos(theta + 0.5 * k1_theta * dt)
                  - spring_force2;
    const k2_theta = omega + 0.5 * k1_omega * dt;
    const k2_omega = - (2 * (v + 0.5 * k1_v * dt) * (omega + 0.5 * k1_omega * dt)
                        + g * Math.sin(theta + 0.5 * k1_theta * dt))
                        / (L0 + L_prime + 0.5 * k1_L * dt);

    const k3_L = v + 0.5 * k2_v * dt;
    const spring_force3 = (L_prime + 0.5 * k2_L * dt) > 0 ? (k / m) * (L_prime + 0.5 * k2_L * dt) : 0;
    const k3_v = (L0 + L_prime + 0.5 * k2_L * dt) * (omega + 0.5 * k2_omega * dt) ** 2
                  + g * Math.cos(theta + 0.5 * k2_theta * dt)
                  - spring_force3;
    const k3_theta = omega + 0.5 * k2_omega * dt;
    const k3_omega = - (2 * (v + 0.5 * k2_v * dt) * (omega + 0.5 * k2_omega * dt)
                        + g * Math.sin(theta + 0.5 * k2_theta * dt))
                        / (L0 + L_prime + 0.5 * k2_L * dt);

    const k4_L = v + k3_v * dt;
    const spring_force4 = (L_prime + k3_L * dt) > 0 ? (k / m) * (L_prime + k3_L * dt) : 0;
    const k4_v = (L0 + L_prime + k3_L * dt) * (omega + k3_omega * dt) ** 2
                  + g * Math.cos(theta + k3_theta * dt)
                  - spring_force4;
    const k4_theta = omega + k3_omega * dt;
    const k4_omega = - (2 * (v + k3_v * dt) * (omega + k3_omega * dt)
                        + g * Math.sin(theta + k3_theta * dt))
                        / (L0 + L_prime + k3_L * dt);

    L_prime += (k1_L + 2 * k2_L + 2 * k3_L + k4_L) / 6 * dt;
    v += (k1_v + 2 * k2_v + 2 * k3_v + k4_v) / 6 * dt;
    theta += (k1_theta + 2 * k2_theta + 2 * k3_theta + k4_theta) / 6 * dt;
    omega += (k1_omega + 2 * k2_omega + 2 * k3_omega + k4_omega) / 6 * dt;
}

function drawSpringPendulum(L_prime, theta) {
    svg.innerHTML = ''; /* 清空SVG内容 */

    const L_total = L0 + L_prime;
    const x_m = width / 2 + L_total * Math.sin(theta);
    const y_m = height / 4 + L_total * Math.cos(theta);

    /* 绘制弹簧 */
    const spring = document.createElementNS("http://www.w3.org/2000/svg", "line");
    spring.setAttribute("x1", width / 2);
    spring.setAttribute("y1", height / 4);
    spring.setAttribute("x2", x_m);
    spring.setAttribute("y2", y_m);
    spring.setAttribute("stroke", "black");
    spring.setAttribute("stroke-width", "1");
    svg.appendChild(spring);

    /* 绘制质量块 */
    const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
    circle.setAttribute("cx", x_m);
    circle.setAttribute("cy", y_m);
    circle.setAttribute("r", "10");
    circle.setAttribute("fill", "#d74514");
    svg.appendChild(circle);
}

function animate() {
    simulateSpringPendulum();
    drawSpringPendulum(L_prime, theta);
    animationId = requestAnimationFrame(animate);
}

animate();

Spring Pendulum Animation

本文将介绍如何使用拉格朗日方程来描述单摆和弹簧摆的运动，并通过数值模拟展示其动态行为。

拉格朗日力学

拉格朗日力学 (Lagrangian Mechanics) 是一种描述物理系统动力学行为的理论框架。它基于拉格朗日量 (Lagrangian) $\mathcal{L}$ 的概念，定义为系统的动能 $T$ 与势能 $U$ 之差：

\[\mathcal{L} = T - U\]

通过拉格朗日量，可以导出描述系统运动的欧拉-拉格朗日方程 (Euler-Lagrange Equation)：

\[\frac{d}{dt} \left(\frac{\partial \mathcal{L}}{\partial \dot{q}_i}\right) - \frac{\partial \mathcal{L}}{\partial q_i} = 0\]

其中，$q_i$ 是系统的广义坐标，$\dot{q}_i$ 是其对应的广义速度。

欧拉-拉格朗日方程这样的常微分方程 (Ordinary Differential Equation, ODE) 可以通过数值方法进行求解，从而模拟系统的动态行为。

在实际计算中，我们通常需要先表达系统的动能和势能，然后计算拉格朗日量，最后求解欧拉-拉格朗日方程以获得运动方程。

Runge-Kutta 方法

我们考虑常微分方程的一般形式：

\[\frac{dy}{dt} = f\left(t, y\right), \quad y\left(t_0\right) = y_0\]

对于该方程，欧拉方法 (Euler Method) 提供了一种简单的数值解法：

\[y_{n+1} = y_n + f\left(t_n, y_n\right) \Delta t\]

但欧拉方法的精度较低

如果 $\Delta t$ 较大，容易产生累积误差
如果 $\Delta t$ 较小，计算量会显著增加
对于刚性方程，欧拉方法可能不稳定

为提高精度，可以采用更高级的数值积分方法，如 Runge-Kutta 方法 (Runge-Kutta Method)。

相比于欧拉方法使用区间起点 $\left(t_n, y_n\right)$ 的斜率，Runge-Kutta 方法通过在区间内多个点计算斜率的加权平均来更新 $y$ 的值，从而提高精度。

Runge-Kutta 方法的经典形式是四阶 Runge-Kutta 方法 (RK4)，其更新公式为：

\[\begin{aligned} k_1 &= f\left(t_n, y_n\right) \\ k_2 &= f\left(t_n + \frac{\Delta t}{2}, y_n + \frac{\Delta t}{2} k_1\right) \\ k_3 &= f\left(t_n + \frac{\Delta t}{2}, y_n + \frac{\Delta t}{2} k_2\right) \\ k_4 &= f\left(t_n + \Delta t, y_n + \Delta t k_3\right) \\ y_{n+1} &= y_n + \frac{\Delta t}{6} \left(k_1 + 2 k_2 + 2 k_3 + k_4\right) \end{aligned}\]

其中

$k_1$ 是区间起点的斜率
$k_2$ 是使用 $k_1$ 估计的区间中点的斜率
$k_3$ 是使用 $k_2$ 估计的区间中点的斜率
$k_4$ 是使用 $k_2$ 估计的区间终点的斜率

最终，根据泰勒展开，得到各个斜率所占的权重，综合计算出 $y_{n+1}$ 的值。

这里的泰勒展开具体算法如下。

对于 RK4 的数值解 $y_{n+1} = y_n + \Delta t \left(a_1 k_1 + a_2 k_2 + a_3 k_3 + a_4 k_4\right)$，我们希望其与解析解的泰勒展开在 $\Delta t$ 的各阶项上尽可能匹配。

我们有：

$k_1 = f\left(t_n, y_n\right)$

$k_2 = f\left(t_n + \frac{\Delta t}{2}, y_n + \frac{\Delta t}{2} k_1\right)$

$k_3 = f\left(t_n + \frac{\Delta t}{2}, y_n + \frac{\Delta t}{2} k_2\right)$

$k_4 = f\left(t_n + \Delta t, y_n + \Delta t k_3\right)$

将展开后的 $k_1$、$k_2$、$k_3$、$k_4$ 代入 $y_{n+1}$ 的表达式中，并与解析解的泰勒展开进行比较，可以得到一组关于 $\Delta t$ 各阶系数的方程。

比较 $\Delta t$ 的系数，我们有：

一阶项：$a_1 + a_2 + a_3 + a_4 = 1$

二阶项：$\frac{1}{2} a_2 + \frac{1}{2} a_3 + a_4 = \frac{1}{2}$

三阶项：$\frac{1}{4} a_2 + \frac{1}{4} a_3 + a_4 = \frac{1}{6}$

四阶项：$\frac{1}{8} a_2 + \frac{1}{8} a_3 + a_4 = \frac{1}{24}$

解这组方程，得到：
\[a_1 = \frac{1}{6}, \quad a_2 = \frac{1}{3}, \quad a_3 = \frac{1}{3}, \quad a_4 = \frac{1}{6}\]
因此，RK4 方法的更新公式为：
\[y_{n+1} = y_n + \frac{\Delta t}{6} \left(k_1 + 2 k_2 + 2 k_3 + k_4\right)\]

RK4 方法的局部截断误差为 $O\left(\Delta t^5\right)$，全局截断误差为 $O\left(\Delta t^4\right)$，显著优于欧拉方法的 $O\left(\Delta t^2\right)$。

单摆

假设一个质量为 $m$ 的物体通过一根长度为 $L$ 的不可伸长且无质量的绳子悬挂在固定点上，形成一个单摆系统。设摆锤与竖直方向的夹角为 $\theta$，则摆锤的笛卡尔坐标可以表示为：

\[\begin{aligned} x_m &= L \sin{\theta} \\ y_m &= -L \cos{\theta} \end{aligned}\]

求其对于时间的一阶导数：

\[\begin{aligned} \dot{x}_m &= L \dot{\theta}\cos{\theta} \\ \dot{y}_m &= L \dot{\theta}\sin{\theta} \end{aligned}\]

动能为：

\[\begin{aligned} T &= \frac{1}{2} m {\nu}^2 \\ &= \frac{1}{2} m \left(\dot{x}_m^2 + \dot{y}_m^2\right) \\ &= \frac{1}{2} m \left(L^2 \dot{\theta}^2 \cos^2{\theta} + L^2 \dot{\theta}^2 \sin^2{\theta}\right) \\ &= \frac{1}{2} m L^2 \dot{\theta}^2 \end{aligned}\]

势能为：

\[\begin{aligned} U &= m g h \\ &= m g \left(-L \cos{\theta}\right) \\ &= -m g L \cos{\theta} \end{aligned}\]

由此计算出拉格朗日量：

\[\begin{aligned} \mathcal{L} &= T - U \\ &= \frac{1}{2} m L^2 \dot{\theta}^2 -\left(- m g L \cos{\theta}\right) \\ &= \frac{1}{2} m L^2 \dot{\theta}^2 + m g L \cos{\theta} \\ &= m L \left(\frac{1}{2} L \dot{\theta}^2 + g \cos{\theta}\right) \end{aligned}\]

求解欧拉-拉格朗日微分方程¹：

\[\begin{aligned} \frac{d}{dt} \left(\frac{\partial \mathcal{L}}{\partial \dot{\theta}}\right) - \frac{\partial \mathcal{L}}{\partial \theta} &= 0 \\ \frac{d}{dt} \left(\frac{\partial }{\partial \dot{\theta}} \left[m L \left(\frac{1}{2} L \dot{\theta}^2 + g \cos{\theta}\right)\right]\right) \\ - \frac{\partial }{\partial \theta} \left[m L \left(\frac{1}{2} L \dot{\theta}^2 + g \cos{\theta}\right)\right] &= 0 \\ \frac{d}{dt} \left[\frac{\partial }{\partial \dot{\theta}} \left(\frac{1}{2} L \dot{\theta}^2 + g \cos{\theta}\right)\right] \\ - \frac{\partial }{\partial \theta} \left(\frac{1}{2} L \dot{\theta}^2 + g \cos{\theta}\right) &= 0 \\ \frac{d}{dt} \left[\frac{\partial }{\partial \dot{\theta}} \left(\frac{1}{2} L \dot{\theta}^2\right) + \frac{\partial }{\partial \dot{\theta}} \left(g \cos{\theta}\right)\right] \\ - \left[\frac{\partial }{\partial \theta} \left(\frac{1}{2} L \dot{\theta}^2\right) + \frac{\partial }{\partial \theta} \left(g \cos{\theta}\right)\right] &= 0 \\ \frac{d}{dt} \left(L \dot{\theta} + 0\right) - \left[0 + \left(- g \sin{\theta}\right)\right] &= 0 \\ \frac{d}{dt} \left(L \dot{\theta}\right) + g \sin{\theta} &= 0 \\ L \ddot{\theta} + g \sin{\theta} &= 0 \end{aligned}\] \[\ddot{\theta} = -\frac{g \sin{\theta}}{L}\]

给定初始条件 $\theta(0) = \theta_0$，$\dot{\theta}(0) = \omega_0$，可以利用上面得到的 $\ddot{\theta}$ 方程进行数值模拟，迭代计算 $\theta(t)$ 和 $\dot{\theta}(t)$ 的值：

let theta = theta0; // 初始角度
let omega = omega0; // 初始角速度
let dt = 0.01;      // 时间步长

function simulatePendulum() {
    let alpha = - g * Math.sin(theta) / L; // 计算角加速度
    omega += alpha * dt;                   // 更新角速度
    theta += omega * dt;                   // 更新角度
}

while (true) {
    simulatePendulum(); // 持续模拟
    // 在这里可以添加代码来绘制或记录 theta 和 omega 的值
}

但这种方法在角度较大时会产生较大误差，可以使用更精确的数值积分方法如 Runge-Kutta 方法来提高模拟精度。

Runge-Kutta 方法利用四阶近似来更新状态变量：

\[\begin{aligned} k_1^{\theta} &= \omega \\ k_1^{\omega} &= -\frac{g}{L} \sin{\theta} \\ k_2^{\theta} &= \omega + 0.5 k_1^{\omega} dt \\ k_2^{\omega} &= -\frac{g}{L} \sin{\left(\theta + 0.5 k_1^{\theta} dt\right)} \\ k_3^{\theta} &= \omega + 0.5 k_2^{\omega} dt \\ k_3^{\omega} &= -\frac{g}{L} \sin{\left(\theta + 0.5 k_2^{\theta} dt\right)} \\ k_4^{\theta} &= \omega + k_3^{\omega} dt \\ k_4^{\omega} &= -\frac{g}{L} \sin{\left(\theta + k_3^{\theta} dt\right)} \\ \theta &= \theta + \frac{1}{6} \left(k_1^{\theta} + 2 k_2^{\theta} + 2 k_3^{\theta} + k_4^{\theta}\right) \\ \omega &= \omega + \frac{1}{6} \left(k_1^{\omega} + 2 k_2^{\omega} + 2 k_3^{\omega} + k_4^{\omega}\right) \end{aligned}\]

let theta = theta0; // 初始角度
let omega = omega0; // 初始角速度
let dt = 0.01;      // 时间步长

function simulatePendulum() {
    let k1_theta = omega;
    let k1_omega = - (g / L) * Math.sin(theta);
    let k2_theta = omega + 0.5 * k1_omega * dt;
    let k2_omega = - (g / L) * Math.sin(theta + 0.5 * k1_theta * dt);
    let k3_theta = omega + 0.5 * k2_omega * dt;
    let k3_omega = - (g / L) * Math.sin(theta + 0.5 * k2_theta * dt);
    let k4_theta = omega + k3_omega * dt;
    let k4_omega = - (g / L) * Math.sin(theta + k3_theta * dt);

    theta += (k1_theta + 2 * k2_theta + 2 * k3_theta + k4_theta) / 6;
    omega += (k1_omega + 2 * k2_omega + 2 * k3_omega + k4_omega) / 6;
}

while (true) {
    simulatePendulum(); // 持续模拟
    // 在这里可以添加代码来绘制或记录 theta 和 omega 的值
}

下面是完整的代码示例：

<div class="settings-wrap">
    <label for="L-input">绳长: <input type="number" id="L-input" value="150" step="1" min="50" max="300"></label>
    <label for="m-input">质量: <input type="number" id="m-input" value="1" step="0.1" min="0.1" max="10"></label>
    <label for="dt-input">时间步长: <input type="number" id="dt-input" value="0.35" step="0.01" min="0.01" max="1"></label>
</div>
<div class="settings-wrap">
    <label for="theta-slider">初始角度: <span id="theta-value">0.785</span></label>
    <input type="range" id="theta-slider" min="0" max="6.2832" step="0.01" value="0.785">
</div>
<svg id="pendulum-svg" width="400" height="400"></svg>
<button id="pause-btn" class="pause-btn" style="margin-top: 10px;">暂停</button>
‌‌‍

* {
    box-sizing: border-box;
}

body {
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    height: 100%;
    margin: 0;
    background-color: #f0f0f0;
}

svg {
    border: 1px solid #ccc;
    background-color: white;
}

.settings-wrap {
    display: flex;
    flex-wrap: wrap;
    gap: 10px;
    margin-bottom: 10px;
}

.settings-wrap label {
    font-size: 14px;
}

.settings-wrap input {
    margin-left: 5px;
}

.settings-wrap input[type="number"] {
    width: 50px;
}

.settings-wrap input[type="range"] {
    width: 180px;
}

.pause-btn {
    outline: none;
    border: none;
    background-color: #d74514;
    color: white;
    border-radius: 4px;
    padding: 4px 16px;
    font-size: 16px;
    cursor: pointer;
}

.pause-btn:hover {
    background-color: #a32d0f;
}

const svg = document.getElementById('pendulum-svg');
const width = svg.clientWidth;
const height = svg.clientHeight;

let L = 150;  /* 绳长 */
let m = 1;    /* 质量 */
const g = 9.81; /* 重力加速度 */

let theta = Math.PI / 4;  /* 初始角度 */
let omega = 0;            /* 初始角速度 */
let dt = 0.35;          /* 时间步长 */

let animationId;
let isPaused = false;

const thetaSlider = document.getElementById('theta-slider');
const thetaValue = document.getElementById('theta-value');
const LInput = document.getElementById('L-input');
const mInput = document.getElementById('m-input');
const dtInput = document.getElementById('dt-input');
const pauseBtn = document.getElementById('pause-btn');

function simulatePendulum() {
    const k1_theta = omega;
    const k1_omega = - (g / L) * Math.sin(theta);

    const k2_theta = omega + 0.5 * k1_omega * dt;
    const k2_omega = - (g / L) * Math.sin(theta + 0.5 * k1_theta * dt);

    const k3_theta = omega + 0.5 * k2_omega * dt;
    const k3_omega = - (g / L) * Math.sin(theta + 0.5 * k2_theta * dt);

    const k4_theta = omega + k3_omega * dt;
    const k4_omega = - (g / L) * Math.sin(theta + k3_theta * dt);

    theta += (k1_theta + 2 * k2_theta + 2 * k3_theta + k4_theta) / 6 * dt;
    omega += (k1_omega + 2 * k2_omega + 2 * k3_omega + k4_omega) / 6 * dt;
}

function drawPendulum(theta) {
    svg.innerHTML = ''; /* 清空SVG内容 */

    const x_m = width / 2 + L * Math.sin(theta);
    const y_m = height / 4 + L * Math.cos(theta);

    /* 绘制绳子 */
    const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
    line.setAttribute("x1", width / 2);
    line.setAttribute("y1", height / 4);
    line.setAttribute("x2", x_m);
    line.setAttribute("y2", y_m);
    line.setAttribute("stroke", "black");
    line.setAttribute("stroke-width", "1");
    svg.appendChild(line);

    /* 绘制质量块 */
    const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
    circle.setAttribute("cx", x_m);
    circle.setAttribute("cy", y_m);
    circle.setAttribute("r", "10");
    circle.setAttribute("fill", "#d74514");
    svg.appendChild(circle);
}

function animate() {
    simulatePendulum();
    drawPendulum(theta);
    animationId = requestAnimationFrame(animate);
}

function resetAnimation() {
    cancelAnimationFrame(animationId);
    theta = parseFloat(thetaSlider.value);
    omega = 0; /* 固定初始角速度为 0 */
    L = parseFloat(LInput.value);
    m = parseFloat(mInput.value);
    dt = parseFloat(dtInput.value);
    if (!isPaused) {
        animate();
    }
}

pauseBtn.addEventListener('click', () => {
    if (isPaused) {
        isPaused = false;
        animate();
        pauseBtn.textContent = '暂停';
    } else {
        isPaused = true;
        cancelAnimationFrame(animationId);
        pauseBtn.textContent = '恢复';
    }
});

thetaSlider.addEventListener('input', () => {
    thetaValue.textContent = thetaSlider.value;
    resetAnimation();
});

LInput.addEventListener('input', resetAnimation);
mInput.addEventListener('input', resetAnimation);
dtInput.addEventListener('input', resetAnimation);

animate();

Pendulum Simulation

弹簧摆

假设一个质量为 $m$ 的物体通过一根弹簧连接在固定点上，弹簧的自然长度为 $L_0$，弹簧常数为 $k$。设摆锤与竖直方向的夹角为 $\theta$，弹簧的伸长量为 $L^\prime$，则摆锤的笛卡尔坐标可以表示为：

\[\begin{aligned} x_m &= (L_0 + L^\prime) \sin{\theta} \\ y_m &= -(L_0 + L^\prime) \cos{\theta} \end{aligned}\]

求其对于时间的一阶导数：

\[\begin{aligned} \dot{x}_m &= \dot{L}^\prime \sin{\theta} + \left(L_0 + L^\prime\right) \dot{\theta} \cos{\theta} \\ \dot{y}_m &= -\dot{L}^\prime \cos{\theta} + \left(L_0 + L^\prime\right) \dot{\theta} \sin{\theta} \end{aligned}\]

动能为：

\[\begin{aligned} T =& \frac{1}{2} m {\nu}^2 \\ =& \frac{1}{2} m \left(\dot{x}_m^2 + \dot{y}_m^2\right) \\ =& \frac{1}{2} m \\ & \left({\left[\dot{L}^\prime \sin{\theta} + \left(L_0 + L^\prime\right) \dot{\theta} \cos{\theta}\right]}^2 + {\left[-\dot{L}^\prime \cos{\theta} + \left(L_0 + L^\prime\right) \dot{\theta} \sin{\theta}\right]}^2\right) \\ =& \frac{1}{2} m \left[\dot{L}^{\prime 2} \left(\sin^2{\theta} + \cos^2{\theta}\right) + \left(L_0 + L^\prime\right)^2 \dot{\theta}^2 \left(\cos^2{\theta} + \sin^2{\theta}\right)\right] \\ =& \frac{1}{2} m \left[\dot{L}^{\prime 2} + \left(L_0 + L^\prime\right)^2 \dot{\theta}^2\right] \end{aligned}\]

势能为：

\[\begin{aligned} U =& U_{\text{gravity}} + U_{\text{spring}} \\ =& m g h + \frac{1}{2} k L^{\prime 2} \\ =& m g \left[-\left(L_0 + L^\prime\right) \cos{\theta}\right] + \frac{1}{2} k L^{\prime 2} \\ =& -m g \left(L_0 + L^\prime\right) \cos{\theta} + \frac{1}{2} k L^{\prime 2} \end{aligned}\]

由此计算出拉格朗日量：

\[\begin{aligned} \mathcal{L} =& T - U \\ =& \frac{1}{2} m \left[\dot{L}^{\prime 2} + \left(L_0 + L^\prime\right)^2 \dot{\theta}^2\right] \\ & - \left[-m g \left(L_0 + L^\prime\right) \cos{\theta} + \frac{1}{2} k L^{\prime 2}\right] \\ =& \frac{1}{2} m \left[\dot{L}^{\prime 2} + \left(L_0 + L^\prime\right)^2 \dot{\theta}^2\right] \\ & + m g \left(L_0 + L^\prime\right) \cos{\theta} - \frac{1}{2} k L^{\prime 2} \end{aligned}\]

求解欧拉-拉格朗日微分方程：

\[\begin{aligned} \frac{d}{dt} \left(\frac{\partial \mathcal{L}}{\partial \dot{L}^\prime}\right) - \frac{\partial \mathcal{L}}{\partial L^\prime} &= 0 \\ \frac{d}{dt} \left(\frac{\partial }{\partial \dot{L}^\prime} \left[\frac{1}{2} m \left(\dot{L}^{\prime 2} + \left(L_0 + L^\prime\right)^2 \dot{\theta}^2\right) + m g \left(L_0 + L^\prime\right) \cos{\theta} - \frac{1}{2} k L^{\prime 2}\right]\right) \\ - \frac{\partial }{\partial L^\prime} \left[\frac{1}{2} m \left(\dot{L}^{\prime 2} + \left(L_0 + L^\prime\right)^2 \dot{\theta}^2\right) + m g \left(L_0 + L^\prime\right) \cos{\theta} - \frac{1}{2} k L^{\prime 2}\right] &= 0 \\ \frac{d}{dt} \left[m \dot{L}^\prime\right] - \left[m \left(L_0 + L^\prime\right) \dot{\theta}^2 + m g \cos{\theta} - k L^\prime\right] &= 0 \\ m \ddot{L}^\prime - m \left(L_0 + L^\prime\right) \dot{\theta}^2 - m g \cos{\theta} + k L^\prime &= 0 \end{aligned}\] \[\begin{aligned} \ddot{L}^\prime &= \left(L_0 + L^\prime\right) \dot{\theta}^2 + g \cos{\theta} - \frac{k}{m} L^\prime \\ \ddot{\theta} &= -\frac{2 \dot{L}^\prime \dot{\theta} + g \sin{\theta}}{L_0 + L^\prime} \end{aligned}\]

给定初始条件 $L^\prime(0) = L_0^\prime$，$\dot{L}^\prime(0) = v_0$，$\theta(0) = \theta_0$，$\dot{\theta}(0) = \omega_0$，可以利用上面得到的 $\ddot{L}^\prime$ 和 $\ddot{\theta}$ 方程进行数值模拟，迭代计算 $L^\prime(t)$、$\dot{L}^\prime(t)$、$\theta(t)$ 和 $\dot{\theta}(t)$ 的值：

let L0 = 100;           // 弹簧自然长度
let k = 0.5;            // 弹簧常数
let m = 1;              // 质量
let g = 9.81;           // 重力加速度
let L_prime = L0_prime; // 初始弹簧伸长量
let v = v0;             // 初始伸长速度
let theta = theta0;     // 初始角度
let omega = omega0;     // 初始角速度
let dt = 0.01;          // 时间步长

function simulateSpringPendulum() {
    let alpha_L = (L0 + L_prime) * omega * omega + g * Math.cos(theta) - (k / m) * L_prime; // 计算伸长加速度
    let alpha_theta = - (2 * v * omega + g * Math.sin(theta)) / (L0 + L_prime);              // 计算角加速度
    v += alpha_L * dt;                   // 更新伸长速度
    L_prime += v * dt;                   // 更新伸长量
    omega += alpha_theta * dt;           // 更新角速度
    theta += omega * dt;                 // 更新角度
}

while (true) {
    simulateSpringPendulum(); // 持续模拟
    // 在这里可以添加代码来绘制或记录 L_prime、v、theta 和 omega 的值
}

同样的，可以使用 Runge-Kutta 方法来提高模拟精度。

\[\begin{aligned} k_1^{L} =& v \\ k_1^{v} =& \left(L_0 + L^\prime\right) \omega^2 + g \cos{\theta} - \frac{k}{m} L^\prime \\ k_1^{\theta} =& \omega \\ k_1^{\omega} =& -\frac{2 v \omega + g \sin{\theta}}{L_0 + L^\prime} \\ k_2^{L} =& v + 0.5 k_1^{v} dt \\ k_2^{v} =& \left(L_0 + L^\prime + 0.5 k_1^{L} dt\right) \left(\omega + 0.5 k_1^{\omega} dt\right)^2 \\ & + g \cos{\left(\theta + 0.5 k_1^{\theta} dt\right)} - \frac{k}{m} \left(L^\prime + 0.5 k_1^{L} dt\right) \\ k_2^{\theta} =& \omega + 0.5 k_1^{\omega} dt \\ k_2^{\omega} =& -\frac{2 \left(v + 0.5 k_1^{v} dt\right) \left(\omega + 0.5 k_1^{\omega} dt\right) + g \sin{\left(\theta + 0.5 k_1^{\theta} dt\right)}}{L_0 + L^\prime + 0.5 k_1^{L} dt} \\ k_3^{L} =& v + 0.5 k_2^{v} dt \\ k_3^{v} =& \left(L_0 + L^\prime + 0.5 k_2^{L} dt\right) \left(\omega + 0.5 k_2^{\omega} dt\right)^2 \\ & + g \cos{\left(\theta + 0.5 k_2^{\theta} dt\right)} - \frac{k}{m} \left(L^\prime + 0.5 k_2^{L} dt\right) \\ k_3^{\theta} =& \omega + 0.5 k_2^{\omega} dt \\ k_3^{\omega} =& -\frac{2 \left(v + 0.5 k_2^{v} dt\right) \left(\omega + 0.5 k_2^{\omega} dt\right) + g \sin{\left(\theta + 0.5 k_2^{\theta} dt\right)}}{L_0 + L^\prime + 0.5 k_2^{L} dt} \\ k_4^{L} =& v + k_3^{v} dt \\ k_4^{v} =& \left(L_0 + L^\prime + k_3^{L} dt\right) \left(\omega + k_3^{\omega} dt\right)^2 \\ & + g \cos{\left(\theta + k_3^{\theta} dt\right)} - \frac{k}{m} \left(L^\prime + k_3^{L} dt\right) \\ k_4^{\theta} =& \omega + k_3^{\omega} dt \\ k_4^{\omega} =& -\frac{2 \left(v + k_3^{v} dt\right) \left(\omega + k_3^{\omega} dt\right) + g \sin{\left(\theta + k_3^{\theta} dt\right)}}{L_0 + L^\prime + k_3^{L} dt} \\ L^\prime =& L^\prime + \frac{1}{6} \left(k_1^{L} + 2 k_2^{L} + 2 k_3^{L} + k_4^{L}\right) \\ v =& v + \frac{1}{6} \left(k_1^{v} + 2 k_2^{v} + 2 k_3^{v} + k_4^{v}\right) \\ \theta =& \theta + \frac{1}{6} \left(k_1^{\theta} + 2 k_2^{\theta} + 2 k_3^{\theta} + k_4^{\theta}\right) \\ \omega =& \omega + \frac{1}{6} \left(k_1^{\omega} + 2 k_2^{\omega} + 2 k_3^{\omega} + k_4^{\omega}\right) \end{aligned}\]

let L0 = 100;           // 弹簧自然长度
let k = 0.5;            // 弹簧常数
let m = 1;              // 质量
let g = 9.81;           // 重力加速度
let L_prime = L0_prime; // 初始弹簧伸长量
let v = v0;             // 初始伸长速度
let theta = theta0;     // 初始角度
let omega = omega0;     // 初始角速度
let dt = 0.01;          // 时间步长

function simulateSpringPendulum() {
    const k1_L = v;
    const k1_v = (L0 + L_prime) * omega * omega + g * Math.cos(theta) - (k / m) * L_prime;
    const k1_theta = omega;
    const k1_omega = - (2 * v * omega + g * Math.sin(theta)) / (L0 + L_prime);

    const k2_L = v + 0.5 * k1_v * dt;
    const k2_v = (L0 + L_prime + 0.5 * k1_L * dt) * (omega + 0.5 * k1_omega * dt) ** 2
                  + g * Math.cos(theta + 0.5 * k1_theta * dt)
                  - (k / m) * (L_prime + 0.5 * k1_L * dt);
    const k2_theta = omega + 0.5 * k1_omega * dt;
    const k2_omega = - (2 * (v + 0.5 * k1_v * dt) * (omega + 0.5 * k1_omega * dt)
                        + g * Math.sin(theta + 0.5 * k1_theta * dt))
                        / (L0 + L_prime + 0.5 * k1_L * dt);

    const k3_L = v + 0.5 * k2_v * dt;
    const k3_v = (L0 + L_prime + 0.5 * k2_L * dt) * (omega + 0.5 * k2_omega * dt) ** 2
                  + g * Math.cos(theta + 0.5 * k2_theta * dt)
                  - (k / m) * (L_prime + 0.5 * k2_L * dt);
    const k3_theta = omega + 0.5 * k2_omega * dt;
    const k3_omega = - (2 * (v + 0.5 * k2_v * dt) * (omega + 0.5 * k2_omega * dt)
                        + g * Math.sin(theta + 0.5 * k2_theta * dt))
                        / (L0 + L_prime + 0.5 * k2_L * dt);

    const k4_L = v + k3_v * dt;
    const k4_v = (L0 + L_prime + k3_L * dt) * (omega + k3_omega * dt) ** 2
                  + g * Math.cos(theta + k3_theta * dt)
                  - (k / m) * (L_prime + k3_L * dt);
    const k4_theta = omega + k3_omega * dt;
    const k4_omega = - (2 * (v + k3_v * dt) * (omega + k3_omega * dt)
                        + g * Math.sin(theta + k3_theta * dt))
                        / (L0 + L_prime + k3_L * dt);

    L_prime += (k1_L + 2 * k2_L + 2 * k3_L + k4_L) / 6 * dt;
    v += (k1_v + 2 * k2_v + 2 * k3_v + k4_v) / 6 * dt;
    theta += (k1_theta + 2 * k2_theta + 2 * k3_theta + k4_theta) / 6 * dt;
    omega += (k1_omega + 2 * k2_omega + 2 * k3_omega + k4_omega) / 6 * dt;
}

while (true) {
    simulateSpringPendulum(); // 持续模拟
    // 在这里可以添加代码来绘制或记录 L_prime、v、theta 和 omega 的值
}

在实现前，我们还需要注意弹簧绳只能产生拉力，不能产生压力，因此当弹簧伸长量 $L^\prime < 0$ 时，弹力应为 $0$，此时物体将只受重力作用。

下面是完整的代码示例：

<div class="settings-wrap">
    <label for="L0-input">弹簧自然长度: <input type="number" id="L0-input" value="100" step="1" min="50" max="200"></label>
    <label for="Lprime-input">初始弹簧伸长量: <input type="number" id="Lprime-input" value="0" step="1" min="0" max="100"></label>
    <label for="k-input">弹簧常数: <input type="number" id="k-input" value="0.5" step="0.1" min="0.1" max="5"></label>
</div>
<div class="settings-wrap">
    <label for="m-input">质量: <input type="number" id="m-input" value="2" step="0.1" min="0.1" max="10"></label>
    <label for="dt-input">时间步长: <input type="number" id="dt-input" value="0.35" step="0.01" min="0.01" max="1"></label>
</div>
<div class="settings-wrap">
    <label for="theta-slider">初始角度: <span id="theta-value">0.785</span></label>
    <input type="range" id="theta-slider" min="0" max="6.2832" step="0.01" value="0.785">
</div>
<svg id="spring-pendulum-svg" width="400" height="400"></svg>
<button id="pause-btn" class="pause-btn" style="margin-top: 10px;">暂停</button>
‌‌‍

* {
    box-sizing: border-box;
}

body {
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    height: 100%;
    margin: 0;
    background-color: #f0f0f0;
}

svg {
    border: 1px solid #ccc;
    background-color: white;
}

.settings-wrap {
    display: flex;
    flex-wrap: wrap;
    gap: 10px;
    margin-bottom: 10px;
}

.settings-wrap label {
    font-size: 14px;
}

.settings-wrap input {
    margin-left: 5px;
}

.settings-wrap input[type="number"] {
    width: 50px;
}

.settings-wrap input[type="range"] {
    width: 180px;
}

.pause-btn {
    outline: none;
    border: none;
    background-color: #d74514;
    color: white;
    border-radius: 4px;
    padding: 4px 16px;
    font-size: 16px;
    cursor: pointer;
}

.pause-btn:hover {
    background-color: #a32d0f;
}

const svg = document.getElementById('spring-pendulum-svg');
const width = svg.clientWidth;
const height = svg.clientHeight;

let L0 = 100;           /* 弹簧自然长度 */
let k = 0.5;            /* 弹簧常数 */
let m = 2;              /* 质量 */
const g = 9.81;         /* 重力加速度 */

let L_prime = 0;          /* 初始弹簧伸长量 */
let v = 0;                /* 初始伸长速度 */
let theta = Math.PI / 4;  /* 初始角度 */
let omega = 0;            /* 初始角速度 */
let dt = 0.35;            /* 时间步长 */

let animationId;
let isPaused = false;

const LprimeInput = document.getElementById('Lprime-input');
const thetaSlider = document.getElementById('theta-slider');
const thetaValue = document.getElementById('theta-value');
const L0Input = document.getElementById('L0-input');
const kInput = document.getElementById('k-input');
const mInput = document.getElementById('m-input');
const dtInput = document.getElementById('dt-input');
const pauseBtn = document.getElementById('pause-btn');

function simulateSpringPendulum() {
    const spring_force1 = L_prime > 0 ? (k / m) * L_prime : 0;
    const k1_L = v;
    const k1_v = (L0 + L_prime) * omega * omega + g * Math.cos(theta) - spring_force1;
    const k1_theta = omega;
    const k1_omega = - (2 * v * omega + g * Math.sin(theta)) / (L0 + L_prime);

    const k2_L = v + 0.5 * k1_v * dt;
    const spring_force2 = (L_prime + 0.5 * k1_L * dt) > 0 ? (k / m) * (L_prime + 0.5 * k1_L * dt) : 0;
    const k2_v = (L0 + L_prime + 0.5 * k1_L * dt) * (omega + 0.5 * k1_omega * dt) ** 2
                  + g * Math.cos(theta + 0.5 * k1_theta * dt)
                  - spring_force2;
    const k2_theta = omega + 0.5 * k1_omega * dt;
    const k2_omega = - (2 * (v + 0.5 * k1_v * dt) * (omega + 0.5 * k1_omega * dt)
                        + g * Math.sin(theta + 0.5 * k1_theta * dt))
                        / (L0 + L_prime + 0.5 * k1_L * dt);

    const k3_L = v + 0.5 * k2_v * dt;
    const spring_force3 = (L_prime + 0.5 * k2_L * dt) > 0 ? (k / m) * (L_prime + 0.5 * k2_L * dt) : 0;
    const k3_v = (L0 + L_prime + 0.5 * k2_L * dt) * (omega + 0.5 * k2_omega * dt) ** 2
                  + g * Math.cos(theta + 0.5 * k2_theta * dt)
                  - spring_force3;
    const k3_theta = omega + 0.5 * k2_omega * dt;
    const k3_omega = - (2 * (v + 0.5 * k2_v * dt) * (omega + 0.5 * k2_omega * dt)
                        + g * Math.sin(theta + 0.5 * k2_theta * dt))
                        / (L0 + L_prime + 0.5 * k2_L * dt);

    const k4_L = v + k3_v * dt;
    const spring_force4 = (L_prime + k3_L * dt) > 0 ? (k / m) * (L_prime + k3_L * dt) : 0;
    const k4_v = (L0 + L_prime + k3_L * dt) * (omega + k3_omega * dt) ** 2
                  + g * Math.cos(theta + k3_theta * dt)
                  - spring_force4;
    const k4_theta = omega + k3_omega * dt;
    const k4_omega = - (2 * (v + k3_v * dt) * (omega + k3_omega * dt)
                        + g * Math.sin(theta + k3_theta * dt))
                        / (L0 + L_prime + k3_L * dt);

    L_prime += (k1_L + 2 * k2_L + 2 * k3_L + k4_L) / 6 * dt;
    v += (k1_v + 2 * k2_v + 2 * k3_v + k4_v) / 6 * dt;
    theta += (k1_theta + 2 * k2_theta + 2 * k3_theta + k4_theta) / 6 * dt;
    omega += (k1_omega + 2 * k2_omega + 2 * k3_omega + k4_omega) / 6 * dt;
}

function drawSpringPendulum(L_prime, theta) {
    svg.innerHTML = ''; /* 清空SVG内容 */

    const L_total = L0 + L_prime;
    const x_m = width / 2 + L_total * Math.sin(theta);
    const y_m = height / 4 + L_total * Math.cos(theta);

    /* 计算紧绷程度 */
    let color;
    let dashArray = "none";
    if (L_prime <= 0) {
        color = "gray";
        dashArray = "5,5";
    } else {
        const max_L = 60; /* 假设最大伸长量为 60 */
        const tightness = Math.min(1, L_prime / max_L);
        const hue = 120 - 120 * tightness; /* 从绿色(120)到红色(0) */
        color = `hsl(${hue}, 100%, 50%)`;
    }

    /* 绘制弹簧 */
    const spring = document.createElementNS("http://www.w3.org/2000/svg", "line");
    spring.setAttribute("x1", width / 2);
    spring.setAttribute("y1", height / 4);
    spring.setAttribute("x2", x_m);
    spring.setAttribute("y2", y_m);
    spring.setAttribute("stroke", color);
    spring.setAttribute("stroke-width", "1");
    spring.setAttribute("stroke-dasharray", dashArray);
    svg.appendChild(spring);

    /* 绘制质量块 */
    const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
    circle.setAttribute("cx", x_m);
    circle.setAttribute("cy", y_m);
    circle.setAttribute("r", "10");
    circle.setAttribute("fill", "#d74514");
    svg.appendChild(circle);
}

function animate() {
    simulateSpringPendulum();
    drawSpringPendulum(L_prime, theta);
    animationId = requestAnimationFrame(animate);
}

function resetAnimation() {
    cancelAnimationFrame(animationId);
    L_prime = parseFloat(LprimeInput.value);
    v = 0; /* 固定初始伸长速度为 0 */
    theta = parseFloat(thetaSlider.value);
    omega = 0; /* 固定初始角速度为 0 */
    L0 = parseFloat(L0Input.value);
    k = parseFloat(kInput.value);
    m = parseFloat(mInput.value);
    dt = parseFloat(dtInput.value);
    if (!isPaused) {
        animate();
    }
}

pauseBtn.addEventListener('click', () => {
    if (isPaused) {
        isPaused = false;
        animate();
        pauseBtn.textContent = '暂停';
    } else {
        isPaused = true;
        cancelAnimationFrame(animationId);
        pauseBtn.textContent = '恢复';
    }
});

LprimeInput.addEventListener('input', resetAnimation);
thetaSlider.addEventListener('input', () => {
    thetaValue.textContent = thetaSlider.value;
    resetAnimation();
});
L0Input.addEventListener('input', resetAnimation);
kInput.addEventListener('input', resetAnimation);
mInput.addEventListener('input', resetAnimation);
dtInput.addEventListener('input', resetAnimation);

animate();

Spring Pendulum Simulation

我们这边使用绳子的颜色来表示弹簧的紧绷程度。

你可以试着将初始角度调大一些，然后观察弹簧摆在弹簧绳有松弛时的运动情况。

这段代码似乎还有点 bug，小球如果超出画布范围就会卡住，可以尝试修复它。

讨论

在上面的内容中，我们看到似乎只能使用数值方法来模拟弹簧摆的运动轨迹，是否无法得到解析解呢？

事实上，弹簧摆的运动方程是一个耦合的非线性微分方程组，一般情况下是无法通过解析方法求解的。不过，在某些特定条件下，可以对方程进行线性化处理，从而得到近似的解析解。例如，当摆动角度较小且弹簧伸长量较小时，可以将 $\sin{\theta} \approx \theta$ 和 $L^\prime \approx 0$ 代入方程，得到简化后的线性微分方程组，从而求解出近似的解析解。

但这种近似解仅在小角度和小伸长量范围内有效，对于大角度或大伸长量的情况，仍然需要依赖数值方法进行模拟。

对于数值解法的选择，除了上面介绍的 Runge-Kutta 方法外，还可以考虑其他数值积分方法，如 Verlet 积分法、Leapfrog 方法等。这些方法在处理物理系统时具有较好的能量守恒性质，适合用于长时间模拟。

不过，即便选用了更高级的数值方法，我们最终的结果仍然可能出现问题，这是由于浮点数运算的精度限制所导致的。例如，对于 JavaScript 有一个著名的浮点数精度问题 $0.1 + 0.2 = 0.30000000000000004$：

console.log(0.1 + 0.2);

feedback Ready

这样的精度误差在长时间的数值模拟中会逐渐积累，最终导致结果偏离真实情况。因此，在进行数值模拟时，可能还需要配合一些数值稳定化技术，如自适应时间步长调整、能量修正等，以减小误差的积累。

部分参考资料：Nima Aghdaii - Physics Simulation ↩

算法笔记 (3) - 波函数坍缩与程序化生成

mail@ch3nyang.top (Ch3nyang) — Sun, 05 Oct 2025 00:01:00 +0800

随机地图与开放世界永远令人着迷。从早期的 MineCraft 到现代的 No Man’s Sky，程序化生成的世界为玩家提供了无尽的探索和发现的机会。

在诸多程序化生成算法中，波函数坍缩（Wave Function Collapse, WFC）算法因其独特的生成方式和令人惊叹的结果而脱颖而出。下面就是我们使用波函数坍缩算法生成的图案：

3Bricks

Knot

MoreFlowers

Mountains

Village

Water

Circle

Lake

接下来，我们将深入探讨波函数坍缩算法的原理、实现以及应用。

请客吃饭的感悟

假设你是 The Family Guys 中国分 guy。你想要请你一大家子吃饭，大家需要围坐在一张大圆桌旁。但是位置有限，需要合理安排每个人的位置，以确保每个人都能愉快地交流:

你太爷爷是个冥顽不化的臭老九，他要是不坐主位，就会给你念之乎者也说你们是不肖子孙
你大伯是山东人，向来坚持女人不能上桌，需要让他尽量远离女人
你大舅舅是个男同，经常给你的两个妹夫暗送秋波，你需要把他们分开得远远的
你二舅舅是个花花公子，喜欢调戏你的小姨子，他们也不能坐一起
你小姨子极为泼辣，只有她老娘和老爹可以拿着鸡毛掸子才能压住她，所以需要让这三个人形成两面包夹芝士
你姑姑是从东北嫁过来的，爱吃地饺，需要把她安排到和大黄在一起
你自己是苏波宁，不配和上海来的表哥坐一起
…

你头都要炸了，这该怎么安排是好！

忽然，你想起来在本博客里见过一个叫做波函数坍缩算法的东西。

在量子力学里，一个粒子在被观测前可能处于多个状态的叠加，一旦观测，它就会「坍缩」到某个确定状态。

类似地，在安排座位时：

第一步：叠加态 —— 刚开始，每个座位都处于「叠加态」，每个人理论上都可以坐在任何位置。就像薛定谔的猫，你姑姑既在主位也在次位，你大伯既挨着女人也远离女人，一切皆有可能。
第二步：观测坍缩 —— 你首先将太爷爷安排在了主位，这就是第一次”观测”。瞬间，这个决定像水池中的涟漪向外扩散，所有座位的「可能性」开始坍缩：
- 你小姨子不再能坐到主位旁边的两个位置 (可能性从 N 个减少到 N-2 个)
- 你太爷爷显然也不应该和大黄坐，所以你姑姑也不能坐在主位旁边 (又减少了 1 种可能)
- 其他位置依然是叠加态，但可能性空间变小了
第三步：连锁坍缩 —— 接下来你随机让大伯坐太爷爷左手边，这是第二次「观测」。又一波涟漪扩散：
- 大伯这边半张桌子都不能坐女人了 (半张桌子的女性可能性全部坍缩为 0)
- 由于你小姨子不能坐这半张桌子，她爹妈也不能坐这边 (连锁坍缩)
- 你大舅舅也不能坐这边，因为他要和你大伯分开 (继续坍缩)
第四步：强制坍缩 —— 算来算去，你发现大伯左手边的位置已经「过度坍缩」了——这个地儿的所有可能性只剩下一个：你自己！这就像量子态完全确定，再也没有其他选择。于是你就把自己安排在了那里。
第五步：递归坍缩 —— 你继续随机「观测」下一个人，每一次决定都会引发新的涟漪，不断压缩剩余位置的可能性空间，直到所有座位都从「叠加态」坍缩为「确定态」。

你顿悟了，这就是波函数坍缩算法！每一次决定都像一次量子观测，将无序的可能性逐步坍缩为有序的确定性，而约束条件就像物理定律，限制着坍缩的方向。

波函数坍缩算法

波函数坍缩算法（Wave Function Collapse, WFC）是一种基于约束满足问题（Constraint Satisfaction Problem, CSP）的程序化生成算法。它通过模拟量子力学中的波函数坍缩过程，生成符合特定规则的图案或结构。

与上文请客吃饭类似，波函数坍缩算法的核心思想是将生成过程视为一个约束满足问题。它通过以下步骤实现：

定义样本：首先，选择一个或多个样本图案，这些图案将作为生成新图案的基础
建立约束：分析样本图案，提取出其中的规则和约束。这些约束将指导新图案的生成过程
初始化状态：创建一个初始状态，通常是一个空白的网格或图像，每个单元格都处于「叠加态」，可以接受多种可能的值
观测与坍缩：随机选择一个单元格进行「观测」，根据约束条件确定该单元格的具体值，并更新周围单元格的可能性
重复迭代：不断重复观测与坍缩的过程，直到整个网格或图像都被填充为止

接下来，我们来一步一步地看看其实现。

样本与约束

首先是定义样本，其通常是一些具备一定重复特征和结构性的小图案，比如砖块、花纹、山脉等。下面是一些很经典的样本：

但这些样本还无法直接使用——总不能把一堆一模一样的图复制粘贴无数份吧！因此，我们需要先从其中提取出一些基本的 瓦片（Tile）。

例如，下面是一个 $16 \times 16$ 的 Water 样本，我们从其中使用滑动窗口可以提取出 $16 \times 16$ 个 $3 \times 3$ 的瓦片：

值得注意的是，边界处通过环绕连接（Wrap-around）来处理，这样可以确保瓦片在边界处也能正确匹配。

你也许已经发现，有很多瓦片是完全一样的。但我们并不需要去重，因为相同的瓦片数量恰恰体现了样本的「特征」，在后期生成时会影响概率分布。这就好像在很多大模型训练集中，「澳门银河」这个词出现的频率远高于「波函数坍缩」，所以生成时更容易出现前者。

当然，每个瓦片并不仅仅是它本身，它还可以旋转、翻转，对应共 $8$ 种形态：

值得注意的是，并不是所有情况下都需要考虑变换，因为变换会带来不一样的邻接关系——或者更直观地讲，图像风格。例如 Water 在不变换和变换下生成的结果就完全不同：

不变换

旋转和翻转变换

接下来便是建立约束了。每个瓦片的上下左右分别可以连接哪些瓦片，这些连接关系便是约束条件。

通常，我们认为，对应的边相同的瓦片可以连接在一起。例如，下面两个瓦片就是可以左右连接的：

我们可以通过遍历所有瓦片，记录每个瓦片在四个方向上可以连接的瓦片集合。

观测与坍缩

有了样本和约束，接下来便是核心的观测与坍缩过程了。

最开始，结果图像中的每个单元格都处于叠加态，意味着它们可以接受所有瓦片类型。我们可以用一个二维数组 possibleTiles 来表示每个单元格的可能瓦片集合：

\[possibleTiles[x][y] = \{tile_1, tile_2, \ldots, tile_n\}\]

每当我们随机选择一个单元格进行观测时，我们会从它的可能瓦片集合中随机选择一个瓦片，并将该单元格的状态坍缩为这个瓦片：

\[selectedTile[x][y] = random(possibleTiles[x][y])\]

接着，我们需要更新周围单元格的可能瓦片集合，以确保它们仍然满足约束条件。假设我们选择了单元格 $(x, y)$ 并将其坍缩为瓦片 $tile_k$，那么我们需要检查它的四个邻居：

\[\begin{align*} possibleTiles[x-1][y] =& possibleTiles[x-1][y] \\&\cap canConnect(tile_k, left) \\ possibleTiles[x+1][y] =& possibleTiles[x+1][y] \\&\cap canConnect(tile_k, right) \\ possibleTiles[x][y-1] =& possibleTiles[x][y-1] \\&\cap canConnect(tile_k, up) \\ possibleTiles[x][y+1] =& possibleTiles[x][y+1] \\&\cap canConnect(tile_k, down) \\ \end{align*}\]

但是，这会带来连锁反应——当一个单元格的可能瓦片集合被更新后，它的邻居也可能需要更新，依此类推。为此，我们可以使用一个队列来跟踪需要更新的单元格：

初始化队列，将刚刚坍缩的单元格的邻居加入队列
当队列不为空时，取出一个单元格，更新它的可能瓦片集合
如果该单元格的可能瓦片集合发生变化，将它的邻居加入队列
重复步骤 2 和 3，直到队列为空

同时，我们还需要处理过度坍缩的情况——当一个单元格的可能瓦片集合变为空时，说明当前的选择导致了矛盾。此时，我们需要回溯到上一个状态，重新选择一个瓦片。

我们已经搞清楚了观测与坍缩的过程，但是，我们每次应该先观测哪个单元格呢？

这里，我们可以采用一种启发式的方法：每次选择可能瓦片集合最小的单元格进行观测。这种单元格的「熵」最小，这样可以最大化地减少不确定性，避免过早地陷入矛盾。

不过，为了防止陷入局部最优，我们可以在选择时引入一些随机性——在所有可能瓦片集合最小的单元格中，随机选择一个进行观测；或是在计算熵时加入一些噪声。

不断重复以上过程，直到所有单元格都被坍缩为具体的瓦片，或者无法继续进行，我们便得到了最终的生成结果！

实现

至此，我们便可以给出一个 Python 版本的波函数坍缩算法实现：

点击展开代码

"""
Wave Function Collapse (波函数坍缩) 图像生成器

这个程序使用 WFC 算法从输入图像中提取瓦片，并生成新的相似纹理图像。
算法通过约束传播确保相邻瓦片的边缘匹配，从而生成连贯的图像。
"""

import os
import random
import time
from datetime import datetime
from typing import Optional

import pygame

# ============================================================================
# 初始化
# ============================================================================

pygame.init()

MAX_INT: int = 2**31 - 1


# ============================================================================
# 配置类
# ============================================================================

class Config:
    """全局配置参数"""

    # 瓦片来源设置
    TILE_SOURCE_MODE: str = "folder"  # "image" 或 "folder" - 从图像切割或从文件夹读取
    TILE_FOLDER_PATH: str = "tiles"  # 当模式为"folder"时，从此文件夹读取PNG文件作为瓦片

    # 输入图像设置
    ORIGINAL_IMG_PATH: str = "Water.png"  # 源图像路径（仅在image模式下使用）
    TILE_SIZE: int = 4  # 瓦片尺寸（像素），决定提取多大的图案块（仅在image模式下使用）

    # 输出图像设置
    OUTPUT_WIDTH: int = 24  # 输出图像宽度（瓦片数量）
    OUTPUT_HEIGHT: int = 24  # 输出图像高度（瓦片数量）
    SCALE: float = 1.0  # 显示缩放比例

    # 瓦片变换设置
    ALLOW_ROTATE: bool = True  # 是否允许旋转瓦片（增加变化性）
    ALLOW_FLIP: bool = True  # 是否允许翻转瓦片（增加变化性）

    # 显示设置
    SHOW_GENERATION: bool = True  # 是否实时显示生成过程
    GENERATION_DELAY: float = 0.0001  # 每步之间的延迟（秒），0表示最快速度

    # 输出设置
    SAVE_OUTPUT: bool = True  # 是否保存生成的图像
    OUTPUT_DIR: str = "output"  # 输出目录

    # Pygame显示对象（延迟创建）
    DISPLAY: pygame.Surface = None


# 确保输出尺寸为整数
Config.OUTPUT_WIDTH = int(Config.OUTPUT_WIDTH)
Config.OUTPUT_HEIGHT = int(Config.OUTPUT_HEIGHT)


# ============================================================================
# 瓦片类
# ============================================================================

class Tile:
    """
    表示一个图像瓦片（图案块）

    瓦片是从源图像中提取的小块图案，包含完整的像素数据和边缘信息。
    边缘信息用于WFC算法中的瓦片匹配。
    """

    def __init__(self, pixels: list[list[tuple]]):
        """
        初始化瓦片

        参数:
            pixels: 2D数组 [y][x]，每个元素是RGBA颜色元组
        """
        self.pixels = pixels
        self.height = len(pixels)
        self.width = len(pixels[0]) if pixels else 0

        # 提取四条边缘（用于匹配相邻瓦片）
        self.edges = {
            'up': tuple(pixels[0]),  # 顶部边缘（第一行）
            'right': tuple(row[-1] for row in pixels),  # 右侧边缘（最后一列）
            'down': tuple(pixels[-1]),  # 底部边缘（最后一行）
            'left': tuple(row[0] for row in pixels)  # 左侧边缘（第一列）
        }

        # 创建Pygame Surface用于渲染
        self.surface = pygame.Surface((self.width, self.height), pygame.SRCALPHA)
        for y in range(self.height):
            for x in range(self.width):
                self.surface.set_at((x, y), pixels[y][x])

    def rotate_90(self) -> 'Tile':
        """
        顺时针旋转90度

        返回:
            旋转后的新瓦片对象
        """
        new_pixels = [
            [self.pixels[self.height - 1 - x][y] for x in range(self.height)]
            for y in range(self.width)
        ]
        return Tile(new_pixels)

    def flip_horizontal(self) -> 'Tile':
        """
        水平翻转（左右镜像）

        返回:
            翻转后的新瓦片对象
        """
        new_pixels = [row[::-1] for row in self.pixels]
        return Tile(new_pixels)


# ============================================================================
# 瓦片加载和处理函数
# ============================================================================

def load_tiles_from_image(image_path: str, tile_size: int) -> list[Tile]:
    """
    使用滑动窗口从图像中提取瓦片

    通过在源图像上滑动一个tile_size×tile_size的窗口，
    每次移动1个像素，提取所有可能的图案块。

    参数:
        image_path: 源图像路径
        tile_size: 瓦片尺寸（正方形边长）

    返回:
        提取的唯一瓦片列表
    """
    img = pygame.image.load(image_path)
    width, height = img.get_size()

    tiles = []
    tile_set = set()  # 用于去重（避免重复的图案）

    # 滑动窗口提取瓦片（步长为1像素）
    for y in range(height - tile_size + 1):
        for x in range(width - tile_size + 1):
            # 提取tile_size × tile_size的像素块
            pixels = []
            for dy in range(tile_size):
                row = []
                for dx in range(tile_size):
                    color = img.get_at((x + dx, y + dy))
                    row.append((color.r, color.g, color.b, color.a))
                pixels.append(row)

            # 使用边缘元组作为唯一标识进行去重
            tile = Tile(pixels)
            edge_signature = (
                tile.edges['up'],
                tile.edges['right'],
                tile.edges['down'],
                tile.edges['left']
            )

            if edge_signature not in tile_set:
                tile_set.add(edge_signature)
                tiles.append(tile)

    print(f"从图像提取了 {len(tiles)} 个唯一瓦片")
    return tiles


def load_tiles_from_folder(folder_path: str) -> list[Tile]:
    """
    从文件夹中加载所有PNG图像作为瓦片

    读取指定文件夹中的所有PNG文件，每个文件作为一个瓦片。
    所有瓦片必须具有相同的尺寸。

    参数:
        folder_path: 包含PNG瓦片文件的文件夹路径

    返回:
        加载的瓦片列表
    """
    if not os.path.exists(folder_path):
        raise FileNotFoundError(f"瓦片文件夹不存在: {folder_path}")

    # 获取所有PNG文件
    png_files = [f for f in os.listdir(folder_path) if f.lower().endswith('.png')]

    if not png_files:
        raise ValueError(f"文件夹中没有找到PNG文件: {folder_path}")

    print(f"在文件夹 '{folder_path}' 中找到 {len(png_files)} 个PNG文件")

    tiles = []
    tile_set = set()
    expected_size = None

    for i, filename in enumerate(sorted(png_files)):
        filepath = os.path.join(folder_path, filename)

        try:
            img = pygame.image.load(filepath)
            width, height = img.get_size()

            # 检查所有瓦片尺寸是否一致
            if expected_size is None:
                expected_size = (width, height)
                print(f"  瓦片尺寸: {width}x{height} 像素")
            elif (width, height) != expected_size:
                print(f"  ⚠ 跳过 '{filename}': 尺寸不匹配 ({width}x{height}, 期望 {expected_size[0]}x{expected_size[1]})")
                continue

            # 提取所有像素
            pixels = []
            for y in range(height):
                row = []
                for x in range(width):
                    color = img.get_at((x, y))
                    row.append((color.r, color.g, color.b, color.a))
                pixels.append(row)

            # 创建瓦片并去重
            tile = Tile(pixels)
            edge_signature = (
                tile.edges['up'],
                tile.edges['right'],
                tile.edges['down'],
                tile.edges['left']
            )

            if edge_signature not in tile_set:
                tile_set.add(edge_signature)
                tiles.append(tile)
                print(f"  ✓ 加载: {filename}")
            else:
                print(f"  - 跳过重复: {filename}")

        except Exception as e:
            print(f"  ✗ 加载失败 '{filename}': {e}")
            continue

    if not tiles:
        raise ValueError("没有成功加载任何瓦片")

    print(f"成功加载 {len(tiles)} 个唯一瓦片")
    return tiles


def generate_tile_variants(
    base_tiles: list[Tile],
    allow_rotate: bool,
    allow_flip: bool
) -> list[Tile]:
    """
    生成瓦片的旋转和翻转变体

    通过旋转和翻转原始瓦片，可以增加可用瓦片的数量和多样性，
    从而生成更丰富的图案。

    参数:
        base_tiles: 原始瓦片列表
        allow_rotate: 是否生成旋转变体（0°, 90°, 180°, 270°）
        allow_flip: 是否生成翻转变体

    返回:
        包含所有变体的瓦片列表
    """
    all_tiles = []
    tile_set = set()

    for tile in base_tiles:
        variants = [tile]

        # 生成旋转变体（90°, 180°, 270°）
        if allow_rotate:
            t = tile
            for _ in range(3):
                t = t.rotate_90()
                variants.append(t)

        # 生成翻转变体
        if allow_flip:
            flipped = tile.flip_horizontal()
            variants.append(flipped)

            # 翻转后的瓦片也可以旋转
            if allow_rotate:
                t = flipped
                for _ in range(3):
                    t = t.rotate_90()
                    variants.append(t)

        # 去重（有些变体可能相同，如对称图案）
        for v in variants:
            sig = (v.edges['up'], v.edges['right'], v.edges['down'], v.edges['left'])
            if sig not in tile_set:
                tile_set.add(sig)
                all_tiles.append(v)

    return all_tiles


def build_adjacency_rules(tiles: list[Tile]) -> dict:
    """
    构建瓦片邻接规则

    计算哪些瓦片可以相邻放置。两个瓦片可以相邻当且仅当
    它们接触的边缘像素完全相同。

    参数:
        tiles: 所有可用的瓦片列表

    返回:
        邻接规则字典，格式为 {瓦片索引: {'up': [...], 'right': [...], ...}}
    """
    rules = {
        i: {'up': [], 'right': [], 'down': [], 'left': []}
        for i in range(len(tiles))
    }

    # 对每一对瓦片，检查它们是否可以相邻
    for i, tile1 in enumerate(tiles):
        for j, tile2 in enumerate(tiles):
            # 检查tile1的右边缘是否匹配tile2的左边缘
            if tile1.edges['right'] == tile2.edges['left']:
                rules[i]['right'].append(j)
                rules[j]['left'].append(i)

            # 检查tile1的下边缘是否匹配tile2的上边缘
            if tile1.edges['down'] == tile2.edges['up']:
                rules[i]['down'].append(j)
                rules[j]['up'].append(i)

    return rules


# ============================================================================
# WFC网格类
# ============================================================================

class WFCGrid:
    """
    Wave Function Collapse 算法的核心网格类

    维护一个网格，其中每个格子都有一组可能的瓦片选项。
    通过不断"塌缩"（选择）格子的瓦片并传播约束，最终生成完整图像。
    """

    def __init__(
        self,
        width: int,
        height: int,
        tiles: list[Tile],
        rules: dict
    ):
        """
        初始化WFC网格

        参数:
            width: 网格宽度（瓦片数量）
            height: 网格高度（瓦片数量）
            tiles: 可用的瓦片列表
            rules: 瓦片邻接规则
        """
        self.width = width
        self.height = height
        self.tiles = tiles
        self.rules = rules
        self.num_tiles = len(tiles)

        # 每个格子的可能选项（初始时每个格子都可以是任意瓦片）
        self.grid = [
            [set(range(self.num_tiles)) for _ in range(width)]
            for _ in range(height)
        ]

        # 已确定的瓦片（None表示未确定）
        self.collapsed = [
            [None for _ in range(width)]
            for _ in range(height)
        ]

    def get_min_entropy_cell(self) -> Optional[tuple[int, int]]:
        """
        找到熵最小的未塌缩格子

        熵表示一个格子的不确定性（可能选项的数量）。
        WFC算法优先选择熵最小的格子进行塌缩。

        返回:
            (x, y) 坐标，如果没有可用格子则返回None
        """
        min_entropy = self.num_tiles + 1
        candidates = []

        for y in range(self.height):
            for x in range(self.width):
                if self.collapsed[y][x] is None:
                    entropy = len(self.grid[y][x])

                    if entropy == 0:
                        return None  # 无解（矛盾）

                    if entropy < min_entropy:
                        min_entropy = entropy
                        candidates = [(x, y)]
                    elif entropy == min_entropy:
                        candidates.append((x, y))

        # 在熵相同的格子中随机选择一个
        return random.choice(candidates) if candidates else None

    def collapse(self, x: int, y: int):
        """
        塌缩指定格子（选择一个瓦片）

        从该格子的可能选项中随机选择一个瓦片，
        然后传播约束到相邻格子。

        参数:
            x: 格子的x坐标
            y: 格子的y坐标
        """
        if self.collapsed[y][x] is not None:
            return  # 已经塌缩过

        if not self.grid[y][x]:
            return  # 无可用选项

        # 随机选择一个瓦片
        tile_idx = random.choice(list(self.grid[y][x]))
        self.collapsed[y][x] = tile_idx
        self.grid[y][x] = {tile_idx}

        # 传播约束到相邻格子
        self.propagate(x, y)

    def propagate(self, start_x: int, start_y: int):
        """
        约束传播算法

        当一个格子被塌缩后，根据邻接规则更新相邻格子的可能选项。
        这个过程会递归地传播到更远的格子。

        参数:
            start_x: 起始格子的x坐标
            start_y: 起始格子的y坐标
        """
        stack = [(start_x, start_y)]

        while stack:
            x, y = stack.pop()

            # 检查四个方向的邻居
            directions = [
                (x, y - 1, 'up', 'down'),      # 上方邻居
                (x + 1, y, 'right', 'left'),   # 右方邻居
                (x, y + 1, 'down', 'up'),      # 下方邻居
                (x - 1, y, 'left', 'right')    # 左方邻居
            ]

            for nx, ny, my_dir, their_dir in directions:
                # 检查邻居是否在网格范围内
                if 0 <= nx < self.width and 0 <= ny < self.height:
                    if self.collapsed[ny][nx] is None:
                        # 计算邻居的有效选项
                        # （必须与当前格子的所有可能瓦片兼容）
                        valid_neighbors = set()
                        for tile_idx in self.grid[y][x]:
                            valid_neighbors.update(self.rules[tile_idx][my_dir])

                        # 更新邻居的选项（取交集）
                        old_options = self.grid[ny][nx]
                        new_options = old_options & valid_neighbors

                        # 如果选项发生变化，继续传播
                        if new_options != old_options:
                            self.grid[ny][nx] = new_options
                            if new_options:  # 只有非空时才继续传播
                                stack.append((nx, ny))

    def is_fully_collapsed(self) -> bool:
        """
        检查是否所有格子都已塌缩

        返回:
            True表示生成完成，False表示还有未确定的格子
        """
        for y in range(self.height):
            for x in range(self.width):
                if self.collapsed[y][x] is None:
                    return False
        return True

    def has_contradiction(self) -> bool:
        """
        检查是否存在矛盾

        矛盾指某个格子没有任何可用的瓦片选项，
        这意味着当前的塌缩序列无法完成。

        返回:
            True表示存在矛盾，需要重新开始
        """
        for y in range(self.height):
            for x in range(self.width):
                if self.collapsed[y][x] is None and not self.grid[y][x]:
                    return True
        return False


# ============================================================================
# WFC算法执行函数
# ============================================================================

def run_wfc(
    width: int,
    height: int,
    tiles: list[Tile],
    rules: dict,
    max_attempts: int = 10
) -> Optional[WFCGrid]:
    """
    运行WFC算法（无显示）

    参数:
        width: 输出宽度（瓦片数量）
        height: 输出高度（瓦片数量）
        tiles: 可用瓦片列表
        rules: 邻接规则
        max_attempts: 最大尝试次数

    返回:
        成功时返回完成的网格，失败返回None
    """
    for attempt in range(max_attempts):
        print(f"\n尝试第 {attempt + 1} 次生成...")
        grid = WFCGrid(width, height, tiles, rules)

        steps = 0
        while not grid.is_fully_collapsed():
            # 检查是否出现矛盾
            if grid.has_contradiction():
                print(f"  ✗ 发现矛盾（步骤 {steps}），重新开始")
                break

            # 找到熵最小的格子
            cell = grid.get_min_entropy_cell()
            if cell is None:
                print(f"  ✗ 无法继续（步骤 {steps}），重新开始")
                break

            # 塌缩该格子
            x, y = cell
            grid.collapse(x, y)
            steps += 1

            # 显示进度
            if Config.SHOW_GENERATION and steps % 50 == 0:
                uncollapsed = sum(
                    1 for row in grid.collapsed
                    for cell in row if cell is None
                )
                print(f"  进度: {steps} 步，剩余 {uncollapsed} 个格子")
                time.sleep(Config.GENERATION_DELAY)

        # 检查是否成功完成
        if grid.is_fully_collapsed():
            print(f"✓ 生成成功！共 {steps} 步")
            return grid

    print(f"\n⚠ {max_attempts} 次尝试后失败")
    return None


def run_wfc_with_display(
    width: int,
    height: int,
    tiles: list[Tile],
    rules: dict,
    display: pygame.Surface,
    scale: float,
    max_attempts: int = 10
) -> Optional[WFCGrid]:
    """
    运行WFC算法，并实时显示生成过程

    参数:
        width: 输出宽度（瓦片数量）
        height: 输出高度（瓦片数量）
        tiles: 可用瓦片列表
        rules: 邻接规则
        display: Pygame显示窗口
        scale: 显示缩放比例
        max_attempts: 最大尝试次数

    返回:
        成功时返回完成的网格，失败返回None
    """
    tile_size = tiles[0].width
    overlap = 1
    original_width = tile_size + (width - 1) * (tile_size - overlap)
    original_height = tile_size + (height - 1) * (tile_size - overlap)
    scaled_width = int(original_width * scale)
    scaled_height = int(original_height * scale)

    # 创建用于实时渲染的surface
    render_surface = pygame.Surface((original_width, original_height), pygame.SRCALPHA)
    clock = pygame.time.Clock()

    for attempt in range(max_attempts):
        print(f"\n尝试第 {attempt + 1} 次生成...")
        grid = WFCGrid(width, height, tiles, rules)
        render_surface.fill((50, 50, 50, 255))  # 灰色背景表示未确定的区域

        steps = 0
        while not grid.is_fully_collapsed():
            # 处理pygame事件（允许用户关闭窗口）
            for event in pygame.event.get():
                if event.type == pygame.QUIT or \
                   (event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE):
                    pygame.quit()
                    return None

            # 检查是否出现矛盾
            if grid.has_contradiction():
                print(f"  ✗ 发现矛盾（步骤 {steps}），重新开始")
                break

            # 找到熵最小的格子
            cell = grid.get_min_entropy_cell()
            if cell is None:
                print(f"  ✗ 无法继续（步骤 {steps}），重新开始")
                break

            # 塌缩该格子
            x, y = cell
            grid.collapse(x, y)
            steps += 1

            # 实时渲染刚刚塌缩的瓦片
            if Config.SHOW_GENERATION:
                tile_idx = grid.collapsed[y][x]
                if tile_idx is not None:
                    tile = tiles[tile_idx]
                    pos_x = x * (tile_size - overlap)
                    pos_y = y * (tile_size - overlap)

                    # 绘制瓦片的所有像素
                    for ty in range(tile_size):
                        for tx in range(tile_size):
                            pixel = tile.pixels[ty][tx]
                            dest_x = pos_x + tx
                            dest_y = pos_y + ty
                            render_surface.set_at((dest_x, dest_y), pixel)

                # 缩放并显示
                scaled_surface = pygame.transform.scale(
                    render_surface,
                    (scaled_width, scaled_height)
                )
                display.fill((255, 255, 255))
                display.blit(scaled_surface, (0, 0))

                # 显示统计信息
                if steps % 10 == 0:
                    uncollapsed = sum(
                        1 for row in grid.collapsed
                        for cell in row if cell is None
                    )
                    progress = (steps / (width * height)) * 100
                    pygame.display.set_caption(
                        f"WFC生成中... 步骤:{steps}/{width*height} "
                        f"进度:{progress:.1f}% 剩余:{uncollapsed}"
                    )

                pygame.display.flip()
                clock.tick(1000)  # 限制最大帧率

                if Config.GENERATION_DELAY > 0:
                    time.sleep(Config.GENERATION_DELAY)

        # 检查是否成功完成
        if grid.is_fully_collapsed():
            print(f"✓ 生成成功！共 {steps} 步")
            return grid

    print(f"\n⚠ {max_attempts} 次尝试后失败")
    return None


# ============================================================================
# 渲染和输出函数
# ============================================================================

def generate_output_filename() -> str:
    """
    生成包含配置信息的输出文件名

    文件名格式: 源图像名_瓦片大小_输出尺寸_变换_时间戳.png
    例如: Water_t4_24x24_RF_20240101_120000.png

    返回:
        生成的文件名
    """
    # 获取源图像名（不含扩展名）
    source_name = os.path.splitext(os.path.basename(Config.ORIGINAL_IMG_PATH))[0]

    # 生成时间戳
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")

    # 构建变换描述
    rotate_str = "R" if Config.ALLOW_ROTATE else ""
    flip_str = "F" if Config.ALLOW_FLIP else ""
    transform_str = rotate_str + flip_str if (rotate_str or flip_str) else "NoTrans"

    # 构建完整文件名
    filename = (
        f"{source_name}_t{Config.TILE_SIZE}_"
        f"{Config.OUTPUT_WIDTH}x{Config.OUTPUT_HEIGHT}_"
        f"{transform_str}_{timestamp}.png"
    )

    return filename


def render_grid(grid: WFCGrid, tiles: list[Tile], scale: float) -> pygame.Surface:
    """
    渲染网格到Surface，正确处理瓦片重叠

    相邻瓦片共享边缘像素，确保生成的图像无缝连接。

    参数:
        grid: 完成的WFC网格
        tiles: 瓦片列表
        scale: 缩放比例

    返回:
        渲染并缩放后的Surface
    """
    tile_size = tiles[0].width  # 瓦片的完整尺寸
    overlap = 1  # 相邻瓦片共享1个像素的边缘

    # 计算原始图像尺寸
    # 第一个瓦片占 tile_size 像素
    # 后续每个瓦片增加 (tile_size - overlap) 像素
    original_width = tile_size + (grid.width - 1) * (tile_size - overlap)
    original_height = tile_size + (grid.height - 1) * (tile_size - overlap)

    print(f"  瓦片尺寸: {tile_size}x{tile_size} 像素")
    print(f"  网格尺寸: {grid.width}x{grid.height} 个瓦片")
    print(f"  原始图像尺寸: {original_width}x{original_height} 像素")
    print(f"  缩放后尺寸: {int(original_width * scale)}x{int(original_height * scale)} 像素")

    # 创建渲染surface
    surface = pygame.Surface((original_width, original_height), pygame.SRCALPHA)

    # 渲染每个瓦片（相邻瓦片重叠绘制）
    for y in range(grid.height):
        for x in range(grid.width):
            tile_idx = grid.collapsed[y][x]
            if tile_idx is not None:
                tile = tiles[tile_idx]

                # 计算此瓦片在最终图像中的左上角位置
                pos_x = x * (tile_size - overlap)
                pos_y = y * (tile_size - overlap)

                # 绘制完整的瓦片（所有像素）
                for ty in range(tile_size):
                    for tx in range(tile_size):
                        pixel = tile.pixels[ty][tx]
                        dest_x = pos_x + tx
                        dest_y = pos_y + ty
                        surface.set_at((dest_x, dest_y), pixel)

    # 缩放surface
    scaled_width = int(original_width * scale)
    scaled_height = int(original_height * scale)
    scaled_surface = pygame.transform.scale(surface, (scaled_width, scaled_height))

    return scaled_surface


# ============================================================================
# 主函数
# ============================================================================

def main():
    """
    主程序入口

    执行流程:
    1. 加载并提取瓦片
    2. 生成瓦片变体
    3. 构建邻接规则
    4. 创建显示窗口
    5. 运行WFC算法
    6. 渲染并保存结果
    """
    print("=" * 60)
    print("Wave Function Collapse - 图像生成器")
    print("=" * 60)

    start_time = time.time()

    # ========================================================================
    # 第1步: 加载瓦片
    # ========================================================================
    print(f"\n【第1步】加载瓦片...")
    print(f"         模式: {Config.TILE_SOURCE_MODE}")

    if Config.TILE_SOURCE_MODE == "folder":
        # 从文件夹加载PNG瓦片
        print(f"         文件夹路径: {Config.TILE_FOLDER_PATH}")
        base_tiles = load_tiles_from_folder(Config.TILE_FOLDER_PATH)
    elif Config.TILE_SOURCE_MODE == "image":
        # 从图像切割瓦片
        print(f"         源图像: {Config.ORIGINAL_IMG_PATH}")
        print(f"         瓦片大小: {Config.TILE_SIZE}x{Config.TILE_SIZE}")
        base_tiles = load_tiles_from_image(Config.ORIGINAL_IMG_PATH, Config.TILE_SIZE)
    else:
        raise ValueError(f"不支持的瓦片来源模式: {Config.TILE_SOURCE_MODE}，请使用 'image' 或 'folder'")

    # ========================================================================
    # 第2步: 生成变体
    # ========================================================================
    print(f"\n【第2步】生成变体 (旋转={Config.ALLOW_ROTATE}, 翻转={Config.ALLOW_FLIP})...")
    all_tiles = generate_tile_variants(
        base_tiles,
        Config.ALLOW_ROTATE,
        Config.ALLOW_FLIP
    )
    print(f"         总共 {len(all_tiles)} 个瓦片")

    # ========================================================================
    # 第3步: 构建邻接规则
    # ========================================================================
    print("\n【第3步】构建邻接规则...")
    rules = build_adjacency_rules(all_tiles)

    # 统计规则
    total_rules = sum(
        len(r['up']) + len(r['right']) + len(r['down']) + len(r['left'])
        for r in rules.values()
    )
    print(f"         总共 {total_rules} 条邻接规则")

    # 显示前几个瓦片的规则统计
    print("\n         前5个瓦片的邻接规则:")
    for i in range(min(5, len(all_tiles))):
        print(f"           瓦片 {i}: 上={len(rules[i]['up'])}, "
              f"右={len(rules[i]['right'])}, "
              f"下={len(rules[i]['down'])}, "
              f"左={len(rules[i]['left'])}")

    # ========================================================================
    # 第4步: 创建显示窗口
    # ========================================================================
    tile_size = all_tiles[0].width
    overlap = 1
    original_width = tile_size + (Config.OUTPUT_WIDTH - 1) * (tile_size - overlap)
    original_height = tile_size + (Config.OUTPUT_HEIGHT - 1) * (tile_size - overlap)
    window_width = int(original_width * Config.SCALE)
    window_height = int(original_height * Config.SCALE)

    print(f"\n【第4步】创建窗口: {window_width}x{window_height} 像素")
    Config.DISPLAY = pygame.display.set_mode((window_width, window_height))
    pygame.display.set_caption("Wave Function Collapse - 初始化中...")

    # ========================================================================
    # 第5步: 运行WFC算法
    # ========================================================================
    print(f"\n【第5步】开始生成 {Config.OUTPUT_WIDTH}x{Config.OUTPUT_HEIGHT} 的图像...")

    if Config.SHOW_GENERATION:
        grid = run_wfc_with_display(
            Config.OUTPUT_WIDTH,
            Config.OUTPUT_HEIGHT,
            all_tiles,
            rules,
            Config.DISPLAY,
            Config.SCALE,
            max_attempts=20
        )
    else:
        grid = run_wfc(
            Config.OUTPUT_WIDTH,
            Config.OUTPUT_HEIGHT,
            all_tiles,
            rules,
            max_attempts=20
        )

    # 检查生成是否成功
    if grid is None:
        print("\n❌ 生成失败！尝试调整参数：")
        print("   - 减小输出尺寸")
        print("   - 增大瓦片尺寸")
        print("   - 启用旋转/翻转")
        return

    # ========================================================================
    # 第6步: 渲染最终图像
    # ========================================================================
    print("\n【第6步】渲染最终图像...")
    rendered = render_grid(grid, all_tiles, Config.SCALE)

    # 保存图像
    if Config.SAVE_OUTPUT:
        # 确保输出目录存在
        os.makedirs(Config.OUTPUT_DIR, exist_ok=True)

        # 生成包含设置信息的文件名
        filename = generate_output_filename()
        output_path = os.path.join(Config.OUTPUT_DIR, filename)

        pygame.image.save(rendered, output_path)
        print(f"         图像已保存到: {output_path}")

    # ========================================================================
    # 显示总结信息
    # ========================================================================
    elapsed = time.time() - start_time
    print(f"\n{'=' * 60}")
    print(f"✓ 生成完成！总耗时: {elapsed:.2f}秒")
    print(f"{'=' * 60}")

    # ========================================================================
    # 显示循环（等待用户关闭窗口）
    # ========================================================================
    pygame.display.set_caption("Wave Function Collapse - 完成！按ESC退出")
    print("\n窗口已打开，按ESC或关闭窗口退出...")

    clock = pygame.time.Clock()
    running = True
    while running:
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
            elif event.type == pygame.KEYDOWN:
                if event.key == pygame.K_ESCAPE:
                    running = False

        Config.DISPLAY.fill((255, 255, 255))
        Config.DISPLAY.blit(rendered, (0, 0))
        pygame.display.flip()
        clock.tick(30)

    pygame.quit()
    print("\n程序结束")


# ============================================================================
# 程序入口
# ============================================================================

if __name__ == "__main__":
    main()

相关样本文件可以参考 GitHub - WaveFunctionCollapse。

讨论

算法优势

这个算法从效率角度来讲，算不上特别高效，但它的优势在于极高的自由度。

例如，我们上文是从一个样本图像中提取瓦片并生成新图像，但实际上，我们可以直接指定一组瓦片，以生成特定风格的图案：

Circuit

Knots

Castle

FloorPlan

同样的，对于游戏地图生成，我们还可以指定某处必须是某种瓦片（如水域），或是某处必须是空地等。这给了我们极大的灵活性。

从平面到立体

WFC 算法的另一个优势是，它并不局限于二维平面。我们可以将其扩展到三维，生成体素化的 3D 模型。

目前，已有很多类似的项目在做这件事，例如 Procedural Building Generation in Unity、Proc Skater 2016 等等。

对于三维情况，算法几乎不变，但瓦片变成了立方体，邻接规则也从四个方向变成了六个方向（上下左右前后）。这使得我们可以生成复杂的三维结构，例如建筑、地形等。在这种条件下，每次塌缩造成的影响会更大，更加容易出现矛盾，因此需要更强的瓦片集和更复杂的邻接规则。

形式化理解零知识证明

mail@ch3nyang.top (Ch3nyang) — Wed, 01 Oct 2025 19:00:00 +0800

如何在不让对方知道我内裤颜色的情况下，向对方证明我穿了内裤？你也许需要了解零知识证明。

为了理解本文，你可能需要具备密码学的基础知识，了解哈希函数、公钥密码学等概念。你也需要了解 NP 完全性、图论等计算复杂性理论的基础知识。可以参考之前的文章。

Intro

假设我们有一个 5x5 的数字网格，里面随机填充了数字 1 到 25。我们想向别人证明 25 这个数字在网格中存在，但不想透露它的位置。

为了实现这一点，我们可以用一块不透明的遮罩覆盖整个网格，只在 25 所在的位置挖一个洞。这样，观察者能看到洞里露出的数字 25，知道它确实存在于网格中，但无法确定它在表格中的相对位置，因为其他数字都被遮住了。

下面是一个可以互动的演示，展示了这个概念：

Your browser does not support iframes. Click here to visit the content

另一个更加经典的例子是阿里巴巴洞穴 (Ali Baba cave) 问题：

洞穴有一个需要口令才能打开的魔法门，里面是环形道路
Alice 向 Bob 声称她知道开门口令，但不想直接把口令告诉 Bob
他们设计一个交互协议，Bob 在洞口等，Alice 随机选一条路进入，Bob 再随机喊她从某一条路出来
- 如果 Alice 真知道口令，她总能从要求的那条路出来（可以走中间开门穿过去）
- 如果不知道，只有 50% 概率猜对 Bob 的要求
如果 Bob 看到 Alice 从正确的路出来，Bob 会认为 Alice 可能知道口令，对其信任度更加了一分

值得注意的是，如果 Alice 是作弊者，则她必须在进入洞穴前就「赌」Bob 会让她从哪边出来。如果赌 A 出口，她就从 A 进去；如果 Bob 恰好喊 A，她就成功了。如果 Bob 喊 B，她就失败了。

重复多次后，Bob 便有极高的把握相信 Alice 知道口令——但 Bob 没有看到口令本身，也不知道口令是什么。

以上两个例子都展示了零知识证明的核心思想：在不透露任何额外信息的情况下，向对方证明某个陈述为真。

零知识证明的定义

1985 年，Shafi Goldwasser、Silvio Micali 和 Charles Rackoff 率先在《互动证明系统的知识复杂性》一文中提出了零知识证明的概念。他们定义了零知识证明为一种协议，使得一方（证明者）可以向另一方（验证者）证明某个陈述为真，而不揭示任何信息，除了这个特定陈述为真。

零知识证明必须满足三个性质：

完备性 (completeness)：若所要证之事为真，则诚实的证明者能说服诚实验证者
可靠性 (soundness)：若命题为假，则作弊证明者仅得极小机会能说服诚实验证者该事为真
零知识性 (zero-knowledge)：若命题为真，则验证者除此之外，过程中没有得悉任何其他信息

需要注意的是，零知识证明允许有很少的概率，让作弊证明者能向验证者「证明」假命题。这个概率称为可靠性误差 (soundness error)。换句话说，零知识证明是证明命题为真的概率极大，但并不是一定为真。

当然，上面的定义太过模糊了，为了在数学和计算机科学中精确地描述和证明其安全性，下面给出一个更形式化的定义。

在给出定义前，我们先介绍一些必要的概念：

交互证明系统 (interactive proof system) 是指一对图灵机 $\left( P, V \right)$ 交换信息。其中 $P$ 是证明者；$V$ 是验证者，其为概率多项式时间 (PPT) 机器。
- 如果陈述为真，$V$ 以极高的概率接受该陈述
- 如果陈述为假，任何计算能力有限的恶意 $P^*$ 只能以可忽略的概率说服 $V$ 接受该陈述
零知识性 (zero-knowledge) 是指对于任何（可能恶意的）PPT 验证者 $V^*$，存在一个 PPT 模拟器 $S$，能在不知道证据 $w$ 的情况下，生成一个与真实交互记录（即 $V^*$ 与诚实证明者 $P$ 交互时的视图）计算上不可区分的输出。
计算模型和语言

设 $L$ 是一个 NP 的语言（例如 $L=\left\{所有可满足的布尔公式\right\}$）。对于 $x \in L$，存在一个证据 $w$ 使得 $R_L: (x, w) \in R$，其中 $R$ 是一个多项式时间可验证的关系。
视图 (view)

在真实交互中，验证者 $V^*$ 看到的视图包括：
- 公共输入 $x$ 和自己的随机带 $r$（所有可能的随机选择）
- 从证明者 $P$ 收到的消息
- 对于非黑盒模拟情况下，$V^*$ 的内部状态
$\text{View}_{V^*}^{P}(x) = \left\{ \left( r, m_1, m_2, \cdots, m_t \right) \right\}$ 表示 $V^*$ 在与 $P$ 交互时的视图。其中，$m_i$ 是第 $i$ 轮交互中 $P$ 发送给 $V^*$ 的消息。
模拟器 (simulator)

模拟器 $S$ 是一个 PPT 算法，给定陈述 $x$ 和对 $V^*$ 的描述，可以访问 $V^*$ 作为子程序，并尝试输出一个分布上与 $\text{View}_{V^*}^{P}(x)$ 计算上不可区分的视图。
- 对于黑盒模拟，$S$ 把 $V^*$ 作为一个黑盒子，不能访问其内部状态，只能通过输入输出交互
- 对于非黑盒模拟，$S$ 可以访问 $V^*$ 的代码或内部状态，并可以据此构造模拟
计算不可区分性 (computational indistinguishability)

两个分布族 $\left\{ X_n \right\}$ 和 $\left\{ Y_n \right\}$ 计算上不可区分，若对于任意 PPT 区分器 $D$，有：
\[\left| \Pr\left[ D\left( X_n \right) = 1 \right] - \Pr\left[ D\left( Y_n \right) = 1 \right] \right| < \text{negl}(n)\]
其中 $\text{negl}(n)$ 是一个忽略函数。该式表示随着 $n$ 增大，差值趋近于零。

零知识证明分为三类：

完美零知识 (perfect zero-knowledge, PZK)：模拟器生成的视图与真实交互的视图在统计上完全相同，即
\[\text{View}_{V^*}^{P}(x) \equiv S^{V^*}(x)\]
统计零知识 (statistical zero-knowledge, SZK)：模拟器生成的视图与真实交互的视图在统计距离上可以忽略，即
\[\text{View}_{V^*}^{P}(x) \approx S^{V^*}(x)\]
计算零知识 (computational zero-knowledge, CZK)：模拟器生成的视图与真实交互的视图在计算上不可区分。即对于任意 PPT 区分器 $D$，有
\[\left| \Pr\left[ D\left( \text{View}_{V^*}^{P}(x) \right) = 1 \right] - \Pr\left[ D\left( S^{V^*}(x) \right) = 1 \right] \right| < \text{negl}(n)\]

现在，我们终于可以给出 CZK 的形式化定义：

一个交互证明系统 $\left( P, V \right)$ 对语言 $L$ 是计算零知识的，若对于任意 PPT 验证者 $V^*$，存在一个 PPT 模拟器 $S$，使得对于所有 $x \in L$ 及给 $V^*$ 的先验信息 $z$，有：

\[\left\{ \text{View}_{V^*(z)}^{P}(x) \right\} \approx_c \left\{ S^{V^*(z)}(x, z) \right\}\]

其中：

$\text{View}_{V^*(z)}^{P}(x)$ 是 $V^*$ 在输入 $x$ 和先验信息 $z$ 下与 $P$ 交互后的视图
$\approx_c$ 表示计算上不可区分
$S^{V^*(z)}(x, z)$ 是模拟器 $S$ 在不知道证据情况下的输出

交互式零知识证明协议

根据以上内容，我们可以设计出一些零知识证明协议。其通常包含了以下几个步骤：

承诺 (commitment)：证明者 $P$ 生成一个承诺值 $C$，并将其发送给验证者 $V$。这个承诺值是对某个秘密信息 $w$ 的加密表示，确保 $P$ 不能在后续步骤中更改 $w$
挑战 (challenge)：验证者 $V$ 随机选择一个挑战 $c$，并将其发送给 $P$。这个挑战通常是从一个预定义的集合中随机选择的
响应 (response)：证明者 $P$ 根据挑战 $c$ 和秘密信息 $w$ 计算一个响应 $r$，并将其发送给 $V$
验证 (verification)：验证者 $V$ 使用承诺值 $C$、挑战 $c$ 和响应 $r$ 来验证证明者 $P$ 是否知道秘密信息 $w$。如果验证通过，$V$ 接受该证明；否则拒绝

sequenceDiagram
    participant P as Prover(P)
    participant V as Verifier(V)
    P->>V: 1. Commit C
    V->>P: 2. Challenge c
    P->>V: 3. Response r
    V->>V: 4. Verify (C, c, r)

这种协议被称为 Sigma 协议，因其三步结构（Commit-Challenge-Response）形似希腊字母 $\Sigma$ 而得名。下面我们通过经典的 Schnorr 协议来具体分析。

Schnorr 协议

最经典的交互式零知识证明之一是 Schnorr 协议，用于证明离散对数的知识。在这个问题中，给定一个循环群 $\mathbb{G}$，其生成元为 $g$，阶为 $q$。公开信息为 $y \in \mathbb{G}$，证明者 Alice 声称她知道一个秘密 $x \in \mathbb{Z}_q$，使得 $y = g^x$。她想向验证者 Bob 证明这一点，而不透露 $x$ 的值。

协议步骤

承诺：Alice 选择一个随机数 $r \in \mathbb{Z}_q$（称为 nonce），计算承诺 $C = g^r$，并将 $C$ 发送给 Bob
挑战：Bob 选择一个随机挑战 $c \in \mathbb{Z}_q$，并将其发送给 Alice
响应：Alice 计算响应 $s = r + cx \pmod q$，并将 $s$ 发送给 Bob
验证：Bob 收到 $s$ 后，验证等式 $g^s = C \cdot y^c$ 是否成立

协议分析

完备性 (Completeness)：如果 Alice 是诚实的，她知道 $x$ 并且遵循协议。Bob 的验证会通过，因为：
\[g^s = g^{r+cx} = g^r \cdot g^{cx} = g^r \cdot (g^x)^c = C \cdot y^c\]
因此，诚实的证明者总能说服诚实的验证者
可靠性 (Soundness)：如果 Alice 是一个不知道 $x$ 的作弊者，她能否欺骗 Bob？为了通过验证，她必须在收到挑战 $c$ 后，提供一个能使 $g^s = C \cdot y^c$ 成立的 $s$

假设作弊者 Alice 发送了某个承诺 $C$。当她收到挑战 $c$ 时，她需要找到一个 $s$。由于她不知道 $x$，她无法通过 $s = r + cx$ 计算出正确的 $s$。她成功的唯一机会是在发送 $C$ 之前就猜对 Bob 将要发送的挑战 $c^\prime$
- 她可以选择一个随机的 $s^\prime$，然后计算 $C = g^{s^\prime} \cdot y^{-c^\prime}$
- 她将这个 $C$ 发送给 Bob。如果 Bob 恰好返回挑战 $c = c^\prime$，她就可以用 $s^\prime$ 作为响应，验证将会通过
- 然而，由于 $c$ 是从 $\mathbb{Z}_q$ 中随机选择的，她猜对的概率只有 $1/q$，这是一个可以忽略的极小概率。因此，该协议是可靠的
零知识性 (Zero-Knowledge)：为了证明零知识性，我们需要构建一个模拟器 $S$，它可以在不知道秘密 $x$ 的情况下，生成一个与真实交互记录 $(C, c, s)$ 在计算上不可区分的输出

模拟器 $S$ 的工作方式如下：
1. 选择随机的 $s^\prime \in \mathbb{Z}_q$ 和 $c^\prime \in \mathbb{Z}_q$
2. 计算伪承诺 $C^\prime = g^{s^\prime} \cdot y^{-c^\prime}$
3. 输出三元组 $(C^\prime, c^\prime, s^\prime)$ 作为模拟的交互记录
这个模拟出的三元组 $(C^\prime, c^\prime, s^\prime)$ 与真实交互中生成的三元组 $(C, c, s)$ 具有完全相同的分布。在真实协议中，$r$ 是随机的，$c$ 是随机的，这导致 $s=r+cx$ 也是随机的；在模拟中，$s^\prime$ 和 $c^\prime$ 是随机的，这导致 $C^\prime$ 也是随机的。由于 $C, c, s$ 都是 $\mathbb{Z}_q$ 上的均匀随机元素，任何人都无法区分 $(C, c, s)$ 是来自真实交互还是模拟器。因此，验证者没有获得关于 $x$ 的任何信息

大图的哈密顿环问题

另一个经典的交互式证明例子是图的哈密顿环问题。这是一个著名的 NP 完全问题。假设 Alice (证明者) 想向 Bob (验证者) 证明她知道一个大图 $G$ 的哈密顿环（即一条经过每个顶点恰好一次的闭合路径），但不想透露具体的环。

协议步骤

承诺 (Commitment)：Alice 知道图 $G=(V, E)$ 和一个哈密顿环 $C$。她生成一个随机的顶点置换（permutation）$\pi$，并用它来构造一个新图 $H = \pi(G)$。这个新图 $H$ 与 $G$ 是同构的。然后，Alice 对图 $H$ 的邻接矩阵进行承诺，并将承诺值 $comm(H)$ 发送给 Bob

一个常用的承诺方案是，对邻接矩阵的每个元素进行哈希，然后将这些哈希值构建成一棵默克尔树 (Merkle Tree)，并将树根作为承诺 $comm(H)$
挑战 (Challenge)：Bob 收到承诺后，随机选择一个比特 $b \in \{0, 1\}$ 作为挑战发送给 Alice
响应 (Response)：
- 如果 $b=0$，Alice 公开置换 $\pi$
- 如果 $b=1$，Alice 公开 $H$ 中的哈密顿环 $C^\prime = \pi(C)$，并为构成该环的所有边提供默克尔证明，以证明它们确实是 $H$ 的一部分
验证 (Verification)：
- 如果 Bob 的挑战是 $b=0$，他会验证 $H = \pi(G)$ 是否成立
- 如果 Bob 的挑战是 $b=1$，他会验证 $C^\prime$ 确实是 $H$ 的一个哈密顿环

协议分析

完备性：如果 Alice 知道哈密顿环，她总能正确响应 Bob 的任何挑战
可靠性：如果 Alice 不知道哈密顿环，她只能猜测 Bob 的挑战。她可以准备一个同构图 $H$（对应 $b=0$ 的情况），或者准备一个包含哈密顿环但与 $G$ 无关的图 $H$（对应 $b=1$ 的情况）。无论哪种情况，她成功欺骗 Bob 的概率都只有 $50%$
零知识性：在单次交互中，如果 Bob 挑战 $b=0$，他只看到了一个随机的图同构，没有获得关于哈密顿环的信息。如果他挑战 $b=1$，他只看到了一个随机图中的哈密顿环，无法将其映射回原图 $G$。因此，Bob 没有获得任何关于 $G$ 中哈密顿环的知识

非交互式零知识证明

以上零知识证明协议都需要证明者和验证者之间进行多轮交互。然而，在某些场景下，例如区块链交易或数字签名，证明需要被广播给多个验证者，或者在不同时间进行验证，此时多轮交互变得不切实际。

非交互式零知识证明 (non-interactive zero-knowledge proof, NIZK) 解决了这个问题。在 NIZK 中，证明者可以生成一个单独的证明字符串 $\pi$，任何拥有公开信息的验证者都可以独立地、在任何时间验证该证明，而无需与证明者进行任何交互。

NIZK 的实现通常依赖于一个共同的、可信的参考信息，这被称为公共参考字符串 (Common Reference String, CRS) 模型。CRS 在所有协议参与方之间共享，并被认为是可信的。

Fiat-Shamir 变换

将交互式证明转换为非交互式证明的关键思想是消除由验证者提供的随机挑战。Fiat-Shamir 变换是一种实现此目的的著名技术，它在随机预言机模型 (Random Oracle Model, ROM) 下是安全的。

在 ROM 中，我们假设存在一个理想的密码学哈希函数 $H$，其行为如同一个随机预言机：对于任何新的输入，它都会返回一个真正随机的、均匀分布的输出。

Fiat-Shamir 变换的核心思想是：证明者使用哈希函数 $H$ 自行生成挑战，而不是从验证者那里接收。具体步骤如下：

证明者执行交互式协议的承诺步骤，生成承诺值 $C$
证明者将所有公开信息（如问题陈述 $x$）和本轮的承诺 $C$ 作为输入，通过哈希函数 $H$ 计算挑战：
\[c = H(x, C)\]
证明者使用这个自生成的挑战 $c$ 来计算响应 $s$
最终的非交互式证明 $\pi$ 由承诺和响应组成，即 $\pi = (C, s)$

验证者收到证明 $\pi = (C, s)$ 后，可以独立地执行以下操作：

使用与证明者相同的公开信息 $x$ 和证明中的承诺 $C$，计算出挑战：$c^\prime = H(x, C)$
使用计算出的挑战 $c^\prime$ 和证明中的响应 $s$，执行原始交互式协议的验证步骤

由于密码学哈希函数的输出是确定性的（相同的输入总产生相同的输出）且不可预测的（在计算出哈希值之前无法知道它），这个哈希值有效地替代了真实验证者提供的随机挑战。证明者因为无法预测哈希函数的输出，所以不能像在交互式协议中那样通过预先设计承诺来作弊。

我们可以将 Fiat-Shamir 变换应用于前述的 Schnorr 协议，得到一个非交互式的签名方案（Schnorr 签名）：

证明生成 (签名)：
- Alice (证明者) 拥有秘密 $x$ 和公钥 $y=g^x$
- 她选择一个随机数 $r \in \mathbb{Z}_q$，计算承诺 $C = g^r$
- 她使用哈希函数 $H$ 计算挑战 $c = H(y, C)$
- 她计算响应 $s = r + cx \pmod q$
- 非交互式证明（即签名）为 $\pi = (C, s)$
证明验证 (验证签名)：
- Bob (验证者) 拥有 Alice 的公钥 $y$ 和签名 $\pi = (C, s)$
- 他计算挑战 $c^\prime = H(y, C)$
- 他验证等式 $g^s = C \cdot y^{c^\prime}$ 是否成立

这个过程无需任何交互，Alice 只需发布她的签名 $\pi$，任何人都可以验证它。

zk-SNARKs vs zk-STARKs

在 NIZK 领域，zk-SNARKs 和 zk-STARKs 是目前最重要和最广泛使用的两种技术。它们都是为了生成高效、非交互式的零知识证明，但在实现和特性上存在显著差异。

zk-SNARK (Zero-Knowledge Succinct Non-Interactive Argument of Knowledge)
- 优点：
  - 简洁性 (Succinct)：证明尺寸非常小，通常只有几百个字节，这使得它们非常适合在区块链等存储空间有限的环境中使用
  - 验证快：验证过程非常高效，计算开销很小
- 缺点：
  - 需要可信设置 (Trusted Setup)：大多数 zk-SNARKs 方案需要一个复杂的初始设置阶段来生成公共参数。这个过程会产生一些「有毒废料」（toxic waste），如果这些秘密数据没有被安全销毁，攻击者就可以用它来伪造证明。这个可信设置仪式需要参与者高度诚实
  - 非抗量子性：许多基于椭圆曲线的 zk-SNARKs 方案无法抵抗量子计算机的攻击
zk-STARK (Zero-Knowledge Scalable Transparent Argument of Knowledge)
- 优点：
  - 透明性 (Transparent)：无需可信设置。其公共参数是使用公开、可验证的随机性生成的，消除了对可信设置仪式的依赖，更加安全
  - 可扩展性 (Scalable)：当需要证明的计算规模增大时，其证明生成和验证时间的增长速度优于 zk-SNARKs
  - 抗量子性 (Quantum-Resistant)：它基于更简单的密码学假设（抗碰撞的哈希函数），因此被认为是抗量子的
- 缺点：
  - 证明尺寸大：其证明尺寸比 zk-SNARKs 大得多（通常是几十到几百 KB），这会增加链上存储成本和网络传输开销

特性	zk-SNARK	zk-STARK
*证明大小*	非常小 (Succinct)	较大
*可信设置*	通常需要	不需要 (Transparent)
*抗量子性*	通常不是	是
*密码学假设*	椭圆曲线、配对	抗碰撞哈希函数

总而言之，NIZK 技术，特别是 zk-SNARKs 和 zk-STARKs，是推动零知识证明从理论走向大规模实际应用的关键。它们使得在保护隐私的同时进行复杂验证成为可能，为区块链扩容、去中心化身份等领域打开了新的大门。

应用

零知识证明的应用场景极其广泛，尤其是在需要隐私保护和可验证计算的领域。

隐私交易与混币器

混币器 (Coin Mixer) 旨在打破加密货币交易图谱的可追溯性。Tornado Cash 是一个经典的基于 ZKP 的实现。

其核心思想是：用户将资金存入一个智能合约的「池子」中，之后可以从一个全新的地址将相同金额的资金取出。由于池中混合了大量来自不同用户的资金，外部观察者无法将存款与取款关联起来。

其协议流程如下：

sequenceDiagram
    participant Alice_A as 存款地址
    participant Contract as Tornado Cash 合约
    participant Alice_B as 取款地址

    Alice_A->>Alice_A: 1. 生成秘密 (s) & 无效符 (n)
    Alice_A->>Alice_A: 2. 计算承诺 C = H(s, n)
    Alice_A->>Contract: 3. Deposit(ETH, C)
    Contract->>Contract: 4. 将 C 添加到 Merkle Tree

    Note over Alice_A, Alice_B: 等待一段时间...

    Alice_B->>Alice_B: 5. 为承诺生成 ZKP (π)
    Alice_B->>Alice_B: 6. 计算 Nullifier Hash h_null = H(n)
    Alice_B->>Contract: 7. Withdraw(π, h_null)
    
    Contract->>Contract: 8. 验证 ZKP (π)
    Contract->>Contract: 9. 检查 h_null 是否已经被花费
    alt 尚未花费
        Contract->>Contract: 10a. 记录 h_null 为已花费
        Contract->>Alice_B: 11a. 发送 ETH
    else 已花费
        Contract-->>Alice_B: 10b. 拒绝交易
    end

存款 (Deposit)：
- 用户 Alice 想要存入一定数量的代币（例如 1 ETH）。她首先生成两个大的随机数：一个作为秘密 (secret) $s$，另一个作为无效符 (nullifier) $n$
- 她计算一个承诺 $C$，通常是这两个随机数的哈希值：$C = H(s, n)$
- Alice 将 1 ETH 和这个承诺 $C$ 一起发送到 Tornado Cash 智能合约。合约将 $C$ 添加到一个存款列表（通常是一棵默克尔树）中
取款 (Withdrawal)：
- 在等待一段时间后，Alice 想要从一个全新的、与存款地址无任何关联的地址 B 取款
- 她需要向智能合约证明她知道某个有效承诺 $C$ 对应的秘密 $s$ 和无效符 $n$。这是一个典型的「知识证明」问题
- 她构造一个 zk-SNARK 证明 $\pi$，该证明陈述了以下内容：
  
  我知道一对 $(s, n)$，使得：
  1. 其承诺 $C = H(s, n)$ 存在于合约的存款默克尔树中（通过提供默克尔路径来证明）
  2. 我能正确计算出无效符哈希 $h_{null} = H(n)$
- Alice 向合约提交证明 $\pi$ 和无效符哈希 $h_{null}$
- 验证与防双花：
  - 合约的验证器会检查证明 $\pi$ 是否有效。这个验证过程不会暴露 $s$、$n$ 或原始的承诺 $C$
  - 合约会检查 $h_{null}$ 是否已经被记录在「已花费」列表中。如果未被记录，合约就将 $h_{null}$ 记录下来，并向地址 B 发送 1 ETH。如果已被记录，则拒绝交易，以防止同一笔存款被多次取出（双花攻击）

通过这个过程，Alice 成功地在不暴露任何关联信息的情况下转移了资金，实现了隐私保护。

区块链扩容

ZK-Rollups 是一种 Layer 2 扩容方案，它将大量的交易计算和状态存储移至链下，但将每笔交易的压缩数据和有效性证明保留在链上，从而继承了主链的安全性。

其工作原理如下：

graph TD
    subgraph "二层网络 (链下)"
        U1[用户 1] -- "交易" --> S[定序器]
        U2[用户 2] -- "交易" --> S
        Un["..."] -- "交易" --> S
        S -- "批量打包交易" --> B[交易批次]
        B -- "更新状态并生成证明" --> P{证明者}
        P -- "零知识证明 π" --> S
    end

    subgraph "一层网络 (链上)"
        VC[验证者合约]
        State[L1 状态根]
        VC -- "读/写" --> State
    end

    S -- "提交证明和数据" --> VC
    VC -- "验证证明" --> V_Res{验证结果}
    V_Res -- "通过" --> VC
    VC -- "更新状态根" --> State

链下交易处理：
- 一个或多个被称为定序器 (Sequencer) 或运营者 (Operator) 的节点负责收集用户的链下交易
- 运营者处理这些交易（例如，数千笔转账），并更新链下的状态树（一棵巨大的默克尔树，记录了所有账户的余额和状态）。这个过程会从旧的状态根 $S_{old}$ 变为新的状态根 $S_{new}$
生成证明：
- 对于这一批次的所有交易，运营者需要生成一个零知识证明 $\pi$（通常是 zk-SNARK 或 zk-STARK）
- 该证明 $\pi$ 证实了以下陈述：
  
  存在一批交易 $T$，当它们被依次应用于状态根为 $S_{old}$ 的状态时，会合法地产生一个新的状态根 $S_{new}$。
-「合法地」意味着每笔交易都经过了有效签名，发送方有足够余额，且所有状态转换都遵循协议规则
链上验证：
- 运营者将这个简洁的证明 $\pi$、旧状态根 $S_{old}$、新状态根 $S_{new}$ 以及一些高度压缩的交易数据（用于确保数据可用性）提交到主链上的智能合约
- 主链上的验证器合约执行验证算法 Verify(π, S_old, S_new, data)。这个验证过程非常快速且成本低廉，远低于在主链上执行数千笔交易的成本
- 如果验证通过，合约就将链上存储的状态根更新为 $S_{new}$

通过这种方式，主链节点无需执行每一笔交易，只需验证一个证明，从而将吞吐量提升了几个数量级。zkSync 和 StarkNet 就是基于此技术的著名项目。

去中心化身份与可验证凭证

零知识证明允许用户有选择性地披露其身份信息，而不是全盘托出。

假设你需要向一个在线服务证明你已年满 18 岁，但不想透露你的姓名、确切出生日期或其他任何信息。传统方式是上传你的身份证照片。这会暴露你的姓名、住址、确切出生日期等所有信息，存在严重的隐私泄露风险。

使用零知识证明，你可以通过以下方式实现：

发行凭证：政府或可信机构（Issuer）为你颁发一个经过数字签名的可验证凭证 (Verifiable Credential)，其中包含了你的各项属性，如 {"name": "Alice", "birthDate": "2005-05-20"}
生成证明：当你需要证明年龄时，你的钱包应用会生成一个 ZKP，证明如下陈述：

我持有一个由可信机构公钥签名的有效凭证，且凭证中的 birthDate 字段所代表的年龄大于或等于 18 岁。
验证：你将这个证明提交给在线服务。服务方只需验证该证明的有效性，就能确信你已成年，而完全不知道你的姓名、具体生日或任何其他个人信息

保护机器学习模型的隐私

在某些场景下，模型的所有者希望向用户证明其模型的预测结果是正确的，但不想泄露模型本身（因为模型是宝贵的知识产权）。

例如，一家金融科技公司开发了一个专有的信用评分模型 $M$。用户输入自己的财务数据 $x$，公司返回一个信用评分 $y = M(x)$。用户如何相信这个评分 $y$ 是由那个声称的高级模型 $M$ 诚实计算出来的，而不是公司为了自身利益随便给出的一个数字？

零知识证明可以帮助解决这个问题。具体流程如下：

公司首先对模型 $M$ 的结构和权重进行承诺，并公开承诺值 $comm(M)$
当用户提交数据 $x$ 后，公司计算 $y = M(x)$
公司同时生成一个 ZKP $\pi$，证明：

对于公开的输入 $x$ 和输出 $y$，我知道一个模型 $M$，使得 $y=M(x)$ 成立，并且这个模型 $M$ 的承诺与公开的 $comm(M)$ 一致。
用户收到评分 $y$ 和证明 $\pi$。通过验证 $\pi$，用户可以确信评分是由声称的模型诚实计算得出的，而公司则没有泄露其模型的任何内部细节

Chrome 原生 AI API 开发实践

mail@ch3nyang.top (Ch3nyang) — Tue, 30 Sep 2025 00:00:00 +0800

随着 Web AI 技术的快速发展，浏览器厂商开始将 AI 能力直接集成到浏览器内核中。Chrome 从 138 版本开始，正式提供了一套原生的 AI API，包括翻译、语言检测、文本摘要和语言模型等功能。这意味着开发者可以在不依赖外部服务的情况下，直接调用浏览器内置的 AI 能力来构建智能化的 Web 应用。

本文将详细介绍这些 API 的使用方法，并提供完整的示例代码。

这些功能基本都需要 Chrome 浏览器 138 或更高版本，下面的小工具展示了你的浏览器是否支持这些 API：

Your browser does not support iframes. Click here to visit the content

翻译 API

样例

如果你使用的是 Chrome 浏览器 138 或更高版本，下面的示例便可以直接运行。

Chrome AI 翻译 API 演示

Your browser does not support iframes. Click here to visit the content

当然，这套 API 目前正在逐渐被各浏览器支持，你也可以在 Can I use 上查看最新的支持情况。

使用

首先，由于这些 API 刚结束实验阶段，你需要先检查一下浏览器是否支持这些 API：

if ('Translator' in self) {
  console.log('翻译 API 可用');
}

然后，便可以创建一个翻译器实例：

const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'zh-CN',
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

第一次创建实例时，浏览器会自动下载所需的翻译模型。你可以通过 monitor 回调来监控下载进度。

执行翻译很简单：

const result = await translator.translate('How are you?');
console.log(result);

对于较长的文本，可以使用流式翻译：

const stream = translator.translateStreaming(longText);
for await (const chunk of stream) {
  console.log(chunk);
}

语言检测 API

样例

同样，如果你使用的是 Chrome 浏览器的最新版本，下面的示例也可以直接运行。

Chrome AI 语言检测 API 演示

Your browser does not support iframes. Click here to visit the content

语言检测 API 目前也在逐步推广中，你也可以在 Can I use 上查看最新的支持情况。

使用

首先检查浏览器是否支持语言检测 API：

if ('LanguageDetector' in self) {
  // 语言检测 API 可用
}

然后创建一个语言检测器实例：

const detector = await LanguageDetector.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

同样，第一次创建实例时，浏览器会自动下载所需的语言模型。你可以通过 monitor 回调来监控下载进度。

执行语言检测：

const someUserText = 'Hallo und herzlich willkommen!';
const results = await detector.detect(someUserText);
for (const result of results) {
  // 显示所有可能的语言及其置信度，按可能性从高到低排序
  console.log(result.detectedLanguage, result.confidence);
}
// 输出示例：
// de 0.9993835687637329
// en 0.00038279531872831285
// nl 0.00010798392031574622
// ...

摘要 API

样例

如果你使用的是支持摘要 API 的 Chrome 浏览器版本，下面的示例可以直接运行。

Chrome AI 摘要 API 演示

Your browser does not support iframes. Click here to visit the content

摘要 API 目前也在逐步推广中，你也可以在 Can I use 上查看最新的支持情况。

首次创建摘要器实例时，浏览器会下载所需的模型文件，可能需要一些时间。大小通常在 20MB 到 100MB 之间，具体取决于所选的模型和配置。

使用

首先检查浏览器是否支持摘要 API：

if ('Summarizer' in self) {
  // 摘要 API 可用
}

在使用前，建议检查 API 的可用性：

const availability = await Summarizer.availability();
if (availability === 'unavailable') {
  // 摘要 API 不可用
  return;
}

然后创建一个摘要器实例。注意，创建摘要器需要用户激活（如点击事件）：

if (navigator.userActivation.isActive) {
  const summarizer = await Summarizer.create({
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        console.log(`Downloaded ${e.loaded * 100}%`);
      });
    }
  });
}

你也可以在创建时指定更多选项：

const options = {
  sharedContext: 'This is a scientific article',
  type: 'key-points',        // 摘要类型：tldr、teaser、key-points、headline
  format: 'markdown',        // 输出格式：markdown、plain-text
  length: 'medium',          // 摘要长度：short、medium、long
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  }
};

const summarizer = await Summarizer.create(options);

执行摘要生成：

const longText = document.querySelector('article').innerHTML;
const summary = await summarizer.summarize(longText, {
  context: 'This article is intended for a tech-savvy audience.',
});
console.log(summary);

对于较长的文本，可以使用流式摘要：

const stream = summarizer.summarizeStreaming(longText, {
  context: 'This article is intended for junior developers.',
});
for await (const chunk of stream) {
  console.log(chunk);
}

提示词 API

样例

如果你使用的是支持 Language Model API 的 Chrome 浏览器版本，下面的示例可以直接运行。

Chrome AI 语言模型 API 演示

Your browser does not support iframes. Click here to visit the content

提示词 API 目前也在逐步推广中，你也可以在 Can I use 上查看最新的支持情况。

首次创建语言模型会话时，浏览器会下载所需的模型文件，通常需要一些时间。模型大小可能在几百MB到几GB之间，具体取决于模型类型。

使用

首先检查浏览器是否支持 Language Model API：

if ('LanguageModel' in self) {
  // Language Model API 可用
}

在使用前，建议检查 API 的可用性和参数：

const availability = await LanguageModel.availability();
if (availability === 'unavailable') {
  // Language Model API 不可用
  return;
}

// 获取模型参数
const params = await LanguageModel.params();
console.log(params);
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

基本使用

创建一个基本的语言模型会话：

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

// 发送提示并获得响应
const result = await session.prompt('Write me a poem!');
console.log(result);

参数调节

你可以调整模型的温度和 TopK 参数来控制输出的随机性：

const params = await LanguageModel.params();

// 创建一个温度稍高的会话（更有创意）
const creativeSession = await LanguageModel.create({
  temperature: Math.min(params.defaultTemperature * 1.2, params.maxTemperature),
  topK: params.defaultTopK,
});

初始对话历史

你可以在创建会话时提供初始的对话历史：

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' },
    { role: 'user', content: 'What is the capital of Italy?' },
    { role: 'assistant', content: 'The capital of Italy is Rome.' },
    { role: 'user', content: 'What language is spoken there?' },
    { role: 'assistant', content: 'The official language of Italy is Italian.' },
  ],
});

// 继续对话
const followup = await session.prompt('Tell me about the food there.');

多轮对话

使用数组形式进行多轮对话：

const followup = await session.prompt([
  {
    role: "user",
    content: "I'm nervous about my presentation tomorrow"
  },
  {
    role: "assistant", 
    content: "Presentations are tough!"
  }
]);

流式响应

对于较长的响应，可以使用流式输出：

const stream = session.promptStreaming('Write me an extra-long poem!');
for await (const chunk of stream) {
  console.log(chunk);
}

图像输入

语言模型也支持图像输入（多模态）：

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content: 'You are a skilled analyst who correlates patterns across multiple images.',
    },
  ],
  expectedInputs: [{ type: 'image' }],
});

// 添加图像到对话
await session.append([
  {
    role: 'user',
    content: [
      {
        type: 'text',
        value: `Here's one image. Notes: ${fileNotesInput.value}`,
      },
      { type: 'image', value: fileUpload.files[0] },
    ],
  },
]);

// 分析图像
const result = await session.prompt('What do you see in this image?');

结构化输出

你可以约束模型输出特定格式的 JSON：

const schema = {
  "type": "object",
  "properties": {
    "rating": {
      "type": "number",
      "minimum": 0,
      "maximum": 5
    }
  },
  "required": ["rating"]
};

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5. Only output a JSON
  object { rating }, with a single property whose value is a number:
  The food was delicious, service was excellent, will recommend.
`, { 
  responseConstraint: schema,
  omitResponseConstraintInput: true 
});

console.log(JSON.parse(result)); // { rating: 5 }

会话管理

// 取消操作
const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

// 检查使用配额
console.log(`${session.inputUsage}/${session.inputQuota}`);

// 克隆会话
const clonedSession = await session.clone();

// 销毁会话
session.destroy();

如何在半年内给 3 个开源项目骗到 100+ stars?

mail@ch3nyang.top (Ch3nyang) — Sun, 03 Aug 2025 23:00:00 +0800

在过去的大半年里（严谨点讲是一年），我在 GitHub 种下了三个「瓜」。没想到，这几个瓜蛋子还挺争气，个个都骗到斩获了超过 100 个 stars！

先来看看我种的瓜：

项目	截图
WCY-dt/EasyTransfer 基于 WebRTC 的端到端文件传输工具 2024-06-19 启动 / 2024-12-02 发布单日最多 172 stars
WCY-dt/my-github-2024 GitHub 年终个人总结 2024-12-14 启动 / 2024-12-15 发布单日最多 26 stars
WCY-dt/PongHub 一键部署的端口状态监控工具 2025-07-20 启动 / 2025-07-24 发布单日最多 53 stars

就在第三个项目发布前夜，我沐浴焚香，掐指一算，嘿，您猜怎么着？这波 100+ stars 肯定稳了！

这不是我飘了，而是经过无数个掉头发的夜晚，我好像…摸索出了一套让个人开源项目一不小心就火起来的独门秘籍。

今天我就不藏私了，把这套「骗 Star 大法」总结为三板斧：产品、技术、运营。

第一板斧：产品

做个让用户「哇哦」的项目

想让路过的英雄好汉给你点亮一颗 star，无非是挠到了他们的某个「痒处」。总结下来有四种「仙丹」：

解决痛点：这世上有一种痛，叫「求而不得」。你解决用户的某个实际问题，而这个问题从来没有人解决过。

例如我自己的项目 WCY-dt/EasyTransfer 就是唯一一个同时支持了局域网和广域网的端到端文件传输工具。
蹭热点：紧跟潮流，利用热门话题或者技术吸引用户关注。你要做的，就是在风口上当那只最靓的猪。

例如我朋友的 16131zzzzzzzz/EveryoneNobel 在去年的诺贝尔奖颁布时发布，正好抓住了热点。
顶尖技术：拥有削铁如泥的屠龙刀，强到有公司愿意使用它。

这就太多了，较为经典的比如 vuejs/core 等等，用的人确实非常多。
awesome：做知识的搬运工，搞一些为 awesome-xxx 的项目或是一些教程。

例如我同学做的 Lordog/dive-into-llms 就是一个教程，star 数目非常恐怖。

从这四颗「神丹」里炼一颗，你的项目就有了个不错的「药引子」。

不走寻常路

我的每个项目，都逃不过用户的灵魂拷问：

这个项目和 xxx 项目有啥区别？
能不能加入类似 xxx 项目的功能？

所以，在撸起袖子开干前，先花五分钟看看别人家的孩子：

市面上有哪些同类的开源 / 商业项目？
这些项目的优缺点是什么？
我的想法能否弥补它们的不足？

最后，对着镜子，扪心自问：我特喵真的有必要重复造轮子吗？

说句扎心的，绝大多数开源项目无人关注的根本原因就是重复造轮子。毕竟，用户凭啥要抛弃用顺手的旧爱，投入你这个没啥亮点的备胎的怀抱？

同时，我想提醒一句，我们的创新点最好是从第一步得到，而不是通过这样的市场调研。靠调研憋出来的「创新」，大概率是脱裤子放屁。读过研究生的应该明白这个道理。

做自己经常用的项目

搞开源，本质上是一场用爱发电的苦修。没有 KPI，没有奖金，只有数不尽的 Issue 和 PR，还有几个难缠的傻宝用户。

很多项目作者，脑子一热，「我觉得这个 idea 别人会喜欢」，然后就开搞了。结果一个月后，GitHub 仓库长草，上次更新还停留在 init commit。

我个人的经验是，做一个自用型项目，可以大大提高开源的积极性。而且在使用过程中，你会不断发现「哎呀这里有个 bug」、「咦那里还能再优化」，从而推动自己不断完成项目的迭代更新，通过长期的维护吸引用户使用。

第二板斧：技术

技术，可以说是绝大多数开源项目中最不重要的一部分。我们甚至能看到，一些项目的代码写得和一坨 💩 没有任何区别，照样几千个 star。

技术方面的事情就不具体讲了，我这里提几点个人开源项目中比较特别的。

技术栈的选择

话虽如此，在开始写项目前，技术选型还是很重要的。通常，无外乎两种情况：

我们可以选择一些流行的技术栈来构建项目，这样开发速度更快，社区支持也更好，遇到问题随便一搜就有一堆「老中医」。比方说，
- 前端选用 facebook/react、vuejs/core 等框架，再用 vitejs/vite 之类的构建工具
- 后端选用 Python、Java、Golang、Cpp 等主流语言，搭配上 nodejs/node、pallets/flask、spring-projects/spring-framework 等框架
我还观察到，目前一众「独立开发者」偏爱 vercel/next.js，这应该是被 Vercel 传销了。

不过，选用流行技术的坏处是，想要登上 GitHub Trending 比抢到春运火车票还难，而且需要在功能上做出足够的创新。
当然，我们也可以选择一些小众的技术栈来构建项目，这样本身就会收获对这项技术感兴趣的用户。

要是放到几年前，这基本就是在点名重写一切的 Rust——

语言神，启动！

而现在，也依然有数不清的小众技术栈可供选择。比如，我最近就在试着用 withastro/astro 来写一个项目（好像也不是那么小众了）。

当然，选用小众技术的坏处是，你很有可能遇到一些技术栈本身存在的问题，不得不等待社区修复，或者自己动手。这就不得不提到，我之前使用某项目时遇到一个 bug，动手帮着修复并提交了 PR，结果作者过了半年才想起来上线合并！

不要定时炸弹

在公司，我们可以~~写出无人能够维护的代码，防止自己被裁~~。而对于开源项目，干净整洁的代码既方便自己迭代，也能吸引别的开发者来添砖加瓦。然而，自己的项目往往没有人帮着 CR，初期架构设计也很难做到完美。

公司的代码想要重构很难推动，但个人项目的重构成本就小得多了。对于小型项目，我的经验是主要有两条：

在项目初期，就引入对应的 lint（eslint、pylint 等），并且将其加入到 CI 流程（即 GitHub Actions）中。这样可以尽早发现代码中的问题，不至于自己都看不懂自己的代码
项目每经过一段时间，就评估是否需要重构。通常来说，重构的时机有：
- 在优化迭代过程中，代码中添加了越来越多的功能，最好分离成多个模块
- 某些复杂功能的逻辑越来越繁琐，最好抽离成独立的函数或类
- 项目初期直接定义了一些全局变量、工具函数，后期希望能有更好的封装

记住，漂亮的代码能提升食欲，而屎山代码…能让你当场戒掉夜宵。

求你了，不要 Vibe Coding！

不要 Vibe Coding！不要 Vibe Coding！不要 Vibe Coding！

AI 辅助编程是少不了的，但 Vibe Coding 出来的代码真的是一坨。你要对最终产出的代码负责！

第三板斧：运营

社区建设

就跟你刷约会软件会在主页放上 PS 过的照片，并写上酒吧舞毕业 / xx 大厂程序员一样，README 就是开源项目的门面，好的 README 能够一下子抓住用户。相反，对于那类 README 只有一行字的项目，我通常会直接关闭页面，内心毫无波澜。

当然，不止是 README，开源项目的社区建设还包括了很多容易被忽视的方面。我自己常做的包括：

LICENSE：提供清晰的开源协议，确保用户可以合法使用和贡献代码，这个最好在第一次提交代码时就添加上
CONTRIBUTING：提供贡献指南，帮助用户了解如何参与项目
Issue Template：提供清晰的 Issue 模板，帮助用户更好地描述问题或功能请求
PR Template：提供 PR 模板，帮助贡献者更好地提交代码
Code of Conduct：提供行为准则，确保社区的友好和包容
SECURITY：提供安全报告渠道，确保用户可以安全地使用项目

此外，如果项目有前端或者 CLI，建议贴一张截图，或者提供一个在线 Demo。一张图胜过千言万语，一个 Demo 能直接俘获人心。

吆喝叫卖

酒香也怕巷子深，再好的开源项目也需要宣传。我记得 yyx990803 说过他当初的 vuejs/core 项目就是靠登上 Hacker News 榜首才一炮而红。

个人开发者想登上 Hacker News 的首页实在很难，但我们可以多渠道宣传自己的项目。我们分为国内和国外来谈。（下面是真干货）

国内

国内的开源宣传平台倒是不少，不过基本都没啥人关注。比较有用的主要包括：

科技爱好者周刊：每周发布一次，主要关注技术和开源项目，可以通过邮件 / RSS 订阅。这个周刊的读者数量是真的恐怖，我的几个开源项目都是靠登上周刊获得了一大波关注
小众软件：这里主要是一些比较好玩的应用，商业项目也可以发这里。我觉得这个平台最大的好处是，用户真的很热情，会给你很多有价值的反馈
ahhhhfs：一个博主，人称 A 姐。她的关注量也比较大，不过需要她觉得有意思的项目才会发
少数派：这个平台不用多说了，但我感觉更适合商业项目的宣传
1Link.Fun：每周总共 10 条项目或者文章，贵精不贵多，订阅数很高，而且作者会很用心地帮你写介绍
即刻：活跃用户很多，独立开发项目会更适合这个平台
V2EX：知名社区，不过现在社区氛围逐渐变得一言难尽，而且需要邀请码注册
小红书 / B 站 / 微信公众号等社交媒体平台：你说得对，但是~~小猫补光灯~~

海外

海外我其实没怎么关注，不过有几个平台还是比较有名的：

Hacker News：发 Show HN 的帖子，通常会获得一些关注
Reddit：有很多技术相关的 subreddit：
- r/programming - 综合技术讨论
- r/IMadeThis - 展示个人项目
- r/webdev, r/javascript, r/python - 各种编程语言和技术栈
- r/opensource - 专注于开源项目
不过，很多 subreddit 有 karma 门槛，冒然发帖容易被当成广告删掉。
Product Hunt：每天会有很多新产品发布，还有投票功能。然而，这个平台对中国的用户并不友好，甚至可以说是歧视，感兴趣的可以看看 RSSNext/Folo 和它的恩怨故事
Lobsters：类似 Hacker News 的技术社区，用户群体相对较小但质量较高。这个社区是邀请制的，注册需要用户邀请
Dev.to：一个面向开发者的社区，用户可以发布文章和项目。这个平台对新用户比较友好，注册也很简单
X / YouTube 等社交媒体平台

总结以及一些疑问

为了方便大家参考，我把这三板斧总结成了一张 mindmap：

mindmap
  root)个人<br>开源项目(
    ((📦产品))
      创新点来源
        痛点
        热点
        技术
        搬运工
      市场调研
      ))做自己会用的项目((
    ((🛠️技术))
      技术栈选择
        流行
        小众
      代码整洁
        lint 工具
        重构
      ))不要 Vibe Coding！((
    ((📢运营))
      社区建设
      网络宣传
        国内平台
        海外平台

虽然我已经能熟练地「炮制」一个 100+ star 的项目，但还有两个终极问题困扰着我：

如何持续增长，而不是出道即巅峰？ 项目通常在高强度宣传的那段时间涨 star 很快，但没多久，一天就涨不到 1 个 star 了。如何获得源源不断的关注？
如何吸引更多的贡献者，而不是单打独斗？ 我偶尔会收到一些 PR，但大多数时候都是我自己在维护项目。如何让忽悠吸引更多人参与进来？

这些问题我还在思考中，也欢迎大家分享自己的经验和看法。

从 C10K 到 C10M——从源码深入 I/O 模型的演进

mail@ch3nyang.top (Ch3nyang) — Sat, 12 Jul 2025 00:00:00 +0800

如何让一台服务器接受尽可能多的连接？

The C10k problem is the problem of optimizing network sockets to handle a large number of clients at the same time. The name C10k is a numeronym for concurrently handling ten thousand connections. Handling many concurrent connections is a different problem from handling many requests per second: the latter requires high throughput (processing them quickly), while the former does not have to be fast, but requires efficient scheduling of connections.

早在 1999 年，Dan Kegel 就提出了 C10K 问题¹，旨在解决如何让一台服务器同时处理 $10,000$ 个连接的问题；到了 2010 年前后，这个问题变为了 C10M——即如何用 1U 服务器处理 $10,000,000$ 个连接；而如今，随着服务器性能和网络技术的发展，这个数字还在不断攀升。

在最基本的 socket 编程模型中，服务器通常采用阻塞 I/O 模型，即每个连接都对应一个线程或进程。当面临成千上万个连接时，我们就不得不开启成千上万个线程或进程，这会消耗大量的系统资源，并导致频繁的上下文切换，严重影响性能。

为了解决这个问题，操作系统提供了多种 I/O 模型，使得单个线程或进程能够同时处理多个连接，从而大幅提升服务器的并发处理能力。今天我们就来聊聊，是什么技术，使得这一切成为可能。

`select`

基本使用

select 是 Unix/Linux 系统中最传统的 I/O 多路复用机制之一，它允许程序同时监视多个 fd（如 socket、管道等），并在其中任何一个 fd 就绪（读 / 写 / 异常）时通知应用程序进行处理。

select 的函数原型在 sys/select.h 中：

int select (int nfds,
            fd_set *readfds,
            fd_set *writefds,
            fd_set *exceptfds,
            struct timeval *timeout);

其中，

nfds 是需要监视的 fd 的数量；
readfds 是一个 fd 集合，用于监视可读事件；
writefds 是一个 fd 集合，用于监视可写事件；
exceptfds 是一个 fd 集合，用于监视异常事件；
timeout 是一个指向 struct timeval 的指针，用于设置超时时间。设置为 NULL 表示无限等待，设置为 {0, 0} 表示立即返回。

select 函数会阻塞当前线程，直到其中有至少一个 fd 就绪，或者长时间没有 fd 就绪而导致超时。它的返回值：

正常情况下，返回就绪的 fd 数量；
如果超时，返回 0；
如果出错，返回 -1。

fd_set 是一个特殊的结构体，用于表示 fd 集合。它被定义为：
#define __FD_SETSIZE 1024

typedef long int __fd_mask;
#define __NFDBITS (sizeof(__fd_mask) * 8)

typedef struct {
    __fd_mask fds_bits[__FD_SETSIZE / __NFDBITS];
} fd_set;
fd_set 是一个 bitmap，每个 fd 对应一个比特位，比特位为 1 表示 fd 已就绪。它总共有 __FD_SETSIZE 即 1024 位，因此 select 最多只能监视 1024 个 fd 。

fd_set 主要依靠四个宏来操作：

FD_ZERO(fdsetp)：将 fdsetp 中的所有比特位置 0

FD_SET(fd, fdsetp)：将 fdsetp 中对应 fd 的比特位置 1

FD_CLR(fd, fdsetp)：将 fdsetp 中对应 fd 的比特位置 0

FD_ISSET(fd, fdsetp)：检查 fdsetp 中对应 fd 的比特位是否为 1

这些宏的实现在 select.h 中。
点击查看源码
#define __FDS_BITS(set) ((set)->fds_bits)

#define __FD_ZERO(s)                                                 \
    do {                                                             \
        unsigned int __i;                                            \
        fd_set *__arr = (s);                                         \
        for (__i = 0; __i < sizeof(fd_set)/sizeof(__fd_mask); ++__i) \
            __FDS_BITS[__arr](__i) = 0;                              \
    } while (0)
#define __FD_SET(d, s)                                               \
    ((void)(__FDS_BITS[s](__FD_ELT(d)) |= __FD_MASK(d)))
#define __FD_CLR(d, s)                                               \
    ((void)(__FDS_BITS[s](__FD_ELT(d)) &= ~__FD_MASK(d)))
#define __FD_ISSET(d, s)                                             \
    ((__FDS_BITS[s](__FD_ELT(d))&__FD_MASK(d)) != 0)

#define FD_SET(fd, fdsetp)   __FD_SET (fd, fdsetp)
#define FD_CLR(fd, fdsetp)   __FD_CLR (fd, fdsetp)
#define FD_ISSET(fd, fdsetp) __FD_ISSET (fd, fdsetp)
#define FD_ZERO(fdsetp)      __FD_ZERO (fdsetp)

在使用 select 时，需要依次：

使用 FD_ZERO 清空 fd_set
使用 FD_SET 将需要监视的 fd 添加到 fd_set 中
调用 select 函数进行监视
对返回的 fd_set 进行处理，使用 FD_ISSET 检查哪些 fd 就绪

下面是一个典型的 select 使用示例²。

点击查看代码

#include <stdio.h>
#include <stdlib.h>
#include <sys/select.h>
#include <sys/time.h>

int
main(void)
{
    int             retval;
    fd_set          rfds;
    struct timeval  tv;

    // 监控 stdin (fd 0) 是否有输入
    FD_ZERO(&rfds);
    FD_SET(0, &rfds);

    // 超时时间设置为 5 秒
    tv.tv_sec = 5;
    tv.tv_usec = 0;

    retval = select(1, &rfds, NULL, NULL, &tv);
    // 此时，tv 可能已经被修改

    if (retval == -1)
        perror("select()");
    else if (retval)
        printf("Data is available now.\n");
        // FD_ISSET(0, &rfds) 为真
    else
        printf("No data within five seconds.\n");

    exit(EXIT_SUCCESS);
}

源码解读

select 内部执行时经过了以下步骤：

将传入的 fd_set 拷贝至内核态
再新建三个 fd_set 作为输出（in / out / except）
遍历每一位，如果设置了监视且有事件发生，则将输出的对应位设置为 1
如果没有事件发生，则阻塞等待
如果有事件发生或超时，则返回输出

flowchart LR
  F[将 fd_set<br>拷贝至<br>内核态] --> G[新建三个<br>fd_set<br>作为输出] --> H[遍历<br>每一位<br>检查状态] --> I{fd 设置了监视<br>且有事件<br>发生?}
  I -->|是| J[将输出的<br>对应位<br>设置为 1]
  I -->|否| K{所有位<br>都检查<br>完了?}
  
  J --> K
  K -->|否| H
  K -->|是| N{超时或<br>有事件<br>发生?}
  N -->|否| H
  N -->|是| O[返回<br>输出]

为了合理调度资源，select 还引入了许多优化机制：

栈空间优先

当 select 需要处理的 fd 数量较少（少于 256）时，内核会优先使用栈空间来存储 fd_set，这样可以减少内存分配的开销。而当数量较多时，才会使用堆空间分配。
忙等待

忙等待主要被用于网络驱动中。对于高频小包网络应用，可以减少上下文切换和中断处理的开销，从而提高性能。

忙等待的触发需要同时满足以下条件：
- 网络子系统启用忙等待
- 当前没有更高优先级的任务需要调度
- 至少有一个socket设置了 SO_BUSY_POLL 选项
- 没有检测到任何就绪事件
在每次主循环检查时，会计算当前时间与上次忙等待开始的时间差，如果超过了忙等待的超时时间（通常设置为 2 个 CPU 周期），则会执行一次正常的检查流程。
延迟唤醒

在初始化时，wait->_qproc 会指向 __pollwait() 函数。这个函数相当于一个回调函数，当有事件发生时，内核会调用这个函数来唤醒等待的进程。

当文件描述符就绪时，会将 _qproc 置为 NULL，这样后续检查时，可以避免重复唤醒。

以目前最新的 Linux 6.16 为例，select 的实现在 fs/select.c 中³。

点击查看源码解析

系统调用的入口：

SYSCALL_DEFINE5(select, int, n, fd_set __user *, inp, fd_set __user *, outp,
                fd_set __user *, exp, struct __kernel_old_timeval __user *, tvp)
{
    return kern_select(n, inp, outp, exp, tvp);
}

核心处理函数：

static int kern_select(int n, fd_set __user *inp, fd_set __user *outp,
                       fd_set __user *exp, struct __kernel_old_timeval __user *tvp)
{
    struct timespec64 end_time, *to = NULL;
    struct __kernel_old_timeval tv;
    int ret;

    // 如果设置了超时时间，则拷贝进内核态并转换为 timespec64
    if (tvp) {
        if (copy_from_user(&tv, tvp, sizeof(tv)))
            return -EFAULT;

        to = &end_time;
        if (poll_select_set_timeout(to,
                                    tv.tv_sec + (tv.tv_usec / USEC_PER_SEC),
                                     (tv.tv_usec % USEC_PER_SEC) * NSEC_PER_USEC))
            return -EINVAL;
    }

    // 处理核心逻辑（见下文）
    ret = core_sys_select(n, inp, outp, exp, to);
    // 处理结果
    return poll_select_finish(&end_time, tvp, PT_TIMEVAL, ret);
}

核心处理逻辑：

int core_sys_select(int n, fd_set __user *inp, fd_set __user *outp,
                    fd_set __user *exp, struct timespec64 *end_time)
{
    fd_set_bits fds;
    void *bits;
    int ret, max_fds;
    size_t size, alloc_size;
    struct fdtable *fdt;
    long stack_fds[SELECT_STACK_ALLOC/sizeof(long)];

    ret = -EINVAL;
    if (unlikely(n < 0))
        goto out_nofds;

    rcu_read_lock();
    fdt = files_fdtable(current->files);
    max_fds = fdt->max_fds;
    rcu_read_unlock();
    if (n > max_fds)
        n = max_fds;

    // 总共需要 6 个 bitmap，分别存储 in/out/ex 的输入和输出
    size = FDS_BYTES(n);
    // 如果数量较少，则使用栈分配
    bits = stack_fds;
    if (size > sizeof(stack_fds) / 6) {
        ret = -ENOMEM;
        if (size > (SIZE_MAX / 6))
            goto out_nofds;
        alloc_size = 6 * size;
        // 如果数量较多，则使用堆分配
        bits = kvmalloc(alloc_size, GFP_KERNEL);
        if (!bits)
            goto out_nofds;
    }
    fds.in      = bits;
    fds.out     = bits +   size;
    fds.ex      = bits + 2*size;
    fds.res_in  = bits + 3*size;
    fds.res_out = bits + 4*size;
    fds.res_ex  = bits + 5*size;

    // 将用户态的 fd_set 拷贝至内核态
    if ((ret = get_fd_set(n, inp, fds.in)) ||
        (ret = get_fd_set(n, outp, fds.out)) ||
        (ret = get_fd_set(n, exp, fds.ex)))
        goto out;
    // 清空输出
    zero_fd_set(n, fds.res_in);
    zero_fd_set(n, fds.res_out);
    zero_fd_set(n, fds.res_ex);

    // 调用 do_select 进行实际监控（见下文）
    ret = do_select(n, &fds, end_time);

    if (ret < 0)
        goto out;
    if (!ret) {
        ret = -ERESTARTNOHAND;
        if (signal_pending(current))
            goto out;
        ret = 0;
    }

    // 将结果拷贝回用户态
    if (set_fd_set(n, inp, fds.res_in) ||
        set_fd_set(n, outp, fds.res_out) ||
        set_fd_set(n, exp, fds.res_ex))
        ret = -EFAULT;

 out:
     if (bits != stack_fds)
         kvfree(bits);
 out_nofds:
       return ret;
}

关键监控逻辑：

// 可读事件包括：普通数据可读、优先级带数据可读、数据可读、挂起、错误、无效
#define POLLIN_SET  (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | EPOLLHUP | EPOLLERR | \
                     EPOLLNVAL)
// 可写事件包括：普通数据可写、优先级带数据可写、数据可写、错误、无效
#define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT | EPOLLERR |           \
                     EPOLLNVAL)
// 异常事件包括：高优先级数据可读、无效
#define POLLEX_SET  (EPOLLPRI | EPOLLNVAL)

static noinline_for_stack int do_select(int n, fd_set_bits *fds, struct timespec64*end_time)
{
    ktime_t expire, *to = NULL;
    struct poll_wqueues table;
    poll_table*wait;
    int retval, i, timed_out = 0;
    u64 slack = 0;
    __poll_t busy_flag = net_busy_loop_on() ? POLL_BUSY_LOOP : 0;
    unsigned long busy_start = 0;

    // 获取最大的有效 fd
    rcu_read_lock();
    retval = max_select_fd(n, fds);
    rcu_read_unlock();
    if (retval < 0)
        return retval;
    n = retval;

    // 初始化等待队列
    poll_initwait(&table);
    wait = &table.pt;

    // 处理已经超时的情况
    if (end_time && !end_time->tv_sec && !end_time->tv_nsec) {
        wait->_qproc = NULL;
        timed_out = 1;
    }
    if (end_time && !timed_out)
        slack = select_estimate_accuracy(end_time);
    retval = 0;

    // 循环检查文件描述符状态
    for (;;) {
        unsigned long *rinp, *routp, *rexp, *inp, *outp, *exp;
        bool can_busy_loop = false;

        inp = fds->in; outp = fds->out; exp = fds->ex;
        rinp = fds->res_in; routp = fds->res_out; rexp = fds->res_ex;

        // 遍历所有文件描述符
        for (i = 0; i < n; ++rinp, ++routp, ++rexp) {
            unsigned long in, out, ex, all_bits, bit = 1, j;
            unsigned long res_in = 0, res_out = 0, res_ex = 0;
            __poll_t mask;

            // 每次处理 BITS_PER_LONG 位 fd
            in = *inp++; out = *outp++; ex = *exp++;
            all_bits = in | out | ex;
            // 如果这一段 fd 没有设置任何监控，则跳过
            if (all_bits == 0) {
                i += BITS_PER_LONG;
                continue;
            }

            // 检查这一段 fd 的每个 bit 位
            for (j = 0; j < BITS_PER_LONG; ++j, ++i, bit <<= 1) {
                if (i >= n)
                    break;
                // 如果该 bit 位没有设置监控，则跳过
                if (!(bit & all_bits))
                    continue;
                // 如果该 bit 位设置了监控，则调用 select_poll_one 检查状态（见下文）
                mask = select_poll_one(i, wait, in, out, bit, busy_flag);
                // 检测到可读事件
                if ((mask & POLLIN_SET) && (in & bit)) {
                    res_in |= bit;
                    retval++;
                    wait->_qproc = NULL;
                }
                // 检测到可写事件
                if ((mask & POLLOUT_SET) && (out & bit)) {
                    res_out |= bit;
                    retval++;
                    wait->_qproc = NULL;
                }
                // 检测到异常事件
                if ((mask & POLLEX_SET) && (ex & bit)) {
                    res_ex |= bit;
                    retval++;
                    wait->_qproc = NULL;
                }
                if (retval) {
                    // 如果检测到事件，则结束忙等待
                    can_busy_loop = false;
                    busy_flag = 0;
                } else if (busy_flag & mask)
                    can_busy_loop = true;
            }
            // 保存结果
            if (res_in)
                *rinp = res_in;
            if (res_out)
                *routp = res_out;
            if (res_ex)
                *rexp = res_ex;
            // 重新调度
            cond_resched();
        }
        // 清空等待队列
        wait->_qproc = NULL;
        // 检查是否有就绪的文件描述符或超时
        if (retval || timed_out || signal_pending(current))
            break;
        if (table.error) {
            retval = table.error;
            break;
        }

        // 检查是否可以进入忙等待
        if (can_busy_loop && !need_resched()) {
            if (!busy_start) {
                busy_start = busy_loop_current_time();
                continue;
            }
            if (!busy_loop_timeout(busy_start))
                continue;
        }
        busy_flag = 0;

        if (end_time && !to) {
            expire = timespec64_to_ktime(*end_time);
            to = &expire;
        }

        // 进入等待
        if (!poll_schedule_timeout(&table, TASK_INTERRUPTIBLE,
                       to, slack))
            timed_out = 1;
    }

    poll_freewait(&table);

    return retval;
}

具体检查某一个 fd 的实现：

static inline __poll_t select_poll_one(int fd, poll_table *wait, unsigned long in,
                                       unsigned long out, unsigned long bit,
                                       __poll_t ll_flag)
{
    CLASS(fd, f)(fd);

    if (fd_empty(f))
        return EPOLLNVAL;
    
    // 异常或者低延迟总是会进行检测
    wait->_key = POLLEX_SET | ll_flag;
    // 设置可读和可写的监控位
    if (in & bit)
        wait->_key |= POLLIN_SET;
    if (out & bit)
        wait->_key |= POLLOUT_SET;
    
    // 读取 fd 的状态
    return vfs_poll(fd_file(f), wait);
}

根据这段源码，除了前文所述的几个优化点，还可以发现，尽管在运行时区分了输入的 fd_set 和输出的 fd_set，但返回结果时，输出会覆盖掉原来的输入。因此，select 在每次使用后，都必须重新设置所有传入的参数。

讨论

综合以上讨论，我们得出结论，select 存在如下问题：

最多只能监视 1024 个 fd
每次调用 select 都需要将用户传入的集合拷贝进出内核，开销较大
每次返回结果后，都需要重新设置参数
运行时需要遍历集合的每一位，效率较低

那么，有没有更好的改进方案呢？

`poll`

基本使用

poll 是对 select 的改进，它解决了 select 的一些限制，比如 fd 数量的限制和集合拷贝的问题。

poll 的函数原型在 poll.h 中：

int poll (struct pollfd *fds,
          nfds_t nfds,
          int timeout)

类似的，其中：

fds 是一个指向 pollfd 结构体数组的指针，每个结构体表示一个 fd 及其感兴趣的事件

pollfd 结构体定义在 sys/poll.h 中：

struct pollfd {
    int fd;            // 要监视的文件描述符
    short int events;  // 感兴趣的事件类型
    short int revents; // 就绪的事件类型
};

events 和 revents 字段均为 bitmap，用于表示事件类型。不同的系统可能支持不同的类型，例如对于 GNU/Linux 系统，支持的事件类型定义在 bits/poll.h 中：

// 所有系统共有
#define POLLIN     0x001  // 可读事件
#define POLLPRI    0x002  // 紧急数据事件
#define POLLOUT    0x004  // 可写事件
#define POLLERR    0x008  // 错误事件
#define POLLHUP    0x010  // 挂起事件
#define POLLNVAL   0x020  // 无效请求
// GNU 特有
#define POLLMSG    0x400  // 消息事件
#define POLLREMOVE 0x1000 // 移除事件
#define POLLRDHUP  0x2000 // 读挂起事件

nfds 是数组中元素的数量；
timeout 是等待事件发生的最长时间（毫秒），可以设置为 -1 表示无限等待。

下面是一个典型的 poll 使用示例⁴。

点击查看代码

#include <fcntl.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>

#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
                        } while (0)

int
main(int argc, char *argv[])
{
    int            ready;
    char           buf[10];
    nfds_t         num_open_fds, nfds;
    ssize_t        s;
    struct pollfd  *pfds;

    if (argc < 2) {
      fprintf(stderr, "Usage: %s file...\n", argv[0]);
      exit(EXIT_FAILURE);
    }

    num_open_fds = nfds = argc - 1;
    pfds = calloc(nfds, sizeof(struct pollfd));
    if (pfds == NULL)
        errExit("malloc");

    /* Open each file on command line, and add it to 'pfds' array. */

    for (nfds_t j = 0; j < nfds; j++) {
        pfds[j].fd = open(argv[j + 1], O_RDONLY);
        if (pfds[j].fd == -1)
            errExit("open");

        printf("Opened \"%s\" on fd %d\n", argv[j + 1], pfds[j].fd);

        pfds[j].events = POLLIN;
    }

    /* Keep calling poll() as long as at least one file descriptor is
      open. */

    while (num_open_fds > 0) {
        printf("About to poll()\n");
        ready = poll(pfds, nfds, -1);
        if (ready == -1)
            errExit("poll");

        printf("Ready: %d\n", ready);

        /* Deal with array returned by poll(). */

        for (nfds_t j = 0; j < nfds; j++) {
            if (pfds[j].revents != 0) {
                printf("  fd=%d; events: %s%s%s\n", pfds[j].fd,
                       (pfds[j].revents & POLLIN)  ? "POLLIN "  : "",
                       (pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
                       (pfds[j].revents & POLLERR) ? "POLLERR " : "");

                if (pfds[j].revents & POLLIN) {
                    s = read(pfds[j].fd, buf, sizeof(buf));
                    if (s == -1)
                        errExit("read");
                    printf("    read %zd bytes: %.*s\n",
                          s, (int) s, buf);
                } else {                /* POLLERR | POLLHUP */
                    printf("    closing fd %d\n", pfds[j].fd);
                    if (close(pfds[j].fd) == -1)
                        errExit("close");
                    num_open_fds--;
                }
            }
        }
    }

    printf("All file descriptors closed; bye\n");
    exit(EXIT_SUCCESS);
}

源码解读

poll 的工作原理与 select 类似，都是通过阻塞等待 fd 的状态变化来实现 I/O 多路复用。不同之处在于，poll 不再使用位图来表示 fd，而是使用数组，这样就可以支持更多的 fd。

更确切地讲，用户设置的 pollfd 数组进入内核态处理后会被转换为 poll_list 节点组成的链表，每个节点包含多个 pollfd 结构体。fd 的处理以 poll_list 节点为单位，这样可以减少内存拷贝的开销。

poll_list 节点如下所示：

struct poll_list {
    struct poll_list *next;
    unsigned int len;
    struct pollfd entries[] __counted_by(len);
};

以目前最新的 Linux 6.16 为例，poll 的实现同样也在 fs/select.c 中³。

点击查看源码解析

系统调用的入口：

SYSCALL_DEFINE3(poll, struct pollfd __user *, ufds, unsigned int, nfds,
                int, timeout_msecs)
{
    struct timespec64 end_time, *to = NULL;
    int ret;

    // 设置超时时间
    if (timeout_msecs >= 0) {
        to = &end_time;
        poll_select_set_timeout(to, timeout_msecs / MSEC_PER_SEC,
                                NSEC_PER_MSEC * (timeout_msecs % MSEC_PER_SEC));
    }

    // 调用核心处理函数（见下文）
    ret = do_sys_poll(ufds, nfds, to);

    // 如果被信号中断，设置重启块
    if (ret == -ERESTARTNOHAND) {
        struct restart_block *restart_block;

        restart_block = &current->restart_block;
        restart_block->poll.ufds = ufds;
        restart_block->poll.nfds = nfds;

        if (timeout_msecs >= 0) {
            restart_block->poll.tv_sec = end_time.tv_sec;
            restart_block->poll.tv_nsec = end_time.tv_nsec;
            restart_block->poll.has_timeout = 1;
        } else
            restart_block->poll.has_timeout = 0;

        ret = set_restart_fn(restart_block, do_restart_poll);
    }
    return ret;
}

核心处理函数：

static int do_sys_poll(struct pollfd __user *ufds, unsigned int nfds,
                       struct timespec64 *end_time)
{
    struct poll_wqueues table;
    int err = -EFAULT, fdcount;
    // 使用栈空间存储最开始的一段 poll_list，以减少内存分配
    long stack_pps[POLL_STACK_ALLOC/sizeof(long)];
    struct poll_list *const head = (struct poll_list *)stack_pps;
    struct poll_list *walk = head;
    unsigned int todo = nfds;
    unsigned int len;

    // 检查文件描述符数量限制
    if (nfds > rlimit(RLIMIT_NOFILE))
        return -EINVAL;

    // 根据栈空间大小，计算首次能够处理的 pollfd 最大数量
    len = min_t(unsigned int, nfds, N_STACK_PPS);
    // 将用户传入的 pollfd 数组构建为 poll_list 链表
    for (;;) {
        walk->next = NULL;
        walk->len = len;
        if (!len)
            break;

        // 从用户态拷贝数据到内核态
        if (copy_from_user(walk->entries, ufds + nfds-todo,
                           sizeof(struct pollfd) * walk->len))
            goto out_fds;

        if (walk->len >= todo)
            break;
        todo -= walk->len;

        // 如果栈空间不足，则动态分配内存
        len = min(todo, POLLFD_PER_PAGE);
        walk = walk->next = kmalloc(struct_size(walk, entries, len),
                                    GFP_KERNEL);
        if (!walk) {
            err = -ENOMEM;
            goto out_fds;
        }
    }

    // 初始化等待队列
    poll_initwait(&table);
    // 核心处理逻辑（见下文）
    fdcount = do_poll(head, &table, end_time);
    poll_freewait(&table);

    if (!user_write_access_begin(ufds, nfds * sizeof(*ufds)))
        goto out_fds;

    for (walk = head; walk; walk = walk->next) {
        struct pollfd *fds = walk->entries;
        unsigned int j;

        // 将内核态的结果拷贝回用户态
        for (j = walk->len; j; fds++, ufds++, j--)
            unsafe_put_user(fds->revents, &ufds->revents, Efault);
      }
    user_write_access_end();

    err = fdcount;
out_fds:
    walk = head->next;
    while (walk) {
        struct poll_list *pos = walk;
        walk = walk->next;
        kfree(pos);
    }
    return err;

Efault:
    user_write_access_end();
    err = -EFAULT;
    goto out_fds;
}

核心处理逻辑：

static int do_poll(struct poll_list *list, struct poll_wqueues *wait,
                   struct timespec64 *end_time)
{
    poll_table* pt = &wait->pt;
    ktime_t expire, *to = NULL;
    int timed_out = 0, count = 0;
    u64 slack = 0;
    __poll_t busy_flag = net_busy_loop_on() ? POLL_BUSY_LOOP : 0;
    unsigned long busy_start = 0;

    // 处理已经超时的情况
    if (end_time && !end_time->tv_sec && !end_time->tv_nsec) {
        pt->_qproc = NULL;
        timed_out = 1;
    }

    if (end_time && !timed_out)
        slack = select_estimate_accuracy(end_time);

    // 主循环
    for (;;) {
        struct poll_list *walk;
        bool can_busy_loop = false;

        // 遍历所有的 poll_list 节点
        for (walk = list; walk != NULL; walk = walk->next) {
            struct pollfd * pfd, * pfd_end;

            pfd = walk->entries;
            pfd_end = pfd + walk->len;
            // 遍历 poll_list 节点中的每个 pollfd
            for (; pfd != pfd_end; pfd++) {
                __poll_t mask;
                // 关键监控逻辑（见下文）
                mask = do_pollfd(pfd, pt, &can_busy_loop, busy_flag);
                // 处理就绪的事件
                pfd->revents = mangle_poll(mask);
                if (mask) {
                    count++;
                    pt->_qproc = NULL;
                    busy_flag = 0;
                    can_busy_loop = false;
                }
            }
        }

        pt->_qproc = NULL;
        if (!count) {
            count = wait->error;
            if (signal_pending(current))
                count = -ERESTARTNOHAND;
        }

        // 检查是否超时
        if (count || timed_out)
            break;

        // 检查是否需要进入忙等待
        if (can_busy_loop && !need_resched()) {
            if (!busy_start) {
                busy_start = busy_loop_current_time();
                continue;
            }
            if (!busy_loop_timeout(busy_start))
                continue;
        }
        busy_flag = 0;

        if (end_time && !to) {
            expire = timespec64_to_ktime(*end_time);
            to = &expire;
        }

        // 进入等待
        if (!poll_schedule_timeout(wait, TASK_INTERRUPTIBLE, to, slack))
            timed_out = 1;
    }
    return count;
}

关键监控逻辑：

static inline __poll_t do_pollfd(struct pollfd *pollfd, poll_table *pwait,
                                 bool *can_busy_poll,
                                 __poll_t busy_flag)
{
    int fd = pollfd->fd;
    __poll_t mask, filter;

    if (unlikely(fd < 0))
        return 0;

    CLASS(fd, f)(fd);
    if (fd_empty(f))
        return EPOLLNVAL;

    filter = demangle_poll(pollfd->events) | EPOLLERR | EPOLLHUP;
    pwait->_key = filter | busy_flag;
    mask = vfs_poll(fd_file(f), pwait);
    if (mask & busy_flag)
        *can_busy_poll = true;
    return mask & filter;
}

讨论

可以看到，poll 的使用方式与 select 类似，但它相比之下做了很多优化：

fd 的数量不再有限制，仅需控制在最大内存范围内；
不需要每次设置集合；
支持更多的事件类型。

然而，它仍然存在一些不足之处：

仍然需要遍历整个数组来检查就绪的 fd，效率较低；
水平触发模式（即只要 fd 就绪但没有处理，poll 就会一直返回它）可能导致应用程序频繁被唤醒，浪费 CPU 资源。

Linux 2.5.44 内核中首次引入的 epoll，改进了上述问题。

`epoll`

基本使用

epoll 是 Linux 特有的 I/O 多路复用机制，它在 sys/epoll.h 中总共有 3 个系统调用：

// 创建 epoll 实例
int epoll_create(int size);   // 旧版本
int epoll_create1(int flags); // 新版本

// 控制 epoll 实例
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

// 等待事件
int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);

其中，

epoll_create
- size：指定要监视的 fd 的数量，通常设置为 1。
epoll_create1
- flags：当设置为 0 时，表现和 epoll_create 相同；如果设置为 EPOLL_CLOEXEC，则在执行 exec 时自动关闭该 fd ，防止 fd 泄漏。
epoll_ctl
- epfd：epoll 实例的 fd ；
- op：操作类型（ADD / DEL / MOD）；
- fd：要监视的 fd ；
- event：感兴趣的事件类型。
epoll_wait
- epfd：epoll 实例的 fd ；
- events：就绪事件的数组；
- maxevents：数组的最大容量；
- timeout：超时时间（毫秒）。

epoll_create v.s. epoll_create1

epoll_create 是较早的版本，参数 size 在现代 Linux 系统中已经被忽略，可以随意设置；而 epoll_create1 是较新的版本，增加了 flags 参数，允许设置 fd 的关闭行为，更加灵活和安全。

epoll 的工作原理与 select 和 poll 类似，但它使用了事件驱动的方式，避免了遍历所有 fd 的开销。

epoll 为了解决 poll 的水平触发问题，提供了两种触发模式：

**水平触发 (Level-Triggered)**：当 fd 就绪时，epoll_wait 会一直返回它，直到应用程序处理完毕。
**边缘触发 (Edge-Triggered)**：当 fd 状态发生变化时，epoll_wait 只会在状态变化的瞬间返回一次，之后需要再次注册才能继续接收事件。

下面是一个典型的 epoll 使用示例⁵。

点击查看代码

#define MAX_EVENTS 10
struct epoll_event ev, events[MAX_EVENTS];
int listen_sock, conn_sock, nfds, epollfd;

// 创建 epoll 实例
epollfd = epoll_create1(0);
if (epollfd == -1) {
    perror("epoll_create1");
    exit(EXIT_FAILURE);
}

// 添加监听 socket
ev.events = EPOLLIN;
ev.data.fd = listen_sock;
if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {
    perror("epoll_ctl: listen_sock");
    exit(EXIT_FAILURE);
}

for (;;) {
    // 等待事件发生
    nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);
    if (nfds == -1) {
        perror("epoll_wait");
        exit(EXIT_FAILURE);
    }

    // 处理就绪的事件
    for (int n = 0; n < nfds; ++n) {
        if (events[n].data.fd == listen_sock) {
            // 接受新连接
            conn_sock = accept(listen_sock,
                             (struct sockaddr *) &addr, &addrlen);
            if (conn_sock == -1) {
                perror("accept");
                exit(EXIT_FAILURE);
            }
            setnonblocking(conn_sock);
            // 添加新连接到 epoll
            ev.events = EPOLLIN | EPOLLET;
            ev.data.fd = conn_sock;
            if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,
                        &ev) == -1) {
                perror("epoll_ctl: conn_sock");
                exit(EXIT_FAILURE);
            }
        } else {
            // 处理数据
            do_use_fd(events[n].data.fd);
        }
    }
}

源码解读

epoll 的核心数据结构是一个红黑树（用于管理所有监视的 fd）和一个就绪队列（用于存储就绪的 fd）。

主要数据结构如下：

struct eventpoll {
    spinlock_t lock;
    struct mutex mtx;
    wait_queue_head_t wq;       // 等待队列
    wait_queue_head_t poll_wait; // poll 等待队列
    struct list_head rdllist;   // 就绪队列
    struct rb_root_cached rbr;  // 红黑树根节点
    struct epitem *ovflist;     // 溢出列表
    // ...
};

struct epitem {
    union {
        struct rb_node rbn;     // 红黑树节点
        struct rcu_head rcu;
    };
    struct list_head rdllink;   // 就绪队列链接
    struct epitem *next;
    struct epoll_filefd ffd;    // 文件描述符信息
    struct eventpoll *ep;       // 所属的 eventpoll
    struct epoll_event event;   // 用户设置的事件
    // ...
};

以目前最新的 Linux 6.16 为例，epoll 的实现在 fs/eventpoll.c 中⁶。

点击查看源码解析

创建 epoll 实例：

SYSCALL_DEFINE1(epoll_create1, int, flags)
{
    return do_epoll_create(flags);
}

static int do_epoll_create(int flags)
{
    int error, fd;
    struct eventpoll *ep = NULL;
    struct file *file;

    // 检查 flags 参数
    if (flags & ~EPOLL_CLOEXEC)
        return -EINVAL;

    // 分配 eventpoll 结构
    error = ep_alloc(&ep);
    if (error < 0)
        return error;

    // 获取未使用的文件描述符
    fd = get_unused_fd_flags(O_RDWR | (flags & O_CLOEXEC));
    if (fd < 0) {
        error = fd;
        goto out_free_ep;
    }

    // 创建匿名 inode 文件
    file = anon_inode_getfile("[eventpoll]", &eventpoll_fops, ep,
                             O_RDWR | (flags & O_CLOEXEC));
    if (IS_ERR(file)) {
        error = PTR_ERR(file);
        goto out_free_fd;
    }
    ep->file = file;
    fd_install(fd, file);
    return fd;

out_free_fd:
    put_unused_fd(fd);
out_free_ep:
    ep_free(ep);
    return error;
}

控制 epoll 实例：

SYSCALL_DEFINE4(epoll_ctl, int, epfd, int, op, int, fd,
                struct epoll_event __user *, event)
{
    struct epoll_event epds;

    if (ep_op_has_event(op) &&
        copy_from_user(&epds, event, sizeof(struct epoll_event)))
        return -EFAULT;

    return do_epoll_ctl(epfd, op, fd, &epds, false);
}

int do_epoll_ctl(int epfd, int op, int fd, struct epoll_event *epds,
                bool nonblock)
{
    int error;
    struct fd f, tf;
    struct eventpoll *ep;
    struct epitem *epi;
    struct eventpoll *tep = NULL;

    // 获取 epoll 文件描述符
    f = fdget(epfd);
    if (!f.file)
        return -EBADF;

    // 获取目标文件描述符
    tf = fdget(fd);
    if (!tf.file) {
        error = -EBADF;
        goto error_fput;
    }

    // 验证是否为 epoll 实例
    if (!is_file_epoll(f.file)) {
        error = -EINVAL;
        goto error_tgt_fput;
    }

    ep = f.file->private_data;

    mutex_lock_nested(&ep->mtx, 0);
    // 在红黑树中查找对应的 epitem
    epi = ep_find(ep, tf.file, fd);

    error = -EINVAL;
    switch (op) {
    case EPOLL_CTL_ADD:
        if (!epi) {
            epds->events |= EPOLLERR | EPOLLHUP;
            error = ep_insert(ep, epds, tf.file, fd, full_check);
        }
        break;
    case EPOLL_CTL_DEL:
        if (epi)
            error = ep_remove(ep, epi);
        break;
    case EPOLL_CTL_MOD:
        if (epi) {
            epds->events |= EPOLLERR | EPOLLHUP;
            error = ep_modify(ep, epi, epds);
        }
        break;
    }
    mutex_unlock(&ep->mtx);

error_tgt_fput:
    fdput(tf);
error_fput:
    fdput(f);
    return error;
}

等待事件：

SYSCALL_DEFINE4(epoll_wait, int, epfd, struct epoll_event __user *, events,
                int, maxevents, int, timeout)
{
    return do_epoll_wait(epfd, events, maxevents, timeout);
}

static int do_epoll_wait(int epfd, struct epoll_event __user *events,
                        int maxevents, int timeout)
{
    int error;
    struct fd f;
    struct eventpoll *ep;

    // 参数检查
    if (maxevents <= 0 || maxevents > EP_MAX_EVENTS)
        return -EINVAL;

    if (!access_ok(events, maxevents * sizeof(struct epoll_event)))
        return -EFAULT;

    // 获取 epoll 文件描述符
    f = fdget(epfd);
    if (!f.file)
        return -EBADF;

    if (!is_file_epoll(f.file)) {
        error = -EINVAL;
        goto error_fput;
    }

    ep = f.file->private_data;

    // 核心等待逻辑
    error = ep_poll(ep, events, maxevents, timeout);

error_fput:
    fdput(f);
    return error;
}

static int ep_poll(struct eventpoll *ep, struct epoll_event __user *events,
                  int maxevents, long timeout)
{
    int res = 0, eavail, timed_out = 0;
    u64 slack = 0;
    wait_queue_entry_t wait;
    ktime_t expires, *to = NULL;

    // 设置超时时间
    if (timeout > 0) {
        struct timespec64 end_time = ep_set_mstimeout(timeout);
        slack = select_estimate_accuracy(&end_time);
        to = &expires;
        *to = timespec64_to_ktime(end_time);
    } else if (timeout == 0) {
        timed_out = 1;
        write_lock_irq(&ep->lock);
        eavail = ep_events_available(ep);
        write_unlock_irq(&ep->lock);
        goto send_events;
    }

fetch_events:
    // 检查是否有就绪事件
    if (!ep_events_available(ep))
        ep_busy_loop(ep, timed_out);

    eavail = ep_events_available(ep);
    if (eavail)
        goto send_events;

    // 进入等待
    if (!schedule_hrtimeout_range(to, slack, HRTIMER_MODE_ABS))
        timed_out = 1;

    eavail = ep_events_available(ep);
    if (!eavail)
        goto fetch_events;

send_events:
    // 扫描就绪队列并发送事件
    res = ep_send_events(ep, events, maxevents);

    return res;
}

讨论

epoll 相比 select 和 poll 有以下优势：

无 fd 数量限制：可以监视任意数量的 fd（受系统资源限制）；
高效的事件通知：使用红黑树管理 fd，使用就绪队列存储就绪的 fd，无需遍历所有 fd；
支持边缘触发：避免水平触发模式下的频繁唤醒；
减少数据拷贝：使用内存映射（mmap）可以减少用户态和内核态之间的数据拷贝。

然而，epoll 仍然存在一些不足：

仅适用于 Linux：不具有跨平台性；
仍需系统调用：每次操作都需要陷入内核；
同步 I/O：必须等待事件发生后才能处理。

为了进一步提升性能，Linux 5.1 引入了全新的异步 I/O 框架——io_uring。

`io_uring`

io_uring 是 Linux 在 2019 年引入的全新异步 I/O 接口，由 Jens Axboe 设计开发⁷。它的设计目标是提供一个高性能、低延迟的异步 I/O 框架，解决传统 I/O 模型的性能瓶颈。

io_uring 的核心思想是通过两个无锁环形队列（Submission Queue 和 Completion Queue）在用户态和内核态之间传递 I/O 请求和完成事件，从而大幅减少系统调用开销。

graph LR
    A[用户空间] -->|提交 I/O 请求| B[SQ<br/>Submission Queue]
    B --> C[内核空间<br/>io_uring]
    C -->|完成事件| D[CQ<br/>Completion Queue]
    D --> A

主要特点：

零拷贝：使用共享内存映射，避免数据在用户态和内核态之间拷贝；
批量操作：可以一次性提交多个 I/O 请求，减少系统调用次数；
真正的异步：支持真正的异步 I/O，无需轮询或阻塞等待；
高性能：通过无锁队列和轮询模式，实现极低的延迟。

基本使用

io_uring 的使用需要通过三个系统调用：

// 设置 io_uring 实例
int io_uring_setup(unsigned entries, struct io_uring_params *p);

// 注册文件描述符或缓冲区
int io_uring_register(unsigned int fd, unsigned int opcode,
                     void *arg, unsigned int nr_args);

// 提交 I/O 请求和获取完成事件
int io_uring_enter(unsigned int fd, unsigned int to_submit,
                  unsigned int min_complete, unsigned int flags,
                  sigset_t *sig);

不过在实际使用中，通常会使用 liburing 库来简化操作⁸。

下面是一个使用 liburing 的简单示例：

点击查看代码

#include <liburing.h>
#include <stdio.h>
#include <string.h>

#define QUEUE_DEPTH 1
#define BLOCK_SIZE  4096

int main(int argc, char *argv[]) {
    struct io_uring ring;
    struct io_uring_sqe *sqe;
    struct io_uring_cqe *cqe;
    char buffer[BLOCK_SIZE];
    int fd;

    // 初始化 io_uring
    if (io_uring_queue_init(QUEUE_DEPTH, &ring, 0) < 0) {
        perror("io_uring_queue_init");
        return 1;
    }

    // 打开文件
    fd = open(argv[1], O_RDONLY);
    if (fd < 0) {
        perror("open");
        return 1;
    }

    // 获取一个 SQE（提交队列条目）
    sqe = io_uring_get_sqe(&ring);
    if (!sqe) {
        fprintf(stderr, "Could not get SQE.\n");
        return 1;
    }

    // 准备读取操作
    io_uring_prep_read(sqe, fd, buffer, BLOCK_SIZE, 0);

    // 提交请求
    io_uring_submit(&ring);

    // 等待完成
    io_uring_wait_cqe(&ring, &cqe);

    // 检查结果
    if (cqe->res < 0) {
        fprintf(stderr, "Async read failed: %s\n", strerror(-cqe->res));
        return 1;
    }

    printf("Read %d bytes\n", cqe->res);

    // 标记完成
    io_uring_cqe_seen(&ring, cqe);

    // 清理
    close(fd);
    io_uring_queue_exit(&ring);

    return 0;
}

源码解读

io_uring 的核心数据结构包括：

struct io_ring_ctx {
    struct {
        struct io_rings *rings;           // 共享内存区域
        struct io_ring_sq sq;             // 提交队列
        struct io_ring_cq cq;             // 完成队列
    } ____cacheline_aligned_in_smp;
    
    struct io_wq *io_wq;                  // 工作队列
    struct io_sq_data *sq_data;           // SQ 线程数据
    // ...
};

struct io_rings {
    struct io_uring_sq sq;                // SQ 环形缓冲区
    struct io_uring_cq cq;                // CQ 环形缓冲区
};

io_uring 的实现在 io_uring/ 目录下⁹。

点击查看关键流程

初始化流程：

SYSCALL_DEFINE2(io_uring_setup, u32, entries,
                struct io_uring_params __user *, params)
{
    return io_uring_setup(entries, params);
}

static long io_uring_setup(u32 entries, struct io_uring_params __user *params)
{
    struct io_uring_params p;
    int ret;

    if (copy_from_user(&p, params, sizeof(p)))
        return -EFAULT;

    // 创建 io_uring 实例
    ret = io_uring_create(entries, &p, params);
    if (ret < 0)
        return ret;

    return ret;
}

提交和完成流程：

SYSCALL_DEFINE6(io_uring_enter, unsigned int, fd, u32, to_submit,
                u32, min_complete, u32, flags, const void __user *, argp,
                size_t, argsz)
{
    struct io_ring_ctx *ctx;
    struct file *file;
    long ret;

    // 获取 io_uring 实例
    file = fget(fd);
    if (unlikely(!file))
        return -EBADF;

    ctx = file->private_data;

    // 提交 I/O 请求
    if (to_submit) {
        ret = io_submit_sqes(ctx, to_submit);
        if (ret < 0)
            goto out;
    }

    // 等待完成事件
    if (min_complete) {
        ret = io_cqring_wait(ctx, min_complete, argp, argsz, flags);
    }

out:
    fput(file);
    return ret;
}

讨论

io_uring 代表了 I/O 多路复用的最新发展方向：

优势：
- 极高的性能：通过减少系统调用和上下文切换，实现了比 epoll 更高的吞吐量；
- 真正的异步：支持完全异步的 I/O 操作，包括文件 I/O、网络 I/O 等；
- 灵活性强：支持多种 I/O 操作类型（read、write、accept、connect、fsync 等）；
- 可扩展性好：持续添加新特性，如链式操作、缓冲区选择等。
挑战：
- 复杂性高：API 相对复杂，学习曲线陡峭；
- 兼容性：仅在较新的 Linux 内核（5.1+）中可用；
- 安全问题：早期版本存在一些安全漏洞，需要谨慎使用。

总结

从 select 到 io_uring，我们见证了 I/O 多路复用技术的演进：

timeline
    title I/O 多路复用技术演进
    1983 : select
    1997 : poll
    2002 : epoll
    2019 : io_uring

特性	`select`	`poll`	`epoll`	`io_uring`
fd 数量限制	$1024$	无限制	无限制	无限制
数据拷贝	每次调用	每次调用	仅注册时	零拷贝
遍历开销	$O(n)$	$O(n)$	$O(1)$	$O(1)$
触发模式	水平触发	水平触发	水平/边缘	异步
跨平台	🟢	🟢	🔴	🔴
系统调用	每次轮询	每次轮询	每次轮询	批量提交

选择合适的 I/O 模型需要根据具体场景：

兼容性优先：使用 select 或 poll
高并发场景：使用 epoll
极致性能：使用 io_uring

随着硬件性能的提升和应用需求的增长，I/O 多路复用技术仍在不断发展。从 C10K 到 C10M，再到未来可能的 C100M，这场技术演进的故事还将继续。

Kegel, Dan. “The C10K Problem.” 1999. Link ↩
select(2) - Linux Manual Page ↩
Linux Kernel Source - fs/select.c ↩ ↩²
poll(2) - Linux Manual Page ↩
epoll(7) - Linux Manual Page ↩
Linux Kernel Source - fs/eventpoll.c ↩
Axboe, Jens. “Efficient IO with io_uring.” 2019. Link ↩
liburing - io_uring library ↩
Linux Kernel Source - io_uring ↩

如何组织一个 Go 项目?

mail@ch3nyang.top (Ch3nyang) — Fri, 27 Jun 2025 18:00:00 +0800

前段时间读了微信技术团队的一篇文章（从微信后端仓库发展史谈谈单仓和多仓），讲微信是如何在一步步壮大的过程中，逐步从大仓中剥离公众号、小程序等功能到小仓中，从而解决了各种公共库全都塞在同一个文件夹下导致的耦合、权限等问题。

在这个过程中，微信团队总结了一些经验教训，包括提出了合理规划项目文件结构的重要性：如果一股脑地将所有代码按照功能划分到不同的文件夹中，可能会因为未来的需求，导致文件夹之间产生强耦合，从而影响到代码的可维护性和可扩展性。

看完此文，我想就此谈一谈我对大型项目目录组织的看法。正好，最近 Go 写得比较多，就先从 Go 的项目组织谈起。

不过，谈论 Go 的项目组织前，我不得不搬出 Go 语言作者 Russ Cox 的一则 comment：

There are two problems with this GitHub repo:

it claims to host Go standards and does not, in the sense that these are in no way official standards
the project-layout standard it puts forth is far too complex and not a standard

Regarding “why not tell us the standard Go project layout and we’ll update the doc?”, that only addresses point 2. If there really were standards, they would be in the main Go project doc tree. The standard for project layout would also be a lot shorter. I appreciate your trying to provide a useful resource, but calling it ‘golang-standards’ is claiming more than it is.

But for the record, the minimal standard layout for an importable Go repo is really:

Put a LICENSE file in your root
Put a go.mod file in your root
Put Go code in your repo, in the root or organized into a directory tree as you see fit

That’s it. That’s the “standard”.

In particular:

It is not required to put commands in cmd/.
It is not required to put packages in pkg/.
It is not required to put web stuff in web/.
It is not required to put APIs in api/.
It is not required to put web stuff in web/.
It is not required to put configurations in configs/.
It is not required to put systemd scripts in init/.
It is not required to put shell scripts in scripts/.
It is not required to put Docker files in build/package/.
It is not required to put CI configs in build/ci/.
It is not required to put deployment configs in deployments/.
It is not required to put test support in test/.
It is not required to put documentation in docs/.
It is not required to put supporting tools in tools/.
It is not required to put examples in examples/.
It is not required to put third_party code in third_party/.
It is not required to put git hooks in githooks/.
It is not required to put static assets in assets/.

The importable golang.org/x repos break every one of these “rules”.

可以看到，Go 项目并没有强制要求特定的目录结构，开发者可以根据实际情况灵活组织项目————事实上，如果观察流行的 Go 开源项目，同样也会发现它们的目录结构五花八门。

Go 官方文档给出了一个基础的目录结构，不过看起来只适用于很小的项目；而 golang-standards/project-layout 给出了一个较为通用的项目结构示例，我觉得还不错：

cmd
- myapp
  - main.go
internal
- myapp
  - app.go
- mylib
  - lib.go
pkg
- utils
  - helper.go
api
- myapp.proto
- myapp.pb.go
web
- static
- css
- js
- images
- templates
  - index.html
build
- Dockerfile
- Makefile
configs
- config.yaml
- config.json
init
- db.sql
scripts
- migrate.sh
- deploy.sh
deploy
- k8s
  - deployment.yaml
  - service.yaml
test
- integration
- testdata
docs
- README.md
examples
- simple
  - main.go
go.mod
go.sum
LICENSE

下面来详细解释各个目录的作用：

cmd

cmd 目录通常用于存放应用程序的入口点。每个子目录对应一个可执行程序，通常包含一个 main.go 文件。

例如，项目中有一个名为 myapp 的 RPC 应用，cmd/myapp/main.go 可能如下所示：
```
package main

import (
    "github.com/myorg/myapp/internal/myapp"
    "github.com/myorg/myapp/internal/mylib"
)

func main() {
    myapp.Start()
    mylib.Start()
}
```
不过，如果整个项目只有一个 main.go，那么放到根目录也无妨。
internal

internal 目录用于存放不希望被外部引用的代码。Go 语言的包管理机制会阻止外部包引用 internal 目录下的内容。

例如，对于前文所述项目，internal/myapp/*.go 存放有该应用的实现，可能如下所示：
```
package myapp

import "fmt"

func Start() {
    fmt.Println("myapp started")
}
```
对于多个应用共用的包，也同样可以将其放在 internal 目录下的一个子目录中，例如 internal/mylib，然后在需要使用这些共享代码的应用中引用即可。
pkg

pkg 目录用于存放可以被外部引用的代码。与 internal 目录不同，pkg 目录下的内容可以被其他项目引用。

以 fatedier/frp 为例：
frp pkg 目录结构
collapse_all
- pkg
  - auth
  - config
  - errors
  - featuregate
  - metrics
  - msg
  - ...
可以看到，它是把本该属于 internal 的公共库代码提取到了 pkg 目录下。

通常在两种情况下会使用 pkg 目录：
1. 如果你的项目希望别人可以向其添加插件——而不用修改内部代码，那么将相关的功能抽象成 pkg 目录下的库是一个不错的选择。
2. 别的项目需要使用当前项目中的库。例如，你的一个项目做了企业权限管理系统，这时候你又做了一个新的项目，需要用到这个权限管理系统的某些功能，这时就可以直接引用 pkg 目录下的库，而不需要复制粘贴代码。
目前主流的 Go 项目似乎很少使用 pkg 目录，我看了一圈也只有 fatedier/frp 采用了这种方式。

此外，对于上述第二种情况，更好的做法是将共享的功能抽象成一个独立的库，与具体项目进行解耦。

这里，我想引用 Russ Cox 的一则 Issue 来佐证以上内容：

For the initial development of module support, we’ve kept everything in internal directories to make it easier to make changes as our understanding of what the pieces should look like becomes clearer. But now I think the basic pieces have become pretty clear, and we should think about exporting some packages to help other people who want to write tools working directly with module mechanics.

…

api

api 目录用于存放对外提供的接口定义，通常会包括：
- OpenAPI / Swagger specs
- JSON Schema
- GraphQL Schema
- Protobuf
以 kubernetes/kubernetes 为例：
kubernetes api 目录结构
collapse_all
- api
  - api-rules
    
    *.list
  - discovery
    
    *.json
  - openapi-spec
    
    *.json
对于前文所述项目，api/myapp.proto 存放有该应用的 gRPC 接口定义，可能如下所示：
```
syntax = "proto3";

package myapp;

service MyApp {
    rpc Start(StartRequest) returns (StartResponse);
}

message StartRequest {
    string name = 1;
}

message StartResponse {
    string message = 1;
}
```
同时，也包括了对应的 api/myapp.pb.go 文件。
web

web 目录用于存放与 Web 相关的代码，通常包括：
- 静态文件（如 HTML、CSS、JavaScript）
- 模板文件
- Web 服务器相关代码
以 prometheus/prometheus 为例，其 web 目录中就包含了网页服务程序、API 接口、UI 组件等。

对于前文所述项目，web/static 目录可能存放有静态文件，web/templates 目录可能存放有模板文件。

这一目录不仅可以用在全栈项目中，对于当前较为流行的服务器端渲染（SSR）框架同样适用。
build

build 目录用于存放与项目构建相关的文件，通常包括：
- Dockerfile
- CI/CD 配置文件
- 打包脚本
以 kubernetes/kubernetes 为例，其 build 目录中就包含了大量的 .sh 脚本和 Dockerfile 文件。
config

config 目录用于存放项目的配置文件。

以 prometheus/prometheus 为例，其 config 目录中就包含了 config.go 和 reload.go 两个文件及对应的测试文件，用来处理配置文件的加载和重载。
init

init 目录用于存放项目的初始化代码，通常包括：
- 数据库初始化
- 配置文件加载
- 日志初始化
scripts

scripts 目录用于存放项目的脚本文件，通常包括：
- 数据库迁移脚本
- 备份脚本
- 部署脚本
这里也会经常放一些供 Makefile 使用的脚本。

以 gohugoio/hugo 为例，其 scripts 目录中包含了 Docker 需要使用的 entrypoint.sh 脚本。
deploy

deploy 目录用于存放与项目部署相关的文件，通常包括：
- K8s 配置文件
- Docker Compose 文件
有些地方也会用 deployments 目录。

以 gohugoio/hugo 为例，其 deploy 目录中包含了 deploy.go 和部属用的配置文件。
test

test 目录用于存放项目的测试代码。运行测试时，Go 会自动识别该目录下的测试文件并执行相应的测试用例。

对于不需要 Go 运行的文件，可以放入 test/data 或 test/testdata 目录中，也可以在文件名开头加上 . 或 _。

以 syncthing/syncthing 为例，其 test 目录中包含了各类测试文件及测试需要用到的辅助文件。
docs & examples

docs 目录用于存放项目的文档（不是 go doc 生成的文档）；examples 目录用于存放项目的示例代码。

以 gin-gonic/gin 为例，其 docs 目录中包含了文档 doc.md；而 examples 目录中则……好吧，它们只留了一个 README.md 在里面，告诉你示例代码被移动到了一个单独的仓库中。
其它

其它目录可以根据项目需要自行定义，例如：
- assets：用于存放静态资源，如图片、字体等
- third_party：用于存放第三方依赖的代码和工具
- vendor：用于存放项目的依赖包
- tools：用于存放项目的开发工具
- githooks：用于存放 Git 钩子脚本

以上便是一个较好的 Go 项目目录结构示例。

当然，具体的项目结构还需要根据实际情况进行调整和优化。比如，ollama/ollama 作为一个 AI 项目，根目录下就多了诸如 llm、lm、model、openai 这样的子目录。

总之，合理的目录结构是良好架构的重要组成部分。当代码规模扩大时，它能够有效地降低模块之间的耦合度，提高代码的可维护性和可扩展性。

ReDos——低效的正则表达式

mail@ch3nyang.top (Ch3nyang) — Thu, 08 May 2025 18:00:00 +0800

我之前在写代码时用到了一个正则表达式来匹配 URL，CodeQL 检测出其存在问题：

This part of the regular expression may cause exponential backtracking on strings starting with '0' and containing many repetitions of '0'.

这其实是 CWE-1333，表明一个正则表达式可能出现极为低效的情况。接下来我们来看看具体是怎么回事。

正则表达式通常会被解析为一个非确定性有限自动机（NFA），其中每对状态和输入符号可能存在多个可能的后续状态。算法会逐一尝试所有可能的路径，直到找到匹配项。这一情况通常被称为 backtracking。

例如，对于正则表达式 ^(aa|.)+$，如果输入为无法匹配到的 aaX，算法会尝试以下路径：

按照左侧的 aa 匹配，匹配一次
按照右侧的 . 匹配，匹配两次

我们可以将正则表达式改为 ^(aa|[^a])+$，这样就可以避免同一输入存在多个匹配方法的情况。

一个更加直观的例子是 ^(a+)+$，对于无法匹配的输入 aaaaX，算法会尝试以下路径：

aaaa
aaa + a
aa + aa
a + aaa
aa + a + a
a + aa + a
a + a + aa
a + a + a + a

可以看到，如此简单的正则表达式都有了 8 种匹配的可能方式；而对于 aaaaaaaaaaaaaaaaaX，算法会尝试 $2^{16} = 65536$ 种匹配方式，导致性能严重下降。

我们可以编写代码进行测试：

import time
import re

def test_regex_performance(regex_pattern, test_input):
    start = time.time()
    try:
        re.match(regex_pattern, test_input)
    except:
        pass
    return time.time() - start

bad_input = 'a' * 30 + 'X'
print(test_regex_performance(r'^(a+)+$', bad_input))  # 29.655
print(test_regex_performance(r'^a+$', bad_input))     # 0.0

在上面的代码中，我们使用了 Python 的 re 模块来测试正则表达式的性能。我们可以看到，使用 ^(a+)+$ 的正则表达式时，耗时 29.655 秒，而使用 ^a+$ 时，耗时几乎为 0。

对于攻击者来说，正则表达式的性能问题是一个很好的攻击向量。攻击者可以通过构造输入来导致正则表达式的性能下降，甚至导致拒绝服务（DoS）攻击。这种手段被称为正则表达式拒绝服务（ReDoS）攻击。ReDoS 攻击有许多现实案例，例如 CVE-2022-31129 等。

一些正则表达式引擎（例如 grep 等）使用确定性有限自动机（DFA）来避免 backtracking 的问题。DFA 是一种状态机，它在每个状态下只有一个可能的后续状态，因此不需要 backtracking。DFA 的性能通常比 NFA 更好，但 DFA 的实现通常更复杂。然而，由于扩展正则表达式的引入，正则表达式引擎很难完全实现 DFA，这使得其退化为了 NFA。例如：

反向引用：匹配先前捕获的组，如 (\w+)\1，这无法完全使用 DFA 实现
环视：如 (?=...) 正向肯定查找、(?<!...) 反向否定查找等，可能触发多次子表达式匹配

要想避免 ReDoS 也不难，通常可以检查这样几点：

避免嵌套量词 (a+)+、重叠选择分支 (a|aa)+ 等情况
使用原子组 (?>...) 使得匹配失败后不会回溯
禁用扩展语法，使用纯 DFA 引擎
禁止输入过长的字符串

浅谈 MCP 和 A2A

mail@ch3nyang.top (Ch3nyang) — Mon, 14 Apr 2025 18:00:00 +0800

MCP 已经推出一段时间了，今天我们来聊聊它的原理和我的看法。

什么是 MCP？

MCP 作为一个协议，其参与方包括：

LLM：大语言模型，例如 GPT、Claude 等
MCP Hosts：本地软件，负责处理用户的请求
Local Data Sources：本地数据源，例如文件、数据库等
Remote Services：远程调用的服务，例如地图、翻译工具等
MCP Client：每个软件可以有多个 MCP Client，每个 MCP Client 对应一个本地或远程服务
MCP Server：负责处理 MCP Client 的请求，每种服务只有一个 MCP Server

这里借用一张 MCP 官网上的图：

flowchart LR
    subgraph "Your Computer"
        Host["Host with MCP Client<br>(Claude, IDEs, Tools)"]
        S1["MCP Server A"]
        S2["MCP Server B"]
        S3["MCP Server C"]
        Host <-->|"MCP Protocol"| S1
        Host <-->|"MCP Protocol"| S2
        Host <-->|"MCP Protocol"| S3
        S1 <--> D1[("Local<br>Data Source A")]
        S2 <--> D2[("Local<br>Data Source B")]
    end
    subgraph "Internet"
        S3 <-->|"Web APIs"| D3[(Remote<br>Service C)]
    end

MCP 在使用时按照如下步骤进行：

服务初始化阶段：软件向其所有 MCP Client 发送初始化指令
1. MCP Client 发送 initialize 指令，请求开始初始化
2. MCP Server 返回协议版本和能力（可用的服务调用列表）
3. MCP Client 发送 initialized 指令，表示初始化完成
服务选择阶段：软件确定要调用的服务及其参数
1. 软件结合第一步得到的能力列表，组合为 prompt
2. 软件向大模型发送 prompt
3. 大模型返回消息，其中包含了要调用的服务和参数
服务调用阶段：软件根据大模型的返回值，调用相应的服务

sequenceDiagram
    participant 软件
    participant MCP Client
    participant LLM
    participant MCP Server
    participant 远程服务

    Note over 软件, 远程服务: 服务初始化阶段

    软件->>MCP Client: 初始化
    MCP Client->>MCP Server: initialize
    MCP Server->>MCP Client: 协议版本和能力
    MCP Client->>MCP Server: initialized

    Note over 软件, 远程服务: 服务选择阶段

    软件->>软件: 组合 prompt
    软件->>LLM: prompt
    LLM->>软件: 返回消息

    Note over 软件, 远程服务: 服务调用阶段

    软件->>MCP Client: 调用服务
    MCP Client->>MCP Server: 调用服务
    MCP Server->>远程服务: 调用服务
    远程服务->>MCP Server: 返回结果
    MCP Server->>MCP Client: 返回结果
    MCP Client->>软件: 返回结果

值得注意的是，在 MCP 协议中，正常通信使用的都是 HTTP / SSE 协议，只有 MCP Client 向 MCP Server 调用具体服务时使用了 JSON-RPC 协议。

MCP 好用吗？

目前来看，MCP 最大的作用就是一统天下，给新概念层出不穷的 LLM 服务调用方案提供了一个统一的接口。基于 Anthropic 的影响力，应该会有越来越多的服务提供商跟进，形成良好的社区生态，从而进一步形成壁垒。

然而，就我个人来看，MCP 目前的实现还是有些问题的：

脱裤子放屁

MCP 主要做了两件事情：获取可用服务、选择并调用服务。熟悉微服务架构的朋友们一看就会发现，这不就是 RPC 嘛！你要再看仔细一点，MCP 最终调用服务的时候使用的还是 JSON-RPC 协议，这下子基本可以认为它是 RPC 套壳了。
LLM 上下文长度限制

MCP 需要收集远程服务的接口，而在接口数量较多的情况下（比如 GPTs 有数百万个），LLM 很难处理这么长的上下文。
过于依赖 LLM 的能力

MCP 软件最终调用的服务还是通过 LLM 给出。显然，不同的 LLM 可能会给出不同的服务调用，这根本无法保证服务调用的正确性。比如说，LLM 可能会给出一个不存在的服务，或者给出错误的参数，这些都需要软件自己去处理。
服务必须实现 MCP Server

就这一点来讲，MCP 协议真的是烂中烂。在传统 RPC 下，服务只需要实现一个 API 接口，软件使用时可以直接调用这个接口。然而，在 MCP 协议下，服务必须实现一个 MCP Server，这就导致了服务的实现变得更加复杂。并且，MCP Server 还需要处理 SSE 和 JSON-RPC 两种协议，这无疑增加了开发和维护的成本。
无视安全问题

我深度怀疑 MCP 协议的设计者对网络安全一无所知。MCP 协议的设计完全无视了网络安全问题，尤其是数据隐私和身份验证。MCP 协议没有提供任何身份验证机制，这就意味着任何人都可以伪造 MCP Client 向 MCP Server 发送请求，从而获取敏感数据。此外，MCP 协议也没有提供任何加密机制，这就意味着数据在传输过程中可能会被窃取或篡改。
token 成本

由于 MCP 协议的设计，LLM 在处理请求时需要考虑到所有可用的服务和参数，这无疑增加了 token 的消耗。对于一些 token 成本较高的 LLM 来说，这无疑是一个巨大的负担。当然，MCP 协议的设计者可能会认为这是一个合理的 trade-off，但我个人认为这并不是一个好的设计。
协议缺乏规范化

这一点没什么可解释的。当今所有互联网协议都是有 RFC 的，对比这些 RFC 和 MCP 协议的描述，你会发现 MCP 似乎从来没有考虑过协议的规范化问题。MCP 协议的设计者似乎认为，协议的实现是由 MCP Server 来完成的，而不是由协议本身来完成的。这就导致了 MCP 协议的实现非常不规范，甚至可以说是随意。

当然，Anthropic 自己也注意到了相关的问题，在它们的 Roadmap 中，注册、验证、治理等功能的实现都被提上了日程。尽管可以相信 MCP 未来一定会逐步完善，但搞出这么个半成品协议就发布出来，属于是拉了一大坨，还有一堆媒体跟风上去舔！

A2A 呢？

Google 最近也发布了一个 A2A 协议，自称是 MCP 的补充。

相比于 MCP，A2A 协议的设计做了以下补充：

多 Agent

相比于 MCP 协议处理了 Agent 和服务的关系，A2A 协议处理了 Agent 和 Agent 之间的关系。也就是说，A2A 协议允许多个 Agent 之间进行通信，可以使它们协同工作。
代理发现

A2A 协议允许 Agent 之间进行发现和注册，这样它们就可以相互调用。熟悉微服务架构的朋友们又要说了，这不就是注册中心嘛！
默认安全性

A2A 协议的设计者考虑到了安全性问题，协议中包含了一些安全机制。
规范化

A2A 协议的设计者考虑到了协议的规范化问题，相比于 MCP 协议，A2A 协议更像一个真正的「协议」了。

当然，目前来看，A2A 对 MCP 的改进还是比较有限的。只不过，在当下 LLM 飞速发展的情形下，类似的协议一定会出现 —— Anthropic 和 Google 不做的话，其他公司也会做。希望这样的协议能尽快达到可用的程度，给 LLM 的发展带来更多的可能性。

算法笔记 (2) - git diff 是如何实现的？

mail@ch3nyang.top (Ch3nyang) — Fri, 04 Apr 2025 03:00:00 +0800

你是否好奇过 git diff 是如何高效地比较文件并精确显示变化的？这个看似简单的操作背后，隐藏着相当精妙的算法设计。

假设有两个文件 $A$ 和 $B$，它们分别有 $N=7$ 行和 $M=6$ 行：

 A     B
===   ===
 A     C
 B     B
 C     A
 A     B
 B     A
 B     C
 A

我们可以将这个比较问题抽象为在一个 $N \times M$ 网格中寻找路径：

从任意坐标 $(x, y)$ 出发，我们有三种可能的移动方式：

向右移动到 $(x+1, y)$ — 表示删除第一个文件的第 $x+1$ 行
向下移动到 $(x, y+1)$ — 表示添加第二个文件的第 $y+1$ 行
对角线移动到 $(x+1, y+1)$ — 表示两个文件的对应行内容相同（无需编辑）

对角线移动在 diff 算法中被称为”snake”，关键在于它不会增加我们的编辑距离。

我们的目标是找到一条从 $(0, 0)$ 到 $(N, M)$ 的路径，使得水平移动和垂直移动的总数最小——也就是最小化编辑距离。

这本质上就是经典的最小编辑距离问题，也称为计算两个序列间的 Levenshtein 距离。

动态规划方法

对于这个问题，最直观的解法是使用动态规划：

\[dp[i][j] = \begin{cases} \min\left(dp[i-1][j], dp[i][j-1]\right) + 1 & A[i] \neq B[j] \\ dp[i-1][j-1] & A[i] = B[j] \end{cases}\]

边界条件为：

\[\begin{aligned} dp[0][0] &= 0 \\ dp[i][0] &= i \\ dp[0][j] &= j \end{aligned}\]

这里给出 Python 代码实现：

def diff(A: list[str], B: list[str]) -> tuple[int, list[tuple[str, str, int | None, int | None]]]:
    """
    计算两个序列之间的最小编辑距离（Levenshtein距离）并返回详细的编辑路径。
    
    Args:
        A: 源序列
        B: 目标序列
    
    Returns:
        tuple: 包含两个元素的元组
            - int: 最小编辑距离（需要的最少操作数）
            - list: 编辑路径，每个元素是一个四元组 (操作, 元素值, A索引, B索引)
    
    编辑操作说明:
        '=': 元素相同，无需修改
        '-': 删除操作，A中存在但B中不存在
        '+': 插入操作，B中存在但A中不存在
    """
    N, M = len(A), len(B)
    dp = [[0] * (M + 1) for _ in range(N + 1)]
    for i in range(1, N + 1):
        dp[i][0] = i
    for j in range(1, M + 1):
        dp[0][j] = j
    for i in range(1, N + 1):
        for j in range(1, M + 1):
            if A[i - 1] == B[j - 1]:
                dp[i][j] = dp[i - 1][j - 1]
            else:
                if dp[i - 1][j] < dp[i][j - 1]:
                    dp[i][j] = dp[i - 1][j] + 1
                else:
                    dp[i][j] = dp[i][j - 1] + 1
    i, j = N, M
    path = []
    while i > 0 or j > 0:
        if i > 0 and j > 0 and A[i - 1] == B[j - 1]:
            path.append(('=', A[i - 1], i - 1, j - 1))
            i -= 1
            j -= 1
        elif j > 0 and (i == 0 or dp[i][j - 1] <= dp[i - 1][j]):
            path.append(('+', B[j - 1], None, j - 1))
            j -= 1
        else:
            path.append(('-', A[i - 1], i - 1, None))
            i -= 1
    path.reverse()
    return dp[N][M], path

当存在多条最优路径时，回溯过程需要仔细考虑优先级规则。在我们的实现中，当删除和添加操作的代价相等时，优先选择水平移动（删除操作）而不是垂直移动（添加操作）。这个选择会影响 diff 输出的视觉效果，但不会改变最小编辑距离。

注意： 如果希望优先添加而不是删除，只需将回溯逻辑中的 dp[i][j - 1] <= dp[i - 1][j] 改为 dp[i][j - 1] < dp[i - 1][j]。

下面是运行结果：

A = ["A", "B", "C", "A", "B", "B", "A"]
B = ["C", "B", "A", "B", "A", "C"]
distance, path = diff(A, B)
print("最小编辑距离:", distance)
print("diff:")
for op, val, i, j in path:
    if op == '=':
        print(f"  {val}")
    elif op == '-':
        print(f"- {val}")
    elif op == '+':
        print(f"+ {val}")

DP diff

最小编辑距离: 5
diff:
- A
- B
  C
- A
  B
+ A
  B
  A
+ C

这个方法完全正确！不过，我们的 DP 算法时间复杂度和空间复杂度都是 $O(NM)$。对于大文件来说，这可能会变得相当昂贵。我们能否做得更好呢？

Myers 算法

Myers 算法提供了一个更高效的解决方案，时间复杂度为 $O(N\log N + D^2)$，空间复杂度为 $O(N)$，其中 $D$ 是最小编辑距离。当文件相似度较高（$D$ 较小）时，这比 DP 方法有显著优势。

关键思路是使用不同的坐标系统。我们定义对角线 $k$ 为水平和垂直位置的差值：$k = x - y$。

由于我们需要恰好 $N$ 次水平移动和 $M$ 次垂直移动才能到达 $(N, M)$，我们知道最终的对角线将是 $k = N - M$。而且，最小编辑距离 $D$ 必须满足：

\[D \geq |N - M|\]

算法通过按编辑距离 $D$ 递增的顺序探索路径，使用 $k-D$ 坐标系：

我们不需要填充整个 $N \times M$ 表格，而是逐步探索 $D = 0, 1, 2, \ldots$ 的路径，直到到达目标。对于每个编辑距离 $D$，可能的对角线范围从 $k = -D$ 到 $k = D$（步长为 2，因为每次编辑操作会使 $k$ 改变 $\pm 1$）。

我们维护一个数组 $V$，其中 $V[k]$ 存储在对角线 $k$ 上使用恰好 $D$ 次编辑操作能到达的最远 $x$ 坐标。

初始时，$V[1] = 0$（这里有一个微妙的索引约定——我们从 $D=0$ 时的 $k=0$ 开始）。

策略是在每条对角线上最大化 $x$，这样我们就能尽可能多地进行”免费”的对角线移动（snake）。要用 $D$ 次编辑到达对角线 $k$，我们可以从以下路径选择：

对角线 $k+1$ 通过向下移动（插入）：$x = V[k+1]$
对角线 $k-1$ 通过向右移动（删除）：$x = V[k-1] + 1$

选择取决于边界条件以及哪个选项能给我们更大的 $x$：

当 $k = -D$：必须来自 $k+1$（不能再向左），所以 $x = V[k+1]$
当 $k = D$：必须来自 $k-1$（不能再向右），所以 $x = V[k-1] + 1$
当 $-D < k < D$：选择能给出更大 $x$ 值的那个

合并一下就能得到：

if k == -D or (k != D and V.get(k - 1) < V.get(k + 1)):
    x = V.get(k + 1)
else:
    x = V.get(k - 1) + 1

有了 $x$，我们可以计算出 $y$：

\[y = x - k\]

然后我们可以进行 snake 移动，直到 $A[x] \neq B[y]$：

while x < N and y < M and A[x] == B[y]:
    x += 1
    y += 1

我们继续这个过程，逐步增加 $D$，直到达到目标：当 $V[N - M] \geq N$ 时，我们就找到了从 $(0, 0)$ 到 $(N, M)$ 的最短路径。

下面的示意图展示了 Myers 算法的执行过程：

下面是 Python 代码实现：

def myers_diff(A: list[str], B: list[str]) -> tuple[int, list[tuple[str, str, int | None, int | None]]]:
    """
    使用 Myers 算法计算编辑距离。
    
    返回格式与 DP 版本相同，便于比较。
    """
    N, M = len(A), len(B)
    if N == 0:
        return M, [('+', B[j], None, j) for j in range(M)]
    if M == 0:
        return N, [('-', A[i], i, None) for i in range(N)]
    
    max_d = N + M
    V = {1: 0}
    trace = [V.copy()]
    
    for D in range(max_d + 1):
        new_V = {}
        for k in range(-D, D + 1, 2):
            if k == -D or (k != D and V.get(k - 1, -1) < V.get(k + 1, -1)):
                x = V.get(k + 1, 0)
            else:
                x = V.get(k - 1, 0) + 1
            y = x - k
            
            while x < N and y < M and A[x] == B[y]:
                x += 1
                y += 1
            
            new_V[k] = x
            
            if x >= N and y >= M:
                path = []
                x, y = N, M
                for d in range(D, -1, -1):
                    k = x - y
                    V_prev = trace[d]
                    
                    if k == -d or (k != d and V_prev.get(k - 1, -1) < V_prev.get(k + 1, -1)):
                        prev_k = k + 1
                    else:
                        prev_k = k - 1
                    
                    prev_x = V_prev.get(prev_k, 0)
                    prev_y = prev_x - prev_k
                    
                    while x > prev_x and y > prev_y:
                        path.append(('=', A[x - 1], x - 1, y - 1))
                        x -= 1
                        y -= 1
                    
                    if d > 0:
                        if x == prev_x:
                            path.append(('+', B[y - 1], None, y - 1))
                            y -= 1
                        else:
                            path.append(('-', A[x - 1], x - 1, None))
                            x -= 1
                
                path.reverse()
                return D, path
        
        V = new_V
        trace.append(V.copy())
    
    return max_d, []

下面是运行结果：

A = ["A", "B", "C", "A", "B", "B", "A"]
B = ["C", "B", "A", "B", "A", "C"]
distance, path = myers_diff(A, B)
print("最小编辑距离:", distance)
print("diff:")
for op, val, i, j in path:
    if op == '=':
        print(f"  {val}")
    elif op == '-':
        print(f"- {val}")
    elif op == '+':
        print(f"+ {val}")

Myers diff

最小编辑距离: 5
diff:
- A
- B
  C
- A
  B
+ A
  B
  A
+ C

性能分析

算法比较

虽然 Myers 算法在理论上有更好的复杂度——时间复杂度 $O(N\log N + D^2)$ 和空间复杂度 $O(N)$，相比 DP 的 $O(NM)$——但实际性能很大程度上取决于输入文件的相似程度。

当 $D$ 接近 $N + M$（完全不同的文件）时，Myers 的时间复杂度会退化到 $O((N + M)^2)$，可能比直接的 DP 方法更差。让我们在各种条件下对两种算法进行基准测试：

import random
import time
import matplotlib.pyplot as plt
import numpy as np

def generate_test_case(N: int, M: int, similarity: float) -> tuple[list[str], list[str]]:
    base = [chr(i) for i in range(65, 91)]  # A-Z
    A = [random.choice(base) for _ in range(N)]
    B = []
    for i in range(M):
        if random.random() < similarity and i < N:
            B.append(A[i])
        else:
            B.append(random.choice(base))
    return A, B
def benchmark():
    test_cases = []
    for size in [100, 200, 300, 400, 500, 600]:
        for similarity in [0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.1]:
            test_cases.append((size, size, similarity))
    
    runs_per_test = 100
    results = []
    
    for N, M, sim in test_cases:
        dp_times = []
        myers_times = []
        
        for run in range(runs_per_test):
            A, B = generate_test_case(N, M, sim)
            
            start = time.time()
            dp_distance, _ = diff(A, B)
            dp_time = time.time() - start
            dp_times.append(dp_time)
            
            start = time.time()
            myers_distance, _ = myers_diff(A, B)
            myers_time = time.time() - start
            myers_times.append(myers_time)
            
            assert dp_distance == myers_distance, "结果不一致"
        
        dp_time_avg = np.mean(dp_times)
        dp_time_std = np.std(dp_times)
        myers_time_avg = np.mean(myers_times)
        myers_time_std = np.std(myers_times)
        
        results.append((N, M, sim, dp_time_avg, myers_time_avg))
        print(f"N={N}, M={M}, similarity={sim:.1f} | "
              f"DP: {dp_time_avg:.4f}s (±{dp_time_std:.4f}) | "
              f"Myers: {myers_time_avg:.4f}s (±{myers_time_std:.4f})")
    
    plot_results(results)

def plot_results(results):
    sizes = sorted(set([r[0] for r in results]))
    similarities = sorted(set([r[2] for r in results]), reverse=True)
    
    fig = plt.figure(figsize=(12, 18))
    
    ax1 = plt.subplot(3, 2, 1)
    dp_by_size = {}
    myers_by_size = {}
    for size in sizes:
        size_results = [r for r in results if r[0] == size]
        dp_by_size[size] = np.mean([r[3] for r in size_results])
        myers_by_size[size] = np.mean([r[4] for r in size_results])
    
    x_pos = range(len(sizes))
    width = 0.35
    ax1.bar([x - width/2 for x in x_pos], [dp_by_size[s] for s in sizes], width, label='DP', alpha=0.8)
    ax1.bar([x + width/2 for x in x_pos], [myers_by_size[s] for s in sizes], width, label='Myers', alpha=0.8)
    ax1.set_xlabel('Sequence Length')
    ax1.set_ylabel('Average Time (s)')
    ax1.set_title('Performance by Sequence Length')
    ax1.set_xticks(x_pos)
    ax1.set_xticklabels(sizes)
    ax1.legend()
    ax1.grid(True, alpha=0.3)
    
    ax2 = plt.subplot(3, 2, 2)
    dp_by_sim = {}
    myers_by_sim = {}
    for sim in similarities:
        sim_results = [r for r in results if abs(r[2] - sim) < 0.01]
        dp_by_sim[sim] = np.mean([r[3] for r in sim_results])
        myers_by_sim[sim] = np.mean([r[4] for r in sim_results])
    
    x_pos = range(len(similarities))
    ax2.bar([x - width/2 for x in x_pos], [dp_by_sim[s] for s in similarities], width, label='DP', alpha=0.8)
    ax2.bar([x + width/2 for x in x_pos], [myers_by_sim[s] for s in similarities], width, label='Myers', alpha=0.8)
    ax2.set_xlabel('Similarity')
    ax2.set_ylabel('Average Time (s)')
    ax2.set_title('Performance by Similarity')
    ax2.set_xticks(x_pos)
    ax2.set_xticklabels([f'{s:.1f}' for s in similarities])
    ax2.legend()
    ax2.grid(True, alpha=0.3)
    
    ax3 = plt.subplot(3, 2, 3)
    ratios_by_size = {size: myers_by_size[size] / dp_by_size[size] for size in sizes}
    ax3.plot(sizes, [ratios_by_size[s] for s in sizes], marker='o', linewidth=2, markersize=8)
    ax3.axhline(y=1, color='r', linestyle='--', label='Equal Performance')
    ax3.set_xlabel('Sequence Length')
    ax3.set_ylabel('Myers Time / DP Time')
    ax3.set_title('Performance Ratio (Myers/DP) by Length')
    ax3.legend()
    ax3.grid(True, alpha=0.3)
    
    ax4 = plt.subplot(3, 2, 4)
    dp_heatmap = np.zeros((len(similarities), len(sizes)))
    for i, sim in enumerate(similarities):
        for j, size in enumerate(sizes):
            matching = [r for r in results if r[0] == size and abs(r[2] - sim) < 0.01]
            if matching:
                dp_heatmap[i, j] = matching[0][3]
    
    im1 = ax4.imshow(dp_heatmap, aspect='auto', cmap='YlOrRd')
    ax4.set_xticks(range(len(sizes)))
    ax4.set_xticklabels(sizes)
    ax4.set_yticks(range(len(similarities)))
    ax4.set_yticklabels([f'{s:.1f}' for s in similarities])
    ax4.set_xlabel('Sequence Length')
    ax4.set_ylabel('Similarity')
    ax4.set_title('DP Algorithm Performance (s)')
    plt.colorbar(im1, ax=ax4)
    
    ax5 = plt.subplot(3, 2, 5)
    myers_heatmap = np.zeros((len(similarities), len(sizes)))
    for i, sim in enumerate(similarities):
        for j, size in enumerate(sizes):
            matching = [r for r in results if r[0] == size and abs(r[2] - sim) < 0.01]
            if matching:
                myers_heatmap[i, j] = matching[0][4]
    
    im2 = ax5.imshow(myers_heatmap, aspect='auto', cmap='YlOrRd')
    ax5.set_xticks(range(len(sizes)))
    ax5.set_xticklabels(sizes)
    ax5.set_yticks(range(len(similarities)))
    ax5.set_yticklabels([f'{s:.1f}' for s in similarities])
    ax5.set_xlabel('Sequence Length')
    ax5.set_ylabel('Similarity')
    ax5.set_title('Myers Algorithm Performance (s)')
    plt.colorbar(im2, ax=ax5)
    
    ax6 = plt.subplot(3, 2, 6)
    ratio_heatmap = np.divide(myers_heatmap, dp_heatmap, where=dp_heatmap!=0)
    
    im3 = ax6.imshow(ratio_heatmap, aspect='auto', cmap='RdYlGn_r', vmin=0.5, vmax=1.5)
    ax6.set_xticks(range(len(sizes)))
    ax6.set_xticklabels(sizes)
    ax6.set_yticks(range(len(similarities)))
    ax6.set_yticklabels([f'{s:.1f}' for s in similarities])
    ax6.set_xlabel('Sequence Length')
    ax6.set_ylabel('Similarity')
    ax6.set_title('Performance Ratio (Myers/DP)')
    plt.colorbar(im3, ax=ax6)
    
    plt.tight_layout()
    plt.savefig('diff_algorithm_benchmark.png', dpi=300, bbox_inches='tight')
    plt.show()

benchmark()

Benchmark

N=100, M=100, similarity=0.9 | DP: 0.0008s (±0.0001) | Myers: 0.0001s (±0.0000)
N=100, M=100, similarity=0.8 | DP: 0.0008s (±0.0001) | Myers: 0.0002s (±0.0001)
N=100, M=100, similarity=0.7 | DP: 0.0008s (±0.0000) | Myers: 0.0003s (±0.0001)
N=100, M=100, similarity=0.6 | DP: 0.0008s (±0.0000) | Myers: 0.0006s (±0.0001)
N=100, M=100, similarity=0.5 | DP: 0.0008s (±0.0001) | Myers: 0.0008s (±0.0002)
N=100, M=100, similarity=0.4 | DP: 0.0008s (±0.0000) | Myers: 0.0011s (±0.0002)
N=100, M=100, similarity=0.3 | DP: 0.0008s (±0.0000) | Myers: 0.0013s (±0.0002)
N=100, M=100, similarity=0.2 | DP: 0.0008s (±0.0000) | Myers: 0.0015s (±0.0001)
N=100, M=100, similarity=0.1 | DP: 0.0008s (±0.0000) | Myers: 0.0017s (±0.0001)
N=200, M=200, similarity=0.9 | DP: 0.0031s (±0.0001) | Myers: 0.0002s (±0.0001)
N=200, M=200, similarity=0.8 | DP: 0.0031s (±0.0001) | Myers: 0.0006s (±0.0002)
N=200, M=200, similarity=0.7 | DP: 0.0031s (±0.0000) | Myers: 0.0013s (±0.0003)
N=200, M=200, similarity=0.6 | DP: 0.0032s (±0.0001) | Myers: 0.0021s (±0.0004)
N=200, M=200, similarity=0.5 | DP: 0.0032s (±0.0002) | Myers: 0.0032s (±0.0004)
N=200, M=200, similarity=0.4 | DP: 0.0032s (±0.0001) | Myers: 0.0042s (±0.0005)
N=200, M=200, similarity=0.3 | DP: 0.0032s (±0.0003) | Myers: 0.0052s (±0.0004)
N=200, M=200, similarity=0.2 | DP: 0.0032s (±0.0003) | Myers: 0.0060s (±0.0004)
N=200, M=200, similarity=0.1 | DP: 0.0032s (±0.0003) | Myers: 0.0066s (±0.0003)
N=300, M=300, similarity=0.9 | DP: 0.0074s (±0.0002) | Myers: 0.0004s (±0.0001)
N=300, M=300, similarity=0.8 | DP: 0.0075s (±0.0005) | Myers: 0.0013s (±0.0003)
N=300, M=300, similarity=0.7 | DP: 0.0076s (±0.0003) | Myers: 0.0028s (±0.0006)
N=300, M=300, similarity=0.6 | DP: 0.0077s (±0.0003) | Myers: 0.0045s (±0.0006)
N=300, M=300, similarity=0.5 | DP: 0.0078s (±0.0003) | Myers: 0.0072s (±0.0011)
N=300, M=300, similarity=0.4 | DP: 0.0078s (±0.0003) | Myers: 0.0097s (±0.0013)
N=300, M=300, similarity=0.3 | DP: 0.0079s (±0.0004) | Myers: 0.0119s (±0.0010)
N=300, M=300, similarity=0.2 | DP: 0.0080s (±0.0004) | Myers: 0.0141s (±0.0010)
N=300, M=300, similarity=0.1 | DP: 0.0079s (±0.0004) | Myers: 0.0156s (±0.0007)
N=400, M=400, similarity=0.9 | DP: 0.0140s (±0.0007) | Myers: 0.0007s (±0.0002)
N=400, M=400, similarity=0.8 | DP: 0.0141s (±0.0004) | Myers: 0.0024s (±0.0005)
N=400, M=400, similarity=0.7 | DP: 0.0145s (±0.0008) | Myers: 0.0050s (±0.0007)
N=400, M=400, similarity=0.6 | DP: 0.0147s (±0.0006) | Myers: 0.0085s (±0.0012)
N=400, M=400, similarity=0.5 | DP: 0.0152s (±0.0011) | Myers: 0.0127s (±0.0015)
N=400, M=400, similarity=0.4 | DP: 0.0151s (±0.0007) | Myers: 0.0176s (±0.0016)
N=400, M=400, similarity=0.3 | DP: 0.0150s (±0.0008) | Myers: 0.0221s (±0.0018)
N=400, M=400, similarity=0.2 | DP: 0.0149s (±0.0006) | Myers: 0.0258s (±0.0014)
N=400, M=400, similarity=0.1 | DP: 0.0150s (±0.0012) | Myers: 0.0283s (±0.0010)
N=500, M=500, similarity=0.9 | DP: 0.0227s (±0.0009) | Myers: 0.0010s (±0.0002)
N=500, M=500, similarity=0.8 | DP: 0.0231s (±0.0008) | Myers: 0.0036s (±0.0007)
N=500, M=500, similarity=0.7 | DP: 0.0234s (±0.0007) | Myers: 0.0077s (±0.0011)
N=500, M=500, similarity=0.6 | DP: 0.0239s (±0.0007) | Myers: 0.0131s (±0.0016)
N=500, M=500, similarity=0.5 | DP: 0.0243s (±0.0009) | Myers: 0.0206s (±0.0020)
N=500, M=500, similarity=0.4 | DP: 0.0244s (±0.0012) | Myers: 0.0283s (±0.0021)
N=500, M=500, similarity=0.3 | DP: 0.0244s (±0.0010) | Myers: 0.0354s (±0.0024)
N=500, M=500, similarity=0.2 | DP: 0.0243s (±0.0010) | Myers: 0.0417s (±0.0027)
N=500, M=500, similarity=0.1 | DP: 0.0243s (±0.0007) | Myers: 0.0452s (±0.0020)
N=600, M=600, similarity=0.9 | DP: 0.0337s (±0.0015) | Myers: 0.0015s (±0.0003)
N=600, M=600, similarity=0.8 | DP: 0.0342s (±0.0015) | Myers: 0.0053s (±0.0010)
N=600, M=600, similarity=0.7 | DP: 0.0348s (±0.0014) | Myers: 0.0109s (±0.0015)
N=600, M=600, similarity=0.6 | DP: 0.0360s (±0.0017) | Myers: 0.0198s (±0.0020)
N=600, M=600, similarity=0.5 | DP: 0.0360s (±0.0010) | Myers: 0.0302s (±0.0028)
N=600, M=600, similarity=0.4 | DP: 0.0364s (±0.0020) | Myers: 0.0407s (±0.0034)
N=600, M=600, similarity=0.3 | DP: 0.0359s (±0.0012) | Myers: 0.0513s (±0.0031)
N=600, M=600, similarity=0.2 | DP: 0.0363s (±0.0016) | Myers: 0.0614s (±0.0040)
N=600, M=600, similarity=0.1 | DP: 0.0362s (±0.0014) | Myers: 0.0666s (±0.0033)

结果清楚地表明，当序列高度相似（高相似度比率）时，Myers 表现出色，可以利用许多”snake”移动。然而，随着文件差异增大，Myers 的性能下降，实际上可能比直接的 DP 方法更慢。这很符合直觉：当 $D$ 接近 $N + M$ 时，$D^2$ 因子占主导，抵消了 Myers 的优势。

关键要点： 对于典型的版本控制场景（文件渐进式变化），Myers 通常是更好的选择。对于比较完全不相关的文件，DP 可能更可预测。

提升 Diff 可读性

虽然两种算法都能在编辑距离方面产生最优结果，但它们并不总是生成最具人类可读性的 diff。考虑这两个等价的输出：

更可读：

for (int i = 0; i < n; i++) {
    process1(i);
}
+for (int i = 0; i < n; i++) {
+    process2(i);
+}

较不可读：

for (int i = 0; i < n; i++) {
    process1(i);
+}
+for (int i = 0; i < n; i++) {
+    process2(i);
}

类似地，考虑：

更可读（分组的变化）：

if (isSocketReady()) {
-    sendDataPart1();
-    sendDataPart2();
+    sendDataPartA();
+    sendDataPartB();
}

较不可读（交错的变化）：

if (isSocketReady()) {
-    sendDataPart1();
+    sendDataPartA();
-    sendDataPart2();
+    sendDataPartB();
}

两者达到相同的编辑距离，但第一个版本一眼就能理解得多。

这两种算法本质上都不会优化可读性，但我们可以应用后处理来改善输出。一个简单的方法是将连续的删除和添加操作分组，然后尝试移动块边界以创建更直观的变化模式。

下面是这种后处理的基本实现：

def optimize_diff_readability(path: list[tuple[str, str, int | None, int | None]]) -> list[tuple[str, str, int | None, int | None]]:
    """
    后处理 diff 输出以提高可读性，通过分组相关变化
    并最小化交错操作来实现。
    """
    # 这是一个简化的例子 - 像 git diff 这样的真实实现
    # 使用更复杂的启发式算法
    optimized = []
    i = 0
    
    while i < len(path):
        if path[i][0] == '-':
            # 收集连续的删除操作
            deletions = []
            while i < len(path) and path[i][0] == '-':
                deletions.append(path[i])
                i += 1
            
            # 检查紧随其后的添加操作
            additions = []
            while i < len(path) and path[i][0] == '+':
                additions.append(path[i])
                i += 1
            
            # 添加分组的变化
            optimized.extend(deletions)
            optimized.extend(additions)
        else:
            optimized.append(path[i])
            i += 1
    
    return optimized

这只是冰山一角——像 Git 这样的生产级 diff 工具采用了更复杂的算法来优化可读性，包括：

Patience diff：Myers 的替代方案，往往为代码产生更直观的结果
Histogram diff：patience diff 的变种，具有更好的性能特征
词级和字符级差异：用于行内更细粒度的比较
语义感知：理解代码结构以进行更有意义的比较

总结

看似简单的 git diff 命令实际上蕴含着数十年的算法研究和优化成果。虽然动态规划方法提供了具有可预测 $O(NM)$ 性能的坚实基础，但 Myers 算法为比较相似文件的常见情况提供了卓越的效率——这正是版本控制中遇到的场景。

算法的选择取决于你的具体用例：

使用 Myers 当文件可能相似时（版本控制、增量变化）
使用 DP 当你需要可预测的性能，无论文件相似度如何
考虑两者 并根据快速相似度估计动态选择

理解这些算法不仅揭开了我们最常用的开发工具之一的神秘面纱，还为更广泛的序列比较领域提供了洞察——其应用范围从生物信息学（DNA 序列比对）到抄袭检测等等。

下次你运行 git diff 时，你就会知道在这个看似简单的命令背后，隐藏着多么精妙的算法魔法！

告别 JavaScript : 现代 CSS 特性

mail@ch3nyang.top (Ch3nyang) — Mon, 03 Mar 2025 05:00:00 +0800

现代 CSS 引入了许多新特性和功能，提升了网页设计的灵活性和表现力。本文将介绍一些现代 CSS 的重要特性，包括容器查询、:has() 伪类、选择器嵌套、滚动驱动动画、CSS 锚点定位、作用域样式、级联层、颜色函数、文本优化等。

容器查询

传统的 @media 查询基于视口大小，而容器查询允许组件根据其父容器的大小自适应样式，实现真正的组件级响应式设计。

基础用法

.card-container {
  container-name: card;
  container-type: inline-size;
}

@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 1fr 2fr;
  }
}

容器类型

类型	说明
`size`	可查询容器的块级和内联尺寸
`inline-size`	仅可查询内联尺寸（推荐，性能更好）
`normal`	不是查询容器

查询条件

尺寸查询支持以下条件：

条件	说明
`width` / `height`	宽度 / 高度
`inline-size` / `block-size`	内联大小 / 块级大小
`aspect-ratio`	宽高比
`orientation`	方向（`landscape` / `portrait`）

样式查询（实验性）可以查询容器的 CSS 自定义属性：

@container style(--theme: dark) {
  .element {
    background: #1a1a1a;
    color: white;
  }
}

<div class="card-container">
  <div class="card">
    <div class="card-image">🖼️</div>
    <div class="card-content">
      <h3>响应式卡片</h3>
      <p>拖拽右下角调整容器大小，观察布局变化</p>
    </div>
  </div>
</div>

.card-container {
  container-name: card;
  container-type: inline-size;
  border: 2px dashed #999;
  padding: 20px;
  resize: horizontal;
  overflow: auto;
  min-width: 200px;
  max-width: 100%;
}

.card {
  background: white;
  border-radius: 8px;
  overflow: hidden;
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

.card-image {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  height: 150px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 3rem;
}

.card-content {
  padding: 20px;
}

.card-content h3 {
  margin: 0 0 10px 0;
  color: #333;
}

.card-content p {
  margin: 0;
  color: #666;
  font-size: 0.9rem;
}

/* 当容器宽度 >= 400px 时，切换为横向布局 */
@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 150px 1fr;
  }
  
  .card-image {
    height: auto;
  }
}

容器查询示例

`:has()` 关系伪类

:has() 被称为”父选择器”，可以根据元素的后代或兄弟元素来选择该元素。

/* 选择包含图片的卡片 */
.card:has(img) {
  padding: 0;
}

/* 选择没有子元素的段落 */
p:not(:has(*)) {
  text-indent: 2em;
}

/* 选择后面紧跟特定元素的元素 */
h2:has(+ p) {
  margin-bottom: 0.5em;
}

<div class="demo-container">
  <div class="card">
    <h3>普通卡片</h3>
    <p>这是一个没有特殊内容的卡片</p>
  </div>
  
  <div class="card">
    <h3>包含图标的卡片</h3>
    <span class="icon">⭐</span>
    <p>这个卡片包含星标图标</p>
  </div>
  
  <div class="card">
    <h3>包含按钮的卡片</h3>
    <p>这个卡片包含操作按钮</p>
    <button>点击</button>
  </div>
</div>

.demo-container {
  display: grid;
  gap: 20px;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
}

.card {
  background: #f5f5f5;
  padding: 20px;
  border-radius: 8px;
  border: 2px solid transparent;
  transition: all 0.3s;
}

.card h3 {
  margin: 0 0 10px 0;
  color: #333;
}

.card p {
  margin: 0;
  color: #666;
}

/* 包含图标的卡片显示金色边框 */
.card:has(.icon) {
  border-color: #ffd700;
  background: linear-gradient(135deg, #fff9e6 0%, #fff 100%);
}

/* 包含按钮的卡片显示蓝色边框 */
.card:has(button) {
  border-color: #4a90e2;
  background: linear-gradient(135deg, #e6f2ff 0%, #fff 100%);
}

.icon {
  font-size: 2rem;
  display: block;
  margin: 10px 0;
}

button {
  margin-top: 10px;
  padding: 8px 16px;
  background: #4a90e2;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

:has() 伪类示例

CSS 嵌套

CSS 原生支持选择器嵌套，无需预处理器即可编写更简洁的代码。

.parent {
  color: blue;
  
  /* 使用 & 引用父选择器 */
  &:hover {
    color: red;
  }
  
  /* 嵌套子选择器 */
  .child {
    font-size: 14px;
  }
  
  /* 复合选择器 */
  &.active {
    font-weight: bold;
  }
}

<nav class="menu">
  <ul>
    <li><a href="#" class="active">首页</a></li>
    <li><a href="#">关于</a></li>
    <li>
      <a href="#">服务</a>
      <ul class="submenu">
        <li><a href="#">设计</a></li>
        <li><a href="#">开发</a></li>
      </ul>
    </li>
  </ul>
</nav>

.menu {
  background: #2c3e50;
  padding: 10px;
  border-radius: 8px;
  
  ul {
    list-style: none;
    padding: 0;
    margin: 0;
    display: flex;
    gap: 5px;
    
    li {
      position: relative;
      
      a {
        display: block;
        padding: 10px 20px;
        color: white;
        text-decoration: none;
        border-radius: 4px;
        transition: background 0.3s;
        
        &:hover {
          background: rgba(255,255,255,0.1);
        }
        
        &.active {
          background: #3498db;
        }
      }
      
      &:hover .submenu {
        display: block;
      }
    }
  }
  
  .submenu {
    display: none;
    position: absolute;
    top: 100%;
    left: 0;
    background: #34495e;
    min-width: 150px;
    border-radius: 4px;
    margin-top: 5px;
    flex-direction: column;
    
    li {
      width: 100%;
    }
  }
}

CSS 嵌套示例

滚动驱动动画

基于滚动位置触发和控制动画，无需 JavaScript。

animation-timeline

使用 scroll() 或 view() 函数定义滚动时间线：

/* 基于滚动容器 */
.element {
  animation: fade-in linear;
  animation-timeline: scroll(root block);
}

/* 基于视口可见性 */
.element {
  animation: slide-in linear;
  animation-timeline: view();
  animation-range: entry 0% cover 30%;
}

animation-range

定义动画的触发范围：

entry：元素进入滚动容器时
exit：元素离开滚动容器时
contain：元素完全在滚动容器内时
cover：元素覆盖滚动容器时

<div class="scroll-container">
  <div class="scroll-spacer"></div>
  
  <div class="reveal-card" style="--delay: 0">
    <h3>卡片 1</h3>
    <p>向下滚动查看动画效果</p>
  </div>
  
  <div class="reveal-card" style="--delay: 0.1">
    <h3>卡片 2</h3>
    <p>每个卡片独立触发动画</p>
  </div>
  
  <div class="reveal-card" style="--delay: 0.2">
    <h3>卡片 3</h3>
    <p>基于视口位置自动播放</p>
  </div>
  
  <div class="scroll-spacer"></div>
</div>

.scroll-container {
  height: 400px;
  overflow-y: scroll;
  background: linear-gradient(to bottom, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
  padding: 40px 20px;
  border-radius: 8px;
}

.scroll-spacer {
  height: 200px;
}

.reveal-card {
  background: white;
  padding: 30px;
  margin: 30px 0;
  border-radius: 12px;
  box-shadow: 0 10px 40px rgba(0,0,0,0.3);
  
  animation: reveal-up linear both;
  animation-timeline: view();
  animation-range: entry 0% cover 30%;
}

.reveal-card h3 {
  margin: 0 0 10px 0;
  color: #2c3e50;
}

.reveal-card p {
  margin: 0;
  color: #7f8c8d;
}

@keyframes reveal-up {
  from {
    opacity: 0;
    transform: translateY(100px) scale(0.9);
    filter: blur(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
    filter: blur(0);
  }
}

滚动驱动动画示例

CSS 锚点定位

将元素精确定位到另一个元素的位置，无需 JavaScript。

/* 定义锚点 */
.button {
  anchor-name: --my-button;
}

/* 相对锚点定位 */
.tooltip {
  position: absolute;
  position-anchor: --my-button;
  bottom: anchor(top);
  left: anchor(center);
  translate: -50% 0;
}

<div class="anchor-demo">
  <button class="anchor-button">悬停显示提示</button>
  <div class="tooltip">这是一个提示框</div>
</div>

.anchor-demo {
  padding: 100px 20px;
  text-align: center;
  min-height: 200px;
  position: relative;
}

.anchor-button {
  anchor-name: --my-button;
  padding: 12px 24px;
  background: #3498db;
  color: white;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  font-size: 16px;
  transition: background 0.3s;
}

.anchor-button:hover {
  background: #2980b9;
}

.tooltip {
  position: absolute;
  position-anchor: --my-button;
  bottom: anchor(top);
  left: anchor(center);
  translate: -50% -10px;
  
  background: #2c3e50;
  color: white;
  padding: 8px 12px;
  border-radius: 4px;
  font-size: 14px;
  white-space: nowrap;
  
  opacity: 0;
  pointer-events: none;
  transition: opacity 0.3s;
}

.tooltip::after {
  content: '';
  position: absolute;
  top: 100%;
  left: 50%;
  translate: -50% 0;
  border: 6px solid transparent;
  border-top-color: #2c3e50;
}

.anchor-button:hover + .tooltip {
  opacity: 1;
}

锚点定位示例

@scope 作用域规则

限制 CSS 规则的作用范围，避免样式污染。

@scope (.component) to (.boundary) {
  h2 {
    color: blue;
  }
  
  p {
    font-size: 14px;
  }
}

<article class="scoped-article">
  <h2>文章标题（蓝色）</h2>
  <p>这段文字在作用域内，字号为 14px</p>
  
  <div class="scope-boundary">
    <h2>内部标题（不受影响）</h2>
    <p>这段文字在边界外，使用默认样式</p>
  </div>
</article>

<h2>外部标题（不受影响）</h2>

@scope (.scoped-article) to (.scope-boundary) {
  h2 {
    color: #3498db;
    font-size: 24px;
  }
  
  p {
    font-size: 14px;
    color: #555;
    line-height: 1.6;
  }
}

.scoped-article {
  background: #f8f9fa;
  padding: 20px;
  border-radius: 8px;
  margin-bottom: 20px;
}

.scope-boundary {
  background: white;
  padding: 15px;
  margin-top: 15px;
  border-left: 3px solid #e74c3c;
}

@scope 示例

@layer 级联层

控制样式的优先级顺序，更好地管理复杂样式。

@layer reset, base, components, utilities;

@layer reset {
  * { margin: 0; padding: 0; }
}

@layer base {
  body { font-family: sans-serif; }
}

@layer components {
  .button { padding: 10px 20px; }
}

<div class="layer-demo">
  <button class="btn">基础按钮</button>
  <button class="btn btn-primary">主要按钮</button>
  <button class="btn btn-utility">工具按钮</button>
</div>

@layer base, theme, utilities;

@layer base {
  .btn {
    padding: 10px 20px;
    border: none;
    border-radius: 4px;
    font-size: 14px;
    cursor: pointer;
    background: #ecf0f1;
    color: #2c3e50;
  }
}

@layer theme {
  .btn-primary {
    background: #3498db;
    color: white;
  }
}

@layer utilities {
  .btn-utility {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
    color: white !important;
    font-weight: bold;
  }
}

.layer-demo {
  display: flex;
  gap: 10px;
  padding: 20px;
}

@layer 示例

color-mix() 颜色混合

混合两种颜色生成新颜色。

.element {
  background: color-mix(in srgb, #ff0000 60%, #0000ff 40%);
}

<div class="color-demo">
  <div class="color-box" style="background: #e74c3c">
    <span>红色</span>
  </div>
  <div class="color-box" style="background: #3498db">
    <span>蓝色</span>
  </div>
  <div class="color-box" style="background: color-mix(in srgb, #e74c3c 50%, #3498db 50%)">
    <span>混合 50/50</span>
  </div>
  <div class="color-box" style="background: color-mix(in srgb, #e74c3c 70%, #3498db 30%)">
    <span>混合 70/30</span>
  </div>
</div>

.color-demo {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
  gap: 15px;
  padding: 20px;
}

.color-box {
  aspect-ratio: 1;
  display: flex;
  align-items: center;
  justify-content: center;
  border-radius: 8px;
  color: white;
  font-weight: bold;
  text-align: center;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

.color-box span {
  padding: 10px;
  background: rgba(0,0,0,0.2);
  border-radius: 4px;
}

color-mix() 示例

相对颜色语法

基于现有颜色创建变体。

.element {
  --base: #3498db;
  background: rgb(from var(--base) r g b / 0.5);
  border-color: hsl(from var(--base) h s calc(l - 10%));
}

<div class="relative-color-demo">
  <div class="color-item original">原始颜色</div>
  <div class="color-item lighter">更亮 20%</div>
  <div class="color-item darker">更暗 20%</div>
  <div class="color-item transparent">半透明</div>
</div>

.relative-color-demo {
  --base-color: #3498db;
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
  gap: 15px;
  padding: 20px;
}

.color-item {
  padding: 30px 20px;
  text-align: center;
  color: white;
  font-weight: bold;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

.original {
  background: var(--base-color);
}

.lighter {
  background: hsl(from var(--base-color) h s calc(l + 20%));
}

.darker {
  background: hsl(from var(--base-color) h s calc(l - 20%));
}

.transparent {
  background: rgb(from var(--base-color) r g b / 0.5);
}

相对颜色示例

text-wrap 文本换行

优化文本布局，避免孤行等问题。

值	说明
`wrap`	正常换行
`nowrap`	不换行
`balance`	平衡行长度
`pretty`	优化排版，避免孤字
`stable`	编辑时保持稳定

<div class="text-wrap-demo">
  <div class="text-box">
    <h4>normal（默认）</h4>
    <p style="text-wrap: wrap">
      这是一段很长的文本内容，用于演示不同的文本换行效果。注意观察最后一行的单词分布。
    </p>
  </div>
  
  <div class="text-box">
    <h4>balance（平衡）</h4>
    <p style="text-wrap: balance">
      这是一段很长的文本内容，用于演示不同的文本换行效果。注意观察最后一行的单词分布。
    </p>
  </div>
  
  <div class="text-box">
    <h4>pretty（美化）</h4>
    <p style="text-wrap: pretty">
      这是一段很长的文本内容，用于演示不同的文本换行效果。注意观察最后一行的单词分布。
    </p>
  </div>
</div>

.text-wrap-demo {
  display: grid;
  gap: 20px;
  padding: 20px;
}

.text-box {
  background: #f8f9fa;
  padding: 20px;
  border-radius: 8px;
  max-width: 400px;
}

.text-box h4 {
  margin: 0 0 10px 0;
  color: #2c3e50;
  font-size: 16px;
}

.text-box p {
  margin: 0;
  line-height: 1.6;
  color: #555;
}

text-wrap 示例

subgrid 子网格

子网格继承父网格的轨道定义。

.parent {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 20px;
}

.child {
  display: grid;
  grid-template-columns: subgrid;
  grid-column: span 3;
}

<div class="grid-parent">
  <div class="grid-header">
    <div>列 1</div>
    <div>列 2</div>
    <div>列 3</div>
  </div>
  <div class="grid-item">A1</div>
  <div class="grid-item">A2</div>
  <div class="grid-item">A3</div>
</div>

.grid-parent {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 10px;
  padding: 20px;
  background: #f8f9fa;
  border-radius: 8px;
}

.grid-header {
  grid-column: 1 / -1;
  display: grid;
  grid-template-columns: subgrid;
  background: #3498db;
  color: white;
  font-weight: bold;
  border-radius: 4px;
  overflow: hidden;
}

.grid-header > div {
  padding: 15px;
  text-align: center;
  border-right: 1px solid rgba(255,255,255,0.2);
}

.grid-header > div:last-child {
  border-right: none;
}

.grid-item {
  background: white;
  padding: 20px;
  text-align: center;
  border-radius: 4px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

subgrid 示例

field-sizing 字段大小

控制表单字段根据内容自动调整大小。

textarea {
  field-sizing: content;
  min-height: 3lh;
  max-height: 10lh;
}

<div class="form-demo">
  <label>自动调整高度的文本框：</label>
  <textarea 
    placeholder="输入内容会自动增长高度..."
    style="field-sizing: content"></textarea>
</div>

.form-demo {
  padding: 20px;
  max-width: 500px;
}

.form-demo label {
  display: block;
  margin-bottom: 10px;
  font-weight: bold;
  color: #2c3e50;
}

.form-demo textarea {
  width: 100%;
  padding: 12px;
  border: 2px solid #ddd;
  border-radius: 6px;
  font-size: 14px;
  font-family: inherit;
  resize: none;
  min-height: 60px;
  max-height: 200px;
  transition: border-color 0.3s;
}

.form-demo textarea:focus {
  outline: none;
  border-color: #3498db;
}

field-sizing 示例

消息队列——原理与对比

mail@ch3nyang.top (Ch3nyang) — Mon, 24 Feb 2025 00:00:00 +0800

消息队列是一种先进先出的数据结构，用于存储并在应用程序之间传递消息。

graph LR
    P1((P1)) --> Q(Broker) --> C1((C1))
    P2((P2)) --> Q --> C2((C2))
    P3((P3)) --> Q --> C3((C3))
    subgraph 生产者
        P1
        P2
        P3
    end
    subgraph 消费者
        C1
        C2
        C3
    end

他有这样几个重要功能：

异步处理：生产者和消费者可以异步进行处理，不会相互阻塞，提高了系统的并发性能
削峰填谷：消息队列可以缓冲突发的消息，使得系统在高峰期不会因为消息量过大而崩溃
解耦：消息队列可以将生产者和消费者解耦，使得系统更容易扩展和维护
可靠性：消息队列可以保证消息的可靠传递，即使消费者宕机，消息也不会丢失
延时处理：消息队列可以实现延时处理，比如定时任务
消息分发：消息队列可以实现消息的广播和单播

先了解其中的几个概念：

生产者：生产者是消息的发送方，将消息发送到消息队列中
消费者：消费者是消息的接收方，从消息队列中获取消息
队列：队列是消息的存储地点，生产者将消息发送到队列中，消费者从队列中获取消息，队列是一种先进先出的数据结构
主题/分区：主题是一种发布订阅模型，生产者将消息发送到主题中，消费者订阅主题，当有消息发送到主题时，所有订阅了这个主题的消费者都会收到这个消息。分区是 Kafka 中的概念，主题中存在多个分区，一个分区对应一个消费者，通常来讲分区和消费者数量相同
Broker：消息队列的服务端，负责接收生产者的消息，将消息发送给消费者。一个消息队列系统可能存在多个 Broker，每个 Broker 维护着不同的队列。需要注意的时，Broker 和主题/分区是交错的，每个 Broker 都可以包含所有的主题/分区，每个主题/分区也都可以存在于所有 Broker 中

消息模型

P2P 模型

graph LR
    P((P)) --> Q[[队列]] --> C((C))
    subgraph 生产者
        P
    end
    subgraph 消费者
        C
    end

点对点模型是一种一对一的消息模型，生产者将消息发送到队列中，消费者从队列中获取消息。消息被消费后会从队列中删除。

消费者也可能是多个，但是每个消息只能被一个消费者消费。一个消费者消费掉一个消息后，其他消费者就无法再消费这个消息。

发布订阅模型

graph LR
    P((P)) --> T[[队列]] --> C1((C1))
    T --> C2((C2))
    T --> C3((C3))
    subgraph 生产者
        P
    end
    subgraph 消费者
        C1
        C2
        C3
    end

发布订阅模型是一种一对多的消息模型，生产者将消息发送到主题中，消费者订阅主题，当有消息发送到主题时，所有订阅了这个主题的消费者都会收到这个消息。

如果只有一个消费者订阅了这个主题，那么这个模型就退化成了点对点模型。

RabbitMQ 模型

RabbitMQ 也使用了以上两种消息模型。点对点在 RabbitMQ 中叫做基本消息模型；发布订阅在 RabbitMQ 中叫做工作队列模型。

不过他还有一种额外的订阅模型。RabbitMQ 中的生产者将消息发送到交换机中，交换机将消息发送到各个消息队列中，消费者分别从各自的队列中获取消息。

graph LR
    P((P)) --> E[/交换机/] --> Q1[[队列1]]
    E --> Q2[[队列2]]
    E --> Q3[[队列3]]
    Q1 --> C1((C1))
    Q2 --> C2((C2))
    Q3 --> C3((C3))
    subgraph 生产者
        P
    end
    subgraph 消费者
        C1
        C2
        C3
    end

这种模型又分为三种：

Fanout

Fanout 使用的就是上面的流程。当交换机接收到一条消息时，会以广播的方式将消息发送到所有队列中。

Direct

Direct 模型是一种点对点模型。在生产者生成消息时，需要指定一个 routing key，交换机会根据这个 routing key 将消息发送到对应的队列中。

graph LR
    P((P)) --> E[/交换机/] --"error"--> Q1[[队列1]]
    E --"info"--> Q2[[队列2]]
    E --"warning"--> Q2
    E --"error"--> Q2
    Q1 --> C1((C1))
    Q2 --> C2((C2))
    subgraph 生产者
        P
    end
    subgraph 消费者
        C1
        C2
    end

Topic

Topic 模型是一种发布订阅模型。在生产者生成消息时，同样需要指定一个 routing key，不过这个 routing key 是一个通配符。

它一般由多个单词构成，单词间以 . 分隔。* 表示匹配一个单词，# 表示匹配一个或多个单词。例如：

*.error 匹配 net.error，不匹配 db.error，但不匹配 net.connect.error
#.error 匹配 net.error，db.error，net.connect.error
# 匹配所有消息

graph LR
    P((P)) --> E[/交换机/] --"*.error"--> Q1[[队列1]]
    E --"\#.error"--> Q2[[队列2]]
    E --"\*"--> Q2
    E --"\#"--> Q3[[队列3]]
    Q1 --> C1((C1))
    Q2 --> C2((C2))
    Q3 --> C3((C3))
    subgraph 生产者
        P
    end
    subgraph 消费者
        C1
        C2
        C3
    end

当然，RabbitMQ 还支持 RPC 模型，不过这不属于消息队列的范畴。

RocketMQ 模型

RocketMQ 使用了发布订阅模型。不过，它将队列换成了主题，主题中存在多个队列。

一个队列对应一个消费者，通常来讲队列和消费者数量相同。当然，一个队列只能被一个消费者消费，但是一个消费者可以消费多个队列。

消费者会在队列上维护一个偏移量，用于记录自己消费到了哪里。当消费者成功消费完一个消息后，会更新偏移量。这个偏移量存在的目的是为了支持多个消费者组。

使用多个队列的主要目的是为了提高并发性能。

graph LR
    P1((P1)) --> Q1[[队列1]]
    P1 --> Q2[[队列2]]
    P2((P2)) --> Q2
    P2 --> Q1
    Q1 --> C1((C1))
    Q2 --> C2((C2))
    subgraph 生产者
        P1
        P2
    end
    subgraph 主题
        Q1
        Q2
    end
    subgraph 消费者
        C1
        C2
    end

Kafka 模型

Kafka 和 RocketMQ 几乎一模一样，只是将队列换成了分区。

graph LR
    P1((P1)) --> Q1[[分区1]]
    P1 --> Q2[[分区2]]
    P2((P2)) --> Q2
    P2 --> Q1
    Q1 --> C1((C1))
    Q2 --> C2((C2))
    subgraph 生产者
        P1
        P2
    end
    subgraph 主题
        Q1
        Q2
    end
    subgraph 消费者
        C1
        C2
    end

Spring Boot 使用

RabbitMQ

点击展开

RabbitMQ 的 Spring Boot 使用非常简单，只需要在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.amqp</groupId>
    <artifactId>spring-rabbit-test</artifactId>
    <scope>test</scope>
</dependency>

使用 Docker-Compose 启动 RabbitMQ：

version: '3'
services:
  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "5672:5672"
      - "15672:15672"

执行以下命令启动：

docker-compose up -d

然后在 application.yml 中配置 RabbitMQ 的连接信息：

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest

使用时，首先需要声明队列和交换机：

@Configuration
public class RabbitMQConfig {

    // 直连交换机示例
    public static final String DIRECT_EXCHANGE = "my.direct.exchange";
    public static final String QUEUE_NAME = "my.queue";
    public static final String ROUTING_KEY = "my.routing.key";

    @Bean
    Queue queue() {
        return new Queue(QUEUE_NAME, true);
    }

    @Bean
    DirectExchange directExchange() {
        return new DirectExchange(DIRECT_EXCHANGE);
    }

    @Bean
    Binding binding(Queue queue, DirectExchange exchange) {
        return BindingBuilder.bind(queue).to(exchange).with(ROUTING_KEY);
    }
}

生产者：

@Service
public class RabbitMQProducerService {
    private static final Logger logger = LoggerFactory.getLogger(RabbitMQProducerService.class);

    @Autowired
    private RabbitTemplate rabbitTemplate;

    public void sendMessage(String message) {
        rabbitTemplate.convertAndSend(
          RabbitMQConfig.DIRECT_EXCHANGE,
          RabbitMQConfig.ROUTING_KEY,
          message);
        logger.info("Sent {}", message);
    }
}

消费者：

@Service
public class RabbitMQConsumerService {
    private static final Logger logger = LoggerFactory.getLogger(RabbitMQConsumerService.class);

    private List<String> receivedMessages = new ArrayList<>();

    public List<String> getReceivedMessages() {
        return receivedMessages;
    }

    @RabbitListener(queues = RabbitMQConfig.QUEUE_NAME)
    public void listen(String message) {
        logger.info("Received {}", message);
        receivedMessages.add(message);
    }
}

测试程序：

@SpringBootTest
class RabbitMQApplicationTests {
    @Autowired
    private RabbitMQProducerService producer;
    
    @Autowired
    private RabbitMQConsumerService consumer;

    @Test
    void testSendAndReceive() {
        producer.sendMessage("Hello, RabbitMQ!");
        
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        assertThat(consumer.getReceivedMessages()).contains("Hello, RabbitMQ!");
    }
}

RocketMQ

点击展开

RocketMQ 的 Spring Boot 使用非常简单，只需要在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

使用 Docker-Compose 启动 RocketMQ：

version: '3'
services:
  namesrv:
    image: apache/rocketmq:latest
    ports:
      - "9876:9876"
    environment:
      - "JAVA_OPTS=-Duser.home=/opt"
    command: sh mqnamesrv
  broker:
    image: apache/rocketmq:latest
    ports:
      - "10911:10911"
      - "10909:10909"
    environment:
      - "JAVA_OPTS=-Duser.home=/opt"
    command: sh mqbroker -n namesrv:9876

执行以下命令启动：

docker-compose up -d

然后在 application.yml 中配置 RocketMQ 的连接信息：

rocketmq:
  name-server: localhost:9876
  producer:
    group: my-group
    send-message-timeout: 3000
    retryTimesWhenSendFailed: 2
    retryTimesWhenSendAsyncFailed: 2
    maxMessageSize: 4096
    compressMessageBodyThreshold: 4096
    retryNextServer: false
  consumer:
    group: my-group

生产者：

@Service
public class RocketMQProducerService {
    private static final Logger logger = LoggerFactory.getLogger(RocketMQProducerService.class);

    @Autowired
    private RocketMQTemplate rocketMQTemplate;

    public void sendMessage(String topic, String message) {
        rocketMQTemplate.convertAndSend(topic, message);
        logger.info("Sent {}", message);
    }
}

消费者：

@Service
public class RocketMQConsumerService {
    private static final Logger logger = LoggerFactory.getLogger(RocketMQConsumerService.class);

    private List<String> receivedMessages = new ArrayList<>();

    public List<String> getReceivedMessages() {
        return receivedMessages;
    }

    @RocketMQMessageListener(topic = "my-topic", consumerGroup = "my-group")
    public void onMessage(String message) {
        logger.info("Received {}", message);
        receivedMessages.add(message);
    }
}

测试程序：

@SpringBootTest
class RocketMQApplicationTests {
    @Autowired
    private RocketMQProducerService producer;
    
    @Autowired
    private RocketMQConsumerService consumer;

    @Test
    void testSendAndReceive() {
        producer.sendMessage("my-topic", "Hello, RocketMQ!");
        
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        assertThat(consumer.getReceivedMessages()).contains("Hello, RocketMQ!");
    }
}

Kafka

点击展开

Kafka 的 Spring Boot 使用非常简单，只需要在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

使用 Docker-Compose 启动 Kafka：

version: '3'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    ports:
      - "2181:2181"
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
  kafka:
    image: confluentinc/cp-kafka:latest
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "false"
    depends_on: [zookeeper]

执行以下命令启动：

docker-compose up -d

然后在 application.yml 中配置 Kafka 的连接信息：

spring:
  kafka:
    bootstrap-servers: localhost:9092
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.apache.kafka.common.serialization.StringSerializer
      acks: all
      retries: 3
    consumer:
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      group-id: my-group
      auto-offset-reset: earliest
      enable-auto-commit: false

生产者：

@Service
public class KafkaProducerService {
    private static final Logger logger = LoggerFactory.getLogger(KafkaProducerService.class);

    @Autowired
    private KafkaTemplate<String, String> kafkaTemplate;

    public void sendMessage(String topic, String message) {
        kafkaTemplate.send(topic, message)
            .addCallback(result -> {
                if (result != null) {
                    logger.info(
                        "Sent {} to {}@{}",
                        result.getProducerRecord().value(),
                        result.getRecordMetadata().topic(),
                        result.getRecordMetadata().offset());
                }
            },
            ex -> {
                logger.error("Failed to send: {}", ex.getMessage());
            });
    }
}

消费者：

@Service
public class KafkaConsumerService {
    private static final Logger logger = LoggerFactory.getLogger(KafkaConsumerService.class);

    private List<String> receivedMessages = new ArrayList<>();

    public List<String> getReceivedMessages() {
        return receivedMessages;
    }

    @KafkaListener(topics = "my-topic", groupId = "my-group")
    public void listen(@Payload String message) {
        logger.info("Received {}", message);
        receivedMessages.add(message);
    }
}

测试程序：

@SpringBootTest
@EmbeddedKafka(partitions = 1)
class KafkaApplicationTests {
    @Autowired
    private KafkaProducerService producer;
    
    @Autowired
    private KafkaConsumerService consumer;

    @Test
    void testSendAndReceive() {
        producer.sendMessage("my-topic", "Hello, Kafka!");
        
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        assertThat(consumer.getReceivedMessages()).contains("Hello, Kafka!");
    }
}

底层数据结构

磁盘读写

页缓存

磁盘使用页缓存来减少磁盘 IO：

写入的时候会先写入页缓存，然后将该页标记为脏页
读取的时候会先查找页缓存，如果没有则从磁盘中将数据读入页缓存，然后返回数据

如果要将页缓存持久化到磁盘，那么需要使用 fsync 系统调用。fsync 会将所有的脏页写入磁盘。

不过，如果是顺序写入磁盘，要比随机读写快得多。因此，通过文件追加的方式，可以提高磁盘 IO 的性能。

内存映射文件

mmap 是一种内存映射文件的方式。它将文件映射到内存中，然后通过内存来读写文件。

页缓存是在内核空间中的，而用户空间无法直接访问页缓存。mmap 可以将页缓存映射到用户空间，这样就可以直接访问页缓存了。

用户此时可以使用指针来直接读写页缓存，而不需要调用 read 和 write 系统调用来读写文件。

flowchart LR
    subgraph 物理设备
        A@{ shape: lin-cyl, label: "磁盘" }
    end
    subgraph 内核空间
        B@{ shape: procs, label: "页缓存"}
    end
    subgraph 用户空间
        C[缓冲区]
    end
    A --> B
    B -.-> C

零拷贝

如果用户需要将磁盘上的一块数据通过网络发送出去，那么就需要将数据从磁盘读入页缓存，然后从页缓存拷贝到用户空间的缓冲区，再从缓冲区拷贝到内核空间的 socket 缓冲区，最后写入网卡发送出去。

这样做不但拷贝了多次数据，还执行了多次上下文切换，性能很差。

一种想法是利用前文的 mmap，将页缓存映射到用户空间，然后直接将数据从页缓存拷贝到 socket 缓冲区，这样就避免了一次拷贝。

flowchart LR
    subgraph 物理设备
        A@{ shape: lin-cyl, label: "磁盘" }
        E[网卡]
    end
    subgraph 内核空间
        B@{ shape: procs, label: "页缓存"}
        D[socket 缓冲区]
    end
    subgraph 用户空间
        C[缓冲区]
    end
    A --> B
    B -.-> C
    B --> D
    D --> E

但这样依然会从页缓存拷贝到 socket 缓冲区，还是会有一次拷贝。

更好的方式是使用 sendfile 系统调用。sendfile 通过 DMA 控制器将数据从磁盘读入页缓存，socket 缓冲区只会保存文件描述符和偏移量，不会保存数据。网卡根据 socket 缓冲区中的文件描述符和偏移量直接从页缓存中读取数据发送出去。

flowchart LR
    subgraph 物理设备
        A@{ shape: lin-cyl, label: "磁盘" }
        E[网卡]
    end
    subgraph 内核空间
        B@{ shape: procs, label: "页缓存"}
        D[socket 缓冲区]
    end
    subgraph 用户空间
        C[缓冲区]
    end
    A --> B
    B -.-> C
    B --"fd&offset"--> D
    D -.-> E
    B --> E

RabbitMQ

RabbitMQ 使用了顺序追加的方式。

它的每个队列对应 msg_store_persistent 和 msg_store_transient 两个文件，分别用于持久化和非持久化消息。消息按照顺序追加到文件中，然后通过索引文件进行查找。

它还会维护一个仲裁日志，用于记录消息的状态。当消息被消费后，会将消息的状态从 unacked 改为 acked。

由于 RebbitMQ 中的消息会在被处理完后进行确认，因此会产生大量的随机读写。为了提高性能，RabbitMQ 使用了 B+ 树索引，查找消息。

RocketMQ

RocketMQ 使用了主题混合追加模式。

它拥有多个队列，但只有一个 CommitLog：

消费者订阅的队列只是一个消息的索引文件 ConsumerQueue，队列中的每一个元素包含了消息的物理偏移量、消息大小、Tag 等信息
生产者发送消息时，消息会先顺序追加到 CommitLog 中，然后将其索引写入 ConsumerQueue 中
消费者从 ConsumerQueue 中获取真实消息的物理地址，然后从 CommitLog 中读取消息

在消费者读取 CommitLog 时，理论上是随机的。但由于消息是顺序追加的，所以从整体上来看，还是大体有序的。

RocketMQ 中的 CommitLog 和 ConsumerQueue 都使用了 mmap，不过没有使用零拷贝。

针对页缓存合适刷盘的问题，RocketMQ 使用了文件预分配和文件预热的方式：

文件预分配：CommitLog 的默认大小为 1G，当文件大小超过 1G 时，会再次分配 1G 的空间。RocketMQ 使用了一个后台线程，提前分配好文件空间，避免了切换文件时产生抖动
文件预热：RocketMQ 一方面会将部分地址空间锁定在内存中，防止 SWAP；另一方面会将可能要读取的文件提前载入页缓存

RocketMQ 的优势在于：

读写分离：CommitLog 处理写入，ConsumerQueue 处理读取，提高了并发性能
逻辑队列轻量化：队列中只存储了消息的索引，减少了内存占用

Kafka

Kafka 使用了分区追加模式。

它的每个分区对应一个物理目录，目录格式为 <topic>-<partition>。每个分区中有多个顺序追加写入的日志文件，日志文件的格式为 <segment base offset>.log。

日志文件中包含了偏移量、时间戳、键值和负载数据。

Kafka 为了加速查找，使用了索引文件。索引文件包含两个：

.index 是稀疏索引，记录偏移量到物理位置的映射。

在查找时，Kafka 会二分查找这个索引，定位目标偏移量所在的大致位置，然后结合 mmap 找到物理位置
.timeindex 是时间索引，用于时间范围查找

Kafka 的日志文件没有使用 mmap，但分区文件使用了。同时，Kafka 在发消息时使用了零拷贝。

它的优势在于

高性能：Kafka 使用了零拷贝，提高了性能
分区扩展性：Kafka 的分区可以水平扩展，提高了并发性能

然而，这也造成了 Kafka 的缺点：

仅分区有序，而不是全局有序

如果要保证整个主题的有序，可以：

一个主题中只有一个分区
发送消息时指定分区 ID

推拉模式

消息队列的消费者有两种模式：推模式和拉模式。

推模式

推模式是指 Broker 主动将消息推送给消费者，消费者只需要注册一个监听器，当有消息到达时，Broker 会主动通知消费者。

它的优点是：

实时性高：消息到达后，消费者可以立即处理
使用方便：消费者只需要注册一个监听器，等着就完事了

不过，推模式也有一些缺点，最主要的便是无法控制消费速度：消费者可能处理消息的速度比生产者发送消息的速度慢，这样就会导致消息堆积。

拉模式

拉模式是指消费者主动向 Broker 请求消息。

它的优点是：

控制消费速度：消费者可以根据自己的处理能力来控制消费速度
Broker 实现简单：Broker 只需要存储消息并响应请求即可
可以批量发送：消费者可以一次性请求多条消息

不过，拉模式也有一些缺点：

消息延迟：消费者需要定时请求消息，可能会导致消息延迟
消息忙请求：消息隔了很久才被生产者发送的情况下，消费者可能会频繁请求消息

RocketMQ 和 Kafka 都使用的拉模式；只有 RabbitMQ 使用的是推模式。

RabbitMQ

RabbitMQ 使用的是推模式。

它的推模式基于 AMQP 协议：

首先在 Broker 和消费者之间建立 TCP 长连接
消费者首先使用 basic.consume 命令订阅一个队列，注册为队列的消费者
生产者发送消息到 Broker 后，Broker 立即将消息发送到对应的队列中
消费者收到消息后，会立即处理消息
消费者处理完消息后，发送 basic.ack 命令告诉 Broker 消息已经处理完毕
Broker 收到 basic.ack 命令后，将消息从队列中删除

sequenceDiagram
    participant P as 生产者
    participant Q as Broker
    participant C as 消费者
    C-->>Q: 订阅队列
    P->>Q: 发送消息
    Q->>C: 推送消息
    C->>C: 处理消息
    C->>Q: 确认消息
    Q->>Q: 删除消息

RabbitMQ 也不是完全不能拉模式。消费者可以使用 basic.get 命令主动拉取消息。不过，这种方式性能不高，不推荐使用。

RocketMQ

RocketMQ 使用的是拉模式，但其长轮询可以模拟推模式。

RocketMQ 的拉模式基于长轮询：

消费者拉取请求未命中时，Broker 会将请求挂起 15 秒。如果期间有消息到达，那么 Broker 会立即返回消息
使用基于 Netty 的 TCP 长连接
消费者维护一个偏移量，用于记录自己消费到了哪里，定期向 Broker 发送心跳包，更新偏移量

其具体流程是这样的：

生产者将消息发送到 Broker 上的主题中
Broker 将消息写入 CommitLog 中，然后分发到对应的队列中
消费者向 Broker 发送拉取消息的请求，携带主题、队列 ID 和偏移量
Broker 收到请求后
- 如果有消息立即返回，并带有最新的偏移量
- 如果没有消息则挂起
消费者处理完成后，异步提交偏移量

sequenceDiagram
    participant P as 生产者
    participant Q as Broker
    participant C as 消费者
    P->>Q: 发送消息
    Q->>Q: 写入 CommitLog<br>并分发到队列
    C->>Q: 拉取消息
    Q-->>Q: 没有消息则挂起
    Q->>C: 有消息则返回消息
    C->>C: 处理消息
    C->>Q: 提交新的偏移量

你会看到，RocketMQ 的长轮询通过挂起请求来模拟推模式，提高了消息的实时性。

Kafka

Kafka 使用的是拉模式。

Kafka 的拉模式同样基于长轮询：

消费者拉取请求未命中时，Broker 会将请求挂起 5 分钟。如果期间有消息到达，那么 Broker 会立即返回消息
使用 TCP 长连接
消费者自己维护一个偏移量，用于记录自己消费到了哪里

其具体流程是这样的：

生产者将消息发送到 Broker 上的某个主题
Broker 将消息写入日志文件中，然后分发到对应的分区中
消费者向 Broker 发送拉取消息的请求，携带主题、分区 ID 和偏移量
Broker 收到请求后
- 如果有消息立即返回对应分区的消息批次
- 如果没有消息则挂起
消费者处理完成后，异步提交偏移量

可以看到，Kafka 的拉模式和 RocketMQ 的拉模式非常相似。较大的区别在于，Kafka 的消费者可以自己维护偏移量。

消息丢失

消息丢失是指消息在传输过程中丢失，导致消费者无法收到消息。

生产者消息丢失

生产者消息丢失是指生产者发送消息后，Broker 没有收到消息，导致消费者无法收到消息。

RabbitMQ

RabbitMQ 有两种方式解决生产者消息丢失：

事务：生产者发送消息后，会阻塞并等待 Broker 的确认消息。如果没有收到确认消息，则会重发消息

确认：生产者发送消息后，会立即返回，并不会等待 Broker 的确认消息。生产者会在后台线程中等待 Broker 的确认消息，如果没有收到确认消息，则会重发消息

// 启用Publisher Confirms
channel.confirmSelect();

// 异步确认回调
channel.addConfirmListener((sequenceNumber, multiple) -> {
    // 消息成功到达Broker
}, (sequenceNumber, multiple) -> {
    // 消息发送失败（需重试或记录日志）
});

// 发送消息（需持久化）
AMQP.BasicProperties props = new AMQP.BasicProperties.Builder()
    .deliveryMode(2) // 持久化消息
    .build();
channel.basicPublish("exchange", "routingKey", props, message.getBytes());

RocketMQ

RocketMQ 使用同步发送消息的方式来解决生产者消息丢失，并且内置了重试机制，默认重试 2 次。

DefaultMQProducer producer = new DefaultMQProducer("group_name");
producer.setRetryTimesWhenSendFailed(3); // 同步发送重试次数
producer.send(msg, new SendCallback() {
    @Override
    public void onSuccess(SendResult sendResult) {
        // 发送成功
    }
    @Override
    public void onException(Throwable e) {
        // 发送失败（需人工干预）
    }
});

Kafka

生产者发送消息时，可以设置 acks 参数来控制消息的可靠性：
- acks=0：生产者发送消息后，不需要等待 Broker 的确认。这样做的好处是性能高，但消息可能会丢失
- acks=1：生产者发送消息后，等待 Leader 写入后确认。但如果 Leader 写入后宕机且副本没有同步，那么消息会丢失
- acks=all：生产者发送消息后，等待所有副本写入后确认。这样做的好处是性能低，但消息不会丢失
acks=1 和 acks=all 的区别在于，acks=1 只需要 Leader 写入后确认，而 acks=all 需要所有副本写入后确认

同时，设置 retries 参数来控制消息的重试次数。可以设置为 3

同时，配合 delivery.timeout.ms 来控制消息的超时时间。默认值为 120000，即 2 分钟
```
Properties props = new Properties();
props.put("acks", "all"); // 最强确认机制
props.put("retries", 3); // 重试次数
props.put("max.in.flight.requests.per.connection", 1); // 防止乱序

ProducerRecord<String, String> record =
    new ProducerRecord<>("topic", key, value);
producer.send(record, (metadata, exception) -> {
    if (exception != null) {
        // 记录失败消息（需人工处理）
    }
});
```

同步发送：

ProducerRecord<String, String> record = new ProducerRecord<>("topic", "key", "value");
try {
    RecordMetadata metadata = producer.send(record).get();
} catch (ExecutionException e) {
    e.printStackTrace();
}

这样，使用 get() 方法来获取发送结果，它会阻塞直到收到 Broker 的确认

Broker 消息丢失

Broker 消息丢失是指 Broker 收到消息后宕机，导致消费者无法收到消息。

RabbitMQ

RabbitMQ 使用了持久化的方式来解决 Broker 消息丢失：

// 持久化队列
boolean durable = true;
channel.queueDeclare("queue_name", durable, false, false, null);

他还可以设置镜像队列。镜像队列是指将队列的所有消息都复制到其他节点上，这样即使一个节点宕机，其他节点也可以继续提供服务。

RocketMQ

RocketMQ 支持主从复制：

主节点负责写入消息，从节点负责读取消息
主节点将消息写入 CommitLog 中，然后异步复制到从节点
从节点收到消息后，将消息写入 ConsumerQueue 中
主节点宕机后，从节点会自动选举出新的主节点，继续提供服务

面对主节点宕机后数据丢失的问题，RocketMQ 提供了以下几个参数来进行配置：

同步刷盘
- flushDiskType：设置刷盘方式。可以设置为 ASYNC_FLUSH（异步刷盘）和 SYNC_FLUSH（同步刷盘）。默认值为 ASYNC_FLUSH
- syncFlushTimeout：设置同步刷盘的超时时间。默认值为 5000，即 5 秒
主从复制
- brokerRole：设置 Broker 进行主从复制的方式。可以设置为 SYNC_FLUSH（主从同步刷盘）和 ASYNC_FLUSH（主从异步刷盘）。默认值为 ASYNC_FLUSH

消费者消息丢失

消费者消息丢失是指消费者收到消息后，未能处理成功，导致消息丢失。

RabbitMQ

RabbitMQ 使用了消息确认的方式来解决消费者消息丢失：

消费者收到消息后，会立即处理消息
消费者处理完消息后，发送 basic.ack 命令告诉 Broker 消息已经处理完毕
Broker 收到 basic.ack 命令后，将消息从队列中删除
如果消费者处理消息失败，则发送 basic.nack 命令告诉 Broker 消息未处理成功
Broker 收到 basic.nack 命令后，将消息重新放入队列中
如果消费者在处理消息时宕机，则 Broker 会在 x-message-ttl 设置的时间后，将消息重新放入队列中

RocketMQ

RocketMQ 使用了消费状态返回的方式来解决消费者消息丢失：

消费者收到消息后，会立即处理消息
消费者处理完消息后，返回 ConsumeConcurrentlyStatus.CONSUME_SUCCESS 告诉 Broker 消息已经处理完毕
如果消费者处理消息失败，则返回 ConsumeConcurrentlyStatus.RECONSUME_LATER

他还支持自动重试：

maxReconsumeTimes：设置最大重试次数。默认值为 16
retryInterval：设置重试间隔。默认值为 1000，即 1 秒

当重试次数超过最大重试次数后，消息会被放入死信队列中

Kafka

Kafka 使用了提交偏移量的方式来解决消费者消息丢失：

消费者收到消息后，会立即处理消息
消费者处理完消息后，提交偏移量
如果消费者处理消息失败，则不提交偏移量
如果消费者在处理消息时宕机，则 Broker 会在 auto.offset.reset 设置的时间后，将消息重新放入队列中

这需要我们将 enable.auto.commit 设置为 false，然后手动提交偏移量。

Kafka

在 Kafka 2.8 之前，Kafka 的分布式是通过 Zookeeper 来实现的。Zookeeper 主要完成了以下工作：

Broker 注册：Zookeeper 上有一个节点专门用来记录 Broker 列表，每个 Broker 启动时都会在这个节点下注册自己
Topic 创建：Kafka 中，每个主题都会被分成多个分区，而每个分区可能分布在不同的 Broker 上。Zookeeper 会记录主题包含的分区、以及分区和 Broker 的映射关系
负载均衡：Zookeeper 可以根据分区数量和消费者的情况来对分区进行负载均衡，将分区均衡分配给 Broker

当然，目前 Kafka 以及使用上了 KRaft 协议，不再依赖 Zookeeper。

面对 Leader 宕机后数据丢失的问题，Kafka 提供了以下几个参数来进行配置：

多副本
- unclean.leader.election.enable：如果为 false，那么当 Leader 宕机时，只会选择出同步达到标准的副本作为 Leader
- replication.factor：设置副本的数量。通常设置为 $\geq 3$ 来形成冗余
- min.insync.replicas：设置最小同步副本数。例如，如果设置为 $\geq 2$，则 Leader 写入后，至少有两个副本写入后才会确认
通常来讲，推荐设置为 replication.factor = min.insync.replicas + 1
持久化
- log.flush.interval.ms：日志刷盘的时间间隔，默认值为 30000，即 30 秒
- log.flush.interval.messages：日志刷盘的消息数量。如果调整为 1，则每写入一条消息就会刷盘。这样做的好处是消息不会丢失，但性能低

重复消费

重复消费是指消费者处理消息成功，但由于网络原因，Broker 没有收到确认消息，导致消费者重复收到消息。

RabbitMQ

RabbitMQ 使用了 message-id 和本地去重的方式来解决重复消费。它的每条消息可以设置一个 message-id。

发送时，生产者可以设置一个 message-id，用于标识消息的唯一性
消费时，消费者可以使用 message-id 来判断消息是否已经处理过

RocketMQ

RocketMQ 同样使用了 message-id 和本地去重的方式来解决重复消费。

Kafka

Kafka 一方面启用生产者幂等：

Properties props = new Properties();
props.put("enable.idempotence", "true");

另一方面，消费者先提交偏移量，再处理消息。不过，这样可能导致消息丢失。

分布式事务

分布式事务概述

分布式事务是指事务的参与者分布在不同的节点上，这些节点之间通过网络进行通信。分布式事务的目标是保证事务的 ACID 特性。

原子性：事务要么全部成功，要么全部失败
一致性：事务执行前后，数据的一致性不变
隔离性：事务之间互不干扰
持久性：事务一旦提交，数据就会持久化

对于分布式系统来讲，最终往往只会达到最终一致性。最终一致性是指，系统的所有节点在一段时间内达到一致状态。

分布式事务的实现主要有三种方式：

2PC

两阶段提交是一种同步的分布式事务协议。它分为两个阶段：
- 准备阶段：协调者询问各个参与者是否可以提交事务
- 提交阶段：协调者根据参与者的回复决定是否提交事务
2PC 存在几个问题：
- 阻塞：在准备阶段，协调者和所有参与者都会阻塞等待
- 单点故障：协调者是一个单点，一旦宕机，整个事务就会失败
TCC

TCC 是一种异步的分布式事务协议。它分为三个阶段：
- Try 阶段：尝试执行业务逻辑
- Confirm 阶段：如果 Try 阶段都能成功，执行实际的业务逻辑
- Cancel 阶段：如果 Try 阶段有一个失败，执行回滚操作
TCC 适用于高并发场景，但是需要业务代码支持。同时，Confirm 和 Cancel 阶段需要保证幂等性，否则会导致数据不一致。
事务消息

事务消息是一种异步的分布式事务协议。它主要做的是让两个事务要么同时成功，要么同时失败。

具体来讲，消息队列可以用于解决分布式事务的两个问题：

数据一致性：消息队列可以保证消息的可靠传递，即使消费者宕机，消息也不会丢失
服务调用：消息队列可以实现服务之间的异步调用，提高了系统的并发性能

RabbitMQ 事务消息

RebbitMQ 的事务使用基于传统 AMQP 事务，原生并不支持事务消息。不过，可以通过 confirm 和 return 机制来勉强实现事务消息。

confirm 机制是指生产者发送消息后，消息队列会返回一个确认消息。如果生产者没有收到确认消息，那么就会重发消息。
return 机制是指生产者发送消息后，如果消息队列没有收到消息，那么消息队列会将消息返回给生产者。

它的流程是这样的：

生产者发送消息后，消息队列会返回一个确认消息。确认消息包含是否收到以及收到了几条。如果生产者没有收到确认消息，那么就会重发消息
消费者消费后，该消息被标记为已消费，但并不会立即删除
消费者处理完事务后，发送确认消息给 Broker
Broker 收到确认消息后，将消息删除

sequenceDiagram
    participant A as 事务主动方
    participant MQ as Broker
    participant B as 事务被动方
    A->>A: 操作业务数据
    A->>A: 定时器查找<br>未成功处理的消息
    A->>MQ: 发送消息
    MQ->>B: 接收消息
    B->>B: 操作业务数据
    B->>MQ: 回复执行结果
    MQ->>A: 接收回复
    A->>A: 根据回复结果<br>决定提交事务<br>或者回滚事务

这里有两个要点:

消息幂等性：服务器发出的一条消息，只能被处理一次
失败重试：使用定时器将之前未成功处理的消息重新发送

这一机制依赖业务代码实现其中的一些功能，例如消息重发等，效率不高，适合低吞吐事务场景。

RocketMQ 事务消息

RocketMQ 提供了原生的事务消息的机制。它从底层上来讲还是使用了两阶段提交的方式，确保消息的可靠传递，保障了较高的一致性，适用于电商、金融等场景。

它的主要流程是这样的：

生产者将消息内容、主题、队列 ID 等组装起来作为 Half 消息到 Broker 中，Broker 取出其中的主题、队列 ID 等作为消息属性，然后将其放入 RMQ_SYS_TRANS_HALF_TOPIC 主题的 0 号队列中。这个队列是一个特殊的队列，对于消费者来讲是不可见的
生产者在成功发送完消息后，执行本地事务。根据本地事务的执行结果，生产者向 Broker 发送 Commit 或者 Rollback 消息。该消息为单向消息，不会等待 Broker 的回复
Broker 收到消息后
- 如果收到 Commit，那么就将 Half 消息重新组装，放入正确的主题和队列投递出去；然后将 Half 消息放入 RMQ_SYS_TRANS_OP_HALF_TOPIC 主题中，表明这个消息以及处理过
- 如果收到 Rollback，只会将 Half 消息放入 RMQ_SYS_TRANS_OP_HALF_TOPIC 主题中
Broker 有一个定时服务，遍历 RMQ_SYS_TRANS_OP_HALF_TOPIC 中的内容，对 RMQ_SYS_TRANS_HALF_TOPIC 去重找到还没处理过的消息。然后对找出来的消息进行反查，这个反查请求是单向的。
如果多次反查都没有收到回复，那么就按照 Rollback 处理

这里会发现，RocketMQ 不会立刻删除 Half 消息，而是先保存已经处理过的消息，然后通过定时任务去重。这是因为 RocketMQ 使用的是顺序追加写入，短时间内不会更改已经写入的消息。每次反查时会将 Half 消息再入盘一次，这样一来，可以记录下反查的次数。

RocketMQ 事务消息有两点特点：

确保本地事务和消息发送要么同时成功，要么同时失败
增加事务反查机制，提高事务执行的成功率

sequenceDiagram
    participant A as 事务主动方
    participant MQ as Broker
    participant B as 事务被动方
    A->>MQ: Half 消息
    MQ->>MQ: 持久化消息
    MQ->>A: 返回 Half 消息发送成功
    A->>A: 执行本地事务
    A->>MQ: 根据本地事务结果<br>发送 Commit 或者 Rollback
    MQ-->>A: 如果没有收到，反查事务状态
    A-->>A: 检查事务状态
    A-->>MQ: 返回 Commit 或者 Rollback
    MQ->>B: 如果收到 Commit<br>执行业务逻辑
    MQ-->>MQ: 如果收到 Rollback，丢弃

Kafka 事务消息

RocketMQ 解决了本地事务执行和消息发送之间的约束，而 Kafka 则解决了一次性发送多个消息时多个消息之间的约束。对于 Kafka 来讲，多个消息要么同时成功，要么同时失败。这有点像我们之前讲的 TCC 模型。

不过它的事务消息并不是那种原生的，而是依靠幂等机制来实现 Exactly Once 语义。

消息可靠性分为三种：

At Most Once：消息可能会丢失，但不会重复

At Least Once：消息不会丢失，但可能会重复

Exactly Once：消息不会丢失，也不会重复

事务消息的目标是实现 Exactly Once 语义

Kafka 的 Exactly Once 就是纯骗，它并不是说从生产者到消费者的整个过程都既不会丢失也不会重复，而是说从 Kafka 的一个主题到另一个主题满足 Exactly Once 语义。

这一特性是通过事务 ID 来实现的。Kafka 会为每个事务生成一个事务 ID，然后将这个事务 ID 附加到消息中。消费者在消费消息时，会根据事务 ID 来判断消息是否重复。

它的具体流程是这样的：

事务开始时，生产者像协调者发送一个事务开始请求，协调者将它记录到事务日志中，标记为 ongoing
然后生产者开始边执行事务，边发送一堆真正的事务消息。这些事务消息就记录在普通的消息队列中。如果消费者愿意的话，现在就消费也不是不行
事务结束时，生产者向协调者发送一个提交或者回滚请求
如果是提交请求
- 协调者会首先执行预提交操作，即将事务状态从 ongoing 改为 prepare，并写入事务日志
- 然后向事务分区发送事务结束的消息，并向事务日志写入 committed 状态
- 消费者收到事务结束的消息后，放心大胆地消费刚刚普通消息队列里传来的消息
如果是回滚请求
- 协调者会首先执行预回滚操作，即将事务状态从 ongoing 改为 abort，并写入事务日志
- 然后向事务分区发送事务结束的消息，并向事务日志写入 aborted 状态
- 消费者收到事务结束的消息后，将普通消息队列中的消息丢弃

Kafka 的事务消息有两点特点：

确保一次性发送多个消息要么同时成功，要么同时失败
是否消费事务的逻辑由消费者的业务代码实现

sequenceDiagram
    participant A as 事务主动方
    participant MQ as Broker
    participant B as 事务被动方
    A->>MQ: 事务开始请求
    MQ->>MQ: 写入事务日志
    A->>MQ: 发送事务消息 A
    MQ->>MQ: 持久化为普通消息
    A->>MQ: 发送事务消息 B
    MQ->>MQ: 持久化为普通消息
    A->>MQ: 根据本地事务结果<br>发送提交或者回滚请求
    MQ->>MQ: 更改事务状态并写入事务日志
    MQ->>B: 发送事务结束消息
    MQ->>B: 消费/丢弃事务消息 A
    MQ->>B: 消费/丢弃事务消息 B

特殊队列

死信队列

当消息无法被消费时，会将消息发送到一个特殊的队列中，这个队列就是死信队列。

RabbitMQ

RabbitMQ 消息加入死信队列的原因主要有以下几种：

消息被拒绝（即 Nack）
消息过期（即 TTL）
队列满了

为了处理死信队列中的消息，RabbitMQ 提供了一个特殊的交换机，叫做死信交换机（DLX）。绑定了死信交换机的队列就是死信队列（DLQ）

// 死信交换器和队列
channel.exchangeDeclare("dlx", "direct");
channel.queueDeclare("dlq", true, false, false, null);
channel.queueBind("dlq", "dlx", "dlx-routing-key");

// 主队列绑定死信交换器
Map<String, Object> args = new HashMap<>();
args.put("x-dead-letter-exchange", "dlx");
args.put("x-dead-letter-routing-key", "dlx-routing-key");
channel.queueDeclare("main_queue", true, false, false, args);

// 消费者拒绝消息成为死信
DeliverCallback deliverCallback = (consumerTag, delivery) -> {
    channel.basicNack(delivery.getEnvelope().getDeliveryTag(), false, false);
};

RocketMQ

RocketMQ 的消息重试消费失败超过最大重试次数（默认为 16）后，会将消息发送到死信队列中。死信队列的主题为 %DLQ%<consumer_group>

// 消费者设置最大重试次数
DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("group_name");
consumer.setMaxReconsumeTimes(3); // 最大重试次数

// 消息监听器返回消费失败状态
consumer.registerMessageListener((MessageListenerConcurrently) (msgs, context) -> {
    return ConsumeConcurrentlyStatus.RECONSUME_LATER;
});

Kafka

Kafka 并不支持死信队列。只能让消费者自己在处理失败时，将其发送到死信主题中。

延迟队列

延迟队列是指，当消息发送到队列中时，会设置一个延迟时间，只有在延迟时间到达后，消息才会被消费。

RabbitMQ

RabbitMQ 基于 AMQP 协议，本身并不支持延迟队列，但可以有插件 rabbitmq_delayed_message_exchange 来实现。

// 启用延迟插件类型
Map<String, Object> args = new HashMap<>();
args.put("x-delayed-type", "direct");
channel.exchangeDeclare("delayed_exchange", "x-delayed-message", true, false, args);

// 发送延迟消息（30秒）
AMQP.BasicProperties.Builder props = new AMQP.BasicProperties.Builder();
props.headers(new HashMap<>()).header("x-delay", 30000);
channel.basicPublish("delayed_exchange", "routing_key", props.build(), message.getBytes());

RocketMQ

RocketMQ 的延迟队列是通过主题的延迟级别来实现的。每个主题都有 18 个延迟级别，分别对应 1s、5s、10s、30s、1m 等。

Message msg = new Message("TopicTest", "TagA", "Hello RocketMQ".getBytes());
msg.setDelayTimeLevel(3); // 对应10秒延迟
SendResult sendResult = producer.send(msg);

Kafka

Kafka 本身并不支持延迟队列。只能让生产者设置一个延迟时间戳，消费者在消费时判断当前时间是否超过延迟时间。

优先级队列

优先级队列是指，当消息发送到队列中时，会设置一个优先级，优先级高的消息会优先被消费。

RabbitMQ

RabbitMQ 的优先级队列是通过在队列中设置一个参数 x-max-priority 来实现的。这个参数表示队列的最大优先级，范围是 0 到 255。

// 创建支持优先级的队列
Map<String, Object> args = new HashMap<>();
args.put("x-max-priority", 10); // 最大优先级为10
channel.queueDeclare("priority_queue", true, false, false, args);

// 发送优先级消息
AMQP.BasicProperties props = new AMQP.BasicProperties.Builder().priority(5).build();
channel.basicPublish("", "priority_queue", props, "High priority message".getBytes());

我的服务器成了 DDoS 的肉鸡!

mail@ch3nyang.top (Ch3nyang) — Sun, 19 Jan 2025 17:00:00 +0800

悲报！我的一台 VPS 成了 DNS 反射放大攻击的肉鸡！

今天上 HostEONS 看来一眼，发现我的一台 VPS 的带宽异常飙升，每天的上传流量达到了 10 个 G。

我一看，这流量不对劲啊，怎么会这么高？

我赶紧登录服务器，跑了一下 iftop，发现我服务器的 48083 端口在疯狂访问 one.one.one.one:domain 和 dns.google:domain。结合高上传流量低下载流量，我立刻意识到，我的服务器成了 DNS 反射放大攻击的肉鸡！

首先火速改掉了 SSH 的端口和密码。然后来排查恶意进程。

首先看看和 53、43083 端口关联的进程：

lsof -i :53
lsof -i :43083

什么也没有。那还是先看看它在请求什么站点的 DNS 吧：

sudo tcpdump -i eth0 -n udp port 53 -vvv

然后发现全在访问 *.nv.gov、*.us.gov、*.gov 等老美的政府网站。鉴于这台 VPS 位置在 LA，请求这些玩意儿倒也算合理。

我又看了下

top
crontab
隐藏进程
最近修改/删除的可执行文件
最近的用户登录

但什么异常也没看到。我还跑了下 Rootkit，也是一无所获。

抽象了啊，这个问题有点难搞！

然而，这台服务器上还跑着几个网站，重装系统有点麻烦。我决定把这个问题搁置，先配一下 iptables，把不用的端口都关掉，然后再看看情况。

$ iptables -L
Chain INPUT (policy DROP)
target     prot opt source    destination
ACCEPT     all  --  anywhere  anywhere
ACCEPT     all  --  anywhere  anywhere  ctstate RELATED,ESTABLISHED
ACCEPT     tcp  --  anywhere  anywhere  tcp dpt:PORT ctstate NEW limit: avg 5/min burst 5
ACCEPT     tcp  --  anywhere  anywhere  tcp dpt:PORT
ACCEPT     udp  --  anywhere  anywhere  udp dpt:3478
ACCEPT     udp  --  anywhere  anywhere  udp dpts:50000:51000
ACCEPT     tcp  --  anywhere  anywhere  tcp dpt:http
ACCEPT     tcp  --  anywhere  anywhere  tcp dpt:https
ACCEPT     icmp --  anywhere  anywhere  icmp echo-request limit: avg 1/sec burst 5
SYN_FLOOD  tcp  --  anywhere  anywhere  tcp flags:FIN,SYN,RST,ACK/SYN

Chain FORWARD (policy DROP)
target     prot opt source    destination

Chain OUTPUT (policy ACCEPT)
target     prot opt source    destination

Chain SYN_FLOOD (1 references)
target     prot opt source    destination
RETURN     all  --  anywhere  anywhere  limit: avg 1/sec burst 3
DROP       all  --  anywhere  anywhere

现在，53 就访问不了了，不过我也没有需要访问它的服务。

目前来看，服务器暂时安全了。后面有时间我再排查排查，看看能不能把这个恶意进程揪出来。

特性	`select`	`poll`	`epoll`	`io_uring`
fd 数量限制	\(1024\)	无限制	无限制	无限制
数据拷贝	每次调用	每次调用	仅注册时	零拷贝
遍历开销	\(O(n)\)	\(O(n)\)	\(O(1)\)	\(O(1)\)
触发模式	水平触发	水平触发	水平/边缘	异步
跨平台	🟢	🟢	🔴	🔴
系统调用	每次轮询	每次轮询	每次轮询	批量提交

Ch3nyang's Blog

企鹅岛上的鱼指导

毕业典礼随想：站在聚光灯外的人

AI时代的爱情

正确的人

岘港海鲜加油

人类码

希望指数

在桌面应用中使用反向代理实现网页预览

同源策略与 CORS

页面资源加载

静态资源重写

CSS 中的 URL 重写

内联样式处理

动态请求拦截

资源代理端点

X链接处理与外部跳转

链接重写策略

客户端点击拦截

XHistory API 拦截

特殊情况处理

懒加载图片

HTML 实体解码

Electron 是怎么做的？

从根源解决：为 Wails 贡献 WebviewPanel

总结

Vibe Coding 一个复杂项目——问题与经验分享

CI/CD for AI

统一的开发命令

测试的陷阱

前端部分

运维部分

屎山是怎样炼成的

何时重构？

如何重构？

所以，AI 能取代程序员吗？

越过长城，走向世界——翻墙协议的历史与原理浅析

GFW 技术简介

常见代理协议

传统 VPN

Shadowsocks (SS)

ShadowsocksR (SSR)

VMess

Trojan

VLESS / Xray

REALITY

Hysteria

NaïveProxy

常见代理工具

V2Ray 与 Xray

Sing-Box

Clash 系列

其他工具

结语

算法笔记 (4) - 弹簧摆

拉格朗日力学

Runge-Kutta 方法

单摆

弹簧摆

讨论

算法笔记 (3) - 波函数坍缩与程序化生成

请客吃饭的感悟

波函数坍缩算法

样本与约束

观测与坍缩

实现

讨论

算法优势

从平面到立体

形式化理解零知识证明

Intro

零知识证明的定义

交互式零知识证明协议

Schnorr 协议

协议步骤

协议分析

大图的哈密顿环问题

协议步骤

协议分析

非交互式零知识证明

从根源解决：为 Wails 贡献 `WebviewPanel`

`select`

`poll`

`epoll`

`io_uring`