参考《原神，启动》的梗，做的一个娱乐向视频。

公司收到了Navicat的侵权警告, 很有可能要吃官司。在此还是呼吁大家使用正版，拒绝使用盗版软件。

另外，开发者常用的软件的合法替代品，视频中也有推荐。

Background

Look at the DDL below, can you tell the meaning of CHARSET=utf8mb4 and COLLATE=utf8mb4_general_ci?

That is the knowledge that today I want to share with you.

今天跟大家分享AI使用心得：不再是让AI帮我们写代码，而是直接帮我们干活！

前言

熟悉我的人都知道，我对代码是有追求的。

正式参加工作后，我就知道，复制粘贴是坏的实践，自己一直极力避免做这样的事。要是遇到了别人复制粘贴，要么喷，要么自己改。

我早期认为：复制代码就是菜。

后来认为：复制代码可能不是菜，而是懒，没有素养，自我要求。

而现在：代码其实也没那么重要；某些情况下复制粘贴是可以接受的。

编码经过七个年头，我思想上为何会有如此改变？难道这就是传说中的七年之痒?

正文

我总结了一下，主要有以下原因：
1.深刻地理解了源码与测试用例之间的关系。只相信测试用例，而不是相信源码。如果你只改源码而不是补充相应的测试代码，那所谓的有追求是盲目、片面的。

2.对具体的编码实现已经缺乏兴致了。尤其是有AI的情况下，真的是有手就会，何必要我来写呢？我负责设计，再进行 Code Review　不是更好吗？

3.要考虑时间成本。如果别人已经做了一大半，我何必重头开始？

4.提升对质量的认知。聚集于产出质量，而不仅仅是代码质量，那么你就会发现，要做的事还挺多，再考虑时间成本，需要做一个权衡取舍。

这是个职场吐槽帖，也是个自我反思、情绪管理帖。

我在沟通上，有以下可以改正的点：
0. 这个东西我也不太懂，要不你先自己看一下。改成：我帮你问一下，等下搞清楚了回复你

1. 我要下班了，周一再回。改成：我身体不舒服，先回去了，等下回复你
2. 你自己安排不合理，凭什么要我陪你加班？改成：放心，我配合你，有事就沟通
3. 你看不懂代码吗？怎么当P7的？改成：你还需要什么，你说；你还有哪里不懂的，我给你解答
4. 最后，全程忍住反问的冲动，不要使用反问句，尽量改成陈述句。陈述句使人冷静，反问句只会让矛盾升级，加剧愤怒！

事情是这样的。

我跟素未谋面的同事在工作上要有一些配合，主要是我提供技术方案、文档给他。

对方工作能力不足就算了，时间管理也不行。8.3号一整天没来找我，8.4号白天也没来找我，快下班了，才打电话跟我说要资料。

这是第一层不满：快下班了，没什么耐心了，我不想别人打扰我周五下班。

电话中，他的语气带着责备，明显是甩锅的意味。找人办事，要别人配合还用这种语气，这是第二层不满。我开始怒他，我说，“兄弟，你冷静下。”

接着，他又跟我扯淡，我一看时间，六点钟了，是时候下班。我就说，“有什么问题发钉钉，我周一给你解决。”　他急了，他说，“你不能下班，你不能走，你要陪我！”
tmd，自己延误工期，还要我陪你加班，哪个这个道理？这是第三层不满，我有点破防了。我开始说一些不太理智、不太专业的话。

我说，“凭什么要我陪你加班？V我50，我就陪你”。他说，“你在搞笑吧，不如让领导V你50？”　
他接着说，“这个东西很急，客户今天晚上就要！”　我说，“那是你的事，你的客户，又不是我的客户。”

这两句话一出，味道就有点不对了。本来全然是他不占理的，现在他抓住的我语言上漏洞，开始要拉我下水了。

于是马上拉群、打字，向领导打小报告，一幅小学生向老师告状的模样。

这情商，这行为，我们还能好好配合？我们接下来净在群里互怒，要么是甩锅，要么是暗示对方能力不行，没有一个人在解决问题。

最后，我回去以后，还是带着不满加了班。不但自己加，还搞得我的 leader　也跟着加，让　leader 对那个人也无语，心情不好了。

这一点，我有点自责，因为我连累了我的 leader。而这也是我为什么反思并把这件事情写出来的原因，自己不爽只是自己的事，连累到他人，我就过意不去了。

我不希望这种事情再次发生！我应该能掌握事态，Let me take control of things!

下次再有这种事，一定是先把工作上的问题解决，然后再远离傻逼。不要在傻逼身上浪费时间，多说一句话、甚至只是骂一句都不值得！

想一想，已经几年没跟人因为工作的事情跟人发生明面上的不愉快了。我的情绪管理能力似乎下降了，这也是个契机，让我重新对这方面重视起来。

经验上看，除了开头的句式转换以外，其实有一个心法值得学习。那就是永远不要跟人在明面上闹不愉快。

同时，结合“阳奉阴违”的技巧，你不用去做口舌之争，你去做你的事就行了。
比如，我准备下班了，对方说，“你不要下班，你不能走。”　我可以回复，“好的，我不走，我上个厕所。”　然后我就挂掉电话，下班走人，这不是很简单吗？何必反问他“为什么我不能走？”没有意义啊！

总之，明面上不与人闹翻，保持自己情绪的稳定，一方面是职业素养体现，另一方面也是自己涵养的体现。
还有一方面，那就是有利于身心健康——生气是会对身体器官造成伤害的，如高血压、胃疼、肠胃不适！

前言

本次迭代做的工作主要是回收项目能力，具体做法是把 fork 出去的代码合并回来。

这次迭代因为各种原因，延期了快一个星期（周六还加了班）。

那么，我从工作流、方法论的角度，反思了自己可以改进的点，期望在这种迁移旧代码的实践中，抽取出能复用的经验。

动手前，至少梳理出接口清单

太轻信旧代码了，抱着代码迁移过来，跑起来就能用的态度，没能及时发现功能遗漏点，到了提测才发现有功能未实现，这是可以避免的。

更优的工作流应该是：

1. 先进行业务梳理
2. 整理出接口清单
3. 再进行代码迁移
4. 根据接口清单，逐个验证迁移的代码是否符合需求

迁移时，采取结队编程

看到有 500 个文件要迁移，觉得用分治的思路去实现会更高效，但这种思维有一个误区：做得快不等于有效率，因为效率需要的是有用功，而不是无用功。

实践表明，初期对业务的理解、代码的熟悉程度还不够深入，迁移代码遇到分歧点时，个人在独自处理时容易产生错误——而这种错误并不自知，这才是最蛋疼的地方。

所以，我才建议，采取结队编程实践，两个人一起来迁移代码，这样子遇到分歧时可以讨论，而不是贸然行动。表面上看，这样的进程慢了，实际上却能提高对代码、业务的理解，提高了迁移的正确率，真正地提高效率。

迁移后，需要对自己负责的功能设计测试用例

这里的本质，是不能完全依赖别人。虽然测试人员会编写测试用例，也会进行用例评审，但这里会有两个问题：

1. 前期评审时，自己的心思可能在理解业务、功能设计与改造以及代码迁移，没有多少心思能去 debug 用例的精细程度
2. 测试也是人，也会有遗漏，并且没有接触源码，有些特殊的、极端的边界场景，自己作为研发人员，更容易发现

可以看成，我们自己设计的用例是对测试人员给出的测试用例的补充。

当然，由于时间的关系，做完善的测试一般都不太可能了。
对于 legacy code，想补充 service 层的单元测试成本是很高的。写 controller 层的测试，可能也没有太多时间。
但至少应该用 postman 进行调试，或者在用户界面上点几下，不能完全等着前端或测试人员反馈，认为没有反馈就是没有 bug。

前言

还在把 AI 当作搜索引擎的替代品，有问题才问 AI，没问题就在那边吭哧吭哧地撸代码？如果是这样，那你真的 OUT了！现在正经人谁还自己一行行地写代码啊，都是 AI 生成的代码——没有 AI 我不写（手动滑稽）。

本文将搁置争议，秉持实用主义，讨论在 AI 可以辅助我们编码的情况下，应采取什么样的实践，从而利用好工具，提高工作效率。

本文将分享 AI 时代的编程新实践，教你如何从一个 "Ctrl + C"、 "Ctrl + V" 工程师，变成一个 "Tab + Enter" 工程师🤣。

开发流程

软件的一般研发流程为：

1. 需求分析
2. 程序设计
3. 代码编写
4. 软件测试
5. 部署上线

我们在这里主要关心步骤2~4，因为与 AI 结合得比较紧密。虽然需求分析也可以借助 AI，但不是本文的重点，故不做讨论。

程序设计

经过需求分析、逻辑梳理后，在编写实际代码前，需要进行程序设计。

此环节的产物是设计文档，是什么类型的设计文档不重要，重要的是伪代码的输出。

虽然《Code Complete》早就推荐过伪代码的实践，但对此人们容易有一个误区：认为写伪代码花的时间，已经够把实际代码写好了。但 AIGC 时代，此问题可以轻松破解：AI 写代码的速度肯定比人快，因此，只要能找到方法能让 AI 生成符合需求的代码，就值得花时间去研究。而伪代码，就是让 AI 快速生成符合期望的实际代码的最好方式。

为什么这么说呢？因为想要让 AIGC 符合期望，恰当的 Prompt 必不可少。但如何写好这个 Prompt，需要提供多少上下文，才能让 AI 更好地理解我们的意图，这是需要技巧、需要调试的。而经过精心设计的伪代码，本身已经提供了足够的上下文，且意图足够聚焦，减轻了对 Prompt 的要求，又提高了 AIGC 的成功率。

我们来看一下伪代码示例：

上述代码主要表达的内容是：

1. 对初始数据进行加密
2. 返回加密后的相关内容
3. 涉及到了一系列的算法

对于伪代码的编写，有如以建议：

1. 不要纠结类型，不要局限于某一种编程语言的语法，不用试图写能编译通过的代码——这只会限制了你的表达
2. 命名一定要准确，符合领域术语，这一点很关键。这一点可以通过查找资料、看书、问 AI 来实现。千万不要只是生硬地汉译英，不专业的表达会妨碍 AI 的理解

代码编写

代码编写分为以下几步：

1. 把伪代码转换成目标语言可执行的代码
2. 根据项目情况，对生成的代码进行改造
3. 利用 AI 编码辅助工具编写剩余的代码

生成真实代码

让 AI 生成代码的 prompt 很简单，示例如下：

根据实际情况，把 Java 替换成 Node.js/Python/Go 即可。

使用 chatGPT 结果截图：

完整代码如下：

把上述代码 copy 下来，放到工程中，根据需要改造即可。

这里特别要说下，强烈推荐使用原版 AI，而不是寻找平替，同样的 prompt，下图是某一中文平替输出的结果：
只生成了函数声明，没有生成函数实现。二者对比，未免相形见绌。

辅助编程工具

改造的过程中，少不了 AI pair programming tools。对此，我推荐使用 Amazon 的 CodeWhisperer，原因很简单，跟 GitHub Copilot 相比，它是免费的😃。

CodeWhisperer 的安装可以看文末的安装教程，我们先来看一下它是怎么辅助我们编码的。

第一种方式是最简单的，那就是什么都不管，等待智能提示即可，就好像 IDEA 原来的提示一样，只不过更智能。

下图示例中，要把原来的中文异常提示，修改成英文，而我只输入了两个字符 IM， 就得到了智能提示，补全了完整的英文字符串！

可以注意到，上图的智能建议一共有 5 条，相应的快捷键为：

1. 方向键 ->，查看下一条提示
2. 方向键 <-，查看上一条提示
3. Tab，采用该提示
4. Esc，拒绝提示

我们再来看第二种 CodeWhisperer 的使用方式，编写注释，获得编码建议。

最后一种就是编写一个空函数，让 CodeWhisperer 根据函数名去猜测函数的实现，这种情况需要足够的上下文，才能得到令人满意的结果。

软件测试

AI 生成的内容，并不是完全可信任的，因此，单元测试的重要性变得尤为突出。

对上述代码编写测试代码后，实际上并不能一次通过，因为前面 AI 生成的代码参数有误。

此时需要一边执行单测，一边根据结果与 AI 进行交互：

经过修改，最终测试用例通过👏！

总结

本文通过案例，展示了 AI 如何结合软件研发的流程，提升我们的编程效率的。

其中，个人认为最重要的是编写伪代码与进行单元测试。有趣的是，这两样实践在 AIGC 时代之前，就已经被认为是最佳实践。这给我们启示：某些方法论、实践经得起时间的考验，技术更新迭代，它们历久弥新。

对于AI编程的到底应该怎么看，其实 GitHub Copilot 的产品标语已经很好地概括了：Your AI pair programmer。在结队编程里，由两个人一起来进行编程活动。一个是 Navigator，负责指导、审查，另一个 Driver，负责具体的代码编写。AI 的出现，其实是取代了 Driver 的角色，而另一个充当 Navigator 角色的人，仍然是不可或缺的。

最后，AI 是否能进一步渗透我们的工作流，还有待探索。此文作引抛砖引玉之用，期待大家的后续分享。

附：CodeWhisperer 安装

下载 2023 年的 IDEA，打开 Plugins Marketplace，找到 AWS Toolkit

安装完成、重启 IDEA 后，点击左下角，按下图所示操作：

如果第一次使用，就点击 1 处进行注册，如果已经有账号了，就点击 2 处使用自己的账号登录。

注册、登录、授权成功后，出现如图所示页面，即可使用 CodeWhisperer。

看看大佬的演讲，还是有很多启发的。别的不说，推荐的书单就很有价值。

事件还原

业务流程：

1. app-a 上传文件
2. app-b 下载文件后使用文件

其他信息：

1. 开发、测试环境使用 MinIO
2. 生产环境使用 Amazon S3

问题：

1. app-a 上传文件成功
2. app-b 使用文件报错

逐步分析定位问题：

1. app-a 与 app-b　配置是否一致？——确认都是使用 S3
2. S3 是否正确配置？有没权限问题？——确认配置正确，没有权限问题
3. app-a 是否真的上传成功？——确认文件已在 S3
4. app-b 是否下载成功？——根据日志，判断下载失败，得到的信息是：文件不存在。

所以问题就在于，为什么 app-b 的代码会判断文件不存在？

• 是传过去的路径参数不对？
• 还是 app-b　的逻辑有问题？

经过确认，传参是正确的，那么只有一个推论： app-b 判断文件是否存在的逻辑有问题。

具体是哪里有问题呢？

原来文件下载前，有一个判断目录是否存在的逻辑，其实现是判断 S3 的对象是否存在，示例代码如下：

则该代码永远为 false。

如何修复呢？改为调用 listObjects就可以了。如下图所示（左边是修改前，右边是修改后）：

分析

很难想像，为什么在涉及对象存储的代码中，会有判断目录是否存在的逻辑。

好在我是个善于为别人找理由的人。我观察了下代码库，发现接口与类结构如下：

如果定义 IStorage 与实现 S3Storage 的代码的人并不相同（我相信很可能是这样），那么我更倾向于认为责任在定义 IStorage 的人身上，因为TA并没有合理地设计接口，导致后来者被迫实现没有意义的接口，从而出错。

结论

为什么开发、测试环境没问题？或者说，为什么 MinIO　没这个问题？那是因为实现 MinIOStorage 的人，没有踩这个坑。

所以，本此事件给我来的经验教训是什么呢？既不是 S3 如何判断目录是否存在，也不是接口定义的重要性。而是：要让测试环境与生产环境尽可能保持一致，提前暴露问题。而不是测试环境是这样的配置，生产环境又是那样的配置——这就会加大生产环境出问题的可能性！

为了完善博客，不得不升级至 Vuepress2。期间开发层面的各种问题我都忍了，但最终CI环节报错，我真的受不了了！

总结一下，我对Vue生态不满的地方在于：

1. Vue总是破坏性升级，新技术完全不管旧用户的体验
2. 你要新技术可以，别逼我跟着用，我不想破坏 CI 的稳定性

大家好，今天给大家来评测一下几个AI工具，然后做一个推荐。

首先要评测的当然是ChatGPT了，因为最早用的就是它。

R.I.P 🙏

Vim是我入行以来，一直在用的工具，可以说整个编程生涯都离不开它。

这几天听闻Vim作者离世了，便想来聊聊我与Vim的故事，以表纪念。

前言

系统满足多租户需求，是很常见的场景。本文主要聊一下在维护旧系统过程中，发现的前人多租户方案中设计、实现不合理的地方。

背景

在维护旧系统时，踩了各种坑，终于忍不住在群里吐槽了下，于是有以下对话。



既然群友有疑问，我索性就整理了一下，把前因后果清楚。

正文

1.首先，租户数据隔离级别应该如何，没有唯一标准，评价只有是否合适。因此，逻辑隔离、物理隔离，都不是吐槽点。

2.原来的设计是，采取逻辑隔离方案，具体做法是，给每一张表都加上了tenant_id字段。问题就在于，有必要每一张表加吗？系统的权限设计是：先有租户，再有应用，用户、角色、资源、权限设置等内容都挂在应用下，所以，应用下的内容，关联 app_id 就行了，根本不需要tenant_id。

3.冗余多一个字段，会出现什么问题呢？先不提查询性能、存储空间等细节，就说很实际的场景：
3.1 每张表都加 tenant_id，几乎每条 sql 都要加 where tenant_id = ? ，那程序员会怎么做？首先想到的是用框架自动注入 sql
3.2 在后台管理端，有一个超级管理员，能够查询出所有租户的内容，也就是说，此时查询不能带 where tenant_id = ?，也即不能让框架注入 sql

要同时兼容上述逻辑，程序员又会怎么做呢？于是就引入了万恶的全局变量，类似于 injectSql = true，就添加 tenant_id 作为过滤条件。但默认是不是要 injectSql = true 呢？每个项目代码又不一样，你不运行，你都不知道。

更恶心的是，需求变化后，是否需要带上 tenant_id 的逻辑与原来不一致时，你得在某行代码执行前，手动设置 inejctSql 的值，在该行代码之后，再手动复原——因为如果不复原，作为全局变量，会影响到后面的代码！

md，这时候后你才会知道，还不如老老实实地设置 tenant_id，显示地设置，好过这种隐蔽的依赖。

4.但这还不是最难搞的。因为上述的是代码问题，真正难搞的是数据问题。考虑一种场景：超级管理员在后台管理某租户的应用，手动为租户添加数据，请问，新增的数据 tenant_id 的值是什么，某租户的 id，还是超级管理员的id？按逻辑来说，应该是某租户的 tenant_id。但问题在于，由于理解不同，或由于疏忽让框架自动注入了 tenant_id，导致上述场景，有些数据的 tenant_id 是超级管理员的id。而又因为超级管理员进行查询时，是不带 tenant_id 作为过滤条件的，因此即使 tenant_id 的值设置错误，依然在界面上能显示，使得这个问题一直存在着，旧数据一直被保留并使用。

5.现在，有需求要导出某个租户下的数据，结果发现 tenant_id 乱七八糟，你难不难受？

6.那么，梳理完逻辑链条，我认为，虽然某些程序员的在实现上犯了低级错误，但不是主要原因，罪魁祸首应该是设计上的懒惰。设计精细一点，明确好 tenant_id 到哪张表为止，也就没有后面的 sql 注入、数据错误那么多事了。所以，我才说，给租户隔离等于给每张表加 tenant_id 的设计很傻逼！

介绍

全书链接：https://www.ximalaya.com/album/43891910

虽然这是英语专业的大学教材，但不用担心难度——只要英语不是太差，上过大学的都能看，甚至刚参加完高考的学生就能看。

虽然名字说是精读，但自己依然可以泛读、挑选着读。因此，本文记录的是经过个人挑选认为值得一读的文章，最主要的目的是，塑造全英文阅读的习惯。除此之外，也有开阔视野，增进对西方文化、经典文学作品的了解之意。

值得一读的文章

本册里面大部分是记叙文，阅读趣味性比较强。

欧亨利不愧是大师，第一册里收录了两篇他的小说。

• After Twenty Years
  经典短篇小说，应该大家都在学校看过中文版。https://www.ximalaya.com/sound/356764931
• Hearts And Hands
  我认为这篇小说是第一册中最有阅读难度的，可以作为阅读能力的检测，看能不能读懂。反正我第一次没读懂。本文使用了经典的结尾手法——最后一句话反转全文。https://americanliterature.com/author/o-henry/short-story/hearts-and-hands

另外，戏剧 The Monsters Are Due in Maple Street 也值得一读

• https://www.ximalaya.com/sound/357087229

总结一下，本册难度较低，就是来建立信心的。如果想只阅读精华，那只看我挑选出的三篇文章就够了。适应了全英文阅读后，就可以开始看第二册的内容了。

介绍

全书链接：https://www.ximalaya.com/album/44290107

本册多了一些议论文，难度有所增加。同时记叙文也更加有内涵，立意高了不少。 另外就是，语言难度有所上升——比如一些骂人的话，单词能认识，变成句子就不懂了😂。

值得一读的文章

say-yes-by-tobias-wolff 第一次没读懂，看到最后，我还以为家里进小偷了 😂

原文：https://www.missmccalister.com/uploads/3/0/9/3/30937509/lesson-7a-say-yes-by-tobias-wolff.pdf

• wiki
  说明：https://en.wikipedia.org/wiki/Say_Yes_(short_story)

The Dog of Pompeii 讲述了一个盲人男孩与一只小狗的故事，令人泪目。结尾比较含蓄，思考片刻明白后，就破防了～

原文：https://www.acaedu.net/cms/lib3/TX01001550/Centricity/Domain/562/Week%206%20-%20The%20Dog%20of%20Pompeii.pdf

button button 人心拷问：如果按下按钮，你能得到一笔钱，但世上会有一人因此而死去，你会按下按钮吗？

原文：https://christian_fuller.myteachersite.org/teacher/files/documents/button%20button.pdf

A Doctor's Dilemma 医生的困境

• 原文：http://www.kekenet.com/daxue/201706/508290.shtml
• 拓展阅读，肖伯纳的 THE DOCTOR’S DILEMMA
  ：https://www.gutenberg.org/files/5070/5070-h/5070-h.htm

the-oyster-and-the-pearl

• 原文：http://www.kekenet.com/daxue/201708/521462.shtml

解析：https://schoolworkhelper.net/william-saroyans-the-oyster-and-the-pearl-summary-analysis/

文册收录了两篇奥巴马的演讲，还是挺有意思的，能打动人心的部分当然有，同时也可以看出一些政治家演讲的特色：

1. 赞美对方。糖衣炮弹过去，对方就伸手不打笑脸人
2. 用好词，美化自己，把功劳往自己身上揽
3. 强调双方关系： 我们是很友好的哦、我们是合作伙伴哦
4. 回顾历史，展望未来：我们已经走了很长的路，做出了很多的改变，取得了很大的进步，为了下一代、为了未来，我们要加油鸭！

相关链接：

• 竞选胜利演讲：http://www.kekenet.com/daxue/201707/518237.shtml
• 在上海的演讲：http://www.kekenet.com/daxue/201708/518540.shtml

另外，我摘录了一些觉得不错的句子：

• When dealing with people, let us remember we are not dealing with creatures of logic.
• We are dealing with creatures of emotion, creatures bristling with prejudices, and motivated by pride and vanity.
• Any fool can criticize, condemn and complain—and most fools do. But it takes character and self-control to be
  understanding and forgiving.

介绍

全书链接：https://www.ximalaya.com/album/44439108

阅读本册，我在阅读上开始有了一定的厌倦感。这种厌倦感来自于，文章看得多了，不再首先关注是否完整读懂了文章，而是更关心文章是否有趣、是否吸引人——如果不能吸引我，我都不想去关心你在说什么。所以，有些说明议论文，我是跳着看的，因为某些段落让我觉得很无聊，内容不吸引我，行文呆板僵硬，充满了说教的味道。

这种转变，说明了两点：

1. 我开始应用我在中文阅读中培养出来的阅读喜爱，去评判英文文章了
2. 我开始有意识地运用阅读技巧，恰当地泛读，不再是拿到一篇文章就逐字逐句地读

值得一读的文章

A-DILL-PICKLE 讲述的是曾经的恋人偶遇，欧亨利式结尾：

原文：https://www.katherinemansfieldsociety.org/archive/www.katherinemansfieldsociety.org/assets/KM-Stories/A-DILL-PICKLE1917.pdf

• wiki
  解析：https://en.wikipedia.org/wiki/A_Dill_Pickle#Plot_summary

The Invisible Japanese Gentlemen

原文：https://www.ff.umb.sk/app/cmsFile.php?disposition=a&ID=4292

• 分析：http://sittingbee.com/the-invisible-japanese-gentlemen-graham-greene/

My Grandmother, the Bag Lady 被这篇文章打动，泪目了

• 原文：http://www.kekenet.com/daxue/201704/504622.shtml

The End of the Civil War 本册收录了挺多美国南北战争相关的内容，这是其中角度新颖的一篇

• 原文：http://www.kekenet.com/daxue/201705/509083.shtml

Why Historians Disagree 科普了一下历史学是如何看待历史，有助于我们更理性地学习历史

• 原文：https://www.ximalaya.com/sound/361971944

the-most-dangerous-game 可以说是三册中最精彩的一篇小说之一，不容错过

原文+分析（左边是内容，右边是分析）：https://www.litcharts.com/lit/the-most-dangerous-game/summary-and-analysis

The Bench 用一个黑人小哥故意坐在标明只能由欧洲人坐的板凳上的故事，以小见大，描绘了 Civil War 之后美国种族歧视现状

• 原文：http://www.kekenet.com/daxue/201708/521739.shtml

Twelve Angry Men 十二怒汉，是本册的精彩内容之一。激发了对法治话题的兴趣，看得我直接睡不着，接着去B站看电影版。

• 原文：http://www.kekenet.com/daxue/201708/522771.shtml

电影：https://www.bilibili.com/bangumi/play/ep332629?theme=movie

介绍

全书链接：https://www.ximalaya.com/album/44641280

本册立意又高了一个层次，开始讨论哲学、政治等上层建筑，并提供了新颖的视角。如果说，前几册是开阔视野，本册开始拓展思维了。

值得一读的文章

Groundless Beliefs 提醒我们，自认为正确的东西，很可能只是毫无根据的盲从

• 原文：http://www.kekenet.com/daxue/201808/561902.shtml

Economic Growth Is a Path to Perdition, Not Prosperity 提醒我们更加理性地看待“增长”

• 原文：http://www.kekenet.com/daxue/201811/571277.shtml

The Damned Human Race 其实我觉得本文并非“值得一读”，但还列举出来原因有二：一是毕竟是马克·吐温之作，不可怠慢；二是我认为其论点新颖，不愧为讽刺大师，但论据越到后面越无说服力，可列为“反面教材”

• 原文：http://www.kekenet.com/daxue/201812/573461.shtml

A String of Beads 挺有趣的文章，揭示了人们普遍的一种心理：事情的真相相比，人们更在意的是故事的戏剧性，或是否符合自己心中的设定

• 原文：http://www.kekenet.com/daxue/201812/574998.shtml

The World House 马丁·路德·金 的文章

• 原文：http://www.kekenet.com/daxue/201901/576160.shtml

Soldier's Heart 也叫PTSD，由战后士兵自述

• 原文：http://www.kekenet.com/daxue/201902/578424.shtml

Secrets 这是一篇可以让人由好奇变为感动的文章。我原以为讲的是主人公的 “aunt” 与其旧情人的故事，直到最后，“forgive”一词的出现，令我恍然大悟，瞬间泪目。为避免剧透，我不细说了，强烈推荐。

• 原文：http://www.kekenet.com/daxue/201903/580020.shtml

The Rivals
两个男的在言语上较劲，只觉得好笑，可看到后面，我心情如此图
强烈推荐，你一定也会“surprised”!

• 原文：http://www.kekenet.com/daxue/201904/584021.shtml

Cord：一对母女的故事

• 原文：https://www.ximalaya.com/sound/364021411

论文分析。有一定难度，因为它是综合了同一个作者的三篇文章进行分析，需要挑选着读：https://www.yuque.com/office/yuque/0/2022/pdf/160590/1657283857640-11aa59bb-edc1-475f-a97f-37124a27afd9.pdf

The Never-Ending Fight “机器人学之父”阿西莫夫的反迷信文章

• 原文：https://www.ximalaya.com/sound/364032034

Man of the Moment 又到了令人享受的戏剧欣赏时间

• 原文：https://www.ximalaya.com/sound/364032690

Is Everybody Happy 讨论了幸福的定义

• 原文：https://www.ximalaya.com/sound/364033142

  
  

介绍

全书链接：https://www.ximalaya.com/album/49466046

本册开始，阅读难度再次上升，同时也更有思考的乐趣。另外，从本册开始，会在后面推荐一些著名的英文演讲，其中就有大家熟悉的乔布斯，激发读者的热情。

Who Are You and What Are You Doing Here

原文链接：https://m.kekenet.com/daxue/201909/593904.shtml

本文分享了作者教育观，并阐述了上大学的意义，否定了上学是为了就业的观点。

摘录如下： Education has one salient enemy in present-day America, and that enemy is education——university education in
particular. To almost every university education is a means to an end. For students, that end is a good job.

The best reason to read great writers is to see if they may know you better than you know yourself. You may find your
own suppressed and rejected thoughts flowing back to you with an "alienated majesty." Reading the great writers, you may
have the experience that Longinus associated with the sublime: You feel that you have actually created the text
yourself. For somehow your predecessors are more yourself than you are.

Trying to figure out whether the stuff you're reading is true or false and being open to having your life changed is a
fraught, controversial activity. Doing so requires energy from the professors. This kind of perspective-altering
teaching and learning can cause the things which administrators fear above all else: trouble, arguments, bad press, etc.

Two Kinds

原文链接：https://m.kekenet.com/daxue/201909/595380.shtml

本文以女儿的视角讲述了母亲望女成凤而女儿叛逆的故事，文中母亲代表的中国式家庭教育观，我想不少人会感同身受。用现在的眼光看来，这只不过是一段充满了失败的沟通、无法双赢的家庭教育经历，借助非暴力沟通或双赢思维是能够避免的。

摘录如下： I didn't budge. And then I decided. I didn't have to do what my mother said anymore. I wasn't her slave. This
wasn't China. I had listened to her before and look what happened. She was the stupid one.

You want me to be someone that I'm not!" I sobbed. "I will never be the kind of daughter you want me to be!"

"Only two kinds of daughters," she shouted in Chinese. "Those who are obedient and those who follow their own mind! Only
one kind of daughter can live in this house. Obedient daughter!"

"Then I wish I wasn't your daughter, I wish you weren't my mother," I shouted.

Love is a Fallacy

原文链接：https://www.ximalaya.com/sound/414753193

这多篇看下来，这篇是目前最有意思、最有趣、最令人忍俊不禁的。为避免剧透，我就少说一点。本文首尾响应，完美闭环，看完后我直呼我直呼，哈哈哈哈。就说到这了，总之墙裂推荐。

Rewriting American History

原文链接：https://www.ximalaya.com/sound/414754775

本文讲述的是美国历史教材的一些变化及背后的思考。我认可其中的一个做法：不是对历史给一个所谓正统的结论，而是充分准备材料，从不同的角度陈述观点，引导人思考。

Nobel Peace Price About Global Warming

原文链接：https://www.ximalaya.com/sound/414756339

The Bluest Eyes

原文链接：https://www.ximalaya.com/sound/414757228

这是个记叙文，然而，我认为确是这么多篇文章中，最难懂的。

How News Becomes Options and Opinions Off-Limits

原文链接：https://www.ximalaya.com/sound/414759448

本文说明了当代一种社会现代：人们在看新闻，不是在看“事实”，而是在看“观点”，作者认为，现在的新闻跟小说并非没有相似之处了。然而，作者对这种现象并非完全持否定态度，他认为这是言论自由的一种方式。最后，作者还表达了在自由社会对“尊重”一词的看法。

摘录如下： In any version of a free society, the value of free speech must rank the highest, for that is the freedom without
which all other freedoms would fall.

In free societies, you must have the free play of ideas. There must be arguments, and it must be impassioned and
untrammeled.

A free society is not a calm and eventless place——that is the kind of static, dead society dictators try to create. Free
societies are dynamic, noisy, turbulent and full of radical disagreements.

The Indispensable Opposition

原文链接：https://m.kekenet.com/daxue/202001/603745.shtml

本文所表达的观点，属于民主与自由思想的经典内容：不可缺少的反对派（或忠诚的反对派）。

摘录如下： I wholly disapprove of what you say, but will defend to the death your right to say it.

If we truly wish to understand why freedom is necessary in a civilized society, we must begin by realizing that, because
freedom of discussion improves our own opinions, the liberties of other men are our own vital necessity.

We must insist that free oratory is only the beginning of free speech; it is not the end, but a means to an end. The end
is to find the truth.

The only reason for dwelling on all this is that if we are to preserve democracy we must understand its principles. And
the principle which distinguishes it from all other forms of government is that in a democracy the opposition not only
is tolerated as constitutional but must be maintained because it is in fact indispensable.

The democratic system cannot be operated without effective opposition. For, in making the great experiment of governing
people by consent rather than by coercion, it is not sufficient that the party in power should have a majority. It is
just as necessary that the party in power should never outrage the minority. That means that it must listen to the
minority and be moved by the criticisms of the minority. That means that its measures must take account of the
minority's objections, and that in administering measures it must remember that the minority may become the majority.

The Danger of a Single Story

原文链接：https://www.ximalaya.com/sound/414765357

认识到硬币有正反面，并坚持凡事至少从两个角度去看待与分析，那么本篇文章就没白读。

摘录如下： It is impossible to talk about the single story without talking about power. Power is the ability not just to tell
the story of another person, but to make it the definitive story of that person.

All of these stories make me who l am. But to insist on only these negative stories is to flatten my experience and to
overlook the many other stories that formed me.

The single story creates stereotypes,and the problem with stereotypes is not that theyare untrue, but that they are
incomplete. They make one story become the only story.

The consequence of the single story is this: It robs people of dignity. It makes our recognition of our equal humanity
difficult. It emphasizes how we are different rather than how we are similar.

Come Rain or Come Shine

原文链接：https://www.ximalaya.com/sound/414767340

看得不太懂，但故事倒挺有意思的。

解析：https://medium.com/the-afterglow/come-rain-or-come-shine-by-kazuo-ishiguro-finding-the-moment-b09e418652db

Invisible Man

原文链接：https://www.ximalaya.com/sound/414776047

节选自同名小说（有改编），telling a story about a black teenager present his speech before white people.

You've Got to Find What You Love

原文链接：https://www.ximalaya.com/sound/414769322

Steve Jobs 在 Standford 的演讲，没想到 Jobs 声音这么年轻！演讲分享三个故事，表达主旨“follow your heart”。

精彩摘录如下： You can't connect the dots looking forward: You can only connect them looking backwards. So you have to trust
that the dots will somehow connect in your future. You have to trust in something-your destiny,life,whatever. Because
believing that the dots will connect down the road will give you the confidence to follow your heart, even when it leads
you off the well-worn path. And that would make all the difference.

Sometimes life is gonna hit you in the head with a brick. Don't lose faith. I'm convinced that the only thing that kept
me going was that I loved what I did. You've got to find what you love. And that is as true for your work as it is for
your lovers. Your work is going to fill a large part of your life, and the only way to be truly satisfied is to do what
you believe is great work. And the only way to do great work is to love what you do. If you haven't found it yet, keep
looking, and don't settle. As with all matters of the heart, you'll know when you find it. And like any great
relationship, it just gets better and better as the years roll on. So keep looking. Don't settle.

I have looked in the mirror every morning and asked myself: "If today were the last day of my life,would I want to do
what l am about to do today?" And whenever the answer has been "No" for too many days in a row, l know I need to change
something. Remembering that I'll be dead soon is the most important tool I've ever encountered to help me make the big
choices in life. Because almost everything-all external expectations, all pride, all fear of embarrassment or
failure-these things just fall away in the face of death,leaving only what is truly important. Remembering that you are
going to die is the best way I know to avoid the trap of thinking you have something to lose. You are already naked.
There is no reason not to follow your heart.

Where Do We Go from Here

原文链接：https://www.ximalaya.com/sound/414771197

本文是马丁·路德·金的另一篇呼吁黑人平等的演讲，从中可以看到与《I Have a Dream》的影子。

摘录如下： As long as the mind is enslaved, the body can never be free. Psychological freedom,a firm sense of self-esteem, is
the most powerful weapon against the long night of physical slavery. No Lincolnian emancipation proclamation or
Johnsonian civil rights bill can totally bring this kind of freedom. The Negro will only be free when he reaches down to
the inner depths of his own being and signs with the pen and ink of assertive manhood his own emancipation proclamation.

And so I say to you today that I still stand by nonviolence. For through violence you may murder a murderer but you
can't murder murder. Through violence you may murder a liar but you can't establish truth. Through violence you may
murder a hater,but you can't murder hate. Darkness cannot put out darkness. Only light can do that.

前言

全书链接：https://www.ximalaya.com/album/49468954

本册是整个系列的最后一册了，完结撒花🎉

Paper Tigers

原文链接：https://www.ximalaya.com/sound/414998175

探讨了 Asian American 的教育经历与社会成就不符的现象。

摘录如下： Let me summarize my feelings toward Asian values: Damn filial piety. Damn grade grubbing. Damn Ivy League mania.
Damn deference to authority. Damn humility and hard work. Damn harmonious relations. Damn sacrificing for the future.
Damn earnest, striving middle-class servility.

Maybe a traditionally Asian upbringing is the problem. In order to be a leader, you must have followers. Associates are
initially judged on how well they do the work they are assigned. But being a leader requires different skill sets. “The
traits that got you to where you are won't necessarily take you to the next level," says the diversity consultant Jane
Hyun, who wrote a book called Breaking the Bamboo Ceiling.

At Yale, Chua made the connection between her upbringing and her adult dissatisfaction. “My parents didn't sit around
talking about politics and philosophy at the dinner table," she told the students. Even after she had escaped from
corporate law and made it onto a law faculty,“I was kind of lost. I just didn't feel the passion."

Chua's Chinese education had gotten her through an elite schooling, but it left her unprepared for the real world.

注：Chua
也就是《虎妈战歌》的作者：https://baike.baidu.com/item/%E8%94%A1%E7%BE%8E%E5%84%BF/3424632#7

What Is News

原文链接：https://www.ximalaya.com/sound/414999846

提示我们如何看待新闻，与前面的如何看待历史可谓是姐妹篇。

摘录如下： The news is made rather than gather.

We see what we expect to see. We focus on what we are paid to see. And those who pay us to see usually expect us to
accept their notions.

“What is news?" News,we might say, may be history in its first and best form, or the stuff of literature, or a record of
the condition of a society, or the expression of things, but in its worst form it can also be mainly a “filler,” a
“come-on" to keep the viewer's attention until the commercials come.

All of which leads us to reiterate, first, that there are no simple answers to the question “What is news?"
And, second, that it is not our purpose to tell you what you ought to believe about the question. The purpose of this
chapter is to arouse your interest in thinking about the question. Your answers are to be found by knowing what you feel
is significant and how your sense of the significant conforms with or departs from that of others. Answers are to be
found in your ideas about the purpose of public communication, and in your judgment of the kind of society you live in
and wish to live in. We cannot provide answers to these questions. But you also need to know something about the
problems, limitations, traditions, motivations, and, yes, even the delusions of the television news industry.

At War with the Planet

原文链接：https://www.ximalaya.com/sound/415001340

本文为了我们科普了人类社会与自然环境的特征，提供了一个新颖而深刻的视角来看待人与自然的关系，启发我们在采取人与自然和谐相处的措施时，不要走极端。

How to Get the Poor off Our Conscience

原文链接：https://www.ximalaya.com/sound/415004615

本文讨论了面对一直存在的贫富差距现象，社会思想、政府措施在历史上经历了怎样的变化。

Housewifely Arts

原文链接：https://www.ximalaya.com/sound/415006607

本文主要表达的是对母亲的回忆，其实属于可看可不看类型，之所以还放上来，原因有二：

1. 冷幽默，毕竟有几处地方让我笑了
2. 引以为戒，千万别学女主

The One Against The Many

原文链接：https://www.ximalaya.com/sound/415007539

本文主要是讲美国文明的，没有一个地方出现China，但几乎处处都能看到China的影子。绝对不容错过的好文，可以说是反洗脑的基础。

精彩摘录： It is important here to insist on the distinction between ideals and ideology. Ideals refer to the long-run goals
of a nation and the spirit in which these goals are pursued. Ideology is something different, more systematic, more
detailed, more comprehensive, more dogmatic.

An ideology, in other words, is an abstraction from reality. There is nothing wrong with abstractions or models. In
fact, we could not conduct discourse without them. The ideological fallacy is to forget that ideology is an abstraction
from reality and to regard it as reality itself. The besetting sin of the ideologist, in short, is to confuse his own
tidy models with the vast, turbulent, unpredictable, and untidy reality which is the stuff of human experience.

Consider for a moment the ideologist's view of history. The ideologist contends that the mysteries of history can be
understood in terms of a clear-cut, absolute, social creed which explains the past and forecasts the future. Ideology
thus presupposes a closed universe whose history is determined, whose principles are fixed, whose values and objectives
are deducible from a central body of social dogma and often whose central dogma is confided to the custody of an
infallible priesthood.

The American tradition has found this view of human history repugnant and false, against the belief in the
all-encompassing power of a single explanation, against the commitment to the absolutism of ideology, against the notion
that all answers to political and social problems can be found in the back of some sacred book, against the
deterministic interpretation of history.

Ideologists are afraid of the free flow of ideas, even of deviant ideas within their own ideology. They are convinced
they have a monopoly on the Truth. Therefore they always feel that they are only saving the world when they slaughter
the heretics. Their objective remains that of making the world over in the image of their dogmatic ideology. The goal is
a monolithic world, organized on the principle of infallibility-but the only certainty in an absolute system is the
certainty of absolute abuse.

The goal of free men is quite different. Free men know many truths, but they doubt whether any mortal man knows the
Truth. Their religious and their intellectual heritage join in leading them to suspect fellow men who lay claim to
infallibility. They believe that there is no greater delusion than for man to mistake himself for God. They accept the
limitations of the human intellect and the infirmity of the human spirit.

Notes on the English Character

原文链接：https://www.ximalaya.com/sound/415017440

本文对英格兰人的性格特征进行了简单的探讨。

The Death of a Pig

原文链接：https://www.ximalaya.com/sound/415019607

本文主人公本计划养一只猪来吃，却养死了。为何把这篇文章收录进来呢，可能是因为里面细节写得好吧，把主人公的病急乱投医的场景写得较为生动。

Don't Eat Fortune's Cookie

原文链接：https://www.ximalaya.com/sound/415020743

Princeton学长回校演讲，核心观点是：你以为你的成功全靠实力，然而其中隐含着运气。

The Accidental Universe

原文链接：https://www.ximalaya.com/sound/415022329

本文是物理相关的说明文，讲了多重宇宙假设，提出一种观点：我们所在的宇宙是出于偶然。

Rowling's Speech at Harvard

原文链接：https://www.ximalaya.com/sound/415018537

罗琳的英音很好听，而且本次演讲也很幽默，建议边看边听。

为什么学

不可否认，英语始终在工作、生活中扮演着不可或缺的角色。可能有人并未意识到，我们的科学技术、政治经济、文化娱乐等领域都深受着英语世界的影响。掌握英语，运用英语，始终是非常必要的。

也许有人会反驳：我又不出国，我又不去外企上班，学英语有啥用？嗯，说得有道理，这属于实用主义。那么按此逻辑，但凡有以下需求，就不得不承认要学英语：

• 出国
• 去外企
• 有国际化需求
• 学习专业领域的前沿知识

我们尤其关注最后一点，它是与本职业相关的。以程序员为例，很多新的技术都起源于西方世界，往往文档资料都是先有英文版的，想要中文版至少要半年甚至更久，要想技术快人一步，职业发展更上一层楼，英语能力必不可少。

此时也许有人会担心，自己已错过了最佳的学习时机，现在太迟了吧？非也。种一棵树最好的时机是10年前，其次是现在。如果把人生当成马拉松，那么现在开始，一定来得及，绝不会晚。记住，Better late than never!

怎么学

关于怎么学的问题，我认为需要内外兼修。

建设心态

在意识到、并承认掌握英语的必要性后，我们需要真正地相信：现在行动并不晚。

如果这点不能相信，那说什么都没用，因为人会找各种借口让自己放弃，如“现在没时间，还有更重要的事”、“性价比太低了”、“以后再说吧”、“用中文也行”。如果是这样，那事情注定是要失败的。

其次，要学会耐心。人们常常高估一个月所能做的事，却低估一年所能做的事。不要浮躁，学会接受每天进步一点点：

有了耐心，才能在整个过程中，抵制住营销号“神奇方法”的诱惑。记住，耐心是美德，这在别的领域也适用。

与此同时，在学习过程中，注意建立自己的信心。从怀疑自己是否能，到相信自己能，最后内化成不再需要强调这件事。

提升认知

一定要搞明白：英语是技能，不只是知识。技能意味着，不仅要输入，还要输出，且需要反复地练习。

所以，在学习过程中，一定要让输入与输出闭环：如果想提高听力，就要辅以口语练习；如果想提高阅读能力，就要做相应的写作练习。

整个过程中，强调的是实践，是行动力，而不是记忆力。不要妄想把大量的知识装入脑子里——那是没用的，因为它不属于你。只有经过练习、能说出来或写出来的东西，才是你的，才会内化成自己的能力。

以上认知很重要，如果不能达成共识，那后面的方法对你是无效的。

明确意义

需要问一下自己，英语对自己而言到底是什么？

是考试、考证上分的手段，还是升职加薪的工具，抑或是丰富自己、了解另一种文化、开阔视野的方式？

上面只是举例，并且例子之间并不冲突，是可以兼容的。

总之，对这个问题的回答，反映了个人动机，对行动力有很大的影响。

制定计划

整个学习过程是超过一个月的，对于这种时长的事件，是需要制定计划的。

说直白了，就是要拆分目标，评估工作量，然后按计划执行，并能在实践中结合自身情况动态调整。这种能力，不仅是学英语，学任何东西都是适用的。

培养习惯

注意培养自己的习惯，利用惯性帮助自己坚持，减少半途而废的可能。

建议固定时间、固定地点来学习，可以结合自己的日常作息规律，养成一个新的习惯。如每天早上起来，或晚上洗完澡后，固定抽时间来学习。

注重方法

前面说了那么多，都是内功，放在前面，是因为我认为心态建设、认知及习惯比方法更重要。

至于学习方法，因学习内容而异。按照知识体系划可大致分为：

• 基础知识：
  • 音标
  • 单词
  • 语法
• 综合能力
  • 听说
  • 读写

基础知识是一定要掌握的，而对于综合能力，基于实用主义，不同目的可有不同的侧重。简单来说就是：

• 如果需要利用英文资料学习、工作，或想阅读英文原著，或只需与人进行文字交流，应侧重读写
• 如果需要与人进行即时言语沟通，或想看“生肉”，或想听英文有声读物，应侧重听说

今天主要是作为开篇，做个介绍，具体的方法，会在后续的内容中逐步展开。

方法

音标与发音是最基础也是最重要的环节，侧重听说的同学，一定要掌握好；侧重读写的人，也不能懈怠，因为这跟后面的单词学习有关系。

我推荐根据赖世雄的《美语音标》进行学习：

• 在微信公众号 常春藤英语集团 买相关书籍
• 在 喜马拉雅 或 B站 听相关音频，进行跟读练习
• 下载 谷歌翻译 app（或别的app），设置成 英 => 中 翻译，检查自己发音正确，翻译软件能正确识别就算合格

有人可能会问，赖世雄是谁，没听说过啊。这是可以理解的，因为在进行这样的学习之前，我也没听过，但他却是中国十大名师之一。他最励志的经历是，一个在高考英语中只能得7分（满分100分）的人，经过学习，成为英语教学硕士。这是典型的后天成才的前辈，跟着他学，经过本人亲自验证，绝对靠谱。

我给出了我之前的学习进度记录，仅供参考

学完之后，如果有兴趣，可以了解下进阶内容。American pronunciation workshop：https://www.bilibili.com/video/BV1qE411v7oE
（我特意找了没有字幕的视频，建议就这样看。如果是侧重读写的同学，直接跳过就好）

再给出关于音标的一些资料：

• 音标发音大全 48个英语音标表（IPA,DJ音标,KK音标对照表）
• 一文理解IPA音标、DJ音标、KK音标的区别

讨论

这里我补充几点，虽然不是核心，却与主题息息相关：

1. 是否要买实体书？
2. 为什么是美语，而不是“英语”
3. 关于口音（accent）

建议买实体书

现在网络这么发达，信息随处可得，所以很可能你不愿意买实体书。

这样也行，但我仍然建议买书，反正我买了全套，因为我认为从某种意义上讲，实体书有助于提升行动力。还记得前面我们讲到过，整个学习过程强调的是实践，行动力或执行力是很重要的。而购买的动作，本身就是执行力的一种表现。

而相对的，白嫖的行为背后，隐含着不愿意付出的意味，这种思维本身是不可取的。当然，这也许是我过度解读，你可以继续白嫖。

不想买实体书的另一个原因是，书多了不方便，比如搬家很麻烦。对这个问题，我是这样处理的，仅供参考：

• 捐书
• 送人

美语是主流

也许有人认为英音更好听，某些时候，我也赞同这个观点。但我们还是实用主义，现在西方世界谁说话最大声，大家都清楚。毕竟“日不落”已然衰落，现在还是美刀更好使（还在说刀的事，手动滑稽）！所以，美语才是主流。

一定要学英音的，建议通关后重修发音，或现在就另找门派学习。

不要纠结口音

在国内的网络平台上，很常见的场景是一群人对某个中国人的口音评头论足，说什么“这个不正宗、不地道啊”，“你这个也不像美音呀”、”工地散装英语哈哈哈“。

我都不知道这些人在纠结什么。谁说话没口音呢？你作为中国人，能跟新闻联播主持人一样说普通话吗？你不也带点地方特色？就算是美国人，不同的地区，也有不同的口音，你说谁才是正宗的呢？

语言最重要的功能是沟通，能让别人听懂是首要需求——如果你的口音并不影响别人听懂并理解你，那就不用纠结它。这也是前面为什么我建议下载翻译软件的原因，让机器来判断你发音是否正确，免去担心自己口音的困扰。

总结一下，今天分享了音标学习的方法与经验，后面将分享单词的学习。

方法

单词是听说读写的基础，是有必要花时间去学习的。

然而，我不太喜欢使用“背单词”这样的描述，因为这会显得是在死记硬背、追求机械的记忆。对于单词的学习，我有以下建议：

1. 请务必打好音标基础。一个单词如果你不会念、你听不出来，那就没有真正的掌握
2. 结合上下文理解。一定要把单词放到句子里去学习，而不要只看英文单词选中文含义（或反之），因为英文单词与中文词汇并非一对一的关系，并且这样只是记忆，没有获得理解。
3. 只推荐利用词根记忆（当然并非百分百有效）
4. 学习软件：欧路词典——免费，全平台通用

以手机欧路词典为例，打开后，点击“学习”，选择适合自己的单词本（或先做测试让软件来推荐），进行学习即可。

注意结合个人情况，进行学习设置，例如学习新词数量及、复习数量。

就我个人而言，我的做法是把全部单词刷一遍，过滤掉我完全掌握的，然后再进行新词的复习。

提醒

必须要给大家一个提醒，避免进入单词学习的陷阱：那就是忍受不了单词学习进度缓慢、记了又忘的情况，于是追求“超级记忆术”，把单词一股脑装在脑子里。

回顾前面所说，学习英语强调的是实践，而不是记忆。所以，不论记忆方法有多高明，它只能解决输入，不能解决输出的问题。因此，我们的重点应该放在输入与输出闭环上，而不是追求单方面“多快好省”。

网络平台上很多鼓吹类似于“一天背六千个单词”的营销内容，就是抓住了人们没有正确理解的情况下贪多求快的心理，一定要警惕。

再者，单词与阅读理解，并非简单的线性对应关系，即不是单词量学得越多，阅读理解越深。另一方面来说，也不是只有单词量“爆表”，才能进行全英文阅读。

以我自身为例，我可以阅读原著，但我的词汇量不过四千左右。

我之前在某个词汇量评测网站做过评估：http://testyourvocab.com/result?user=13229458

4360 是网站为我估算的单词数量。

为求精确，我还找了一本考研（包含了高考、四级、六级、考研词汇）的单词本，把上面的所有单词刷了一遍，结果如下：

上图的含义为：

• 0 个未学习，意思是单词本的所有单词我都遇到了一遍了，并且我都进行了掌握程度判断
• 已掌握 3844，意是这些单词我一看就能知道是什么意思，并且能做翻译
• 学习中 4122，具体又可细分为：
  • 认识：一词多义，仅知道部分的中文含义，当其在另一个句子中体现另一种意思时，自己不知道
  • 模糊：原先不知道中文含义，但根据例句能隐约推断出其含义
  • 不认识：给了例句也看不懂

从上面我对学习中的单词的分类就可以看出，单词这件事，不是非黑即白的。而把单词掌握数量直接与英语能力挂钩，也是不可取的。

我在学生时代，其实没有买过一本单词本，也没有刻意地去背过单词（例如每天固定背50个），所以上述词汇量，还是挺客观的。就以词汇量而言，可能很多人都比我强——既然单词对我来说不是困扰，那对大家来说，应该也不是。我想这点信心，大家是可以有的。

总之，我想说的是，单词重要，却也不用刻意强调“背”这件事。把单词与英语能力直接挂钩，追求神奇的背单词的方法，这是很多人学英语的误区。而在这种误区下，就催生了速成的方法论，迎合了浮躁社会下急功近利的心态。但其实，强调实践，讲究输入输出闭环，才是更符合客观规律的学习方式。

记住：重要的不是你记住了多少单词，而是你能运用多少单词来造句。

延伸阅读：刷7000个单词的经验总结。

前言

听说篇相对独立，与读写篇没有依赖关系，但需要确保前面的基础已打好。

方法

听说属于综合能力，建议遵循以下学习步骤：

1. 激发兴趣，建立信心
2. 明确方向
3. 脚踏实地，坚持输入并输出

1.建立信心

首先找到有趣的音视频材料，利用生动的内容增加学习的动力。同时应注意材料的难度不应过高，有助于自己建立信心——已经很有自信的同学可跳过此步骤。我推荐以下材料：

• Journey to the West： https://b23.tv/61xkAgc
• English at Work：https://www.bbc.co.uk/learningenglish/english/features/english-at-work

前者是西游记英文动画版，后者是BBC的职场英语动画片，任选其一即可（如果是实用主义，当然选第二个啦）。
两个材料都是只有英文字幕的，要逐渐习惯这种模式。这就是为什么说学习时要注重心理建设，因为需要走出舒适区。

记住，上面给的材料，主要是帮助自己建立自信的， 学到什么不重要，重要的是你觉得自己行了，可以进行下一步了。

2.明确方向

在进行深入学习前，我们需要明确自己的学习方向，究竟是 Daily English 还是 Business English?

当然可以全部都学，但那是结果，在过程中总要分个前后。对这个问题的回答，取决于读者自己。

Daily English 我推荐：https://www.youtube.com/c/EnglishSpeakingCourses/search?query=conversation
这个视频如果看不了，可以看我写的教程：https://www.yuque.com/levy/blog/how-to-surf

Business English，我推荐 eslpod 的教材：

1. Using English at Work
2. English for Business Meetings
3. Interview Questions Answered

这里特别说下，eslpod 的创始人是英语方面的语言学及教育学的博士，可以说没有人比他更懂英语教学（手动滑稽）！跟着他学，我成功地喜欢上了美语，从此以后听加州口音会觉得最舒服。

以上三本教材我自己买了，有需要的可以私信我发你。

另外，赖世雄的《高级美语》也极力推荐，它是属于综合性的教材，内容方面起到开阔视野的作用。而我推荐它的原因是，本书北美外教的发音尤为悦耳，朗读课文时简直“说得比唱得还好听”，练习听说的同学一定不要错过。

3.坚持输入并输出

有了材料还远远不够，只是在听、光在那里看，结果还是哑巴英语。因此，对于无论什么材料，我建议这样使用：

1. 不看课本（字幕），全部语音听完
2. 看课本（字幕），做笔记，学习单词与短语
3. 慢速跟读
   1. 看课本（字幕），播一句，暂停，跟读一句
   2. 不看课本（字幕），播一句，暂停，跟读一句
   3. 看课本（字幕），不暂停，课程跟读
4. 独自念出来，并使用手机软件（如微信）录音，听一听自己说的效果，并进行语音翻译，以检测自己的输出正确率
5. 脱稿表达（此步骤可选）

在这里分享一个我遇到的“困境”。在进行不看课本的慢速跟读的练习时，播一句跟读一句的形式，让我很容易犯困。但我没有因此就放弃，也没想办法强行提神，而是转而把它当作催眠工具——困了就睡觉。这样过了两周，有一天晚上，我没有犯困，做完了训练。而那一天也是我走出“困境”的日子，后面的日子里，再也没犯困过！

其实我不止有一次类似的“犯困”经历，都是与学习新东西有关的。我想，这可能是大脑在生理上对学习的抗拒。对于新领域的知识或不同寻常的学习方式，是需要走出舒适区的，而这种“犯困”可能是大脑潜意识在拒绝走出舒适区。对此，应对方法很简单，那就是坚持下去，每天固定时间执行相应的学习动作，直到大脑潜意识“屈服”，转而适应新的东西。

以上就是今天要分享的关于听说练习的内容，下一期将分享英语读写的学习经验。

前言

读写篇相对独立，与听说篇没有依赖关系，但需要确保前面的基础已打好。

阅读能力升级之旅

我先给出自己经历过的全英阅读能力的变化过程，仅供参考：

1. 看到英文网站，第一反应是点击切换中文版
2. 一些技术资料、技术文章，往往是英文，没有翻译，只能硬着头皮借助浏览器的翻译或词典进行全英阅读
3. 适应了阅读英文技术文档、英文技术博客，但看非技术领域的内容，如在 wikipedia 上查某个人物、某部电影，第一反应是切换中文版（此时对英文的阅读只停留在自己的专业领域）
4. 尝试阅读全英书籍。其实看得明白，但总觉得太慢了、是不是在浪费时间、好想看中文版，需要耐着性子阅读
5. 阅读量到达一定后，开始对内容挑剔，如认为议论文没有生动的例子不吸引人，或内容充满说教不想看，于是开始学会挑重点，跳过不重要或没兴趣的内容，不再逐字逐句阅读
6. 阅读英文在感观上跟阅读中文没有重大的区别，也即看到英文内容，不会再想“这是英文，不是中文哦”——翻阅内容，看就完事了

这是怎么做到的呢？我主要采用了以下方法。

阅读方法

建立信心

如果之前读者并没有全英文的阅读体验，建议先根据兴趣选一本书（或阅读材料）后，在两周内读完它——无论用什么手段，一定要在该时间段内完成。此举似小实大，有两点内涵：

• 时长再拉长，你很可能读了后面忘前面；时间越长，越拖延，则两相结合，很可能最终放弃了阅读
• 在较短的时间内读完，能快速建立信心，为后续阅读打下基础

第一本书或阅读材料很关键，感兴趣是最重要的，当然也可以结合后面提到的蓝思值进行选材。

我当初使用的是 轻听英语 app，在上面看完了英文文字加语音版的死亡笔记。看完后感受如下：

• 一开始的阅读速度比音频的播放速度还要慢，如果没有兴趣，很可能就没耐心了
• 因为是动漫的文字版，除了画外音（内心的独白），几乎全是人物的对话，这些内容是很容易理解的

之后我信心大涨，用一周时间，把魔兽世界官方小说《Arthas: Rise of the Lich King》原版看完了。

根据蓝思值选书

有了信心之后，我们就可以科学地、有节奏地培养自己的英文阅读能力了。

核心思路是评估自己的阅读蓝思值，再找到适合自己的阅读材料。什么是蓝思值呢？

假设你的阅读水平是 600L，那么蓝思值在 550L~700L 的阅读材料比较适合你。再低就太简单，达不到提升的效果；再高就超出阅读能力太多，很可能读不下去（因为我们在讲全英文阅读，所以我就不翻译了）。

综上所述，推荐按以下步骤提升阅读能力：

1. 评估自己的阅读能力 https://readtheory.org/
2. 找到自己感兴趣的读物，通过网站判定书籍的蓝思值是否合适 https://hub.lexile.com/find-a-book/book-results

相关的 app 我推荐: 轻听英语，里面的书都是免费的。当然大家也可以推荐别的 app，直接有标明蓝思值的就最好不过了。

巧查生词

阅读的一个拦路虎是生词。大家的第一反应是认为生词太多，看不懂，很容易放弃。

首先，我推荐欧路词典。如果是在电脑上看 pdf，鼠标选中区域就能查词或翻译，非常方便。

再者，表达一个观点：有些单词不认识，甚至有些句子无法理解，并不影响对情节的核心内容的理解。事实上，除去欧亨利式结尾的短篇小说，书的内容越多，其核心内容越不容易受生词影响。因为主题是贯穿全文的，前面因为生词没看懂，后文换了个说法，你就能看得懂了！

因此，对生词，我建议：一页只查一个生词。它的意义是：

1. 你不会因为频繁查生词而影响阅读体验。事实上，试图把每一个生词都查一遍，是阅读不下去的主要原因！
2. 因为查词机会的“稀缺性”，你把机会留给你认为最有价值的生词
3. 强迫你的大脑思考，如何在带着许多“迷雾”的情况下，去理解句子、段落，抓住故事的核心情节，理解书籍的中心思想

在阅读《Arthas: Rise of the Lich King》的时候，我的体验就是：

• 有些形容词或副词不认识，并不影响理解句子的大意
• 阅读几章后，为加快阅读速度，只出现一次的生词，我不再查字典——我只查出现过至少两次的单词
• 再看到后面，有些单词不认识，我都懒得查了，反正不影响我对整体剧情的理解

阅读材料推荐

如果实在找不到全英阅读材料，我推荐看《现代大学英语精读(第2版）》, 我已经挑选了值得一读的文章，英语高考有120分或过了四级的人，应该可以直接点击查看。

写作

阅读是输入，写作是输出，二者是相辅相成的。 对于写的能力，推荐从读书笔记开始做练习 （就像看完中文书那样做笔记），也可以找机会与人发邮件。

读书笔记示例：

这是我购买 eslpod.com 教材时发的邮件：

这是我申请 JetBrains 正版授权时发的邮件：

还有一种方法， 那就是利用软件的翻译功能，把自己写的中文笔记，翻译成英文，再去校对、修改。很多文本类 Web 应用都有此功能，可以利用起来。
这种方法本质就是，自己一开始不知道英文文章写什么，那就从校对、修改开始做起；自己不能写完整的英文文章，那就从摘取段落开始做起。适应这个过程后，写作的障碍就减少了。

总结一下，英文读写的提升需要踏出舒适区，要耐着性子，不要怕慢。坚持去做，量变终会有质变！

前言

之前有提到过两个英文能力评测的网站，分别用于评估蓝思值与单词量。实践中我发现有些细节可能会被大家忽略，故写下此文，以作手把手教学之用。

单词量

进入网站：https://preply.com/en/learn/english/test-your-vocab

看到如图所示区域，开始勾选单词，规则很简单：一眼看上去认识的就勾选，不认识、犹豫的都跳过，之后点击红框处继续。注意，千万不要勾选的过程中去查单词。

在下一页，重复上面的步骤，之后点击 Continue，等待几秒钟，就会出现评估的单词量。

对于该结果，网站有以下值得注意的解释：

1. 结果偏差在正负10%左右：

Your vocabulary count has a margin of error of approximately ±10%. We also round results above 10,000 to the nearest 100, and results above 300 to the nearest 10.

2. 英语非母语者，用单词量作为能力标准通常划分如下：

3. 结果一年测一次最有效

阅读能力

评估阅读能力也就是评估蓝思值。进入网站：https://readtheory.org/

右上角点击注册：

选择作为学生：

可以直接使用谷歌账号注册：

如果不能谷歌，可以看我写的谷歌教程：https://www.yuque.com/levy/blog/how-to-surf
或者自己填表单，进入下一步。

确保自己至少有20分钟的空闲时间，之后点击已经准备好了：

开始做题，一共8道，看不懂就乱选，后面的题目会根据你的答题情况自动调整：

做完后，点击确认：

点击下图红框处：

往下翻阅，即可看到自己的蓝思值初步评分：

再给出通用的蓝思值能力对照表：

以上就是今天的英文能力评测手把手教学啦，希望对大家有所帮助。

这周算是完成了今年定下的刷单词的任务，写篇文章总结下，为这件事划上一个句号，也给有需要的人一定的参考价值。

首先，解释下为什么完成度不是100%，我也称之为完成任务。因为软件出问题了（又或是我使用方式问题），剩下的单词无法进行学习了，进度条止步于此。我也不想纠结于这一点，就这样吧，算是残缺美。

再者，说明下为什么要做这件事。主要原因有三：

1. 主动扩充词汇量，与英文阅读相辅相成。诚然，可以一边阅读一边积累词汇，但这种方式我认为是“被动”的，并且有看我之前英文阅读经验分享的朋友，会知道我阅读时查词的频率很低的，如此增加词汇量的效率太慢。另外，词汇又有高频与低频、重点与非重点之分，而这是单词本的强项，因此利用单词本是接触“精华词汇”的高效方式。
2. 我想知道自己确切的词汇量。虽然在之前分享的在线工具中，我评测过自己的词汇量（7000），但自己感觉有点“虚”，一方面误差有10%，另一方面我觉得波动太大了（两年前测是4000），不太相信，于是打算用刷单词本的“笨方法”去确认自己的词汇量。
3. 我想体验一下刷单词本的经历。这点我在之前的文章中也透露过，我在学生时代是没有买过单词本、也没有拿着单词本去背诵过，基本都是靠音标+词根，边学课文时边记忆，讲究的是一个自然，没有刻意。然而，这隐约有种“不踏实”之感，没有经过刻意练习，似乎得来的单词“不会珍惜”，于是便趁这个机会把这个经历补上。

最后，我想强调的是，注意我“刷单词”，而不是“背单词”这种描述上的差别。“刷”重在强调，过一遍，有个印象、能认识；“背”强调的是死记硬背，机械地记忆——虽然我认为练习需要刻意，但却不认为它等同于死记。

很多人在学习单词觉得很痛苦，半途而废，很大的原因是强调背，把内容强塞进脑子里很让人痛苦；而背了又忘，更是让人感到强烈的挫败感。在这里，我想分享的经验是，此时需要进行思维的转换：你允许自己忘记某些单词。可以把新单词想像成陌生人，总有人能与你成为好友，总有人不能给你留下深刻印象，总有人与你相处不愉快——这么多单词，你先认识容易认识的，很难“相处”、容易忘记的单词，后面再说呗，没必要一口气吃成胖子。

为了减少痛苦，我有以下经验，它们是属于启发式的（heuristic），仅供参考。每个人应总结符合自己的经验，其核心思想是分层次、分类，不要一刀切。

对单词的掌握程度区分优先级：

• 读：阅读时能看懂是什么意思；就算第一眼看不出单词意思，结合上下文能推测出意思才行
• 听：别人正常语速、慢速说时，自己能听出这是哪个单词
• 说：我不对此有强制要求，看着音标能发音即可，因为当前我的英语实践场景中，并不侧重说
• 写：此优先级最低，因为写作不是考试，我完全可以查词典，因此有些词很难记我就索性不记，如官僚主义（bureaucratism）、资产阶级（bourgeois）——我能听、阅读，但放弃掌握写

对词意进行分类掌握：有的词十几个意思，你哪能一下子全记住？

• 结合相应的例句，一次只记一个意思
• 常见的词意，优先记住
• 冷门的词意，可以跳过
• 另外，有些中文词意解释很牵强，可以找英英释义

对词汇进行分类掌握：识别出单词属于哪个领域的

• 计算机、法律、经济、日常生活、文学等领域的词汇，我放在较高优先级，尽量去掌握
• 医学领域、非考试重点词汇，我不太重视，能认识就认识，觉得认识上有困难就跳过

当然，单词不能纯刷，要结合阅读一起来做。我选择的是外国语学院的英语专业教材《现代大学英语精读》，二者结合，相辅相成。

还有就是，最好固定时间段，以便形成习惯，如上班坐地铁，或晚饭后等较规律的时间段。

最后，我想说的是，刷了这本单词本，并不意味着我就 master 7,000 English words。它对我而言，更多的是在英语学习经历上，具有里程碑的意义。回顾一下，从2022年2月份开始到，到现在历经大约7个月，我算是把英语单词这件事的“遗憾”给补上了，此事至此告一段落，我可以开始新的旅程了🎉。

前言

有了 ChatGPT 后，练习外语口语的门槛再次降低，没有外语环境再也不是问题了——AI 就是你的专属私教。

本文将分享借助 AI 进行口语练习的一些工具、方法与实践经验，仅供参考。

准备工作

在开始之前，要准备好几样东西：

0. ChatGPT, 如果没有账号或不能上网，请查看上网教程
1. Chrome 浏览器插件 voice-control-for-chatgpt
2. 口语练习题，根据个人需求查找即可，下文将以雅思为例进行说明

安装好插件后，打开 chatGPT 界面，下方就会出现语音输入按钮。

常用Prompt

下面总结了常用的 Prompt，可以有根据需要进行使用或调整。

设置角色：

1. Please act as an English teacher.
2. Please act as an English-speaking test examiner.
3. Please act as IELTS speaking test examiner.

进入一问一答模式：

1. You're supposed to asked me questions and wait for my answer. The next question is: xxx

对回答进行完善：

1. Please revise my answer
2. Please modify my answer to make it more fluent

对回答进行评分：

1. Please rate my answer

进行对话

第一句话，是设置好 AI 的角色，让它扮演口语考官。

可以使用以下 prompt:

可以看出，语音转文字出现错误，单词 IELTS 始终未能正确识别，但 ChatGPT 却能明白其中的意思。

开启语音插件的意义在于，如果语音识别不了自己说的话，很有可能是自己的发音有问题，起到提醒自己纠正发音的作用。另外，ChatGPT 回复的文字，也会转换成语音输出，顺便练习了听力。

根据练习材料，让 AI 问自己问题。

记得让 AI 对自己的回答评分，可以使用以下 prompt：

进行下一个问题：

上述回答不太好，AI 给出了理由：

修改后再回答，有所进步

再问下一个问题：

这个回答同样不理想，但看了提示也不知道要怎么改：

此时可以新建一个聊天窗口，让 AI 提供示例回答：

根据示例答案，结合关键词，重新组织语言，切换回原聊天窗口，再回答一次：

有所进步！

有时对话长了，AI 会“糊涂”如下所示：

此时要重新强调它扮演的角色，让其回忆起上下文，可以使用以下 prompt:

除此之外，就没啥值得注意的了。重复上述过程，不断练习即可。

记录回答

做完了练习，还要作笔记。但在记录回答之前，还要润色一下，毕竟口语表达的时候，可能会存在语法错误。

进入 https://quillbot.com/，把答案复制上去，先进行语法检查：

再进行流畅度润色：

最后保存到笔记本上即可。

Arm 是另一种CPU架构（CISC），与常见的 x86 有所不同（RISC）。

跟我们有什么关系呢？

1. MacOS 的 M1 芯片是基于 Arm 的
2. 云厂商及生态都在积极与 Arm 进行合作
3. Docker 镜像的构建有注意事项

构建镜像时，为 Arm 平台构建镜像时，常见的问题：exec user process caused: exec format error。
这是因为试图在 x86 机器上执行对平台有依赖的命令，如 shell 命令。

解决办法就是，想办法把相关命令前置，提前执行，再构建镜像。

如注释掉 Dockerfile 里的　Run chmod 777，改成在构建镜像前执行。

视频里有更详细的讲解：

前言

把静态资源放到云厂商的对象存储服务中托管是很常见的实践，但由于涉及的事项较多，故记录下来，方便查阅。

本文主要以阿里云OSS的控制台界面作为操作示例，其逻辑同样适用于华为云OBS、Amazon S3，只是可能界面上有差异，具体需要看相关的官方文档。

阿里云OSS

对于新建的bucket，需要做一些设置，才能正常使用静态资源。

绑定域名

则使用自定义域名访问，可以解决访问 html 变成下载的问题。

CNAME设置

如果绑定的是同一个阿里云账号下的域名，则可以自动添加 CNAME 记录。否则需要手动添加。

查看 bucket 外网地址：my-bucket.oss-cn-shenzhen.aliyuncs.com

则去域名解析供应商设置：
static.domain.com(自定义域名） -> CNAME -> my-bucket.oss-cn-shenzhen.aliyuncs.com

HTTPS证书托管

上传证书，开启 HTTPS

如果没有证书，查看教程获取：🔒免费开启HTTPS

公共读

这样可以解决访问链接超时的问题。

CORS跨域设置

在基础设置下，找到跨域设置

在来源中设置域名，或ip地址。下面给出最简单的示例为 *，实际可以根据需要填写允许的域名，一行一个。

• 将allowed origins设置成 *
• 将allowed methods设置成GET, POST, PUT, DELETE, HEAD
• 将allowed headers设置成 *
• 将expose headers设置成
  • etag
  • x-oss-request-id

这样可以解决字体无法显示、JavaScript跨域的问题。

华为云OBS

跨域设置

华为云的入口如下：

具体规则的填写是类似阿里云OSS的。

misc

存储多份 docker 认证信息：

使用：

get-version.sh

build-image.sh

support command:

build-image.sh (remember to replace xxx with true value)：

startup.sh

startup.sh

背景

当你为 LLM 应用构建镜像时，发现整个过程很慢，一看镜像体积：好家伙，1.76 G！

能不能减少镜像体积，缩短打包时间啊？本文将分享两招实用的技巧，让 Python 应用的镜像体积减少 50%。

原始Dockerfile

先来看看 Dockerfile 的原始模样：

使用slim镜像

最简单快捷的优化方式，是修改第一行代码，使用 slim 镜像。

重点是：为什么用 slim，而不是 alpine？

这里我们就要搞清楚，Alpine 是 Linux 众多发行版中的一员，与 CentOS、Ubuntu、Archlinux 之类一样，只是一个发行版的名字，主打一个小巧安全。

然而，alpine 镜像有一个陷阱，它使用的标准库与大多数发行版不同，它使用的是 musl libc，与常用的标准库 glibc并不兼容。

而在 alpine 镜像中，使用 Wheel 文件(后缀为 .whl) 安装 Python 依赖时，可能会出现兼容性问题，因为 Wheel 会与 C 语言的扩展库有关联，而这些 C extensions 不一定与 musl libc兼容，尤其是使用到了 NumPy、 Pandas 的时候。

那么为什么 slim 镜像又可以呢？因为 slim 镜像是基于 Debian 的, 使用的是 glibc，通过删除了许多非必需的软件包方式，优化了体积。

因此，在 Python 中，最稳妥的做法是，做 slim 镜像，而不是 alpine。

减少层数、取消本地缓存

来看这两行代码：

安装依赖，应该一步到位，我们可以把这两行压缩成一行，以减少 docker layer 数量。

另外，pip 安装依赖时，会在本地生成缓存，而这对于镜像来说是无用的，可以添加参数 --no-cache-dir禁止此行为。

则上述两行代码优化如下：

优化效果

第一次优化，使用 slim 镜像：

第二次优化，减少层数、取消本地缓存：

小小的改动，大大的变化！

参考

https://icloudnative.io/posts/intro-guide-to-dockerfile-best-practices/
https://icloudnative.io/posts/docker-images-part2-details-specific-to-different-languages
https://www.ardanlabs.com/blog/2020/04/docker-images-part3-going-farther-reduce-image-size

结论：如果可移植性很重要，那么应该使用 sh！一般编写 Dockerfile　时，有关的脚本优先使用 sh。

常见问题：明明是存在的、可执行的shell脚本，却在容器报错 No such file or directory，很可能是因为shell脚本开头声明了bash，但容器里只能执行 sh。

视频里有实战演示：

• 📦vue组件发布npm最佳实践
• 🔨揭秘vue-sfc-cli：组件研发利器
• 🚀Github集成TravisCI：自动发布
• ⚡Github集成Netlify：快速预览PR
• 🌪自动化的Github Workflow
• 🤖如何写一个GithubApp
• 🔒免费开启HTTPS
• 🕸捕获与改写HTTPS请求

本文将分享常用的 Web 页面性能分析工具，以及一个前端项目性能优化的实战经验。

检测

使用两个工具分析项目首页性能情况：

1. https://developers.google.com/speed/pagespeed/insights/
2. https://tools.pingdom.com/

得到结果如下：


可以看到，首页超过50%的请求都与图片有空，优化空间比较大，因此第一步应该是优化图片加载。

图片优化

关于图片，PageSpeed 的优化建议如下：

根据文章《把图片优化指南做成一个组件：v-img》，找到首页的图片相关的代码：

1. 把 <img>  元素修改成 <v-img/> ，注意设置 width 或 height
2. 把 <div ``style="background-image: url(img-url)"``></div> 修改成 <div v-img="{src: img-url}"></div>

注意：img-url 应该是 oss 的链接，并且是 https 协议。
如果是 http 协议，或不指定协议 //img-url，则很可能会出现下图的情况：

如果图片是放在项目中，且项目并没有部署到 oss，则无法享受自动加载 webp 格式图片的福利。

则在此环节，一次性做到了上图中的三个优化点。

提高TTFB时间

来看下一条优化建议：

因为项目是服务端渲染的，有些请求是在服务端做了。找到相关代码：

经过分析，上述代码存在两个问题：

1. 可在客户端执行却放在了服务端
2. 可并行执行却写成了串行

修改如下：

通过分析请求日志发现，有一个请求应该是在客户端发送，代码本意也是在客户端执行，却在服务端也执行了。
找到发送请求的代码：

原来是代码写在了 created 里，这是个经典的案例：为了让请求更早一点发送，不写在 mounted 钩子，而写在 created 里，导致请求分别在 server-side 与 client-side 都执行了。具体说明请看 vue ssr 官方文档。

修改如下：

移除未使用的 Javascript

来看下一条优化建议：

因为经过多次迭代，有可能某些功能曾经上线过，后来被下线，但当时代码没删干净，所以留下一些现在没用的第三方库。根据建议，找到这些引入的 js，确保不影响正常功能后，删除即可。

此时注意用到以下基本操作：

1. google/github 查询库的用途
2. git history/annotate 查看是何人何时引入、并在何处使用的，如何代码不能表明意图，则最好找到相关人员询问是有何意图。

延迟静态资源的加载

来看另一个相关的建议：

如果有些第三方 js 确实有用到，但却不是关键资源，则可以延迟其加载或解析时机，缩短阻塞时间。

以一些第三方代码为例，它们并不是关键资源，可以在 window.onload 事件触发后，再加载

启用文本压缩

首先是启用文本压缩，采用 gzip 是最简单的方式。对应的请求头是：Content-Encoding

因为静态资源是放到对象储存服务上的，故应该修改相关的配置。

• 如果是阿里云OSS，点击查看参考文档
• 如果是华为云OBS，点击查看参考文档

这里要注意的是，对于静态资源的访问，最好使用自定义域名，而不是存储桶的域名，方便CDN做加速优化。

优化缓存策略

下一条相关的优化建议是缓存策略，对应的请求头是：Cache-Control

简单来说，就是在静态资源（html 除外）的 HTTP 响应头中设置如下字段：

以阿里云 oss 为例进行说明，其他静态资源存储如 obs、S3 都是同理。

对于少量的资源，可以进行手工操作。打开 oss-browser，找到相应资源：

本中使用的 oss-browser 版本，一次只能对一个资源进行 HTTP 头的设置，操作十分不便，可以登录阿里云控制台进行批量操作。

当然，最根本的解决办法，是使用 阿里云oss命令行工具 上传的时候就进行设置。

注意，在命令行里别乱设置 Content-Encoding:gzip，否则会出现下面的情况，页面都打不开，具体说明查看详情

Git最佳实践

精简提交

一次只提交一个“瘦”的功能，同时只包含相关改动文件。例如，对于两个错误的修复应该进行两次不同的提交。
如果发现写提交信息时，需要写两点以上;  则可以考虑拆分提交。

频繁提交

一次提交应只对应一个“瘦”的功能。从而达到频繁提交的目标。
经常性地提交改动可以确保不会出现特别庞大的提交，同时也可以比较精准地对应到所需要的改动上。

此外，通过频繁地提交也可以比较快速地和其他开发人员来共享你的改动。同样也会避免在整合代码时出现过多的合并冲突。相反的，非常庞大的提交会加大整合代码时出现冲突的风险，解决这些冲突也会非常复杂。

不要提交不完整的改动

虽然原则上来说不要提交一些还没有完成的改动，但是对于一个非常庞大的新功能来说，也并不意味着你必须整体完成这个功能后才可以提交。恰恰相反，你必须把那些改动正确地分割成一些有意义的逻辑模块来进行频繁地提交。

如果你仅仅是因为急着想要下班，或者是想要得到一个干净的工作副本（比如想要切换到另一个分支上），你可以利用 Git 所提供的储藏（Stash）功能来解决这些问题。切记不要把那些不完整的改动提交到仓库中。

提交前测试那些改动

不要理所当然地认为自己完成的改动都是正确的。所有的改动一定要通过彻底地测试才表示它真正地被完成了。

版本控制不是备份系统

版本控制系统具有一个很强大的附带功能，那就是服务器端的备份功能。但是千万不要把 VCS 仅仅当成一个备份系统。特别需要注意的是，只能提交那些有意义的改动。

Github实例

一个功能对应一个分支

下面是好的示例： 格式化代码，也应该单独一个PR
下面是不好的示例：因为一个PR修改了不同的主题内容

提交“瘦”的PR

参考文章：https://deliveroo.engineering/2017/09/06/play-pull-request-roulette.html#ideas-to-make-your-prs-more-review-friendly
其中最重要的一点：不要一次提交一个很大改动的PR，否则别人很难 review，要学会拆分步骤。
下面是一个 PR 示例：
拆分前，包含了35个改动，很难 review

下图是拆分后：

单个PR的改动文件只有11个
每个 PR 改动的文件少了，这样 review 起来就更容易了。

使用正确的标题

相关规范看这里

另外，请回答：出于什么原因需要进行这次修改？具体改动了些什么？

• 使用一定要使用现在时祈使句（例如要使用 change ，而不是 changed 或 changes）。
• 优先使用正面肯定语句，而不是否定句。

好的示例：docs: extraQuery 的正确使用方法
不好的示例：docs: 更新不直观的例子

根据模板填写PR描述

这是我们 Github 的 PR 模板，融合了我们的最佳实践
下面是实际的好的例子

自动关闭issue

当pr合并时，将自动close issue

1+2 review 规则

1 是指发起 PR 的人，2 是指进行 code review 的人。也即，每一个 PR，至少要经过两个团队成员 approve 才能合并。

上面是针对 github 的协作，项目组中可酌情变为 1+1 规则

礼貌提问

在 github 向人提问时，需要有礼貌。当提出 feature request时，还要说明自己的情况，尽可能提供更多的信息给对方。

上面的示例有三个重点：

1. 开头表达感谢
2. 中间说明己方的使用情况，并给出相应链接
3. 最后参考业界已有实现，给出一个方案设想，并给出相应链接

学习资源

• Pro Git
• https://learngitbranching.js.org

前言

合并时代码常见问题是冲突、提交错代码以及合并错分支，本文将说明这些问题的解决方案，为代码合并打下坚实的基础，以应对未来可能出现的分支模型多样化、协作流程复杂化的场景。
在说明问题前，先定义一些概念：

• feat：指代功能分支
• dev 与 test：指代两条不同的长驻分支，它们具有以下特点：
  • 受保护，不能直接推送
  • 不会被删除
  • 二者之间不直接合并，也即合并方式一般是 feat -> dev，feat -> test
• MR：merge request。代码合并请求

以及说明本文解决冲突涉及到的工具及平台：

• 使用 IDEA 解决冲突（JetBrains系列的工具都适用）
• 使用 GitLab 托管代码

功能分支合并长驻分支冲突

这是最常见的场景：feat1 与 feat2 并行开发，当提交MR（ feat1 -> dev ）时，发现冲突了，无法合并。
下面先给出解决思路，再给出图文操作步骤。

解决思路

1. 因为合并的方向是 feat -> dev，所以解决冲突应该是在本地 dev 合并 feat
2. 又因为本地 dev 不能向远程推送，因而需要基于 dev 切一个新分支 conflict/resolved
3. 推送 conflict/resolved 分支
4. 提交 MR：conflict/resolved -> dev

操作步骤

1. 本地切换到 dev 分支，更新代码
2. 合并相应的 feat 分支

1. 弹出冲突提示，点击合并

1. 首先处理无冲突的代码，点击下图红框处

1. 再根据情况，选择合并代码或丢弃代码。

1. 在 dev 分支上切出新分支，推荐命名为 conflict/xxx

1. 推送代码，提交MR（conflict -> dev)，记得勾选合并后删除

功能分支被污染

分支一多，人难免失误，很可能造成 feat 分支被污染，即当提MR（feat -> test）时，出现不想合并到 test的代码或提交记录。
这种场景的出现可能有多种原因：

1. 研发过程中出现误操作，如出现了 dev -> feat 的合并
2. feat 分支的基线分支搞错了，如从 dev 切出了 feat

解决思路

1. 基于目标分支如 (test 分支）切一个干净的分支 clean
2. 使用 cherry-pick，挑选自己想要的提交
3. 再提交MR（clean -> test）

注意的是，要按提交顺序进行 cherry-pick，以避免遗漏或出错。

操作步骤

1. 更新目标分支（在这里是 test）

1. 基于 test 切新分支，这里示例命名为：clean

1. 在拥有最新代码的分支（这里是 feat） 找到并选中相应的提交记录
2. 右键，点击 Cherry-Pick
3. 则相应的提交记录就会合并到 clean 分支
4. 推送 clean，提交MR（clean -> test）

挑选别的分支部分代码合并

有可能会出现这样一种场景：

• 最新的生产代码里，假设版本为v1.3.0，包含了 feat 分支的代码
• 为了减少分支的冗余，代码一旦上生产后，就会清除相应的功能分支，也即此时仓库里没有 feat 分支了
• 客户方部署的版本代码为 v1.1.0，而客户不想升级到最新的版本，只想要 feat 分支相应的功能

此时该如何是好？

解决思路

其实只要触发“挑选”关键字，就可以考虑使用 cherry-pick。
feat 分支就算被删了，只要提交记录还在，那也没关系：

• 在v1.3.0 的代码库中，按分支筛选，找出 feat 分支对应的提交记录
• 通过 cherry-pick 把 feat 分支的代码合并到客户方的代码分支即可

注意：毕竟跨越了版本，无法保证合并过去后的代码一定能正确工作，需要进行充分地测试。

操作步骤

此操作本质还是 cherry-pick，参考前面 cherry-pick 的示例即可。

分享两个Git的小技巧， 都是关于在 IDEA 里查看Git的历史记录的。

这两个技巧，简单却实用。面对年代久远、团队人员流失严重的代码，靠的就是这两个技巧, 从提交记录里品读岁月史书，从蛛丝马迹中寻找遗失的真相。

第一个是叫 annotate with git blame。
在IDEA的行号这个位置，右键，再点击即可。如图所示：

效果就是，每一行代码都会显示，该行代码是由谁提交的、 什么时候提交的。

在合并冲突的时候也可以用这个技巧。

对左右两边进行git blame一下， 然后就可以看到如图所示的情况：

这样就能提供更多的信息帮助解决冲突。

就算冲突无法自己解决，也至少能知道提交代码的是谁，可以找到作者去进行沟通。

当然git blame 是有一些注意点的。因为它本质上显示的是某一行代码的最后提交人， 也就是last modified的一个概念，而有些时候这并不意味着最后的修改人就是代码的原作者。

之所以这样，可能会有以下的原因:

1. 代码格式化
2. 移动代码，比如说拷贝代码、迁移代码
3. 合并代码，解决冲突

上述操作都会改变最后修改人的这个属性，但此时显然最后修改人并非原作者。

这说明，有时候仅知道了某一行代码是由谁最近修改的还不够，还需要知道某一个文件经过了怎么样的修改。

这就引出了第二个小技巧了: git show history。

点击IDEA某个文件的空白处，然后右键，选择git，然后点击 show history。

就会出现如图所示的这样的一个 git log的 界面。

那么这样就可以看到这个文件从最初到至今经历过了怎样的修改、 有过哪些人在上面修改， 从而更好的进行记录追踪。

这两个技巧， 其实是越有经验就对你帮助越大的。因为你，年限越长，你看别人的代码的机会就越； 而如果你年限尚浅的话，更多的是你的代码被别人 review。

前言

本文将列举Git常见场景，并给出相应解决方案。

约定： 下文代码块中${}里面表示的是变量，具体值视情况而定，其余的都是正确可执行的命令。

推荐： 图形化交互式Git教程

配置

Mac/Linux 用户 执行以下操作

Windows用户在桌面用户文件夹下有个.gitconfig隐藏文件，直接修改即可

补充以下内容

增强

Mac或Linux用户，推荐安装https://github.com/robbyrussell/oh-my-zsh，增强命令行体验。

记住账号密码

初始化

在项目根目录，执行以下命令

或克隆远程仓库到本地，自动初始化

本地提交

取消未暂存的修改

取消add

取消提交

或者

修正提交

适用于提交信息有误或有遗漏，需要修正最新提交信息的场景。

stash修改

适用于当前功能开发并不完整，不能产生一次提交，但却要开发另外功能的场景

恢复stash

分支管理

创建分支

查看远程分支

创建干净历史分支

删除分支

远程仓库

远程仓库管理

一般而言，称默认远程仓库为 origin，如果是通过本地 git init 初始化的，需要手动添加远程仓库

如果有多个远程仓库，为之取不同的名字即可。

之后用以下命令进行推送：

使用以下命令查看所有远程仓库

浅克隆

适用于仓库很大，对过往历史不关心，想快速克隆的场景。

克隆指定分支

适用于只想要某一分支代码的场景。

克隆失败因为文件名太长

报错信息为：error: unable to create file xxx.java: Filename too long

注意，如果是使用 IDEA 进行克隆，很可能会看忽略该报错，但可以根据以下经验加以验证：如果 git clone 完成后，工作区并不干净（可以用 git status 检查）、不能切换分支，说明很可能就是上述情况。

强行推送

适用于本地开发了一段时间，最近才在代码托管平台上初始化远程仓库的场景

取消错误的推送

适用于推送了错误的提交后, 想取消该推送的场景

标签管理

新建本地标签

删除本地标签

查看本地所有标签

推送本地标签

获取远程标签

删除远程标签

其他

cherry-pick

1. checkout目标分支(target branch)
2. 选中相应的提交记录，右键
3. 点击Cherry-pick
4. 则相应的提交记录就会合并到目标分支

merge unrelated histories

遇到上述问题时，可以使用 --allow-unrelated-histories ，如

git log 丢失最新提交

有 commit 从旧到新示意如下： c1 <- c2 <- c3(HEAD)

可能因为误操作，git reset 或 git checkout 到了 c2，此时再使用 git log，发现看不见 c3，怎么办？

可以使用

会显示出 HEAD 指针的变动轨迹，最新的变动在前面：

找到 c3 对应的 hash，checkout 即可：

查看分支创建时间

注意，本地分支可以查看到 clone 或 create 的日期：

但远程分支，并不能确切地知道分支创建的日期：

根据文件搜索历史

从所有提交中删除一个文件

如果代码已经推送到了远程仓库，还需要强制推送

前言

GitLab 在企业内部还是比较通用的，其 CI 用起来个人也觉得比 Jenkins 顺手，因此在这里分享一下相关的实践经验。

安装与配置

GitLab Runner 安装

进行 Gitlab CI 的第一步是要安装 GitLab Runner。如果公司、团队内部已安装过，可以跳过这一步。

这里推荐使用 docker 的方式安装，复制以下命令执行即可：

其他安装方式可查阅文档。

GitLab Runner 注册

GitLab Runner 安装以后，还要注册到 GitLab 的项目中才能使用，此步骤需要项目的 Maintainer 权限。

在注册前，可以先检查下，自己的项目中是否已有可以使用的 GitLab Runner（如果看不到 Settings，说明没有权限），如果有就记住其名字，然后跳过此步骤。

GitLab Runner 根据范围分为三种。

下面以 Specific Runner 为例进行说明。

进入项目如下界面：

拿到 URL 及 token：

执行命令进行注册:

根据提示输入内容，其中 URL 及 token 就是前面步骤中 Web 界面获取的信息。

命令行操作示例如下，注意两点即可：

1. 最重要的就是 URL 与 token，需要根据实际情况填写
2. 其他参数可以与示例完全一致

注册成功后，显示示例如下：

提交.gitlab-ci.yml

要想 Gitlab Runner 工作，还需要在项目根目录提交 .gitlab-ci.yml 文件。

建议提交.gitlab-ci.yml文件前，在 GitLab 先进行语法校验。

如果错误，会有提示。

如果配置成功，会看到 GitLab 的图标：

如果图标如下所示，说明文件有误，比如文件名开头多了个空格🤦‍♂️：

以上就是 GitLab CI 所需的基本环境配置，接下来进行实战内容讲解。

合并代码前进行检查

背景

有的产品线使用 Jenkins 进行 CI，但又没设置好相应的 GitLab 插件，于是会形成这样一个流程：

• feature 分支发起 Merge Request
• 合并至受保护的分支
• 登录 Jenkins，点击构建
• 构建失败，原因：编译报错

最后一点，非常难以忍受，因为代码已经合并进去了，木已成舟。此时面对编译报错，第一反应是解决报错，重新编译。但有没有一种可能，我根本不想要这些编译报错的代码呢？

笔者还是更倾向于防患于未然的思维模式，也即不能通过编译的代码，不允许合并至受保护的分支。而使用 Gitlab CI 来做这件事比 Jenkins 体验更丝滑，下面就来介绍一下具体的做法。

设置MR检查

进入项目如下界面：

勾选流水线必须成功。

.gitlab-ci.yml 示例

简单示例如下，根据实际情况修改：

上述示例要设置成功，还要确保 .m2/settings.xml 文件存在。

效果

当流水线还未结束时，不能提前合并代码，只能等待流水线成功。

如果流水线失败了，不能合并。

集成单元测试

核心思路就是在 CI 环境运行 mvn test。

可能遇到的问题在于，由于项目依赖关系：

1. 旧代码中运行不通过的测试影响到了 mvn test 的结果
2. pom.xml 无法读取相关的配置

首先，假设根目录为 parent，其下有三个子模块：

• a
• b
• common

每个目录都有 pom.xml，其中所有子模块的属性值都来自于 parent 目录的 pom.xml。

而我们需要进行持续集成的模块是 b，则 maven 命令应该如下：

则此时就跳过了子模块 a。

但如果子模块 b 又依赖了 common，此时 common 的遗留的测试用例报错了，那我们的解决办法只能是：一个个地解决报错。

当上述 maven 命令可以运行后，就可以修改 Gitlab CI 的配置，然后设置调度任务，让 Gitlab 每天都跑测试用例。一旦用例执行不通过，就会发邮件通知到我们。

线上发布 jar

可以在前文的基础上，设置流水线自动发布 jar。

Maven配置

考虑到一个项目A，可能划分了多个模块，并非每个模块都需要发布 jar，可以修改对应模块的 pom.xml

则在项目根目录执行 deploy 命令即可：

.gitlab-ci.yml 配置

相应的配置如下：

代码合并或有新的 commit 时，会执行流水线：

拉取最新的jar

在B项目中，如果要引用A项目打出来的 jar，记得拉取最新的版本，pom.xml 设置如下：

保存中间产物

需要保存中间产物的一个场景是，流水线分多个阶段，后一个阶段依赖前一个阶段的产物。

举个例子：某个 java 项目，需要先编译输出 jar，再基于 jar 构建镜像。

相关示例代码如下：

其他问题与解决方案

环境变量

Settings -> CI/CD -> Variables

如果想隐藏变量值，不在日志中打印，可以在添加变量时勾选 Mask variable:

Node.js

本文主要以 Java 项目为例进行 Gitlab CI 相关的讲解，如果需要 Node.js 项目的示例，可以查看另外两篇文章：

• Playwright UI自动化测试
• Postman API自动化测试

创建不了容器

ERROR: Preparation failed: adding cache volume: set volume permissions: running permission container "d1574748b77fc73a4319a45341af1f0eab983900d81885a02c017ff6c5559f28" for volume "runner-bzsttzs-project-2271-concurrent-0-cache-3c3f060a0374fc8bc39395164f415a70": starting permission container: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:319: getting the final child's pid from pipe caused "EOF"": unknown (linux_set.go:105:0s)

可以尝试的方案：

如果上述方法不行，可尝试重启 docker

本地成功，流水线失败

如果流水线编译报错，本地编译通过，不用怀疑，一定是本地的问题。

本地之所以能编译通过，是因为有缓存。如果 pom.xml 没有设置 <updatePolicy>always</updatePolicy>，编译时很可能使用的是缓存。

清除缓存拉取最新的包即可。

参考文档

• Gitlab CI 示例
• 预设的环境变量
• rules规则说明

背景

团队目前使用的 Git 协作模式是：

1. 对每个功能建立相应的 feat 分支
2. 上研发、测试、UAT环境时，分别把相应的 feat 分支合并进入长驻 dev/test/uat
3. 如有冲突，则在本地更新长驻分支 dev/test/uat，merge feat into current branch，之后 checkout 一个新分支，作为 conflict resolved 分支，推送并合并至远程长驻分支

这个模式简单好懂，且业界流行，最直观的好处是，可以满足以下需求：

1. 某 feat 合并至 dev 后，并不想合并至 test
2. 某 feat 合并至 test 后，并不想合并至 uat

本文暂且不讨论该交付理念的优劣，毕竟每个团队研发情况、交付理念都不一样。 本文关注的是，在满足上述需求的情况下，是否有更好的分支协作方式。

动机

为什么要寻求更好的方式？因为上述分支协作模式，会导致代码冲突的噩梦：

1. feat -> dev，解决冲突
2. feat -> test，又要解决冲突
3. feat -> uat，还要解决冲突

正如此文章所说，“把时间浪费在解决不必要的冲突上”。

再者，功能已经通过测试了，准备上UAT环境时，居然还要解决一大堆曾经解决过的冲突，实在不想接受这种“惊喜”（或者说“惊吓”更合适）——合错代码了怎么办？并且，这么多分支，遗漏了怎么办？这些问题可以解决，但难免有为了解决一个问题，引入更多问题之嫌。

理想中的研发流程是，测试通过后，上 UAT 的体验是平滑的，是不用担心出错的。

为此，本文思考是否存在另一种分支协作的方式。

分析

首先分析一下，“某功能测试通过但不上 UAT”的可操作方法有哪些：

1. 要上 UAT 的 feat 分支逐个依次合并至长驻分支，也即当前的做法
2. 在原计划要上的功能的代码集合中，剔除掉相应 feat 的代码，再上 UAT
3. 相应分支再次提交代码，或提交 revert commit，或屏蔽相应的功能及入口，变相达到目的

剔除代码

先来看第2种方法。filter by branch，这是最先想到且符合直觉的方式，可惜实际上 Git 并没有此功能。

想“剔除某 feat 分支的代码”，可操作方式如下，更多请参考此文章：

1. git rebase
2. git cherry-pick

git rebase要求 commit 是连续的，这对于实际不可行，因为集成分支里各个 feat 分支的提交记录掺杂在一起。

git cherry-pick是可行的。不过其思路是挑捡想要的 commit，放到目标分支，本质上并不是剔除的逻辑。

再次提交

真正的剔除逻辑，存在于第3种方法中。提交一个 revert commit，就可以把之前的代码干掉了（如果想恢复代码，需要 revert "revert commit")。

觉得 revert 可能会对后续恢复代码造成困扰的话，也可以再提交代码，屏蔽相应功能及入口。这种方式适合于功能入口少，功能本身具有类似开关特性的场景。

比较优劣

要比较上述方案优劣，本文倾向于使用功利主义的最佳实践作为指导思想——认为痛苦存在更多共同点，因而为避免消极而努力。换言之，本文关注的是，哪种方案最令人痛苦，则优先淘汰它。

还有一个指导思想：麻烦、辛苦的事情放前面；前面可以多做，后面期望少做。

当前的方式，存在最难受的问题：解决过的冲突，需要重复地解决。涉及范围：全部分支。涉及人员：所有参与研发的人员，即使他们在别的 feat 分支提交代码。

cherry-pick 依然存在要重复解决冲突的问题，且涉及范围同样为全部分支，但涉及人员减少为单人，因为只需要一个做 cherry-pick 的工作，由其解决 cherry-pick 遇到的冲突（当然，很可能需要他人协助）。

再次提交，冲突的可能性将大大减少，涉及范围：相应的 feat 分支。涉及人员：相应的 feat 分支研发人员。

也即使用再次提交的方案，痛苦将降低至最小。这也是符合直觉的：谁出问题，谁负责。某功能不上线了，这也算是“问题”的一种，则相应的负责人去处理，尽可能不影响到其他人。

至于再次提交是使用 revert 还是屏蔽功能及入口，则具体情况具体分析。

实例

下面举例说明，如何应用上述分析结果。

分支模型

长驻分支： dev/test/uat，分别对应环境：研发/测试/UAT

一个月一次的迭代开始时，都建立相应的  release 分支，命名规则可以：

• 按版本，如： release/v2.15
• 按上线日期，如：release/04-26

功能提交

每个研发人员根据相应功能，从 uat checkout 相应的 feat 分支。

每次需要集成发布时，正常的分支合并操作如下：

1. feat -> dev
2. feat -> release
3. release -> test
4. release -> uat

则冲突大多数情况只发生在第前两步，解决之后，后续上测试环境、上 UAT 环境，基本无需担心冲突。

为什么一个 feat 要合并两次？

因为要保证 release 的功能是较为完整的, 至少经过开发人员在 dev 环境的自测。

并且这样也能适应不同的功能分批提测的研发节奏。

功能回撤

当 release 合并至 test 分支后，得到通知，某功能（分支涉及 feat/unwanted）不上 UAT。

则此时，feat/unwanted 相应的研发人员，为了进行功能回滚，操作如下：

1. checkout rollback 分支
2. 进行回滚提交，或 revert，或屏蔽功能入口
3. 请求合并至 UAT（不合并至 release/分支）:

后续要恢复功能，在 rollback 分支操作，再合并至 UAT 即可。

结论

通过分析与比较，本文推荐使用“再次提交”的方式，来满足某 feat 分支合进 test，不合进 uat 分支的需求。

这样做，将改动涉及范围减至最小，涉及人员降为单人，大大减少上 UAT 时合并代码的痛苦，达到平稳上线的目的。

背景

为什么开发这个工具？主要解决以下问题：

1. 提测、上 UAT 时，避免漏合代码。
2. 代码冲突时，团队成员不用再问“解决这个冲突要怎么切分支？”
3. 一个 feature 分支要向多个保护分支提交合并请求时，减少烦琐而易错的选取分支的界面操作。

可能会有人问：为什么会漏合代码？当你在某一个迭代需要来回在不同的 feature 分支切换、一个 feature 横跨多个项目，同时你偶尔还要兼顾 bug 修复的时候，你极容易丢失上下文。
并且，不同的 feature 研发进度不一致，可能出现的一种情况是：feature A 只是合并到 test 分支，但　feature B 却已经合并到了 uat。
对此，有人问你代码到底合并了没，你怎么确认？一个个项目去相应的主干分支里查看提交历史吗？就是因为不想再这样做了，这才有了这个工具。

安装

解压zip

下载并解压文件:

• Windows
• Linux

安装git bash

Windows系统才要安装。
如果 git bash 版本不足 2.41.0，最好安装最新版本。

安装地址：https://gitforwindows.org/

配置

新增文件

复制以下内容：

对于该配置的解释，详见后文。

gitlab_token

先获取 gitlab token，操作如下：

1. 打开Gitlab，右上角点击个人头像

2. 点击左侧边栏

3. 勾选全部权限，并确认生成 token

codebases

适用于多基线的场景。

如产品默认有三个环境，分别对应三条分支 dev、test、master。
同时，又有定制化需求，专门为某一客户进行源码改动，同样有三个环境，则可能出现的配置如下：

环境变量

把 mr 可执行文件所在目录设置到环境变量中：

1. 查找"环境变量"

2. 点击"环境变量"

3. 找到 Path，点击"编辑"

4. 点击"新增"，再点击"浏览"，找到最里层的 mr 目录

（上图是示例，具体路径根据自己的情况而定）

重新打开 git bash 即可生效，记得一定要重新打开！

注：如果是 Linux，那很简单，修改 ~/.bashrc

IDEA

该步骤选填，适用于 JetBrains 系列产品，想在 IDEA 的终端中也使用 mr 命令时可配置。

File -> Settings -> Tools -> Terminal：

使用

可以不带参数运行，查看支持的命令：mr

创建MR

提示输入要提交 MR 的源分支，按回车使用当前分支：

创建成功：

可以处理同名项目的情况：

MR 不会重复创建：

分支没有代码更新时，也不会创建 MR：

查看MR

可以用来查看自己有哪些MR未合并。注意：只显示自己创建的。

• 如果可以合并，显示 [ok]
• 如果有冲突，显示 [conflict]

合并MR

{mr_url} 的值可以根据以下方式来获取：

1. create 命令成功后的输出
2. list 命令的输出
3. gitlab web界面上 MR 的 url

合并前会有确认提示：

可以取消，防止误合并：

冲突处理

解决冲突，切换分支，是很麻烦的事情，故本工具为解决冲突提供了一些辅助功能。

注意：命令行只做拉取代码、切合分支等必要操作，冲突的解决仍需要人工介入，工具不会自动合并代码的。

合并冲突状态的MR：

出现提示，是否自动切换分支为解决冲突作准备：

当然在此之前，要保证工作目录是干净的，如果有修改未提交，会中止切换分支操作：

可以使用 git stash保存修改，合并冲突后，再 git stash pop

命令执行成功时，会切换到 conflict/ 开头的分支。
此时，打开 IDE 或 Git 管理工具，根据提示把相应的分支合并到 conflict/ 分支即可。

以 IDEA 为例：

解决冲突后，再切回命令行，此时有两种选择：

1. 创建 MR，适用于自己没有权限合并的场景
2. 合并 MR，适用于自己有权限合并的场景

如果是创建，再次执行 create 命令即可：

创建的 MR 合并时会自动删除 conflict/ 分支。

如果是合并，同样再次执行 merge 命令即可，此时不用带参数：

启动参数过长

Error running OrderStartupApplication. Command line is too long. Shorten the command line and rerun.
解决方案：

1. 编辑 .idea/workspace.xml
2. 找到 PropertiesComponent
3. 添加：

或者这样：

设置JDK版本

相关报错：

• java: Compilation failed: internal java compiler error
• Cannot resolve jdk.tools:jdk.tools:1.7

解决方案如下。

1.先确保已安装 jdk。

2.修改运行设置


3.修改外部依赖设置

lombok 编译报错

前提：lombok 有maven依赖后，还要安装IDE插件

相关报错：
class lombok.javac.apt.LombokProcessor (in unnamed module @0x29f3e3c7) cannot access class com.sun.tools.javac.processing.JavacProcessingEnvironment (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.processing to unnamed module @0x29f3e3c7：

解决方案：找到相应的 pom.xml，更新依赖版本（如果没有，则添加依赖）

当然，还要确保项目 JDK 版本正确

设置启动参数

Run -> Edit Configurations
注意是 VM options

注入环境变量：spring.profiles.active=local

也可以设置 VM options，不过要带上 -D：-Dspring.profiles.active=local

栈溢出

maven build "Exception in thread "main" java.lang.StackOverflowError"

-Xss40m

不是maven的编译选项在下面

内存不足

-Xmx4011m

相关报错：
java: java.lang.OutOfMemoryError: GC overhead limit exceeded

解决方案：需要进行如图所示修改设置

热加载

相关文章：https://cloud.tencent.com/developer/article/1683029

提示：不用追求自动重新编译，手动按 build 即可。

终端加载环境变量

相关问答：https://stackoverflow.com/questions/36592226/bashrc-not-sourced-on-intellij-ideas-terminal/59138750#59138750

注意两点：

1. shell 命令带上 -i
2. 根据 shell 的版本，使用 .bashrc 或 .zshrc

添加外部jar作为依赖

如下图所示：

打开相应文件夹，选中jar即可。

文件找不到——依赖冲突

相关报错：nested exception is java.io.FileNotFoundException
这一般是 jar 包冲突。

首先确保 pom.xml 的修改已生效，再利用 Maven Helper 插件，寻找冲突的依赖，根据报错信息，把不想的包 exclude 掉，重新加载 pom.xml。

如果报错的包根本不在冲突列表里，也有可能是以下情况：

• 版本不对， 则 google 一下相关报错，设置成正确的版本
• 引入了多余的包，执行了不想要的逻辑

exclue掉：

重新加载：

自动import

文件乱码

如图所示，根据情况修改即可：

autowired 提示变量未赋值

这是因为我使用的是社区版，需要手动设置下：

该方法可以放心使用。
虽然说的是 suppress unsed warning，其实是 suppress never assigned warning， unsed warning 还是会生效的。

运行 class 找不到主类

得到 class 文件后

报错：

错误: 找不到或无法加载主类 App
原因: java.lang.NoClassDefFoundError: com/mycompany/app/App (wrong name: App)

这是因为主类并非在默认包下，故需要在正确的路径下调用全限定名。

运行 jar 找不到主类

打出 jar 后，运行失败，因为主清单找不到主类。这是因为缺少了打包配置

编译时找不到主类

表现：Maven 有相应的 jar，IDEA 能自动 import，编译时却报找不到类 NoClassDefFoundError

实例：flink-quickstart-java 项目就是如此。

原因：这跟 Maven 依赖的 score 有关，因为 pom.xml 对依赖的 scope 定义为 provided，默认时编译不会去找相应的依赖。关于 maven scope 的知识点，点击这里。

解决方案：

1. build configuration
2. modify options
3. 把 provided 加入 classpath

设置Maven目录

尽管IDEA可以设置 local repository，但实际上还是以 settings.xml 的配置为主，注意检查路径是否正确

无法识别 Maven 项目

此时代码的方法、变量不能跳转到定义处，无法编译、找不到主类。

表面上看，这是没有把源码目录设置为 src root，但实际上，这是 pom.xml 解析缓存或Maven依赖下载失败后的结果。

这里又分两种情况：

1. 子模块不能被识别
2. 主模块不能被识别

如果是第1种情况，添加了子模块不能正确识别，删除 <module>my-new-submodule</module> 这一行，重新加载 pom.xml；再重新添加这一行，然后重新加载 pom.xml 即可。

如果是第2种情况，笔者曾遇到的场景是： 因为把 IDEA 下载依赖的进程杀死了而导致的。 解决方案：删除项目，重新创建。

使用了不想要的镜像源

有可能第三方依赖包指定了第三方镜像源，而该镜像源不可用、或网络很慢，此时想避免使用该镜像源。

解决方案：观察日志，确认第三方镜像源的名字，修改 ~/.m2/settings.xml，拦截其请求

以上配置会拦截所有指向 Maven中央仓库、third-party-central 的请求，使用 my-central 下载依赖。

下载 jar 失败

如果因为网络问题， mvn 命令安装依赖失败（如下载某个依赖卡死），可以试试手动下载。

解决方案：

1. 点击相应的 jar 包链接，使用浏览器下载
2. 观察 jar 包的下载链接，把下载到的 jar 复制到相应的 ~/.m2 子目录下
3. 重新执行 mvn install

私服认证401

下载私服依赖时，报了 401。

解决方案：

1. 检查 ~/.m2/settings.xml，找到 server 选项，确保设置了相应的用户名与密码
2. 点击私服链接，输入用户名与密码
3. 如果上述步骤不能正确执行，说明设置有误，需要更正设置；如果上述步骤正常，有可能是 IDEA 抽风，建议：
   1. 删除项目，重新克隆
   2. 手动下载 jar，放到~/.m2 目录

避免缓存

pom.xml 作好设置

或命令行强制不使用依赖：

参考资料

官网：https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html
书籍：《Maven实战》

说明

密码加密是很常见的安全性需求，但由于涉及前后端，前后端分离的情况下，开发人员容易只关心自己熟悉的领域，最终导致“知道要加密，实际还是没明文”的情况发生。

本文分享实际可运行的前后端代码，以减轻大家实现密码密文传输的负担。

流程说明：前端加密，后端解密。

当然，数据库存储的肯定是密文。这里后端解密的意思是：需要使用密码的时候，如获取数据库的连接，由后端解密后使用。

前端代码

记得安装相应的 npm 模块。

后端代码

maven:

源码：

单元测试：

检查名字是否重复是很常用的业务需求，本文推荐一种更省心、更少bug的做法。

推荐做法

借助数据库的来实现，执行以下语句：

然后，在程序里添加全局异常处理类：

示例返回：

Why

为什么这样做呢？因为这样只需要改一次代码。后续再有类似的需求时，只需要增加 SQL 即可，不需要再修改码、不需要重新编译、构建、部署。

如果选择修改代码，则每次至少要修改两个地方：新增、修改都要处理。

示例代码如下：

• 检查是否存在

• 新增接口

• 修改接口

实践的经验表明：改得多，错的多！

基础知识

导入需要用到对象，MultipartFile。

导出需要用到对象：HttpServletResponse。作为 Controller 的最后一个入参即可，框架会自动注入。
也可以从请求上下文获取：

同时注意设置响应头：

应用框架

导出

EasyExcel 做 Excel 导出还是挺方便的。

先建立Java实体与Excel表格内容的映射：

然后收集数据，用下面的语句导出：

导入

EasyExcel 处理导入，体验就没那么丝滑了。

可以先看下示例代码：

设计思路是挺优雅的：事件驱动，把业务逻辑放入这个 Listener 里。

但实践起来就不太优雅了：

1. 无法利用 Spring 进行依赖管理，需要手动在构造器中注入业务对象。对于这一点，我表示很难受。我相信，当业务变得复杂，这个构造器要接收 9 个参数的时候，大部分人都会难受。
2. 需要维护横跨回调函数的“全局变量”。当业务复杂后，势必要引入更多的类成员变量，在 invoke/invokeHead/doAfterAllAnalysed 等回调函数中出现多次，对这几个回调函数而言，类成员变量就是全局变量。代码是可以实现，但个人不倾向于这种做法。另外，这也给我一种”梦回前端“的感觉，我对这种感觉不持有积极态度。

当然上面仅仅是吐槽，又不是不能用。业务不复杂的话，直接用起来就完事了。

常见问题与解决方案

浏览器下载

虽然说 GET 请求可以让浏览器直接下载文件，Postman 也验证过此方案，但很可能实际会让前端采取另一种实现方案：先进行 Ajax 请求，再利用返回的数据创建 Blob 对象，最后才下载。

为什么不直接让浏览器下载，而要前端转一层呢？大概率是因为鉴权问题——因为浏览器 GET 请求不能带上授权相关的请求头，小概率原因是想前端显示 loading 状态。

前端多转一层，很可能转出问题，排查起来，既要 debug 接口，又要 debug 前端代码，吃力不讨好。

对此，我推荐的实践是：请求 url 带上 token 信息，如 /download?token=xxx，让后端对于下载接口特殊处理，以更前端少做一次处理，直接让浏览器下载文件即可。

上传文件大小限制

导入本质是文件上传，服务端会生成临时文件，当文件过大时，需要修改相关设置。

以下是 Spring 的相关配置。

缺少字体

Excel 的导出需要字体文件。

缺少字体时，可能会报错：

为什么会缺少字体呢？一个经典的例子就是，使用了过于精简的基础镜像来打包应用，如使用 busybox 就会报错：

解决方案就是换一个更“丰满”一点的镜像。

但如果没有导出的内容没有格式要求，其实推荐优先使用 CSV。因为 CSV 不需要字体，而又与 Excel 兼容。

序列化失败

一般应用程序都会对请求参数进行日志打印，当处理文件时，可能会遇到以下错误：

找到相应代码：

问题出在第 12 行，上传的文件 Multipart 对象被序列化时报错了。但这不应认为是 fastjson 问题——就算换也 Jackson，默认情况也是会报错的。

这里具体问题具体分析。笔者的场景，其实只是要打印参数，并不需要序列化文件对象，因此，通过跳过序列化 Multipart 对象解决此问题，示例代码如下：

背景

项目中依赖了一个旧的 snapshot.jar，有人提出要求必须使用 release.jar，不能使用 snapshot。

问题来了，该 jar 所属的源码不知所踪，那还怎么发布 release.jar 呢？这就是本文要解决的问题。

下载

首先我们登录仓库，输入　ArtifactId，找到对应的 snapshot jar 包，并点击进入详情。

找到关键的三个 jar:

• x.jar
• x-sources.jar
• x.pom

分别点击进入详情

依次点击　Path，下载到本地。

修改

首先修改名字，如图所示。

再使用任意工具解压 x.jar，提取出两个文件夹。进入　META-INF

修改　MANIFEST.MF，把里面的 snapshot 字符串去掉（如果有的话）

再点击　maven　文件夹

修改　pom.xml、pom.properties　文件，把里面的 snapshot 字符串去掉。

上传

把前面解压出来的文件重新打包成 jar

然后上传仓库

在Upload中，点击　maven-releases

把三个文件添加上去，点击　Upload。

可以看到，新的 release 版本的 jar 包已经在仓库中了，可以被安装使用了。

概述

建议给常用集合类的变量命名时，后缀带上相应的集合信息，以提高可读性。

当然，在此之前要回答一个问题：当把鼠标放到变量上面时，IDE 会提示变量的类型，为什么还要在命名上做文章？

这是因为，有时并不在 IDE 上阅读代码，比如进行 GitHub 或 GitLab 进行 code review，此时无法获得提示，需要通过命名的规范来帮助理解。

List

List 的变量，一般以 List 或 s 结尾， 如 idList 或 ids。这点易于理解，大家也容易遵守。

坏的示例：

第一眼看到这代码的时候，不知道读者是什么反应？

按照习惯，nodeType 通常要么是字符串、数字、或枚举，但上述居然能调用 forEach 方法？我不禁愣了一下，赶紧去看了下定义，才发现原来是List。

好的示例：

Set

参考List，在变量后面加 Set 即可。

Map

Map 的变量命名是值得重点关注，因为很容易造成差可读性的重灾区。

Map 的变量，推荐根据 key 与 value 来命名。规则表达式为：${key} + To + ${value} + Map，如 idToNameMap。
其中：

• 可以玩一下“文字游戏”，把 To 写成 2（就像把 For 写成 4，这种 word play 是可以接受的），即 id2NameMap
• 如果名字够清晰或已经很长，Map 可以省略，如 id2Name

为什么推荐这样命名？我们先来看一则案例，看一看经典的 Map<String, String> 在实际编码中，命名是如何造成理解上的困难的。

getTableIdMap核心实现如下：

replaceNodeId核心实现如下：

不知读者是否已经晕了？反正我是一头雾水。可能以为是因为我删减了很多代码导致的？恰恰相反，实际代码还有更多的逻辑判断，我已经抽出了核心部分，不需要被其他逻辑干扰了。

上面的代码带来的疑问有：
疑问1：都是 Map<String, String>，tableIdMaps 与 tableMaps 有什么区别，它们存储的到底是什么？从类型上看，也不像是 id -> table 的映射啊。
疑问2：tableMaps.put(tableNode.getNodeId(), tableNodeId); 这个 tableNode.getNodeId() 不是等于 tableNodeId吗？
疑问3：String nodeId = tableMaps.get(tableNode.getNodeId()); 根据 nodeId 拿到 nodeId？

到这里已可以猜到，tableMaps里的 key 与 value 肯定不是单纯的 nodeId 的意思，但这并没有什么帮助，因为我们还是不知道 tableMaps key -> value 映射的到底是什么。

我们来看修改变量名之后，上述代码的效果。

现在是不是好懂很多了：

• str2TableIdMap 存储的 str -> tableId 的映射, 其中 str 是由某种规则拼接而成的字符串，具体规则封装在了 getTableNodeId这个函数里，我们暂时可以不用关心
• nodeId2TableIdMap 存储的是 nodeId -> tableId 的映射

仅仅修改变量名，可读性就有大大提高，效果立竿见影！

背景

不敢说是最佳实践，因为受限于特定技术、框架，并且带上了个人偏好。

虽然原理简单，但细节很多，不想每次搞来搞去，因此还是有记录的价值。

本文用到的技术栈为：MySQL、MyBatis、Java 8、Jackson

需求

删除某个时间段以前的日志。类似于消除浏览记录：

分析

上图只是UI示例，为了适应UI的变化，最好把接口设置成接收两个参数：

• 开始时间
• 结束时间

如果UI如上图所示，则选择过去 7 天时，开始时间就是 1970 年 1 月 1 日，结束时间就是过去第 7 天。

实现

MySQL

对于 MySQL，推荐使用，因为简单直观，且方便：

另一种方式：

上面是时间精确到秒的设计思路，逻辑上没有问题，但体验会有问题：如果是查询某个时间范围的日志还好，精确一点；现在需要是删除日志，谁还关心到秒啊！

通常人们只会关心到天，则考虑一种情况：开始时间与结束时间是同一天，下面的语句无法删除任何记录：

那么现在，就是分歧点了，有两种方案：

1. 程序为开始时间、结束时间填充时分秒：

2. 结束时间 +1 天：

两种方案都是可以行，我推荐的是第二种。并且，由后端处理，不需要前端拼接字符串。

注：结束时间 +1 的原因是，实际存储的的 created_time 是带有时分秒的，而用户选择时，只精确到日，这就相当于时分秒的值为0。如果结束时间不加1，则结束时间当天的记录都无法匹配到。

MyBatis

如果使用的是 >= 这种要SQL写法，MyBatis 就需要转义：

• > 转成 >
• < 转成 <

这就是不推荐这种写法的原因之一。

LoxalDate

都已经 Java 8 了，就不要使用 java.util.Date 了，使用 java.time.LocalDate 吧。方便应对后续的时间操作。

结束时间+1天，非常简单：

记得在 Controller 对时间字段加注解：

否则会报错：

Failed to convert property value of type 'java.lang.String' to required type 'java.time.LocalDate' for property 'startDate'; nested exception is org.springframework.core.convert.ConversionFailedException:

Jackson

如果不想在每个字段都加 @DateTimeFormat 注解，可以利用 Jackson 进行反序列化相关设置。

既然要设置反序列化，那序列化也少不了。我把全部设置的代码放下面了，有需要复制即可：

结语

好了，终于搞完了，我的评价是：

前言

编写函数的目的，最根本的目的是提高可维护性，从而提高研发效率。

本文将推荐一些编写函数的最佳实践，以供参数。

减少重复

这是在遵守 Don't repeat yourself (DRY) 原则。

实践中可以采取一个简单的判断方法：当相同的代码段第二次出现时，就是需要把代码封装成函数的契机。

然而，有时代码只是相似，不完全相同，不能简单地使用 IDEA 右键 + Refactor + Extract Method 来抽取函数。
此时，为减少重复，需要进行一些思考。

可以把程序的划分成三个部分：

一般而言，函数的入参都是数据变量，也即 Data Structure。
而 Java 8 以后，lambda 表达式（也即函数）可以作为入参，其代表的是 Logic。
因此，最抽象的函数，是只定义了 Control、把 Logic 及 Data Structure 都作为入参的函数。当遇到类似却不完全相同的代码、想封装函数有遇难时，可以借助上述思路来梳理逻辑。

隐藏细节

隐藏细节，是为了减少使用者的心智负担，方便其调用。

有一个简单的判断标准：如果调用者需要频繁查看函数内部情况，以确定函数的目的或实现细节，那么隐藏细节的意图是失败的。

建议

为了达到前文所述的目的，如以下实践建议。需要指出的是，以下提倡的是建议，并非金科玉律；只适用于一般情况，并非所有情况，特殊情况是可以特殊处理的。

优先根据业务命名

一般而言，函数名最好是根据业务逻辑、结合业务领域来命名，而不是根据程序逻辑来命名。

示例：

当然，如果有些方法名是专业名词或是耳熟能详的，那直接使用即可，如：

一个函数只做一件事

遵守 Keep it simple stupid (KISS) 原则。

当然，不可能所有函数都达到这个要求——程序入口一般就会做很多事。我们的目标是尽可能地遵守该原则，减少调用者需要频繁查看函数实现的可能。

反例1：做A且做B

坏的示例问题出在哪里呢？根据入参的合法性，有可能产生以下情况：

1. 参数合法，同时做A与B；只要有一个参数不合法，均不做A与B
2. 哪个合法就做哪个，也即可能出现：
   1. 只做A
   2. 只做B
   3. 做A也做B
   4. 二者均不做

到底是什么情况呢？对此疑问，调用方只有查看函数实现，才能了解，于是破坏了封装的意图。
而且，坏的示例还会存在一个问题：如果调用方只想做A怎么办？我想很少人会把原代码拆分成两个函数，更常见的做法是保持原函数不变，并拷贝原函数的部分逻辑，封装一个只做A的新函数——这就造成了代码的冗余，于是减少重复的目的失败了。

反例2：做A或做B

同样的，坏的示例会让人疑惑，搞不清楚函数的意图到底属于以下哪种情况：

1. 要么做A，要么做B，一定会做其中一个
2. 哪个合法做哪个，可能会出现：
   1. 只做A
   2. 只做B
   3. 做A也做B
   4. 二者均不做

当然，一些常见的深入人心的 API，我们是可以接受这种“或逻辑”的：

• saveOrUpdate() // 有 id 就是 update，没有就是 insert
• getOrDefault() // 获取值；如果值不存在，就返回默认值

优先使用纯函数

纯函数(pure function)，可以借助数学中的函数概念来理解：y = f(x)

• 给定 x，能返回确定的 y
• 无论函数调用几次、在何处调用，上述结果都不会变化

纯函数的好处之一是无副作用（side effect）。也即调用函数后，不会对函数作用域以外的变量造成影响。

反例：一个常见的现象，辅助函数会修改入参，主函数的变量生命周期贯穿整个主函数

因为已经省略了其他代码，因此我们不难看出 nodesMap是辅助变量，是为返回结果而服务的，而没有返回值的函数调用很可能修改了该变量。

但实际上，代码逻辑很长，还有其他变量掺杂其中，代码意图并非能够一目了然。假设稍微修改一下，为 getUpstream()添加多一个参数，还能看出函数到底修改了哪个变量吗？

如果 edgesMap是来自主函数的参数呢？

情况变得糟糕了，因为按照 getUpstream()会修改入参的“习性”，我们很难有信心认为 edgesMap一定没有被修改。

上述例子是想表明：为了贪图方便，编写一个不需要返回值而直接修改入参的函数，会给后续的维护增加负担。一方面变量状态难以追踪，另一方面这样的函数也不方便测试。

一般而言，优先使用纯函数，会助于对大函数的拆分，从而使得 KISS 原则更容易被遵守。

当然，总有例外情况。当程序逻辑复杂时，或有些函数就是对 setter 语句的调用，此时不需要返回值并且会造成副作用，又该怎么办呢？请看下一条建议。

编写不需要返回值的函数

有如下建议：

1. 方法名叫setup+ $
2. 一个方法只修改一个变量
3. 要修改的变量就是函数的第一个参数
4. lambda（如果有的话） 作为最后的参数

示例：

参考资料

• functional-programming-mostly-adequate-guide/ch03
• code-complete-2nd-edition.pdf

背景

定义枚举的动机在于，可以作为常量，避免魔法值的出现。并且具有相应的类型，方便检索、与代码提示。

而在使用过程中，一种符合直觉的想法是，期望枚举在具备基本的 key-value 的功能外，还能够承载更多的信息。

本文推荐，不要在枚举中定义数字，直接使用枚举名即可！

Java

极简实现

理想状态下，枚举就应该这样简单！

常见实现

然而，代码库中常见的实现是，使用 enum 关键字定义枚举类型，并写下枚举名以及相应的绑定值

就这点代码，从业务的角度讲，逻辑已经实现了。

但从具体编程语言（Java）的角度讲，工作还没有完成：此时，编译器会提示报错，因为缺少构造函数。

站在调用方的角度，就会发现，我们没有方法拿到枚举里的定义值，也即(1, "this is description for male") ，

因此，还需要编写以下内容：

• final 的成员变量
• 在构造函数中为成员变量赋值
• 定义成员变量相应的 getter 方法

前面说到，我们期望枚举里有 key-value 的功能，则还要再定义 getValueByKey 方法：

有了上面的方法，我们才可以通过传入 code，返回相应的 desc

如果反过来，我们想通过传入 desc 返回相应的 code 呢？还得再写一个方法！真是烦琐！

更好的方式

前面我们可以看到，当关键逻辑写出来以后，还要写那么多模板代码，简直索然无味。

为什么把简单的事情搞复杂，有没有更好的方式？

需要了解到以下事实，枚举类型提供了通过枚举名获得枚举值的方法：

也就是说，如果使用 valueOf的方式来定位枚举值，就可以通过 getter 方法来获取自定义的业务值，不需要再写自定义的 getValueByKey 方法。

为什么还要定义数字？

另外，再看之前的枚举定义，为什么要定义 MALE(1, "this is description for male")呢？
在 MALE本身已经有含义的情况下，为何还要再设置一个数字呢？

这个数字导致了不必要的转换：

1. 前端传数字 -> 后端转成枚举
2. 后端再把枚举转成数字 -> 存入数据库

最蛋疼的就是，select 数据库数据的时候，全是1、2、3，都不知道什么意思。

能不能不要这个数字？ 直接把定义好的枚举名，存入数据库呢？

表面上看，这是因为数据库定义如此——从数据库查出来是数字，因而要根据数字去获取别的业务信息。

然而，我再问了一下，得到的回答是： 上述做法是设计如此。为了节省存储空间及提升查询性能，才在数据库设置的数字，而不是直接存储字符串。

这就引出了另一个问题，需要这样做来提高性能吗？对此，我们接下来要进行数据库层面的讨论。

数据库

数据库本身是支持检举类型的，下文以 MySQL 为例进行说明。

枚举相关的 SQL 语句示例：

存储方式：转换成数字存储，查询时再转换成字符串
存储空间：1 or 2 bytes (65,535 values maximum)

由上可知，为了节省空间及提高查询性能，在数据库层面使用数字代表枚举进行存储，是不必要的，因为数据库本身已有相应的功能。

排序特点

排序规则如下（如执行order by 时）：

• NULL 在最前面，'' 次之，接下来是非空的枚举值
• 定义枚举值时的顺序，就是排序的顺序

推荐使用以下技巧：

• 按字母表顺序定义检举值
• 把检举值转换成字符串再排序 ORDER BY CAST(col AS CHAR) or ORDER BY CONCAT(col)

添加新值

使用枚举类型的最大的问题是，后续添加新值时需要执行 alter table。

如果枚举值经常变动且对枚举值的顺序要求（添加的新值不一定在最后面），则不建议使用枚举类型。

否则的话，可以使用枚举类型。

因为 alter table 的机制是：

1. 创建临时表 t'
2. 插入数据
3. 删除当前表 t
4. 把 t' 重命名为 t

这在表数据量较大时，会导致表被锁较长时间而不可用。

可以使用以下技巧进行更新，记得严格按照顺序执行：

如果在 Navicat 或 DBeaver等图形工具上看不出表结构的变化，请刷新数据库。

总结

本文主要目的是想消除枚举中对魔法数字的误用，试图让 Java 代码、数据库数据、以及前端 API 传参都使用可理解、可读性强的枚举值。

在数据库层面，对于枚举类型字段的注意点，本文也做了说明。如果实在不想每次添加新的枚举值都执行 alter table语句，贪图省事，使用 varchar 存储也未尝不可。

总之，本文想强调的是 Java 代码与数据库数据展示内容的一致性，至于数据库的存储格式，是见仁见智的。

参考资料

• https://www.baeldung.com/java-enum-values
• https://www.baeldung.com/a-guide-to-java-enums
• https://dev.mysql.com/doc/refman/5.7/en/enum.html
• High Performance MySQL 3rd Edition

在 Java 中，对于布尔类型的变量、对象属性或方法参数的定义，到底是用包装类型 Boolean 还是基本类型 boolean 呢？

结论

先说结论：根据《Effective Java》(第三版），始终尽可能地使用基本类型。故应该使用 boolean。

原文如下：

红线处翻译：总结就是，当你有得选的时候，请务必使用基本类型，而非包装类型。

那什么时候使用包装类型呢？原文如下：

红线处翻译：当你没得选、被强制要求时，才使用包装类型。如：使用泛型（使用集合类、调用参数是泛型参数的方法），以及通过反射进行方法调用(使用 invoke 方法）

争议

阿里的《Java开发手册》有提到，类属性强制使用包装类型。

但注意，本文讨论的仅仅是布尔类型，不要发散话题。 那现在就来分析一下，布尔类型有没有必要考虑 null 的情况？

我认为是没有的必要的。理由如下：

• 布尔类型就是二进制的，代码两种情况：1或0；真或假。使用包装类型，出现第三种情况 null，不但要注意空指针异常问题，还要兼容 null 的情况——此时到底是真还是假呢?
• 如果 null 表示的既不是真也不假，而是第三种情况——就不该定义为布尔类型，而应定义为枚举类型，因为一共有三种情况。使用 Boolean 来表示三种情况，是设计上的偷懒。

实战

我们来看一下实际代码中，滥用 Boolean 类型导致的问题。

简单例子

有如下 Controller，使用的是 boolean：

前端传个空值，会得到报错信息：

但如果使用 Boolean，并不能检查出是非法参数：

这原本是前端传参错误，但却无法即使发现。

你可能会问，为什么不先判断 Boolean 变量是否为 null 呢？因为别人在声明 Boolean 变量时，设置了默认值为 false，谁能想到前端会传个 null？

这就是 Boolean 的问题：“千防万防，家贼难防”！

复杂例子

下面是前端传给 Controller 的参数：

需要注意的是，有至少两个 Controller 会接受到了这个参数，并且根据业务的不同，它们对参数的处理是不同的：

• 有的会判断如果 withTable2Api 为 null，就设置为 true
• 有的则完全由前端传值，也即 forkable、withTable2Api 有可能为 null

来看一下，Service 里的相应代码：

这里有什么问题呢？可以看到，第二个 if 使用 !Boolean._TRUE_去判断很别扭，然而，却不能改写成：

这就是布尔值使用 Boolean 类型在实战中最大的问题——你不能任意地进行真或假的判断，而必须兼容上下文中隐式对 null 赋予的含义。

而多人协作过程中，外部调用是很难控制的，因此，此时使用 Boolean，只增加了无谓的编码负担。

附

Joshua Bloch - Effective Java (3rd) - 2018.pdf

背景

遍历一个集合，在里面执行某种操作后，再依次返回每一个元素，常见的实现方式有：

两种方式看起来没多大差别啊，到底用哪种呢？

结论

先说结论：根据《Effective Java》(第三版），forEach 只用于消费数据的场景，并不应该用于计算、累加，故上述代码应该使用 map。

原文如下：

红字处翻译：forEach 仅适用于输出 stream 里的计算结果，并不适合执行计算。

解析

为更好地理解上述结论，需要先理解以下内涵：

Stream 的引入，不仅带来新的语法，也带来了函数式编程的思维。

这里最重要的一点就是：编写纯函数（pure function），不造成副作用（side-effect）。

纯函数可以用数学中的函数映射来理解：y = f(x)

• 给定 x，能唯一确定 y
• 无论函数调用几次、在何处调用，上述结果都不会变化

无副作用意思是：调用函数后，不会对函数作用域以外的变量造成影响。而纯函数，一定是无副作用的。

前文使用 forEach 的代码，其实是造成了副作用的：

很简单的一个识别方法：再调用一次 forEach，result 的结果还是期望的结果吗？显然不是。

但如果 map 方法呢？再调用一次，结果不变！

类似的，修改函数入参，也不是纯函数：

上面的 collectIds函数是令人讨厌的——写代码的人懒得写函数返回时，直接修改函数入参，给后面维护的人留下隐患。

当然，如果一定要用纯函数来看待问题，未免过于理想化，因为有时要执行这样的代码：

虽然上述代码并没影响到函数作用域以外的代码变量，但 myService 会把数据持久化，站在整个应用的角度讲，仍然造成了副作用。

但上述代码可以接受的。因此，建议记住 forEach 只用于消费数据，不用于计算及返回，就不容易混淆。

实战

当然，上述的讨论还是比较偏理论的，我们来看一下实际项目中，滥用 forEach 可能导致可读性较差的问题。

代码一开始，是简单清晰的：

然而，业务会变化，逻辑会复杂，代码也要修改。而上述在 forEach 中修改变量的行为，罪恶的根源在于，它在向后来修改代码的人发出邀请：新增的逻辑，写在这个 forEach 里面就好了！

当仅在 forEach 添加代码就能完成任务的时候，很难有人能抵抗这种诱惑，于是就会变成：

写代码一时爽，维护火葬场。上面的代码，将是维护的噩梦！

并且，如果维护者只想知道函数的整体逻辑，由于变量穿插、隐藏在 forEach 内部，维护者不得不在各种 if-else 里面追踪变量，很容易就陷入不必要的细节中。

如果换个方式来写呢？

效果有大大的不同！

现在想追查哪个变量，简单轻松好多啦！

原因是 json 包含的字段，多于 Java 实体类定义的字段。

解决方法很简单：

或者为相关实体添加注解：

可是，如果用 fastjson，根本不会有这种错误。使用起来也简单，文档在这里。

所以，为什么不用　fastjson　呢？

前言

无论是 C/S 还是 B/S 模式下的应用通过是 API 来交互的。而 API 的消费者与提供者，可以看成一枚硬币的正反面。

通常来说，对 Web 应用而言，前端是消费者，后端是提供者。

今天就站在服务提供方的视角来看下，升级依赖版本，遇到的难点有哪些？

接口调用示意图

已知信息

1. common.jar 的版本是 1.0.0-SNAPSHOT，实际上 common.jar 的最新稳定版已经是 5.x 了。比较了下版本内容，发现二者是不兼容的。
2. 公司有多个业务系统依赖 infra-service，但它们隶属于别的团队

问题

infra-service 的某个接口，现在要修改，多返回一个字段，但因为之前的代码健壮性不够，新接口　common.jar 处理会报错。

于是，想通过让使用方升级 jar 来解决，此方案可行吗？

答案可能出乎意料：不行！

因为：jar 升级版本的动作不在自己的掌控范围内。

说起来很简单：叫他们升一下就行。
但问题是：

1. 他们是谁？
2. 你说升就升？

问题本身在技术层面很简单，但在现实的执行层面，有着超出技术范畴的难点。这便是服务提供者，需要面对的。而这是作为服务的消费者，容易忽视的一点。

复盘

那么，在技术层面，是否能做得更好，避免重蹈覆辙呢？其实是可以的。

有两种思路：

1. 只对外发布稳定版，要么强制自己的接口一直向后兼容；要么一旦有接口不兼容，在保留旧接口的情况下，发布新接口、新 jar。
2. 利用好 SNAPSHOT 版本 jar 会不断覆盖的特性，同时对外发布 1.0.0-SNAPSHOT 版本，以及每次迭代的稳定版。也即，通过使得 1.0.0-SNAPSHOT 永远与最新的稳定版本相同，让使用者及时升级。

说明

对于已知问题有正确答案的场景，适合使用 ragas 的 faithfulness 指标对 GenAI 应用响应结果进行评估，方便进行回归测试。

注意：本文提到的方法，只适用于对已知问题的评估。对于线上运行时，用户提的随机的、不在测试集范围内的问题，不适合用此方法评估。

安装

数据说明

对以下数据进行评估。

事实：Einstein was born in 1879 in Germany.
提问：

1. When did Einstein born?
2. Where did Einstein born?

正确答案：

1. Einstein was born in 1879.
2. Einstein was born in Germany.

正确性❌

这是不能令人满意的——正确的回答，得到的指标分数却不足0.8。
这是因为，正确性的评估，还依赖了相似度。

忠实度✔

符合预期，满足要求！

实战演示

准备好样例问题

准备好正确答案

编写回答函数

进行答案评估

效果如下：

业务背景

备案审查是指规范性文件在制定颁布后，按法定期限报同级或上一级人大常委会备案，由接受备案的人大常委会在法定期限内依照法定标准和程序对其进行监督审查的活动。
在这个过程中，最重要的就是确保下位法不会与上位法相抵触。
因规范性文件众多，而具备审查资格的专家又极少，故工作进程较为缓慢，现期望借助AI的能力，提高效率。

核心流程

项目难点

1. 海量文件，必须自动化分片，不可能人工处理，也即手工插入分隔符是不可行的

解决方案：写代码处理

2. 通过下位法法条，能找到对应的上位法法条

解决方案：在分片质量有所保证的提前下，在常规语义检索的基础上，通过结构化数据筛选，提高匹配率

3. 判断下位法是否与上位法相抵触

解决方案：参考经典案例，学习其判断逻辑；指示AI，无法判断时不要乱下结论。

经验总结

数据很重要，一定要了解业务数据。

数据要分类：

1. 参考的数据要与验证的数据区分开来。一定要在前期就找客户要参考案例，并问清楚如何验证。问清楚后，要么让客户给验证数据，要么自己造验证数据，千万不能连怎么验证都不知道就动手。
2. 基于场景分类，如下位法对上位法范围扩大、范围缩小，它们就要区分开来。

参考资料

什么是上位法
论大语言模型在规范性文件备案审查中的应用
备案审查案例选编

背景

前面有讲数据迁移的案例(mysql-a -> mysql-b)，其实在迁移前还少不了备份。

并且，因为不想停机迁移，因此还要新起一个数据库实例，记为 mysql-b'，复制 mysql-b 的相关数据。这样就能在 mysql-b' 里验证迁移SQL的正确性，以确保 mysql-b 能不宕机完成数据迁移。

在这种情况下，就需要用到我们今天的主角，数据备份工具 mysqldump。

架构

注意到：

1. 从 mysql-b -> mysql-b'，就要用到工具 mysqldump
2. 关于 sql 的编写在另一文中已有提及，就不重复了
3. 只能通过跳板机在终端连接数据库实例，因此无法使用图例界面操作。

安装

首先要在跳板机安装 mysqldump。

如果够幸运，可以用包管理工具安装：

如果配置有问题安装不了，可以直接下载 mysql 二进制包：

如果还不行，那就本地下载，然后把 mysqldump 压缩通过 scp 上传到跳板机。

有人会想，这么麻烦，为何不直接复制 mysql-b 的数据文件？这是因为：

1. 没有进入 mysql-b 宿主机的权限
2. 复制磁盘文件更麻烦，后面会讲

导出

导出命令很简单的，类似 mysql 客户端连接，指定用户名、表名、导出文件，再根据提示输入密码即可。

然而命令行的提示，暗示事情令有玄机：

1. 首先，这样简单的命令，只能导出表数据，其他数据如触发器则并没导出
2. 其次，由于目标数据库开启了 GTID 模式(gtid_mode=ON)，导出的文件会有相关的设置

--set-gtid-purged=OFF

打开 dump.sql 的前 30 行，可以看到 GTIDs 的相关内容。

Here's a quick overview of how GTIDs(Global Transaction Identifiers) work in MySQL：

• GTIDs uniquely identify every transaction.
• Allow replicas to track replication positions.
• Enable failover and repointing replication.

因为 mysql-b 是主从架构的，开启 GTIDs 很正常，但我们要用来测试的 mysql-b' 是单实例的，并不需要它。
如果未正确设置，导入的时候是会报错的。

因此，在这种情况下，导出语句可以添加以下参数：

也即命令变成：

当然，也可以修改 dump.sql，把 GTIDs 相关的语句删除掉。

--ignore-table

导出的文件可能会很大，而如果我们要把文件在不同的机器之间传输，这就会让过程变得很慢。此时，我们希望导出的文件越小越好。

我们利用以下 SQL来确认下，目标库中到底是哪些表占据了较大的存储空间：

接着我们根据业务，分析哪些表的数据是必要的，哪些表的数据可以不用导出。添加以下参数把不需要导出的表忽略掉：

示例命令：

注意：该参数一次只能忽略一张表，故忽略多张表需要声明多次。

导入

导入命令类似导出，只不过此时使用的是 mysql　客户端，并且重定向符号不同。

为什么不?

现在来回答为什么不直接复制MySQL的磁盘文件。

根据前面我们知道，也许我们的需求是部分备份，而不是全量备份，则直接拷贝磁盘文件，在数据量大的情况下，只会造成传输负担，反而“欲速则不达”。

另外，复制磁盘文件，为保证数据一致性，要求MySQL必须停止运行。主要有以下原因：

1. Ative Transactions: Copying database files directly may lead to data inconsistency if there are active transactions or changes happening in the database while the files are being copied.
2. Flush and Sync: The MySQL server may buffer data in memory and write it to disk periodically. When you copy files directly, you may capture data that is in memory and not yet written to disk.
3. File Locks: Some storage engines, such as MyISAM, may use file-level locks, which can prevent you from copying files while the server is running. InnoDB, on the other hand, uses a different mechanism (tablespace files), but copying InnoDB files still carries the risk of data inconsistency.

因此，纵然有直接复制MySQL磁盘文件的奇技淫巧，还是不建议使用，我就也不向大家展示了。

背景

项目要做数据迁移，要把 mysql-a 的数据，迁移至 mysql-b，同时 mysql-b 的数据不能丢失。

问题分析：

1. 两个 mysql 实例的表的主键都是自增的，若直接合并，必然造成主键冲突。
2. 可以修改某一方的主键后再迁移，但要注意后续不会因主键增长而发生冲突。

迁移思路:

1. 由于 mysql-b 的数据更重要、且数据量更大，故决定修改 mysql-a 的数据的主键，方案是增加 10w（mysql-b 的单表数据不超过 10w条）
2. mysql-b 的相应的表 AUTO_INCREMENT 加 10w
3. 记得动手前先确保数据已备份

注意：

• mysql-b 的数据量比 mysql-a 的大，所以 mysql-b 也直接设置 AUTO_INCREMENT 加10w。
• 但如果 mysql-a的数量比较大，那是不可行的，此时 mysql-b 需要先 select 出每张表的最大id，作为需要增加的 AUTO_INCREMENT。

备份

迁移前一定要做好备份。备份的技巧在另一篇文章里有讲，就不在此赘述了。

SQL编写

mysql-a 可以先 insert：

再导出新增的数据：

也可以先备份 mysql-a，然后直接 update：

再导出。

对于 mysql-b，需要编写的SQL很简单：

1. 先把当前表的主键自增值找出来
2. 再加 10w

理想中SQL如下：

然而，报错如下：

原因是： The AUTO_INCREMENT value must be a constant or a specific integer value in the ALTER TABLE statement.

那怎么办呢？存储过程就派上用场了。思路是使用存储过程来拼接 alter table 语句，绕过 MySQL 的限制。

存储过程（可复用

上述代码可复用，直接复制粘贴即可，有需要的请自取。

背景

经过调试与验证，我们可以确信自己编写的SQL是正确的，是时候到目标库执行SQL了！

但要小心，在正式环境中执行 SQL，也许会有意想不到的坑！

环境说明

先说明下我们的环境信息。

我们只能通过跳板机的终端连接 mysql、执行SQL，没有DBeaver、Navicat等工具可用。

则我们执行SQL语句的方式有两种：

1. 执行导出的SQL语句文件
2. 复制粘贴SQL语句执行

当然，在执行前，我们要确保已进行了数据备份。

执行SQL文件

执行SQL文件是最简单的，一般实践也是在命令行批量执行SQL文件。

相关的命令与恢复备份的命令一致：

这是推荐的方式，因为执行语句一旦出错，就会停下，并告知是第几行的语句出错。

但出于某些原因，你可能不想把所有SQL语句都合并到一个 script.sql 文件中。
另外，上传文件到跳板机，可能也比较麻烦，于是，你想采用第二种方式。

复制粘贴执行

通过 mysql 客户端直接上 MySQL 后，在命令上执行 SQL 语句会有一个问题：错误的语句不会中断后续的执行。

更可怕的是在命令行里，很可能你SQL语句包括的中文字符串会被过滤掉，变成空字符串。如：

• '创建人' -> ''
• '中英en混杂' -> 'en'

这真是血的教训😭。

我们先来看下错误是否中断的实验。

新建一个只有两行的SQL文件，其中第一行语句是错误的。

使用导入命令：

提示第一行有错误，第二行未执行。这是符合期望的。

但如果连接 mysql 后，在交互式命令行里执行 source 命令：

错误出现并不会中断SQL的执行。
复制语句，粘贴到命令行，表现也是如此：错误只提示，不中断执行。

那么，能否在交互式命令行里执行SQL语句，一旦错误就中断呢？

我们在MySQL官方论坛里找到了相关的帖子：

最终得到的答案是，使用：\e。
进行类vi界面，在这里粘贴 SQL（这里就不会有中文被过滤的问题）

保存退出后，输入 ;则执行 SQL 语句，Ctrl + C　则不执行。

可以看到，这种方式执行 SQL 语句，也是可以遇到错误就中断的。

如果要删除错误的数据怎么办？

尽管经过测试，但也不敢说语句的执行能百分之分成功，因此，这里给个温馨提醒。

如果插入、更新了错误的数据，确实要执行 DELETE 语句，那么请做好以下 checklist:

1. 确保已备份数据
2. 删除前先查询，也即先写 select from，确认一下是目标数据，再改写成 select 改写成 delete
3. 一定要写 where 语句，并且精确到主键，最好只写类似这种语句 where id = 1 或者 where id in (1,2)

logging替代print

目前公司的LLM应用开发使用的是 Python 技术栈，观察源码，发现没有多少日志，纵使有，也是用的 print。

print 的作用，就相当于 Java 的 System.out.print，相当于 Node.js 的 console.log，一般只适合在本地调试，不适合作为日志输出的。

打包成 Docker 镜像时，Python 应用很可能看不到 print 输出。使用 pytest 执行测试用例时，默认也是看不到 print 输出的。再加上 print 太简陋了，输出没有时间，没有级别分类，建议还是弃用，改用专门的日志模块。

使用 Python 内置的日志模块 logging，直接 import 即可使用：

如果要在 pytest 中显示日志，还要在项目根目录添加 pytest.ini 文件，补充如下内容：

logging 模块完整的用法，可以点击查看文章。

何时打印日志

为避免排查线上问题时，被迫吐槽：“怎么一点日志都没有！”建议平时养成打日志的习惯，方便应用的迭代与维护。

下面给出一些通用的打印日志的实践建议，与语言无关，可按需采纳。

1. 外部调用
2. 异常捕获
3. 提前返回
4. 复杂或特殊的if-else

外部调用

调用另一个应用的API，与中间件（如 redis, rocketmq）交互，都属于外部调用，最好调用前后都打印日志（当然，如果返回的数据量太大，酌情可以考虑省略打印部分返回信息）

示例：

异常捕获

异常捕获后，一定要打印日志。实在想偷懒，直接打印堆栈信息都能授受。最忌讳的是，捕获了异常，然后什么都不做，直接把异常信息给“吃了”，这绝对是排查问题的恶手。

示例：

提前返回

如果函数有提前 return 的逻辑，最好返回前也打印日志，不然排查问题时，发现请求进来了，却什么日志也没有，容易让人一头雾水。

示例：

复杂或特殊的if-else

如何定义复杂，又如何定义特殊，这就见仁见智，需要个人在实践中去总结理解了。

一个常见的场景是，某段逻辑因为业务变化要加 if-else 进行特殊处理，你得在这个 if-else 前加上注释，解释其原因。那么这段逻辑就可以添加日志，日志内容就是你的注释内容，也即把注释改写成日志即可。

示例：

需求

查询 MySQL 某个库的全部表的元信息，输出成 Excel，每一张表一个 sheet。

代码

其他细节

上述代码由于库的原因，只能生成新文件或覆盖文件，不能修改原有文件。
执行代码时必须关闭生成的文件，否则报错。
sheet的名字不能超过 31 个字符。
RBG 转 Hex 工具，给单元格、文字上颜色时会用到，因为 Excel 显示的是 RBG，但代码里是 Hex。

操作 Gitlab MR 的命令行工具的源码与测试代码。

源文件：main.py

测试文件：test/test_mr.py

Why

为什么要做单元测试？或者说，为什么要写测试代码？

个人总结为以下两点：

1. 测试左移，降低修复bug的成本
   
2. 形成资产，方便回归测试，后续迭代重构、维护有保障

以上两点，是研发人员写测试代码的本质理由，无论什么类型的测试代码、研发人员用的什么语言、框架都适用。

What

写测试代码究竟是写什么？

个人认为测试代码主要是为了搞清楚两件事：

1. 源码到底会不会在目标环境执行？
2. 源码的执行结果是否符合预期？

第一件事，引出了 code coverage 代码覆盖率的概念；第二件事，则引出了 assert 断言的概念。

How

测试代码的风格

AAA 风格：

1. 组装参数
2. 执行目标方法
3. 执行断言

尤其注意最后的断言，如果没有断言，不叫测试。

常见的错误就是，不写断言，而使用 System.out.println()来判断执行结果。
这样做无法结合 CI 形成有效的自动化测试。 因为这种做法只能让编译通过，源码逻辑也许已经错误了，但测试结果仍然 100% 通过，这是没有意义的。

测试难点

以函数的观点来看。

输入：

1. 内存数据
2. 外部数据

输出：

1. 内存数据
2. 数据库
3. 文件系统
4. 网络调用

单元测试从严格意义上来说需要满足三个No：

1. No DB
2. No Network
3. No I/O

由此，引出了 Mock 的概念及技术。作为单元测试，需要 Mock 依赖，准备好输入数据，并想办法在内存中验证外部输出。

也即，重要的是隔离依赖，让测试可重复执行。

常用工具

1. Junit
2. Mocktio
3. TestMe

Bad Examples

以下是常见的错误测试示例，它们都不是合格的单元测试。

没有测试类

经典错误：写一个 main 方法，把所有测试代码都放进去。这样做的后果是，无论是人还是机器，都不知道原来这里还有测试代码。

没有断言

经典错误：（很可能是单纯地把测试代码从 main 方法移过来）没有断言，依赖人用肉眼判断输出正确与否。

这个例子虽然用上了 Mock 技术，但依赖掩盖不了没有断言的事实。这也许是为了达到测试覆盖率百分百而进行的投机取巧。

无法重复执行

如果代码 Linux 环境运行怎么办？哪里来的 D 盘？

这种情况，正确的做法应该是把依赖的文件作为测试夹具，与测试代码一起放入版本控制中。

参考代码如下：

前言

本文将借助 RestAssured 工具，向大家介绍如何进行 API 测试，从而在团队中开启接口自动化之路。

本文的示例代码使用的是 Java 语言。尽管本文的首要读者是 Java 研发人员，但道理是相通的，其他语言的研发人员也能从中受益。

What

什么是 API 测试？简单来说，可以认为是针对 Controller 层的测试，但不是 Mock，而是会真实地处理请求，与数据库或外部服务进行交互。

Why

为什么要做 API 测试呢？

考虑有过这样的场景：

• 加一个新功能，自测没问题，结果被测试人员发现一个旧模块出了问题，感到措手不及
• 后端写好了接口，前端还没开发好界面，于是感觉不方便自测，因为没有界面，只好催前端快去做页面

API 测试就是来解决上述问题的。做 API 测试的原因有：

• 必要性：做回归测试，避免添加新功能时破坏旧功能。
• 便利性：方便本地调试，不用部署到线上，依赖界面去测试。
• 资产化：让测试用例变成资产，与团队共享。

当然，要做好 API 测试，还要接受这样的认知： 接口自动化测试并不仅仅是测试人员事情，研发人员也有责任把它做好。 否则，研发人员难免会觉得这不关我的事, 从而不愿意写这种代码。 建议研发人员从以下方便思考其好处，提升行动的积极性：

• 减少阻塞，接口自测不再依赖前端
• 提高效率，本地就能自测，不用把应用部署到线上环境
• 提高质量，减少部署到研发环境、前端一调用接口就 500 的情况

为什么不用Postman

Postman 确实是符合直觉的接口调试的第一选项。 但注意，调试不等于测试。

Postman 在实践过程中，最大的问题在于，无法将测试用例有效地资产化:

• 你会在 Postman 里写断言吗？很少吧，你其实是在用肉眼去检查接口成功与否，这本质还是手工测试
• 你的 Postman 数据能与团队共享吗？不能吧，大多数人的 Postman 数据是在本地的，也不会去付费创建一个团队以共享数据
• 你的 Postman 数据在有版本管理吗？没有吧，大多数人的 Postman 数据是与源代码分离的，不利于维护与管理

另外，如果要与 CI 结合，Postman 的数据更适合使用 Node.js 的 Newman。

考虑源代码是 Java，使用 RestAssured，编写 API 测试代码用同一种语言，可以减少使用者的心智负担较轻；并且与源代码放在同一个 Git 仓库中，易于管理。

因此，我仍然会使用 Postman，但更多是把它应用在出现线上问题时，直接复制一个 cURL 用来复现、排查问题的情况。

安装

下面将介绍如何用 Maven 安装 RestAssured。

复制以下内容到 pom.xml 即可。

安装完成后，重启 Spring 容器。

如果安装依赖不成功，可以进行以下检查：

• 显式指定 json-path 与 xml-path 的版本，并排除其他测试包(如 sping-boot-starter-test) 对 json-path 的依赖
• 声明放在 JUnit 前面

快速上手

语法结构为： given()、when()、then()

通用设置

以下代码可直接复制到 Java 测试类中。

getToken方法的示例代码：

请求示例

下面是一个 GET 请求示例，根据响应体进行断言：

下面是一个更完整的POST示例，包含了：

• 组装数据
• 设置body
• 设置query
• 判断响应体的数据结构

提醒，在运行测试代码前，需要做两件事：

• 一定保证 Web 服务已启动，因为这不是 Mock，而是会发送真实的请求。
• 正确配置了环境变量 TOKEN。如果使用 IDEA，可以编辑运行配置，在环境变量里注入类似代码：TOKEN=Bearer xxx

接口依赖

有时在请求接口 B 之前，需要请求接口 A，于是就产生了接口依赖：B 依赖了 A。

此时可以使用 extract() 及 path() 获取请求 A 返回的数据。

上传示例

RestAssured 很强大，还能处理上传与下载的请求，简直让人“爱了爱了”。 下面是具体的示例：

如果想在传文件的基础上，还传其他参数，可以这样写：

对应的前端请求代码为(记录一下，以备不时之需😃)：

下载示例

看到全部用例都执行成功，非常爽快！

持续集成

以集成 Gitlab CI 为例，其核心思路就是在 CI 环境运行 mvn test。

具体做法可以参考笔者的Gitlab CI文章。

其他问题

为什么不用 Pytest

如果编码代码的人员是测试人员，那可能首选 Pytest。但本文面向的读者的 Java 研发——既写 API，也写相应的测试代码。故选型理由参考前面 为什么不用Postman 的回答。

这也是单元测试吗

不是。运行上述测试代码，如果是测试本地接口，需要先在本地启动 Spring 容器；如果是测试线上接口，则需要先把应用部署到线上。因此，这是集成测试。

参考资料

官方文档：https://github.com/rest-assured/rest-assured/wiki/Usage

为什么写端对端测试

写端对端测试代码的最大好处就是，把相关的用例变成可执行的代码，成为项目的资产；结合CI系统，可在后续研发维护过程中，将一部分测试过程自动化，减少重复的手工劳动，既保障质量，又提高效率。

谁来写呢？本文的目标读者是前端研发人员，因而相关测试代码是由前端同学去编写的。

为什么用 Cypress

文档齐全，生态好，对 JavaScript 友好，可简单上手。更多详见：why-cypress

缺点：全英文档

快速开始

安装

下载完依赖后，cypress 还会再从网络下载二进制执行包。安装完成后会在本地全局缓存一份二进制执行包，那么这台机器上所有项目都可以使用这份缓存。文档参考

一般而言，国内用户都会在上述过程中卡住，最好在命令行设置网络代理后再下载（懂的自然懂）。

如果是在 CI 环境，记得缓存 cypress binary。

安装完后，修改 package.json

加速下载

因为安装时，需要科学上网，如果不想设置代理，也能加速下载安装。可以自己先下载官方提供的二进制 cypress.zip，再上传至自己的 OSS。

则安装 Cypress 时，设置 CYPRESS_INSTALL_BINARY 指向对应的地址即可。如

或使用淘宝镜像，缺点是可能包不是最新的。

或这样写

目录结构

推荐结构如上图所示的目录结构：

• cypress 相关的内容放到 test/e2e 文件夹下。与单元测试的 unit 文件夹区分开来
• config 存放不同环境下的变量，如 dev/uat 环境的 baseUrl 是不同的，可分别在 config 里
• fixtures 存放测试 mock 数据
• integration 存放的就是 cypress 的测试用例了，命名规范同 jest：${name}.spec.js
• plugins 存放的是相关插件
• support 存放自定义的 cypress 命令

可以根据要求，修改文件夹目录结构，只要在 cypress.json 里配置好即可：

注意，如果不显示声明这些配置，每次执行 cypress 命令都会自动生成相应的示例文件

cypress.json 是放在项目根目录下的默认配置文件，全部配置项可查看文档

通过 FEMessage/create-nuxt-app 生成的项目默认是使用上面的配置

与 Jest 协同工作

当项目也在使用 jest 进行单元测试时，有两个注意点。

ESLint 配置

推荐项目中存在三份 eslint 配置文件：

当然，还要安装相应的依赖：

测试目录

两个工具都需要明确指定各自的测试目录。

cypress 的测试目录可通过上文所说的 cypress.json 指定。

jest 测试目录则可通过在 jest.config.js 里指定：

检查依赖及生产安装依赖命令

请确保生产安装依赖命令为

上述命令，只会安装 package.json 里声明的 dependencies 依赖，避免因为下载 Cypress 而超时。

因此，也要确保项目中 package.json 中的 dependencies devDependencies 等声明是正确的。

第一个用例

新建 common.spec.js

上面的示例覆盖了三个 cypress 常用命令：

• 跳转页面
• 获取元素
• 断言

这里说一下 should 命令，它相当于是 expect.to 的简写。
如： expect($input).to.be.disabled 可写成 get($input).should('be.disabled')

更多命令，可查看API
常见断言，可查看文档

如果想获得代码提示、代码补全，需在开头添加如下语句，（Webstorm不需要此配置）参考文档

执行 yarn e2e ，出现弹窗

点击文件，即会执行用例。

更复杂的示例

结合TypeScript

在 e2e 目录添加 tsconfig.json，内容如下：

在 e2e/support 添加 index.d.ts，如果有自定义命令的话

将 e2e/integration/xxx.spec.js 重命名为 e2e/integration/xxx.spec.ts，并添加如下2行内容：

持续集成

持续集成的第一步要选择合适的包含 Cypress 的镜像。

注意自身的 Node 版本选择合适的镜像。

另一方面，一般 CI 环境下执行的是 cypress run 命令。

run 与 open 的不同之处在于，run 默认不会启动浏览器界面，使用的是 headless 模式执行用例。

同时，需要安装 Cypress 时，需要设置环境变量 CYPRESS_INSTALL_BINARY

最后，还是要强调一下，在生产安装依赖环节，使用如下命令安装依赖，则不会安装 Cypress 依赖

直接运行 Cypress

直接运行 Cypress 的场景是，e2e 作为 CI 的最后一个阶段，当应用完成部署后，再对应用运行线上的测试。

不推荐选择 cypress/included 镜像直接执行 Cypress 命令，因为很可能会遇到以下问题。
当然，如果自己的用例写的不好，也很可能会出现下面的问题。

使用 start-server-and-test

如果需要本地起个 localhost 服务，然后再运行 cypress。那么可以合作官方推荐的 start-server-and-test 模块。它在 CI 上的执行顺序是：

1. 在系统后台执行拉起本地服务的命令
2. 使用 wait-on 模块监听并等待该本地服务响应 200
3. 执行 test 命令，完成并退出
4. CI 环境此时会自动关闭所有后台进程并退出

下面以 gitlab.com 为例，展示执行完 gitlab jobs 后可看到 test 记录和下载测试产物（视频及截图）

• package.json

• .gitlab-ci.yml

This job is stuck

如果是自建的 gitlab, 可能会遇到这个问题。
这是任务没有打对标签，导致无法给任务分配对应的 Runner。

进入上图所示页面，注意找到可使用的 Runner

如上图所示， docker 标签对应的 Runner 是处于激活状态的，则在 CI 文件里配置即可

Cypress Dashbord

Cypress 官方提供了一个测试记录托管服务。在 CI 命令中，只需要加上 --record --key $key 即可。

CI 日志如下：

更多介绍请查阅官方文档

总结

cypress 比较适合写一个流程测试。一般情况下，只需要把整个正常流程操作使用 cypress 记录下来即可。

一个流程可能长这样：创建->验证->修改->验证->删除->验证。那我们就可以根据该流程，模拟填写合法数据，模拟点击提交按钮，检查页面是否有相应内容即可。

这样，每次开发新功能后，编写测试用例，再跑 Cypress，就能把一部分的回归测试自动化了，保证完成新功能的同时，原有功能最低限度地保持可用。

拓展阅读

• Cypress 实战总结

前言

本文将使用jest进行测试驱动开发的示例，源码在github。
旨在说明在开发中引入单元测试后开发过程，以及测试先行的开发思路。

本文的重点是过程以及思维方法，框架以及用法不是重点。

本文使用的编程语言是javascript，思路对其他语言也是适用的。

本文主要以函数作为测试对象。

环境搭建

假设项目结构为

• 安装依赖

• 打开package.json, 修改scripts字段

之后把测试文件放在test文件夹下，使用yarn test 即可查看测试结果

开发

现在要开发一个函数，根据传入的文件名判断是否为shell文件。

先做好约定：

1. shell文件应该以 .sh 结尾
2. shell文件不以 . 开头
3. 函数为名 isShellFile

下面来看下开发步骤是怎么样的。

文件初始化

在src目录下新建 isShellFile.js

然后一行代码也不写，在test目录下新建 isShellFile.test.js

可以注意到，测试文件的名与源文件名类似，只是中间多了个 .test

第一个用例

打开测试文件 test/isShellFile.test.js ，编写第一个用例，也是最普通的一个: bash.sh

运行 yarn test , 结果如下：

失败是意料之中的，因为 src/isShellFile.js 一行代码也没写，所以测试代码中第5行 isShellFile 无法进行函数调用。

完善源文件src/isShellFile.js

这样 isShellFile 就可以作为函数被调用了。

再运行 yarn test

又报错了，但这次报错原因跟上次不同，说明有进步。

这次报错原因是，期望函数调用返回值为真 , 但实际没有返回真 。

这是当然的，因为在源文件中，根本没有写返回语句。

为了让测试通过，修改 src/isShellFile.js

运行 yarn test , 测试通过了！

把上述修改，提交到版本控制系统中。

第二个用例

观察我们的测试用例，发现太简单了，只有正面的用例，没有反面的、异常的用例

在 test/isShellFile.test.js 添加一个反面的用例

运行 yarn test

(可以发现，在开发过程中需要反复执行上述命令，有个偷懒的办法，执行yarn test --watch，即可监听文件变化，自动执行测试用例)

报错了，期望返回假，但函数返回的是真。这是因为，源文件中， isShellFile 函数永远返回真！

完善 src/isShellFile.js 逻辑

测试通过了

把上述修改提交到版本控制系统

第三个用例

我们再添加一个用例，这次考虑特殊情况： .sh 这种文件，不算是shell文件。

修改 test/isShellFile.test.js

测试不通过

说明逻辑待完善，修改 src/isShellFile.js

测试通过(为精简文章内容，后面不再展示测试通过的输出)，提交代码。

第四个用例

按照第三个用例的逻辑， .bash.sh 也不应该是shell文件，那么函数是否能正确判断呢，测试便知。

修改 test/isShellFile.test.js

测试不通过

说明逻辑待完善，修改 src/isShellFile.js

测试通过，提交代码。

第五个用例

再考虑一种情况，如果 .sh 出现在中间呢？如 bash.sh.txt , 它不应该是shell文件，来看看函数是否能通过测试。

修改 test/isShellFile.test.js

测试不通过

说明逻辑待完善，修改 src/isShellFile.js

测试通过，提交代码。

重构

我们来观察目前 src/isShellFile.js 的函数逻辑

对于 .bashrc 这样的文件，并不是shell文件，因为它是以 . 开头的。

则通过 filename.startsWith('.') 判断即可，前面的函数调用 filename.lastIndexOf(".") 是多余的。也即，目前的函数判断逻辑不够简明。

下面是一种优化思路：

测试通过，提交代码

注意，这个重构示例的重点是：

1. 先完成功能，再重构
2. 重构必须要有测试用例，且确保重构后全部测试用例通过

至于其他方面，见仁见智，并不是重点。

结论

本文通过代码实例，践行了测试先行的理念。

文中的代码实现不是重点，而是开发过程。

文中 文件初始化 及 第一个用例 的内容，尤其值得回味，它体现了两个思路：

• 总是在有一个失败的单元测试后才开始编码
• 用必要的最小代码让测试通过

总的来看，TDD总是处于一个循环中：

1. 编写用例
2. 测试失败
3. 编写代码
4. 测试成功
5. 提交代码
6. 重复以上

通过这样，功能的实现每次都是最小成本的，功能也是有步骤地、通过迭代完成的，而不是一步登天。

更关键的是，完善的测试用例，是开发者的“守护天使”，有了它们，以后在添加新功能时，修改/重构代码都有了可靠的保障，让开发者可以充满信心，code with confidence😎！

另外，测试用例延伸出的思考还有：

1. 不需要追求完美软件，不用过分考虑将来的变化：先设计能符合当前需求的用例，再编码通过测试用例即可。将来有变化，重构代码即可，因为有用例，不用担心改错了。
2. 重构的前提，是存在完善的测试用例。如果没有用例，只有源码，是不敢谈轻易重构，否则就是在走钢丝。

前言

Playwright 是微软于 2020 年发布的一款 E2E testing 工具，跟社区成熟的 Cypress 相比，稍显年轻。然而 Playwright 的主要优势有：

1. 支持多语言：Node.js、Java、Python，也即它并非是前端工程师专属的工具
2. 开箱即用的代码生成功能（Cypress 现在也支持，不过要修改配置或安装插件）

另外，Playwright 的安装没什么门槛，不像 Cypress 可能需要黑魔法。

综上所述，笔者认为 Playwright 是值得在研发过程中引入的一款测试工具，它可以帮助研发、测试团队较平滑地走上自动化测试之路。它适用的典型场景之一，就是做回归测试——测试人员再也不用在界面上使用鼠标进行“点点点”，解放双手，提高测试效率。

安装

根据命令提示，输入如下：

默认会下载所有浏览器，如果没有浏览器兼容性测试的需求，推荐如上图所示，手动安装一个浏览器。

以安装 chromium 为例，相应操作步骤如下：

1. 修改配置

注释掉以下内容：

2. 安装浏览器

等待一段时间即可，如果失败，请重试。

推荐再安装 VS Code 插件，获取更好的使用体验。

使用

代码生成

虽然可以参考 example.spec.ts去编写测试用例，但这不是 Playwright 独特之处。Playwright 最引入注目的，是代码生成功能。

上述命令会打开两个浏览器窗口：

1. 一个是普通的浏览器界面
2. 另一个是代码生成界面，在前一个窗口进行的任何操作，都会生成相应的代码

虽然默认生成代码是 Javascript，但可以选择切换语言：

注意到可以生成 Pytest 的代码，对测试工程师来说，简直是福音。这也提示我们，Playwright 既可以由前端研发来使用，也可以由测试人员来使用，并不限制使用者的职业身份。

点击"Copy"按钮

然后打开代码编辑器，把代码复制进去即可。

点击"Clear"按钮，

可以清空本次操作生成的代码，从而开始进行下一次操作的代码生成。

如果是使用 VS Code 插件，点击"Record new"即可。

修改代码

生成的代码，最好还是检查一下，也许需要去掉一些多余的操作记录。
如下面的代码，Tab的操作只是人工操作时为了方便而进行的按键，对机器而言，是多余的，应该去掉。

如果想基于现在的测试代码，继续生成新的代码，可以使用 VS Code：

• 把光标放到测试用例的最后一行
• 点击"Record at cursor"，即可继续录制

执行用例

如果用例失败了，想查看到底哪里错了，可以用以下命令显示浏览器，查看用例执行过程：

如果是使用 VS Code，直接点击运行用例即可。

勾选左下角的"Show broswer"，即可显示浏览器。

调试用例

对于失败的用例，如何 debug呢？添加 --debug 参数即可。

点击"Step over" 即可执行下一行代码。

如果是使用 VS Code，找到相应的用例，右键出现"Debug Test"，点击即可。

查看报告

在执行完用例后，本地会生成目录 playwright-report，可以通过以下命令查看测试报告

常见场景与解决方案

应用登录

下面给出一个自动登录、并保存用户数据的解决方案。

先创建文件夹，并让 git 忽略它

创建 login.ts

修改 playwright.config.ts

环境变量

通常不同的环境 url 前缀是不同的，我们希望通过变量注入的方式来适配不同的环境，而不是硬编码在测试用例里。

我们可以借助模块 dotenv， 来配置 baseURL。

首先安装该模块：

在项目根目录新建 .env 文件：

输入以下内容：

修改 playwright.config.ts

然后，测试用例里，url 路径只写相对路径 /path，程序会自动拼接成完整的路径：http://dev-domain.company.com/path

以后要测试不同的环境时，只需要修改 .env 的变量值即可。

超时时间

默认的超时时间不太够用，建议修改 playwright.config.ts:

同时要注意拆分用例，没有依赖关系的用例建议拆分开来，避免用例执行时间过长超时。

元素选择

人们对元素选择的第一反应是使用 CSS 或 XPath，但 Playwright 并不鼓励这样使用，因为这些选择器容易改变。较为好的办法是，为测试元素添加专门的属性 testid，如下所示：

然后通过下列方式进行选择：

当然，这种方式会对源代码有侵入。更为折衷的方式是，优先使用下列官方推荐的方法进行元素选择，最后再使用业务 class，

这里值得一提的是，业务class是针对 Tailwind CSS 这种“解构主义”的纯样式class而言的。你会发现，如果全是 Tailwind 的class，没有业务样式，E2E测试代码很不好写。

更复杂的示例：

如果是使用 VS Code，有辅助办法：

1. 点击“Pick locator”
   
2. 切换到浏览器界面，点击目标元素
3. 切回 VS Code，即可看到相应的元素选择代码
   

声明断言 && 检查元素是否存在

生成的代码是没有断言的，因此，很有可能页面报错了，用例执行报告仍然显示成功。为避免这种情况，每个用例至少要有一句断言。

常用的断言是，检查某一元素是否存在：

当然也可以用以下方法，这取决于元素是否可见（元素存在，未必可见）。

注意，Node.js 才可以在 locator 里写 CSS 选择器，如果是 Python, 需要使用query_selector：

更多断言写法，参考官方文档(https://playwright.dev/docs/test-assertions#auto-retrying-assertions)。

获取第n个元素

通过定位器得到的元素可能不止一个，可以使用以下代码获得具体某一个元素：

遍历元素

使用定位器后，调用.all()

获取元素属性

判断子元素数量

使用 $ 及 $$ 元素选择器

鼠标悬浮

有些元素是在鼠标悬浮时才显示或创建的，可以使用以下代码

这里有个问题，自己怎么知道悬浮后显示的元素是否正确地定位到了呢？可以通过下面的小技巧：

1. 切换到 codegen 打开的浏览器页面
2. 打开网页控制台（按F12)
3. 鼠标悬浮在目标元素上面，然后右键，如下图所示

4. 点击控制台内部，则此时元素不会丢失 hover 状态，如下图所示

5. 切换到 VS Code

操作剪贴板

读写剪贴板需要设置权限，下面给出一个判断是否成功从剪贴板获取特定文本的测试用例：

持续集成

以 Gitlab CI 为例，说明 Playwright 如何集成进 CI 流水线中。其他方式如 Jenkins，请参考文档。

首先确保已安装 Gitlab Runner 并成功注册，具体操作可以参考安装文档。

端对端的测试耗时较长，并且对环境的稳定性有要求，作为回归测试的实践时，一般倾向于借助定时任务跑测试用例。

新建调度：

设置调度时间及环境变量：

• 每 6 小时跑一次
• e2e 环境变量的值为 true

现在可以开始编写 .gitlab-ci.yml，下面只给出测试相关的配置。

注意点：

1. entrypoint 解决的是 shell not found 问题
2. --ignore-engines 可以在不修改源码的情况下避免安装失败
3. 只有定时调度才会触发该任务的执行

再修改 Gitlab Runner 的配置，解决yarn命令无法运行的问题：

根据 token 找到对应的 Runner 配置，按照下图所示，把红框处的值设置成 true

config.toml 里面可能会有多个 Runner 配置，如何找到要修改哪一个呢？
可以在项目界面，根据下图所示的 token（w8exPBfA） 去查找。

修改完后，重启 Gitlab Runner

最后，使用 Chromium 可能会出现内存超出限制的问题，需要对 Docker 设置 --ipc=host，配置 .gitlab-ci.yml 如下：

其他

setup.py bdist_wheel did not run successfully

Python安装时，可能会再现此错误。解决方案如下：

之后，再安装

最后，重新安装Playwright即可

前言

虽然之前分享过 RestAssured 进行接口测试的教程，但实践起来，会有阻碍：研发同学还是对 Postman 更熟悉，更倾向于使用 Postman 调试接口，而不是写 Java 代码对 Controller 层进行测试。

而笔者在针对旧的 Java 项目添加接口测试时，又遇到了另一个问题：那就是由于模块依赖，进行接口测试时，还在把旧的测试代码一并带上。虽然说有办法解决，但究竟是麻烦不断。

还有就是，Java 的类型检查，在写接口测试时十分束缚手脚。如下述代码：

笔者实在忍不住吐槽了一番：

笔者思前想后，最终还是放弃测试代码要与源码使用统一技术栈的构想，再次搬出 Postman 作为接口自动化测试的工具。

本地调试

接口集合

新建一个 collection，然后再在里面新建接口。

新建方法多种多样，可以手工新建，也可以 curl 导入，也可以从 swagger 导入。

从 cURL 导入

对于已经上线的接口，使用 cURL 导入非常方便，省去了拼接参数的过程。

下面以获取 token 接口为例进行说明。

打开登录页面，打开浏览器控制台（按 F12），点击登录按钮，找到获取 token 的接口，然后右键 -> Copy -> Copy as cURL（bash）。

再打开 Postman，点击 Import 即可导入接口。

环境变量

点击右上角红框处，即可设置变量，需要先设置环境名。

一般设置 current value 即可，则运行 postman 时使用的就是该值。

如果有多套环境，就点击复制，再修改环境名及包含变量的 current value 即可。

使用 {{var}} 的形式引用变量，可在 url 及 body 处引用环境变量 var。

注意细节，如果是变量值是字符串，要用双引号把它包起来：

Postman内置了全局变量，输入 {{ 会出现提示：

使用示例：

环境变量还可以在测试用例里去修改值：

请求设置

对于请求体的发送，一般进行如下设置：

还可以利用 Pre-request Script， 在请求前动态修改请求设置。
比如有以下场景：

• 线上环境接口路径为：/app-name/api/v1/api-name
• 本地环境接口路径为：/v1/api-name，也即线上环境接口地址多了两个前缀

观察请求在 Postman 中的数据结构如下：

则可以编写前置脚本如下：

接口测试

编写用例

在 Tests 标签页里，即可编写测试，在 SNIPPETS 里会有相应的示例。

下面给出常用CRUD相关接口的测试用例代码：

• 设置 jwt

• 设置当天时间：

• 创建

• 修改

• 查询

• 删除

• 确保返回的数据里没有特定的数据

上传文件

如果要上传文件，则一般进行如下设置：

注意要把文件放到工作目录中。查看工作目录的方法如下：

把要上传的文件放到该目录下：

这样才方便后续运行集合、以及持续集成。

运行集合

本地调试好了，把代码部署到线上环境后，就可以使用 postman 对线上的接口进行测试了。

先切换到对应的环境，再重置变量当前值

再选择集合，点击 Run collection:

点击运行，可以看到集合内所有接口的执行结果：

提示：如果单独调试成功，运行集合却失败，注意检查文件是否已保存。如果文件处于编辑未保存状态，运行集合时使用的是修改前的接口。

持续集成

导出接口

导出接口合集：

使用推荐的格式，导出一个 json 文件。

导出环境变量

也是导出一个 json 文件。

复制要上传的文件

把要上传的文件，复制到项目根目录。

如果没有上传文件的接口，忽略此步骤。

提交到Git

把导出的 json 文件放到项目根目录中（与上传文件同级），并提交到 Git

建立CI任务

以 Gitlab 为例，修改.gitlab-ci.yml，增加以下内容：

推送代码，即可看到流水线

结果如下：

回归测试的必要性

基于 LLM 的 Chat 应用大量依赖了 Prompt Engineering，而用户的输入又千奇百怪，调整了 Prompt 模板，很可能会有意想不到的效果：满足了新需求，却破坏了旧功能。

因此，LLM应用比任何时候都需要回归测试，确保在迭代过程中，不破坏旧功能、不让已修复的bug复现。

而回归测试，当然是自动化执行效率才高。本文交分享如何使用 pytest 对 LLM 应用进行自动化的回归测试。

pytest

安装

pytest 的安装就有坑，如果是使用虚拟环境 venv，安装姿势不正确的话，就会在执行测试用例的时候报错：ModuleNotFoundError: No module named xxx，具体原因参考这篇文章。

正确的安装步骤：

1. 新开一个 bash 终端
2. pip uninstall pytest # 删除全局的 pytest
3. cd xxx && source ./venv/Scripts/activate # 激活虚拟环境
4. pip install pytest # 在虚拟环境中安装 pytest
5. pytest # 启动测试

配置

在项目根目录新建 pytest.ini 文件，最简单的配置如下：

更多的配置可参考文档。

用例

pytest 会自动收集测试用例，要求用例满足以下规范：

1. 文件名以 test_ 开头，如：test_intention.py
2. 用例名以 test_ 开头，如：def test_my_method():

为避免加载不到自定义的函数，需要包含以下代码：

给个实际的例子：

在终端激活虚拟环境后，执行 pytest即可运行上述用例。

如果只想执行单个文件，则指定文件名即可：

如果想出错马上退出，带 -x 参数即可：

持续集成

经过上述的步骤，我们可以在本地对自己的改动进行自动化的回归测试，但这还不够——因为有可能别人修改了代码，却不进行自测！

所以，我们还需要借助 CI 工具，在有人往代码仓库中提交改动后，立刻执行一次回归测试。

以 Gitlab CI 为例（点击查看安装教程），.gitlab-ci.yml 文件如下：

提交代码后就会触发自动化测试、构建镜像并推送。效果截图如下：

说明

AI时代，学会正确上网是必备的技能。不然，谷歌用不了你还能忍，但 New Bing 跟 ChatGPT 都用不了，你还能忍？

本文讲教大家如何购买稳定的包年上网套餐，为使用各种 AI 工具打下基础。

购买指南

点击进入服务页面, 看到如下页面：

点击注册账户, 会出现如图提示：

点击购买产品，就会出现查看产品列表面（为什么要这么绕，因为这是保护措施，避免产品主页被黑）。

推荐购买 Basic 套餐，一个人用的话，学习工作、娱乐看视频，每月 50GB 足够了。多个客户端可以同时在线，反正就是随便玩！算下来，一天不到7毛钱，很划算了。

点击购买后，选择包年，即可享受优惠价格，如下图所示：

支持支付宝，购买非常方便。

客户端

支持全平台客户端：

• Mac 推荐 ClashX
• Windows 推荐 Shadowsocks
• Android 推荐 V2ray
• iOS 推荐 Shadowrocket（花点小钱，使用美区 apple id——文末有分享如何申请）

导入配置

以 Shadowsocks 为例。

根据客户端复制相应的订阅地址:

先禁用系统代理:

点击在线配置:

输入URL，点击更新:

选择一个服务器:

再恢复系统代理，选择PAC模式:

就可以愉快地上网啦！

其他

500 内部代理错误

出现此问题时，一般是内网自定义域名不允许走代理，需要禁用掉系统代理:

修改PAC文件

PAC模式是指：根据规则识别某网站是否需要使用代理访问。

什么时候需要修改PAC文件呢？

• 当某个网站不想走代理
• 设置某网站一定走代理

操作如下（以Shadowsocks为例）:

按下图所示，模仿添加，即可实现遇到下列网站时选择直连:

不走代理的示例修改:

必走代理的示例修改:

保存后记得重启软件。

使用 New Bing