大多数前端开发者在公司里，很少需要直接操心“部署”这件事——那通常是运维或 DevOps 的工作。

但一旦回到个人项目，情况就完全不一样了。写个小博客、搭个文档站，或者搞个 demo 想给朋友看，部署往往成了最大的拦路虎。

常见的选择无非是 Vercel、Netlify 或 GitHub Pages。它们表面上“一键部署”，但细节其实并不轻松：要注册平台账号、要配置域名，还得接受平台的各种限制。国内的一些云服务商（比如阿里云、腾讯云）管控更严格，操作门槛也更高。更让人担心的是，一旦平台宕机，或者因为地区网络问题导致访问不稳定，你的项目可能随时“消失”在用户面前。虽然这种情况不常见，但始终让人心里不踏实。

很多时候，我们只是想快速上线一个小页面，不想被部署流程拖累，有没有更好的方法？

一个更轻的办法

前段时间我发现了一个开源工具 PinMe，主打的就是“极简部署”。

它的使用体验非常直接：

• 不需要服务器


• 不用注册账号


• 在项目目录敲一条命令，就能把项目打包上传到 IPFS 网络


• 很快，你就能拿到一个可访问的地址

实际用起来的感受就是一个字：爽。

整个过程几乎没有繁琐配置，不需要绑定平台账号，也不用担心流量限制或收费。

这让很多场景变得顺手：

• 临时展示一个 demo，不必折腾服务器


• 写了个静态博客，不想搞 CI/CD 流程


• 做了个活动页或 landing page，随时上线就好

以前这些需求可能要纠结“用 GitHub Pages 还是 Vercel”，现在有了 PinMe，直接一键上链就行。

体验一把

接下来看看它在真实场景下的表现：部署流程有多简化？访问速度如何？和传统方案相比有没有优势？

测试项目

为了覆盖不同体量的场景，这次我选了俩类项目来测试：

• 小型项目：fuwari（开源的个人博客项目），打包体积约 4 MB。


• 中大型项目：Soybean Admin（开源的后台管理系统），打包体积约 15 MB。

部署项目

PinMe 提供了两种方式：命令行 和 可视化界面。

这两种方式我们都来试一下。

命令行部署

先全局安装：

npm install -g pinme

然后一条命令上传：

pinme upload <folder/file-path>

比如上传 Soybean Admin，文件大小 15MB：

输入命令之后，等着就可以了：

只用了两分钟，终端返回的 URL 就能直接访问项目的控制页面。还能绑定自己的域名：

点击网站链接就可以看到已经部署好的项目，访问速度还是挺快的：

同样地，上传个人博客也是一样的流程。

部署完成：

可视化部署

不习惯命令行？PinMe 也提供了网页上传，进度条实时显示：

部署完成后会自动进入管理页面：

经过测试，部署速度和命令行几乎一致。

其他功能

历时记录

部署过的网站都能在主页的 History 查看：

历史部署记录：

也可以用命令行：

pinme list

历史部署记录：

删除网站

如果不再需要某个项目，执行以下命令即可：

pinme rm

PinMe 背后的“硬核支撑”

如果只看表层，PinMe 就像一个极简的托管工具。但要理解它为什么能做到“不依赖平台”，还得看看它背后的底层逻辑。

PinMe 的底层依赖 IPFS，这是一个去中心化的分布式文件系统。

要理解它的意义，得先聊聊“去中心化”这个概念。

传统互联网是中心化的：你访问一个网站时，浏览器会通过 DNS 找到某台服务器，然后从这台服务器获取内容。这条链路依赖强烈，一旦 DNS 被劫持、服务器宕机、服务商下线，网站就无法访问。

去中心化的思路完全不同：

• 数据不是放在单一服务器，而是分布在全球节点中


• 访问不依赖“位置”，而是通过内容哈希来检索


• 只要有节点存储这份内容，就能访问到，不怕单点故障

这意味着：

• 更稳定：即使部分节点宕机，内容依然能从其他节点获取。


• 防篡改：文件哪怕改动一个字节，对应的 CID 也会完全不同，从机制上保障了前端资源的完整性和安全性。


• 更自由：不再受制于中心化平台，文件真正由用户自己掌控。

当然，IPFS 地址（哈希）太长，不适合直接记忆和分享。这时候就需要 ENS（Ethereum Name Service）。它和 DNS 类似，但记录存储在以太坊区块链上，不可能被篡改。比如你可以把 myblog.eth 指向某个 IPFS 哈希，别人只要输入 ENS 域名就能访问，不依赖传统 DNS，自然也不会被劫持。

换句话说：

ENS + IPFS = 内容去中心化 + 域名去中心化

前端个人项目瞬间就有了更高的自由度和安全性。

一点初步感受

PinMe 并不是要取代 Vercel 这类成熟平台，但它带来了一种新的选择：更简单、更自由、更去中心化。

如果你只是想快速上线一个小项目，或者对去中心化部署感兴趣，PinMe 值得一试。

• 官网：pinme.eth.limo/


• Github：github.com/glitternetw…

这是一个完全开源的项目，开发团队也会持续更新。如果你在测试过程中有想法或需求，不妨去 GitHub 提个 Issue —— 这不仅能帮助项目成长，也能让它更贴近前端开发的实际使用场景！

前端开发者应该对 Ant Design 不陌生，特别是 React 开发者，antd 应该是组件库的标配了。

近年来随着 AI 的爆火，凡是想要接入 AI 的都想搞一套自己的 AI 交互界面。专注于 AI 场景组件库的开源项目倒不是很多见，近日 antd 宣布推出 Ant Design X 1.0 🚀 ，这是一个基于 Ant Design 的全新 AGI 组件库，使用 React 构建 AI 驱动的用户交互变得更简单了，它可以无缝集成 AI 聊天组件和 API 服务，简化 AI 界面的开发流程。

该项目已在 Github 开源，拥有 1.6K Star！

看了网友的评论，看来大家还是需要的！当前的 Ant Design X 只支持 React 项目，看来 Vue 开发者要羡慕了...

ant-design-x 特性

• 🌈 源自企业级 AI 产品的最佳实践：基于 RICH 交互范式，提供卓越的 AI 交互体验


• 🧩 灵活多样的原子组件：覆盖绝大部分 AI 对话场景，助力快速构建个性化 AI 交互页面


• ⚡ 开箱即用的模型对接能力：轻松对接符合 OpenAI 标准的模型推理服务


• 🔄 高效管理对话数据流：提供好用的数据流管理功能，让开发更高效


• 📦 丰富的样板间支持：提供多种模板，快速启动 LUI 应用开发


• 🛡 TypeScript 全覆盖：采用 TypeScript 开发，提供完整类型支持，提升开发体验与可靠性


• 🎨 深度主题定制能力：支持细粒度的样式调整，满足各种场景的个性化需求

支持组件

以下圈中的部分为 ant-design-x 支持的组件。可以看到主要都是基于 AI Chat 场景的组件设计。现在你可以基于这些组件自由组装搭建一个自己的 AI 界面。

ant-design-x 也提供了一个完整 AI Chat 的 Demo 演示，可以查看 Demo 的代码并直接使用。

更多组件详细内容可参考 组件文档

使用

以下命令安装 @ant-design/x 依赖。

注意，ant-design-x 是基于 Ant Design，因此还需要安装依赖 antd。

yarn add antd @ant-design/x

import React from 'react';

import {

  // 消息气泡

  Bubble,

  // 发送框

  Sender,

} from '@ant-design/x';



const messages = [

  {

    content: 'Hello, Ant Design X!',

    role: 'user',

  },

];

const App = () => (

  <div>

    <Bubble.List items={messages} />

    <Sender />

  </div>

);



export default App;

Ant Design X 前生 ProChat

不知道有没有小伙伴们使用过 ProChat，这个库后面的维护可能会有些不确定性，其维护者表示 “24 年下半年后就没有更多精力来维护这个项目了，Github 上的 Issue 存留了很多，这边只能尽量把一些恶性 Bug 修复”

如上所示，也回答了其和 Ant Design X 的关系：ProChat 是 x 的前生，新用户请直接使用 x，老用户也请尽快迁移到 x。

感兴趣的朋友们可以去试试哦！

什么是事件循环？

事件循环是 JavaScript 运行时的一个核心机制，它管理着代码的执行顺序。它是一种机制，用于处理异步操作，事件循环的核心是一个循环，它不断地检查调用栈和任务队列，以确保代码按照正确的顺序执行。

JavaScript 的单线程本质

JavaScript 被设计为单线程语言，这意味着它只有一个调用栈，一次只能执行一段代码。这听起来像是一个限制，但正是这种简单性让 JavaScript 如此易于使用。

console.log('开始'); // 1



setTimeout(() => {

  console.log('定时器回调'); // 3

}, 1000);



console.log('结束'); // 2



// 输出顺序：

// 开始

// 结束

// 定时器回调

事件循环的组成部分

1. 调用栈（Call Stack）

调用栈是 JavaScript 执行代码的地方。当函数被调用时，它会被推入栈顶；当函数返回时，它会从栈顶弹出。

function first() {

  console.log('第一个函数');

  second();

}



function second() {

  console.log('第二个函数');

}



first();

2. 任务队列（Task Queue）

任务队列（也称为宏任务队列）存储着待处理的任务，如：

• setTimeout 和 setInterval 回调


• I/O 操作


• UI 渲染


• 事件处理程序

3. 微任务队列（Microtask Queue）

微任务队列具有更高的优先级，包括：

• Promise 回调（.then(), .catch(), .finally()）


• queueMicrotask()


• MutationObserver

事件循环的工作流程

事件循环遵循一个简单的循环：

console.log('脚本开始'); // 同步代码



setTimeout(() => {

  console.log('setTimeout'); // 宏任务

}, 0);



Promise.resolve()

  .then(() => {

    console.log('Promise 1'); // 微任务

  })

  .then(() => {

    console.log('Promise 2'); // 微任务

  });



console.log('脚本结束'); // 同步代码



// 输出顺序：

// 脚本开始

// 脚本结束

// Promise 1

// Promise 2

// setTimeout

实际应用示例

场景 1：用户交互与数据获取

// 模拟用户点击和API调用

document.getElementById('button').addEventListener('click', () => {

  console.log('点击事件处理'); // 宏任务

  

  // 微任务优先于渲染

  Promise.resolve().then(() => {

    console.log('Promise 在点击中');

  });

  

  // 模拟API调用

  fetch('/api/data')

    .then(response => response.json())

    .then(data => {

      console.log('获取到的数据:', data); // 微任务

    });

});



console.log('脚本加载完成');

场景 2：动画性能优化

// 不推荐的写法 - 可能阻塞渲染

function processHeavyData() {

  const data = Array.from({length: 100000}, (_, i) => i);

  return data.map(x => Math.sqrt(x)).filter(x => x > 10);

}



// 推荐的写法 - 使用事件循环分块处理

function processInChunks(data, chunkSize = 1000) {

  let index = 0;

  

  function processChunk() {

    const chunk = data.slice(index, index + chunkSize);

    

    // 处理当前块

    chunk.forEach(item => {

      // 处理逻辑

    });

    

    index += chunkSize;

    

    if (index < data.length) {

      // 使用 setTimeout 让出控制权，允许渲染

      setTimeout(processChunk, 0);

    }

  }

  

  processChunk();

}

常见陷阱与最佳实践

陷阱 1：阻塞事件循环

// ❌ 避免 - 长时间运行的同步操作

function blockingOperation() {

  const start = Date.now();

  while (Date.now() - start < 5000) {

    // 阻塞5秒

  }

  console.log('操作完成');

}



// ✅ 推荐 - 使用异步操作

async function nonBlockingOperation() {

  await new Promise(resolve => setTimeout(resolve, 5000));

  console.log('操作完成');

}

陷阱 2：微任务递归

// ❌ 可能导致微任务无限循环

function dangerousRecursion() {

  Promise.resolve().then(dangerousRecursion);

}



// ✅ 使用 setImmediate 或 setTimeout 打破循环

function safeRecursion() {

  Promise.resolve().then(() => {

    setTimeout(safeRecursion, 0);

  });

}

现代 JavaScript 中的事件循环

async/await 与事件循环

async function asyncExample() {

  console.log('开始 async 函数');

  

  await Promise.resolve();

  console.log('在 await 之后'); // 微任务

  

  const result = await fetch('/api/data');

  console.log('数据获取完成'); // 微任务

}



console.log('脚本开始');

asyncExample();

console.log('脚本结束');



// 输出顺序：

// 脚本开始

// 开始 async 函数

// 脚本结束

// 在 await 之后

// 数据获取完成

调试技巧

1. 使用 console 理解执行顺序

console.log('同步 1');



setTimeout(() => console.log('宏任务 1'), 0);



Promise.resolve()

  .then(() => console.log('微任务 1'))

  .then(() => console.log('微任务 2'));



queueMicrotask(() => console.log('微任务 3'));



console.log('同步 2');

2. 性能监控

// 测量任务执行时间

const startTime = performance.now();



setTimeout(() => {

  const endTime = performance.now();

  console.log(`任务执行耗时: ${endTime - startTime}ms`);

}, 0);

执行顺序问题

网上很经典的面试题

async function async1 () {

  console.log('async1 start')

  await async2() 

  console.log('async1 end') 

}



async function async2 () {

  console.log('async2')

}



console.log('script start')



setTimeout(function () { 

  console.log('setTimeout')

}, 0)



async1()



new Promise (function (resolve) { 

  console.log('promise1') 

  resolve()

}).then (function () { 

  console.log('promise2')

})



console.log('script end')

输出结果

script start

async1 start

async2

promise1

script end

async1 end

promise2

setTimeout

总结

理解 JavaScript 事件循环对于编写高效、响应迅速的应用程序至关重要。记住这些关键点：

• 同步代码首先执行


• 微任务在同步代码之后、渲染之前执行


• 宏任务在微任务之后执行


• 避免阻塞主线程


• 合理使用微任务和宏任务

掌握事件循环机制将帮助你写出更好的异步代码，避免常见的性能问题，并创建更流畅的用户体验。

希望这篇博客能帮助你更好地理解 JavaScript 的事件循环机制！如果你有任何问题或想法，欢迎在评论区讨论。

在 JavaScript 开发中，遵循良好的编程规范对于构建高效、可维护的代码至关重要。它不仅能提升代码的可读性，让团队成员之间更容易理解和协作，还能减少错误的发生，提高开发效率。本文将详细介绍 JavaScript 编程中的一些重要规范。

一、命名规范

变量和函数命名

采用小驼峰命名法，第一个单词首字母小写，后续单词首字母大写。例如firstName用于表示名字变量，getUserName函数用于获取用户名。这种命名方式能够清晰地区分变量和函数，并且让名称具有语义化，便于理解其用途。避免使用单字母或无意义的命名，如a、b等，除非在特定的循环等场景下有约定俗成的用法。

常量命名

常量通常使用全大写字母，单词之间用下划线分隔，比如MAX_COUNT表示最大计数，API_URL表示 API 的链接地址。这样的命名方式能够直观地让开发者知道该变量是一个常量，其值在程序运行过程中不会改变。

二、语法规范

使用严格模式

在脚本或函数的开头添加'use strict';开启严格模式。严格模式下，JavaScript 会进行更严格的语法检查，比如禁止使用未声明的变量，防止意外创建全局变量等常见错误。它有助于开发者养成良好的编程习惯，提高代码的质量和稳定性。

// 严格模式

function strictWithExample() {

    'use strict';

    var obj = { x: 1 };

    // 抛出 SyntaxError

    with (obj) {

        console.log(x);

    }

}

strictWithExample();

语句结束加分号

尽管 JavaScript 在某些情况下可以省略分号，但为了避免潜在的错误和代码歧义，强烈建议在每条语句结束后都加上分号。

例如let num = 5和let num = 5;，前者在一些复杂的代码结构中可能会因为自动分号插入机制而出现意想不到的问题，而后者则明确地表示了语句的结束。

let num = 5

console.log(num)

[1, 2, 3].forEach(function (element) {

    console.log(element);

});

在上述代码中，let num = 5 后面没有分号，由于 [ 是 JavaScript 中的数组字面量符号，同时也可以用于数组的索引访问操作（例如 arr[0]），所以引擎会认为你可能想要对 num 进行某种与数组相关的操作，比如 num[1, 2, 3]（虽然这在语法上是错误的，因为 num 是一个数字，不是数组）。

代码缩进

统一使用 2 个或 4 个空格进行缩进，这能让代码的层次结构一目了然。比如在嵌套的if - else语句、循环语句等结构中，合理的缩进能清晰地展示代码的逻辑关系，使代码更易于阅读和维护。

代码块使用大括号

即使代码块中只有一条语句，也建议使用大括号括起来。例如：

if (condition) {

    doSomething();

}

这样在后续需要添加更多语句到代码块中时，能避免因遗漏大括号而导致的语法错误。

三、比较操作规范

尽量使用===和!==进行比较操作，避免使用==和!=。因为==和!=在比较时会进行类型转换，这可能会带来意外结果。例如'5' == 5会返回true，而'5' === 5会返回false，在实际开发中，明确知道数据类型并使用全等操作符能减少错误的发生。

四、代码结构规范

避免全局变量污染

在 JavaScript 开发中，尤其是构建大型项目时，全局变量带来的问题不容小觑。全局变量如同在公共空间随意摆放的物品，极易引发混乱。在一个复杂项目中，可能有多个开发人员同时工作，不同模块的代码相互交织。如果每个模块都随意创建全局变量，很容易出现命名冲突。

• 例如，一个模块定义了全局变量count用于记录某个操作的次数，另一个模块可能也需要使用count变量来记录其他信息，这就会导致变量值被意外覆盖，引发难以排查的错误。

同时，在大型项目中，代码的维护和调试本身就具有挑战性。全局变量的存在会使问题变得更加棘手。因为全局变量在整个程序的生命周期内都存在，其值可能在程序的任何地方被修改。当出现错误时，开发人员很难确定是哪个部分的代码对全局变量进行了不恰当的修改，增加了调试的难度和时间成本。

模块化

为了解决这些问题，模块化是一种非常有效的手段。通过将相关的功能代码封装在一个模块中，每个模块都有自己独立的作用域。在 JavaScript 中，ES6 引入了模块系统，使用export和import关键字来管理模块的导出和导入。例如，有一个处理用户数据的模块userModule.js：

// userModule.js

const userData = {

    name: '',

    age: 0

};



function setUserName(name) {

    userData.name = name;

}



function getUserName() {

    return userData.name;

}



export { setUserName, getUserName };

在这个模块中，userData和setUserName、getUserName函数都在模块内部作用域中，外部无法直接访问userData。只有通过导出的setUserName和getUserName函数，其他模块才能间接操作userData。在其他模块中使用时，可以这样导入：

// main.js

import { setUserName, getUserName } from './userModule.js';



setUserName('John');

console.log(getUserName()); 

这样就有效地避免了全局变量的使用，降低了命名冲突的风险，同时也使得代码的结构更加清晰，易于维护和调试。

立即执行函数表达式（IIFE）

另一种方式是使用立即执行函数表达式（IIFE）。在 JavaScript 中，通过将函数定义包裹在括号中，并紧接着在后面加上括号进行调用，便形成了一个 IIFE。IIFE 能够创建一个独立的函数作用域，在该作用域内定义的变量和函数均为私有。这就确保了函数内部的变量和函数不会被外部随意访问和修改 。例如：

const app = (function () {

    let privateVariable = 10;



    function privateFunction() {

        console.log('This is a private function.');

    }



    return {

        publicFunction: function () {

            privateFunction();

            console.log('The value of private variable is:', privateVariable);

        }

    };

})();



app.publicFunction(); 

在上述代码中，

• (function () {... })()：在包裹匿名函数的括号后面再添加一对括号()，这对括号用于立即调用前面定义的匿名函数。当 JavaScript 引擎执行到这部分代码时，就会立即调用这个匿名函数，所以称为 “立即执行函数”。


• privateVariable和privateFunction都在 IIFE 内部的私有作用域中，因此外部无法直接访问它们。通过返回一个包含publicFunction的对象，向外暴露了一个公共接口，这样一来既实现了功能，又避免了全局变量污染。

合理使用注释

在关键代码逻辑处添加注释，解释代码的功能、用途、算法思路等。注释要简洁准确，避免过度注释。

• 例如在一个复杂的算法函数前，可以注释说明该算法的作用、输入参数和返回值的含义，方便其他开发者理解代码。


• 但不要在过于简单的代码上添加冗余注释，如let num = 1; // 定义一个数字变量，这样的注释对理解代码没有实质性帮助。

五、注释规范

注释分为单行注释和多行注释。单行注释使用//，用于对某一行代码进行简单解释。多行注释使用/* */，适合对一段代码块进行详细说明。在写注释时，要确保注释与代码同步更新，避免代码修改后注释不再准确的情况。

六、异步编程规范

随着 JavaScript 在前端和后端开发中的广泛应用，异步编程变得越来越重要。使用async/await语法可以让异步代码看起来更像同步代码，提高代码的可读性。例如：

async function getData() {

    try {

        let response = await fetch('https://example.com/api');

        let data = await response.json();

        return data;

    } catch (error) {

        console.error('获取数据失败', error);

    }

}

在处理多个异步操作时，要注意合理控制并发数量，避免因过多并发请求导致性能问题。

七、代码格式化规范

使用代码格式化工具，如 Prettier、ESLint 等，能够自动按照设定的规则对代码进行格式化。它可以统一代码风格，包括缩进、空格、换行等，使团队成员的代码风格保持一致，减少因风格差异带来的冲突和阅读障碍。

八、代码复用

尽量编写可复用的代码，通过函数封装、模块封装等方式，将重复使用的代码逻辑提取出来。

• 例如，在多个地方需要对数据进行格式化处理，可以编写一个通用的数据格式化函数，在需要的地方调用，这样不仅能减少代码量，还方便维护和修改。

九、错误处理

在代码中要合理处理错误，使用try - catch块捕获可能出现的异常。对于异步操作，也要通过try - catch或者.catch方法来处理错误。

• 例如在网络请求失败时，要及时向用户反馈错误信息，而不是让程序崩溃。同时，可以自定义错误类型，以便在不同的业务场景下进行更精准的错误处理。

遵循这些 JavaScript 编程规范，能够帮助开发者写出更整洁、高效、易于维护的代码。在实际开发中，团队可以根据项目需求进一步细化和完善这些规范，以提升整个项目的质量。

一.为什么需要理解设计模式？

前端项目会随着需求迭代变得越来越复杂，设计模式的作用就是提前规避 “后期难改、牵一发动全身” 的坑，设计模式的核心价值：解决 “可维护、可扩展” 问题。

1.工厂模式

工厂模式：通过一个统一的 “工厂函数 / 类” 封装对象的创建逻辑，外界只需传入参数（如类型、配置），即可获取所需实例，无需关心实例内部的构造细节。核心是 “创建逻辑与使用逻辑分离”，实现批量、灵活地创建相似对象。

前端应用场景：

1.Axios 实例

2.Vue实例

3.组件库中的 “表单组件工厂”,统一管理所有表单组件的基础属性（如 id、disabled）

2.单例模式：确保全局只有一个实例

核心是为了解决 “重复创建实例导致的资源浪费、状态混乱、逻辑冲突” 问题—— 当某个对象在系统中只需要 “唯一存在” 时，单例模式能确保全局访问到的是同一个实例，从根源避免多实例带来的隐患。

前端典型场景：

1.Vuex单一store实例

2.浏览器的 window 对象

3.原型模式：通过 “复制” 创建新对象

原型模式的核心是 “基于已有对象（原型）复制创建新对象” —— 不是从零开始定义新对象的属性和方法，而是直接 “拷贝” 一个现有对象（原型）的结构，再根据需要修改差异化内容。

前端中原型模式的本质：依托 JavaScript 原型链。

JavaScript 本身就是基于原型的语言，所有对象都有 __proto__ 属性（指向其原型对象），这是原型模式在前端的 “天然实现”。

普通对象原型属性: 只有'proto'属性。

函数原型属性：proto、prototype属性。

prototype：专属属性，只有函数有，用于 "当函数作为构造函数时，给新创建的实例提供原型"。

原型链顶端： Object.prototype.proto :指向null ;

前端典型场景：

1.Object.create()

2.Vue2 的数组方法重写：Vue2 为数组的push、pop等方法添加响应式逻辑，新数组会继承这些重写后的方法。

3.继承

工厂模式与原型模式区别：

工厂模式：

基于参数 / 规则 “全新创建” 对象；

核心目的：封装复杂的创建逻辑，让调用者无需关心对象构造细节。

原型模式

基于 “已有原型对象” 复制生成新对象

核心目的：复用已有对象的属性 / 方法，减少重复定义，支持继承扩展

4.观察者模式：“一对多” 的依赖通知机制

观察者模式（Observer Pattern）是一种 “一对多” 的依赖关系设计模式：

• 存在一个 “被观察者（Subject）” 和多个 “观察者（Observer）”；


• 当被观察者的状态发生变化时，会自动通知所有依赖它的观察者，并触发观察者的更新逻辑；


• 核心是 “解耦被观察者和观察者”—— 双方无需知道彼此的具体实现，只需通过统一的接口通信

前端典型场景：

1.浏览器事件监听（最基础的观察者模式）

浏览器的 DOM 事件本质是观察者模式的实现：

• 被观察者：DOM 元素（如按钮）；


• 观察者：事件处理函数（onclick、onchange 等）；


• 流程：给元素绑定事件（订阅）→ 元素状态变化（如被点击）→ 自动执行所有绑定的事件处理函数（通知观察者）。


• 观察者模式的核心价值是 “状态变化自动同步”

2.状态管理库（Vuex/Pinia/Redux）

Vuex、Redux 等全局状态管理库的核心机制就是观察者模式：

• 被观察者：Store 中的状态（如 state.user、state.cart）；


• 观察者：依赖该状态的组件；


• 流程：组件订阅状态（mapState 或 useSelector）→ 状态更新（commit 或 dispatch）→ 所有订阅该状态的组件自动重新渲染（收到通知更新）

3. 框架的响应式系统（Vue/React）

Vue 的响应式原理（数据驱动视图）和 React 的状态更新机制，底层都依赖观察者模式：

• Vue：数据对象（data）是被观察者，视图（DOM）和计算属性是观察者 —— 数据变化时，Vue 自动触发依赖收集的观察者（视图重新渲染、计算属性重新计算）。


• React：setState 触发状态更新时，组件树中依赖该状态的组件（观察者）会被重新渲染（收到通知执行更新）。

5.发布-订阅模式

发布 - 订阅模式是观察者模式的变体，核心是通过一个 “中间者（事件中心）” 实现 “发布者” 和 “订阅者” 的完全解耦 —— 发布者不用知道谁在订阅，订阅者也不用知道谁在发布，双方仅通过事件中心传递消息，就像 “报社（发布者）→ 邮局（事件中心）→ 订报人（订阅者）” 的关系。

• 三大角色：
  
  
  
  
  1. 发布者（Publisher） ：负责 “发布事件”（比如触发某个状态变化，如用户登录、数据更新），但不直接联系订阅者；
  
  
  2. 订阅者（Subscriber） ：负责 “订阅事件”（比如关注 “用户登录” 事件），并定义事件触发时的 “回调逻辑”（比如登录后显示欢迎信息）；
  
  
  3. 事件中心（Event Bus） ：中间枢纽，负责存储 “事件 - 订阅者” 的映射关系，接收发布者的事件并通知所有订阅者。
  
  
  
  


• 核心逻辑：订阅者先在事件中心 “订阅” 某个事件 → 发布者在事件中心 “发布” 该事件 → 事件中心找到所有订阅该事件的订阅者，触发它们的回调。

与观察者模式区别：

前端典型场景：

1.跨组件通信（事件总线 Event Bus）

2.全局状态管理（如 Redux 的 Action 机制）

• 发布者：组件通过 dispatch(action) 发布 “状态变更事件”；


• 事件中心：Redux 的 Store，存储状态并管理订阅者；


• 订阅者：组件通过 store.subscribe(() => { ... }) 订阅状态变化，状态更新时重新渲染。

状态管理库到底是观察者模式还是发布 - 订阅模式？

状态管理库（如 Vuex、Redux）之所以会让人觉得 “既是观察者模式，又是发布 - 订阅模式”，是因为它们融合了两种模式的核心思想—— 在底层实现上，既保留了观察者模式 “状态与依赖直接关联” 的特性，又通过 “中间层” 实现了发布 - 订阅模式的 “解耦” 优势，本质是两种模式的结合与优化。

1. 底层：状态与组件的 “观察者模式”（直接依赖）

状态管理库中， “全局状态” 与 “依赖该状态的组件”  之间是典型的观察者模式：

• 被观察者：全局状态（如 Vuex 的 state、Redux 的 store）；


• 观察者：订阅了该状态的组件；


• 逻辑：当状态发生变化时，会直接通知所有依赖它的组件（观察者），触发组件重新渲染。

这一层的核心是 “精准依赖”—— 组件只订阅自己需要的状态（比如 Vue 的 mapState、Redux 的 useSelector），状态变化时只有相关组件会被通知，避免无效更新。

2. 上层：组件与状态的 “发布 - 订阅模式”（解耦通信）

状态管理库中， “组件触发状态变更” 与 “状态变更通知组件”  的过程，通过 “中间层（如 commit/dispatch）” 实现，类似发布 - 订阅模式：

• 发布者：触发状态变更的组件（通过 store.commit('increment') 或 dispatch(action) 发布 “状态变更事件”）；


• 事件中心：状态管理库的核心逻辑（如 Vuex 的 Store 实例、Redux 的 dispatch 机制）；


• 订阅者：依赖状态的组件（通过 subscribe 或计算属性订阅状态）。

这一层的核心是 “解耦”—— 组件不需要知道谁会处理状态变更，也不需要知道哪些组件依赖该状态；状态管理库作为中间层，接收 “发布” 的变更请求，处理后再 “通知” 订阅者，双方完全隔离。

6.代理模式

代理模式（Proxy Pattern）是一种 “通过中间代理对象控制对原始对象的访问” 的设计模式 —— 不直接操作目标对象，而是通过一个 “代理” 来间接访问，代理可以在访问前后添加额外逻辑（如权限校验、缓存、日志记录等）。

核心作用：“控制访问” 与 “增强功能”

前端典型场景：

1. 权限控制代理（限制访问）

2.Vue3响应式核心

用 “中间商” 的思路理解 Vue3 响应式：

• 目标对象：你定义的 data 数据（如 { count: 0, user: { name: '张三' } }）；


• 代理对象：Vue3 通过 reactive() 或 ref() 创建的 “响应式代理”（本质是 Proxy 实例）；


• 调用者：组件中的模板（视图）或业务逻辑（如 {{ count }} 或 count.value++）；


• 代理的 “附加操作” ：拦截数据的读取（get）和修改（set），在读取时 “收集依赖”（记录哪些地方用到了这个数据），在修改时 “触发更新”（通知依赖的地方重新渲染）。

1. 目标对象：原始数据 const target = { count: 0 }; 

2. 依赖收集的容器：记录哪些函数依赖了数据（比如视图渲染函数）

const deps = new Set(); 

3. 创建代理对象（核心：拦截读写，添加响应式逻辑） 

const reactiveProxy = new Proxy(target, 

{

// 拦截“读取数据”操作（如访问 count 时）

get(target, key){

    // 附加操作1：

    收集依赖（假设当前正在执行的函数是依赖） 

    if (currentEffect) { deps.add(currentEffect); // 把依赖存起来 } 

    return target[key]; // 返回原始值 }, 

}

 // 拦截“修改数据”操作（如 count++ 时） 

set(target, key, value) { 

// 更新原始数据 

target[key] = value; 

// 附加操作2：触发更新（通知所有依赖重新执行） 

deps.forEach(effect => effect()); return true; } }); 

}

扩展：Vue3响应式对比vue2响应式

1.Vue2 用的是 Object.defineProperty 拦截属性，只能拦截已存在的属性（对新增属性、数组索引修改不友好）；

具体原因拆解：

Object.defineProperty 的工作方式是给对象的某个具体属性添加 getter/setter。

但数组本质是特殊对象（属性是索引，如 arr[0]、arr[1]），如果用 Object.defineProperty 拦截数组，只能逐个拦截索引（如 0、1），但存在两个致命问题：

1.问题一：无法拦截数组的原生方法（push/pop/splice 等）
数组的常用操作（如 push 新增元素、splice 删除元素）是通过调用数组原型上的方法实现的，这些方法会直接修改数组本身，但 Object.defineProperty 无法拦截 “方法调用”，只能拦截 “属性读写”。所以最终Vue2采取了这7个数组方法的重写。

 arrayMethods[method] = function(...args) {

    // 先调用原生方法（比如 push 实际添加元素）

    const result = arrayProto[method].apply(this, args);

    // 手动触发更新（通知依赖重新渲染）

    notifyUpdate(); 

    return result;

2.问题二：拦截数组索引的成本极高，且不实用。

• 初始化成本高：数组长度可能很大（甚至动态变化），提前拦截所有索引会浪费性能；


• 数组长度变化无法拦截：
  当 arr.length = 0 时，数组会清空所有元素（即删除索引 0、1、2），但 Object.defineProperty 只能知道 length 被改成了 0，无法知道具体哪些元素被删除了。

对于响应式系统来说，需要知道 “哪些元素变化了” 才能精准通知依赖这些元素的视图。但 length 拦截只能知道 “长度变了”，无法定位具体变化的元素，导致依赖这些元素的视图可能不会更新（比如某个视图依赖 arr[0]，length=0 后 arr[0] 不存在了，但视图可能还显示旧值）。

2.Vue3 用 Proxy 直接代理整个对象，能拦截所有属性的读写（包括新增、删除、数组操作），是更彻底、更灵活的代理模式实现，这也是 Vue3 响应式比 Vue2 强大的核心原因之一。

总结

最后想强调：设计模式不是必须遵守的 “规则”，而是解决问题的 “工具”。在实际开发中，我们不需要刻意追求 “用满所有模式”，而是根据场景选择合适的工具：

• 需批量创建对象 → 工厂模式


• 需全局唯一实例 → 单例模式


• .....

参考文章：juejin.cn/post/754253…

最近项目做了一个electron项目，记录一下本次客户端热更新中对electron-updater的使用以及遇到的一些问题。

一、配置electron-builder

在electron-builder的配置文件"build"中增加

"publish": [

      {

        "provider": "generic",

        "url": "oss://xxx",

      }

    ]

url: 打包出来的文件存放的地址，配置之后会生成latest.yml文件。electron-updater会去比较这个文件，判断是否需要更新。

二、electron-updater的使用

官方文档： http://www.electron.build/auto-update…

主进程

import { autoUpdater } from "electron-updater";

const { ipcMain } = require("electron");



// 配置提供更新的程序，及build中配置的url

autoUpdater.setFeedURL("oss://xxx")

// 是否自动更新，如果为true，当可以更新时(update-available)自动执行更新下载。

autoUpdater.autoDownload = false



// 1. 在渲染进程里触发获取更新，开始进行更新流程。 (根据具体需求)

ipcMain.on("checkForUpdates", (e, arg) => {

  autoUpdater.checkForUpdates();

});



autoUpdater.on("error", function (error) {

  printUpdaterMessage('error');

  mainWindow.webContents.send("updateError", error);

});



// 2. 开始检查是否有更新

autoUpdater.on("checking-for-update", function () {

  printUpdaterMessage('checking');

});



// 3. 有更新时触发

autoUpdater.on("update-available", function (info) {

  printUpdaterMessage('updateAvailable');

  // 4. 告诉渲染进程有更新，info包含新版本信息

  mainWindow.webContents.send("updateAvailable", info);

});



// 7. 收到确认更新提示，执行下载

ipcMain.on('comfirmUpdate', () => {

  autoUpdater.downloadUpdate()

})



autoUpdater.on("update-not-available", function (info) {

  printUpdaterMessage('updateNotAvailable');

});



// 8. 下载进度，包含进度百分比、下载速度、已下载字节、总字节等

// ps: 调试时，想重复更新，会因为缓存导致该事件不执行，下载直接完成，可找到C:\Users\40551\AppData\Local\xxx-updater\pending下的缓存文件将其删除（这是我本地的路径）

autoUpdater.on("download-progress", function (progressObj) {

  printUpdaterMessage('downloadProgress');

  mainWindow.webContents.send("downloadProgress", progressObj);

});



// 10. 下载完成，告诉渲染进程，是否立即执行更新安装操作

autoUpdater.on("update-downloaded", function () {

    mainWindow.webContents.send("updateDownloaded");

    // 12. 立即更新安装

    ipcMain.on("updateNow", (e, arg) => {

      autoUpdater.quitAndInstall();

    });

  }

);



// 将日志在渲染进程里面打印出来

function printUpdaterMessage(arg) {

  let message = {

    error: "更新出错",

    checking: "正在检查更新",

    updateAvailable: "检测到新版本",

    downloadProgress: "下载中",

    updateNotAvailable: "无新版本",

  };

  mainWindow.webContents.send("printUpdaterMessage", message[arg]??arg);

}

渲染进程:

// 5. 收到主进程可更新的消息，做自己的业务逻辑

ipcRenderer.on('updateAvailable', (event, data) => {

  // do sth.

})



// 6. 点击确认更新

ipcRenderer.send('comfirmUpdate')



// 9. 收到进度信息，做进度条

ipcRenderer.on('downloadProgress', (event, data) => {

  // do sth.

})



// 11. 下载完成，反馈给用户是否立即更新

ipcRenderer.on('updateDownloaded', (event, data) => {

  // do sth.

})



// 12. 告诉主进程，立即更新

ipcRenderer.send("updateNow");

本地环境

如果想在本地环境调试更新，会报错找不到dev-app-update.yml文件
需要自己在根目录(或报错时显示的目录下)手动新建一个dev-app-update.yml里就可以了。文件，将打包生成好的latest.yml复制到dev-app-update.yml里就可以了。

完成截图

深入理解 JavaScript 报错：TypeError: undefined is not a function

在日常的 JavaScript 开发中，几乎每个人都见过这条令人熟悉又头疼的错误信息：

🚀Taimili 艾米莉 ( 一款免费开源的 taimili.com )

艾米莉 是一款优雅便捷的  GitHub Star 管理和加星工具 ，基于 PHP & javascript 构建， 能对github 得 star fork follow watch 管理和提升，最适合github 的深度用户

作者：开源之眼

链接：juejin.cn/post/755906…

来源：稀土掘金

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

TypeError: undefined is not a function

这行报错简短却致命，尤其当代码行数成千上万时，找到问题根源往往需要一点侦探技巧。本文将从原理、常见原因、排查方法和最佳实践四个方面深入讲解这一错误。

一、错误的本质是什么？

首先要知道：

在 JavaScript 中，一切几乎都是对象，包括函数。

当你调用一个变量并在后面加上 () 时，JavaScript 会假设该变量是一个函数对象，并尝试执行它。

let fn;

fn(); // ❌ TypeError: fn is not a function

在上面的例子中，fn 的值是 undefined，但我们却尝试执行它，于是引发了经典错误：

TypeError: undefined is not a function

简单来说：

“你正在试图执行一个并不是函数的东西。”

二、常见的触发场景

让我们来看一些在实际项目中常见的触发情境。

1. 调用未定义的函数

sayHello(); // ❌ TypeError: sayHello is not a function



var sayHello = function() {

  console.log("Hello");

};

原因：var 声明的变量会提升，但赋值不会。执行到函数调用时，sayHello 还是 undefined。

✅ 正确写法：

function sayHello() {

  console.log("Hello");

}

sayHello(); // ✅ Hello

或者：

const sayHello = () => console.log("Hello");

sayHello(); // ✅ Hello

2. 调用了对象上不存在的方法

const user = {};

user.login(); // ❌ TypeError: user.login is not a function

原因：user 对象没有 login 方法，访问结果是 undefined。

✅ 正确做法：

const user = {

  login() {

    console.log("User logged in");

  }

};

user.login(); // ✅ User logged in

3. 第三方库或异步加载未完成

// 某个库尚未加载完成

myLibrary.init(); // ❌ TypeError: myLibrary.init is not a function

原因：脚本加载顺序错误或资源未加载完。

✅ 解决方案：

<script src="mylib.js" onload="initApp()"></script>

或使用现代模块化方式：

import myLibrary from './mylib.js';

myLibrary.init();

4. 被覆盖的函数名

let alert = "Hello";

alert("Hi"); // ❌ TypeError: alert is not a function

原因：内置函数被变量覆盖。

✅ 解决方案：

避免重名：

let message = "Hello";

window.alert("Hi"); // ✅

5. this 指向错误

const obj = {

  run() {

    console.log("Running");

  }

};



const run = obj.run;

run(); // ❌ TypeError: undefined is not a function (在严格模式下)

原因：this 丢失导致方法不再属于原对象。

✅ 解决方案：

const boundRun = obj.run.bind(obj);

boundRun(); // ✅ Running

或直接调用：

obj.run(); // ✅ Running

三、排查思路与调试技巧

当遇到这个错误时，不要慌。按照以下步骤排查：

✅ 1. 查看错误堆栈（stack trace）

浏览器控制台一般会指明出错的文件与行号。

打开 DevTools → Console → 点击错误行号，即可定位具体位置。

✅ 2. 打印变量类型

使用 typeof 或 console.log 检查被调用的变量：

console.log(typeof myFunc); // 应该输出 'function'

✅ 3. 检查函数定义顺序

尤其是在使用 var 或异步加载模块时，注意执行顺序。

✅ 4. 检查导入导出是否匹配

在模块化开发中，这类错误经常来自错误的导入：

// ❌ 错误示例

import { utils } from './utils.js';

utils(); // TypeError: utils is not a function

✅ 应确认模块导出方式：

// utils.js

export default function utils() {}

然后正确导入：

import utils from './utils.js';

utils(); // ✅

四、防止 “undefined is not a function” 的最佳实践

前端老鸟才知道的秘密：void(0)，这东西到底有什么用

那天我盯着同事的代码看了半天，心里默念：这货是不是写错了？

前几天 review 代码，看到一个小年轻写了这么一行：

const foo = void 0;

我当时就乐了，心想：" 这孩子是不是被产品经理逼疯了？直接写undefined不香吗？非得整这出？"

但转念一想，不对啊，这写法我好像在哪儿见过... 仔细一琢磨，卧槽，这不就是前端老司机的暗号吗！

所以，void 0 到底是个啥？

简单来说，void 0就是强行返回 undefined的一种写法。

你可能会问："那我直接写 undefined 不就完事了？干嘛要多此一举？"

问得好！这就要从前端开发的 "血泪史" 说起了。

那些年被 undefined 坑过的日子

在 JavaScript 的远古时期（其实就是 ES5 之前），undefined 这个变量是可以被重写的！

没错，你没听错，就是那个表示 "未定义" 的 undefined，它自己都可能被定义成别的东西...

// 在古老的浏览器里，你可以这么玩（现在别试了）

undefined = "我是谁？我在哪？";

console.log(undefined); // 输出："我是谁？我在哪？"

这就很尴尬了 —— 你用来判断是否未定义的变量，自己都可能被篡改！

这时候，void 0就闪亮登场了。

void 0 的三大绝技

1. 绝对安全的 undefined

void操作符有个特点：不管后面接什么，都返回 undefined。

void 0 // undefined

void "hello" // undefined  

void {} // undefined

void function(){} // undefined

所以void 0就成了获取真正 undefined 的最可靠方式。

2. 阻止链接跳转的老司机

还记得以前写<a href="javascript:void(0)">吗？这就是为了防止点击链接后页面跳转。

虽然现在大家都用event.preventDefault()了，但这可是老一辈前端人的集体记忆啊！

3. 立即执行函数的替代方案

有些老代码里你会看到：

void function() {

  // 立即执行的代码

}();

这其实是为了避免函数声明被误认为是语句开头。

现在还需要 void 0 吗？

说实话，在现代前端开发中，直接用undefined已经足够安全了。ES5 之后的规范规定 undefined 是只读的，不能再被重写。

但为什么还有老司机在用 void 0 呢？

所以，到底用不用？

我的建议是：知道为什么用，比用什么更重要。

如果你是为了代码风格统一，或者团队约定，用 void 0 没问题。

如果只是为了装老司机... 兄弟，真没必要。现在面试官看到 void 0，第一反应可能是："这人是刚从 jQuery 时代穿越过来的吗？"

最后送大家一句话：技术选型就像穿衣服，合适比时髦更重要。  知道每个工具为什么存在，比你盲目跟风要强得多。

在开发Web应用时，深色模式已成为现代UI设计的标配功能。然而，许多项目在实现主题切换时仅简单改变CSS变量，缺乏平滑的过渡动画，导致用户体验突兀。作为开发者，我们常被期望在满足功能需求的同时，打造更精致的用户交互体验。面试中，被问及"如何实现流畅的深色模式切换动画"时，很多人可能只答出使用CSS transition，而忽略了现代浏览器的View Transitions API这一高级解决方案。

读完本文，你将掌握：

前言

在实际项目中，深色模式切换几乎是前端的“标配”。常见做法是通过 classList.toggle("dark") 切换样式，再配合 transition 做淡入淡出。然而，这种效果在用户体验上略显生硬：颜色瞬间大面积切换，即便有渐变也会显得突兀。

随着 View Transitions API 的出现，我们可以给“页面状态切换”添加炫酷的过渡动画。今天就带大家实现一个 以点击位置为圆心、扩散切换主题的深色模式动画，读完本文你将收获：

• 了解 document.startViewTransition 的工作原理


• 学会用 clipPath + animate 控制圆形扩散动画

核心铺垫：我们需要解决什么问题？

在设计方案前，先明确 3 个核心目标：

为此，我们需要用到几个关键技术点：

• View Transitions API：提供 document.startViewTransition，可以对 DOM 状态切换设置过渡动画。


• clip-path：通过 circle(r at x y) 定义动画圆形，从 0px 扩展到最大半径。


• computeMaxRadius：计算从点击点到四角的最大距离，确保圆形覆盖全屏。


• .animate：使用 document.documentElement.animate 精确控制过渡过程。

Math.hypot：计算平面上点到原点的距离

Math.hypot()是ES2017引入的一个JavaScript函数，用于计算所有参数平方和的平方根，即计算n维欧几里得空间中从原点到指定点的距离。

在深色模式切换动画中，我们使用它来计算覆盖整个屏幕的最大圆形半径：

斜边计算：

Math.hypot(maxX, maxY)：使用勾股定理计算从点击点到对角的距离

clip-path

clip-path是CSS属性，允许我们定义元素的可见区域，将其裁剪为基本形状或SVG路径。在深色模式切换动画中，我们用它创建从点击点向外扩散的圆形动画效果。

<basic-shape>一种形状，其大小和位置由 <geometry-box> 的值定义。如果没有指定 <geometry-box>，则将使用 border-box 用为参考框。取值可为以下值中的任意一个：

• inset()
  
  

  定义一个 inset 矩形。



• circle()
  
  

  定义一个圆形（使用一个半径和一个圆心位置）。



• ellipse()
  
  

  定义一个椭圆（使用两个半径和一个圆心位置）。



• polygon()
  
  

  定义一个多边形（使用一个 SVG 填充规则和一组顶点）。



• path()
  
  

  定义一个任意形状（使用一个可选的 SVG 填充规则和一个 SVG 路径定义）。

这里使用circle()来实现效果

该函数接受以下参数：

• 半径：定义圆形的大小（0px到计算的最大半径）


• at关键词：分隔半径和中心点位置


• 中心点位置：使用x y坐标指定圆形中心

startViewTransition：浏览器视图转换API

基本概念

document.startViewTransition()是View Transitions API的核心方法，它告诉浏览器DOM即将发生变化，并允许我们为这些变化创建平滑的过渡动画。

生命周期与关键事件

浏览器兼容性处理

在实际应用中，我们需要检查浏览器是否支持此API：

const isAppearanceTransition =

    document.startViewTransition &&

    !window.matchMedia("(prefers-reduced-motion: reduce)").matches;

if (!isAppearanceTransition) {

    // 不支持View Transitions API时的降级处理

    isDark.value = !isDark.value;

    setupThemeClass(isDark.value);

    return;

}

这种处理确保在不支持新特性的浏览器中，功能仍然可用，只是没有动画效果。

核心实现：从逻辑到代码

graph TD



    A[用户点击切换按钮] --> B{浏览器是否支持<br/>View Transitions API?}

    B -- 否 --> C[直接切换主题变量<br/>无动画效果]

    B -- 是 --> D[获取点击坐标X,Y]

    D --> E[计算覆盖全屏的最大半径]

    E --> F[启动视图转换]

    F --> G[执行回调函数<br/>更新isDark状态]

    G --> H[设置HTML的dark class<br/>更新CSS变量]

    H --> I[等待DOM更新完成<br/>nextTick]

    I --> J[视图转换准备就绪]

    J --> K[应用clipPath动画<br/>从点击点向外扩散]

    K --> L[动画完成<br/>主题切换完成]

    

    style B fill:#f9f,stroke:#333,stroke-width:2px

    style K fill:#9cf,stroke:#333,stroke-width:2px

步骤 1：封装主题切换

    function setupThemeClass(isDark) {

      document.documentElement.classList.toggle("dark", isDark);

      localStorage.setItem("theme", isDark ? "dark" : "light");

    }

作用：控制 html.dark 类名，完成主题切换。

步骤 2：计算扩散最大半径

    function computeMaxRadius(x, y) {

      const maxX = Math.max(x, window.innerWidth - x);

      const maxY = Math.max(y, window.innerHeight - y);

      return Math.hypot(maxX, maxY); // √(maxX² + maxY²)

    }

    

作用：确保无论点击哪里，扩散圆都能覆盖屏幕。

步骤 3：触发 View Transition

    function onToggleClick(event) {

      const isSupported =

        document.startViewTransition &&

        !window.matchMedia("(prefers-reduced-motion: reduce)").matches;



      if (!isSupported) {

        // 回退方案：直接切换

        isDark.value = !isDark.value;

        setupThemeClass(isDark.value);

        return;

      }



      const x = event.clientX;

      const y = event.clientY;

      const endRadius = computeMaxRadius(x, y);



      // 开启视图过渡

      const transition = document.startViewTransition(async () => {

        isDark.value = !isDark.value;

        setupThemeClass(isDark.value);

        await nextTick(); // 等 Vue DOM 更新

      });



      transition.ready.then(() => {

        const clipPath = [

          `circle(0px at ${x}px ${y}px)`,

          `circle(${endRadius}px at ${x}px ${y}px)`,

        ];



        document.documentElement.animate(

          {

            clipPath: isDark.value ? [...clipPath].reverse() : clipPath,

          },

          {

            duration: 450,

            easing: "ease-in",

            pseudoElement: isDark.value

              ? "::view-transition-old(root)"

              : "::view-transition-new(root)",

          }

        );

      });

    }

要点：

*startViewTransition 接收一个回调函数，里面执行 DOM 更新（切换主题）。

*transition.ready.then(...) 可以在 DOM 更新后定义动画效果。

*clipPath 数组定义了从 小圆 → 大圆 的扩散过程。

*pseudoElement 控制是对 新视图 还是 旧视图 应用动画。

步骤 4：覆盖默认过渡样式

    ::view-transition-new(root),

    ::view-transition-old(root) {

      animation: none;

      mix-blend-mode: normal;

    }



    ::view-transition-old(root) {

      z-index: 1;

    }



    ::view-transition-new(root) {

      z-index: 2147483646;

    }



    html.dark::view-transition-old(root) {

      z-index: 2147483646;

    }



    html.dark::view-transition-new(root) {

      z-index: 1;

    }

作用：取消默认动画，手动用 clipPath 控制。通过 z-index 确保层级正确，否则可能看到“旧页面覆盖新页面”的异常。

效果演示

运行后：

• 点击切换按钮时，以点击点为圆心，圆形扩散覆盖全屏，主题在扩散动画过程中完成切换。


• 若浏览器不支持 View Transitions API（如 Safari），则自动降级为普通切换，不影响使用。

完整demo

延伸与避坑

总结

本文我们用 Vue3 + Element Plus + View Transitions API 实现了一个点击扩散式的深色模式切换动画，核心要点：

• startViewTransition：声明 DOM 状态切换的动画上下文。


• clipPath + animate：控制过渡动画形状与过程。


• computeMaxRadius：计算圆形覆盖全屏的半径。


• 优雅降级：确保不支持 API 的浏览器仍能正常切换。

大家好，我是农村程序员，独立开发者，行业观察员，前端之虎陈随易。我会在这里分享关于 独立开发、编程技术、思考感悟 等内容，欢迎关注。

技术群与交朋友请在个人网站联系我，网站 1️⃣：chensuiyi.me，网站 2️⃣：me.yicode.tech。

如果你觉得本文有用，一键三连 (点赞、评论、转发)，就是对我最大的支持~

最近抽空在做我的 VSCode 插件 fnMap (函数地图) 的重构工作。

项目结构主要分为 3 部分：

那么重构呢，我想把 UI 换一下，目前用的是 arco-design-vue，字节出品的一个 UI 框架。

本来蛮喜欢的，但根据最近的更新来看，官方主要做 React 版本去了，Vue 版本 4 个多月没动静了。

而且，VSCode 有主题功能，框架如果要适配主题，那得进行不少魔改微调。

于是，我上下求索，找到这样一个为 VSCode 量身打造的 UI 库 vscode-elements。

这效果，与 VSCode 简直绝配。

开源地址在这：https://github.com/vscode-elements/elements

如果你也在开发 VSCode 扩展，不妨了解一下这个。

在我这目前看到的唯一的缺点呢，就是还没有 Vue 版本。

目前的主要版本是基于 Lit 这个框架开发的，也就是前端标准的 Web Components 技术。

我跟踪这个框架几个星期了，今天 vscode-elements 刚发布 v2.0 版本，是时候为我的 fnMap 提供一份力量了。

也欢迎大家来体验我的 fnMap 插件，8月份 (本月) 将会发布 v9.0 版本，在进化的路上，一路前进。

前言

大家好，我是奈德丽。

过去一年，我主要参与国际机票业务的开发工作，因此每天都要和多语言（i18n）打交道。熟悉我的朋友都知道，我这个人比较“惜力”(并不是，实际上只是忍不下去了)，对于重复笨拙的工作非常抵触，于是，我开始思考如何优化团队的多语言管理模式。

痛点背景

先说说我们在机票项目中遇到的困境。

目前机票项目分为 H5 和 PC 两端，团队在维护多语言时主要通过在线 Excel进行管理：

• 一个 Excel 文件，H5 和 PC 各自占一个 sheet 页；


• 每次更新语言，需要先导出 Excel，然后手动跑脚本生成语言文件，再拷贝到项目中。

听起来还算凑合，但随着项目规模的扩大，问题逐渐显现：

下面是一个实际的 Excel 片段，可以感受一下当时的混乱程度：

用原node脚本生成的语言文件如图

在这样的场景下，每次迭代多语言文件更新都像噩梦一样。

尤其是我们很多翻译是通过AI 机翻生成，后续频繁修改的成本极高。

然而，机票项目的代码量太大、历史包袱太重，短期内几乎不可能彻底改造。

新项目，新机会

机票项目虽然不能动，但在我们启动酒店业务新项目时，我决定不能再重蹈覆辙。

因此，在酒店项目中，我从零搭建了这套更高效的 i18n 管理方案。

目标很简单：

于是，我在项目中新增了一个 scripts 目录，并编写了一个 excel-to-json.js 脚本。

在 package.json 中添加如下命令：

{

  "scripts": {

    "i18n:excel-to-json": "node scripts/excel-to-json.js"

  }

}

以后，只需要运行下面一行命令，就能完成所有工作：

pnpm i18n:excel-to-json

再也不用手动寻找脚本路径，也不用手动复制粘贴，效率直接起飞 🚀。

脚本实现

核心逻辑就是：

从 Excel 读取内容 → 转换为 JSON → 输出到项目 i18n 目录。

完整代码如下：

import fs from 'node:fs'

import os from 'node:os'

import path from 'node:path'

import XLSX from 'xlsx'



/**

 * 语言映射表：Excel 表头 -> 标准语言码

 */

const languageMap = {

  'English': 'en',

  '简中': 'zh-CN',

  'Chinese (Traditional)': 'zh-TW',

  'Korean': 'ko',

  'Spanish': 'es',

  'German Edited': 'de',

  'Italian': 'it',

  'Norwegian': 'no',

  'French': 'fr',

  'Arabic': 'ar',

  'Thailandese': 'th',

  'Malay': 'ms',

}



// 读取 Excel 文件

function readExcel(filePath) {

  if (!fs.existsSync(filePath)) {

    throw new Error(`❌ Excel 文件未找到: ${filePath}`)

  }

  const workbook = XLSX.readFile(filePath)

  const sheet = workbook.Sheets[workbook.SheetNames[0]]

  return XLSX.utils.sheet_to_json(sheet)

}



/**

 * 清空输出目录

 */

function clearOutputDir(dirPath) {

  if (fs.existsSync(dirPath)) {

    fs.readdirSync(dirPath).forEach(file => fs.unlinkSync(path.join(dirPath, file)))

    console.log(`🧹 已清空目录: ${dirPath}`)

  } else {

    fs.mkdirSync(dirPath, { recursive: true })

    console.log(`📂 创建目录: ${dirPath}`)

  }

}



/**

 * 生成 JSON 文件

 */

function generateLocales(rows, outputDir) {

  const locales = {}



  rows.forEach(row => {

    const key = row.Key

    if (!key) return



    // 遍历语言列

    Object.entries(languageMap).forEach(([columnName, langCode]) => {

      if (!locales[langCode]) locales[langCode] = {}



      const value = row[columnName] || ''

      const keys = key.split('.')

      let current = locales[langCode]



      keys.forEach((k, idx) => {

        if (idx === keys.length - 1) {

          current[k] = value

        } else {

          current[k] = current[k] || {}

          current = current[k]

        }

      })

    })

  })



  // 输出文件

  Object.entries(locales).forEach(([lang, data]) => {

    const filePath = path.join(outputDir, `${lang}.json`)

    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8')

    console.log(`✅ 生成文件: ${filePath}`)

  })

}



/**

 * 检测缺失翻译

 */

function detectMissingTranslations(rows) {

  const missing = []

  rows.forEach(row => {

    const key = row.Key

    if (!key) return



    Object.entries(languageMap).forEach(([columnName, langCode]) => {

      const value = row[columnName]

      if (!value?.trim()) {

        missing.push({ key, lang: langCode })

      }

    })

  })

  return missing

}



function logMissingTranslations(missingList) {

  if (missingList.length === 0) {

    console.log('\n🎉 所有 key 的翻译完整！')

    return

  }



  console.warn('\n⚠️ 以下 key 缺少翻译:')

  missingList.forEach(item => {

    console.warn(`  - key: "${item.key}" 缺少语言: ${item.lang}`)

  })

}



function main() {

  const desktopPath = path.join(os.homedir(), 'Desktop', 'hotel多语言.xlsx')

  const outputDir = path.resolve('src/i18n/locales')



  const rows = readExcel(desktopPath)

  clearOutputDir(outputDir)

  generateLocales(rows, outputDir)

  logMissingTranslations(detectMissingTranslations(rows))

}



main()

成果展示

这是在线语言原文档

这是生成后的多语言文件和内容

现在的工作流大幅简化：

这套机制目前在酒店项目中运行良好，团队反馈也很积极。

总结

这次改造让我最大的感触是：

旧项目难以推翻重来，但新项目一定要趁早做好架构设计。

通过这次优化，我们不仅解决了多语言维护的痛点，还提升了团队整体开发效率。

而这套方案在未来如果机票项目有机会重构，也可以直接平滑迁移过去。

我们是袋鼠云数栈 UED 团队，致力于打造优秀的一站式数据中台产品。我们始终保持工匠精神，探索前端道路，为社区积累并传播经验价值。

本文作者：佳岚

什么是行内代码生成？

通过一组快捷键（一般为cmd + k)在选中代码块或者光标处唤起 Prompt 命令弹窗，并且快速的应用生成的代码。

提示词系统

首先是完成一个简易的提示词系统，不同功能对应的提示词与提供的上下文不同， 定义不同的功能场景：

export enum PromptScenario {

    SYNTAX_COMPLETION = 'syntax_completion',    // 语法补全

    CODE_GENERATION = 'code_generation',        // 代码生成

    CODE_EXPLANATION = 'code_explanation',      // 代码解释

    CODE_OPTIMIZATION = 'code_optimization',    // 代码优化

    ERROR_FIXING = 'error_fixing',              // 错误修复

}

每种场景都有对应的系统 prompt 和用户 prompt 模板：

export const PROMPT_TEMPLATES: Record<PromptScenario, PromptTemplate> = {

	[PromptScenario.SYNTAX_COMPLETION]: {

		id: 'syntax_completion',

		scenario: PromptScenario.SYNTAX_COMPLETION,

		title: 'SQL语法补全',

		description: '基于上下文进行智能的SQL语法补全',

		systemPromptTemplate: ``,

		userPromptTemplate: `<|fim_prefix|>{prefix}<|fim_suffix|>{suffix}<|fim_middle|>`,

		temperature: 0.2,

		maxTokens: 256

	},



	[PromptScenario.CODE_GENERATION]: {

		id: 'code_generation',

		scenario: PromptScenario.CODE_GENERATION,

		title: 'SQL代码生成',

		description: '根据需求描述生成相应的SQL代码',

		systemPromptTemplate: `你是{languageName}数据库专家。根据用户需求生成高质量的{languageName}代码。



语言特性：{languageFeatures}



生成要求：

1. 严格遵循 {languageName} 语法规范

2. {syntaxNotes}

3. 生成完整、可执行的SQL语句

4. {performanceTips}

5. 考虑代码的可读性和维护性

6. 回答不要包含任何对话解释内容

7. 保持缩进与参考代码一致`,

		userPromptTemplate: `用户需求：{userPrompt}



参考代码：

\`\`\`sql

{selectedCode}

\`\`\`



请生成符合需求的{languageName}代码：`,

		temperature: 0.3,

		maxTokens: 512

	},

  // ...其他略

}

收集以下上下文信息并动态替换掉提示词模板的变量以生成最终传递给大模型的提示词：

/**

 * 上下文信息

 */

export interface PromptContext {

	/** 当前语言ID */

	languageId: string;

	/** 光标前的代码 */

	prefix?: string;

	/** 光标后的代码 */

	suffix?: string;

	/** 当前文件完整代码 */

	fullCode?: string;

	/** 当前打开的文件名 */

	activeFile?: string;

	/** 用户输入的提示 */

	userPrompt?: string;

	/** 选中的代码 */

	selectedCode?: string;

	/** 错误信息 */

	errorMessage?: string;

	/** 额外的上下文信息 */

	metadata?: Record<string, any>;

}

ViewZone

观察该 Widget 可以发现它是实际占据了一段代码行高度，撑开了上下代码，但没有行号，这是通过 ViewZone实现的。

monaco-editor 中的 viewZone 是一种可以在编辑器的文本行之间自定义插入可视区域的机制，不属于实际代码内容，但可以渲染任意自定义 DOM 内容或空白空间。

核心只有一个changeViewZones，必须使用其回调中的accessor来实现新增删除ViewZone操作

新增示例：

editor.changeViewZones(function (accessor) {

  accessor.addZone({

    afterLineNumber: 10,         // 插入在哪一行后（基于原始代码行号）

    heightInLines: 3,            // zone 的高度（按行数）

    heightInPx: 10,              // zone 的高度（按像素）, 与heightInLines二选一

    domNode: document.createElement('div'), // 需要插入的 DOM 节点

  });

});

删除示例：

editor.changeViewZones(accessor => {

  if (zoneIdRef.current !== null) {

    accessor.removeZone(zoneIdRef.current);

  }

});

但需要注意的是，ViewZones 的视图层级是在可编辑区之下的，我们通过 domNode 创建弹窗后，无法响应点击，所以需要手动为 domNode 添加 z-Index。

但我们咱不用 domNode 直接渲染我们的弹窗组件，而是通过 ViewZone 结合 OverlayWidget 的方式去添加我们要的元素。

OverlayWidget 的层级比可编辑区域的更高，无需考虑层级覆盖问题。

其次，我们需要将 Overlay 的元素通过绝对定位移动到 ViewZone 上，这需要利用 ViewZone 的 onDomNodeTop来实时同步两者的定位。

monaco-editor 中的代码行与 ViewZone 使用了虚拟列表，它们的 top 在滚动时会随着可见性不断变化，所以需要随时同步 ，onDomNodeTop会在每次 ViewZone 的top属性变化时执行。

此外，OverlayWidget 是以整个编辑器最左边为基准的，计算时需要考虑上

editorInstance.changeViewZones((changeAccessor) => {

		viewZoneId = changeAccessor.addZone({

			// ...略

			onDomNodeTop: (top) => {

        // 这里的domNode为overlayWidget所绑定创建的节点

				if (domNode) {

					// 获取编辑器左侧偏移量（行号、代码折叠等组件的宽度）

					const layoutInfo = editorInstance.getLayoutInfo();

					const leftOffset = layoutInfo.contentLeft;



					domNode.style.top = `${top}px`;

					domNode.style.left = `${leftOffset}px`;

					domNode.style.width = `${layoutInfo.contentWidth}px`;

				}

			}

		});

	});

创建 OverlayWidget ：

let overlayWidget: editor.IOverlayWidget | null = null;

let domNode: HTMLDivElement | null = null;

let reactRoot: any = null;



domNode = document.createElement('div');

domNode.className = 'code-generation-overlay-widget';

domNode.style.position = 'absolute';



reactRoot = createRoot(domNode);

reactRoot.render(<CodeGenerationWidget />)



overlayWidget = {

  getId: () => `code-generation-overlay-${position.lineNumber}-${Date.now()}`,

  getDomNode: () => domNode!,

  getPosition: () => null

};



editorInstance.addOverlayWidget(overlayWidget);



// 唤起时，将 widget 滚动到视口

editorInstance.revealLineInCenter(targetLineNumber);

CodeGenerationWidget 动态高度

接下来我们实现 Prompt 输入框根据内容动态调整高度。

输入框部分我们可以直接用 rc-textarea 组件来实现回车自动新增高度。

监听整个容器高度变化触发 onHeightChange 以通知 ViewZone ：

	useEffect(() => {

		if (!containerRef.current) return;

		const observer = new ResizeObserver(() => {

			onHeightChange?.();

		});

		observer.observe(containerRef.current);



		return () => {

			observer.disconnect();

		};

	}, [containerRef]);

注意 ViewZone 只能增或删，不能手动改变其高度，所以需要重新创建一个：

reactRoot.render(

		<CodeGenerationWidget

			editorInstance={editorInstance}

			initialPosition={position}

			initialSelection={selection}

			widgetWidth={widgetWidth}

			onClose={() => dispose()}

			onHeightChange={() => {

				// 高度变化时需要更新ViewZone

				if (viewZoneId && domNode) {

					const actualHeight = domNode.clientHeight;

					editorInstance.changeViewZones((changeAccessor) => {

						changeAccessor.removeZone(viewZoneId!);

						viewZoneId = changeAccessor.addZone({

							afterLineNumber: Math.max(0, targetLineNumber - 1),

							heightInPx: actualHeight + 8,

							domNode: document.createElement('div'),

							onDomNodeTop: (top) => {

								if (domNode) {

									// 获取编辑器左侧偏移量（行号、代码折叠等组件的宽度）

									const layoutInfo = editorInstance.getLayoutInfo();

									const leftOffset = layoutInfo.contentLeft;



									domNode.style.top = `${top}px`;

									domNode.style.left = `${leftOffset}px`;

								}

							}

						});

					});

				}

			}}

		/>

	);

这里如果使用 ViewZone 的 domNode 来渲染组件的方法的话，由于每次高度变化创建新的 ViewZone , 其 domNode 会被重新挂载，那么就会导致每次高度变化时输入框都会失焦。

生成代码 diff 展示

对于选择了代码行后生成，会对原始代码进行编辑修改，我们需要配合行 diff 进行编辑应用结果的展示。对于删除的行使用 ViewZone 进行插入，对于新增的行使用 Decoration 进行高亮标记。

首先需要实现 diff 计算出这些行的信息。 我们需要以最少的操作实现从原始代码到目标代码的转化。

其核心问题是 最长公共子序列（LCS）。最长公共子序列（LCS ）是指在两个或多个序列中，找出一个最长的子序列，使得这个子序列在这些序列中都出现过。与子串不同，子序列不需要在原序列中占用连续的位置。

如 ABCDEF 至 ACEFG , 那么它们的最长公共子序列是 ACEF 。

其算法可以参考 cloud.tencent.com/developer/a… 学习，这里我们直接就使用现成的库jsdiff 去实现了。

完整实现：

export enum DiffLineType {

	UNCHANGED = 'unchanged',

	ADDED = 'added',

	DELETED = 'deleted'

}



export interface DiffLine {

	type: DiffLineType;

	originalLineNumber?: number; // 原始行号

	newLineNumber?: number; // 新行号

	content: string; // 行内容

}



/**

 * 计算两个字符串数组的diff

 */

export const calculateDiff = (originalLines: string[], newLines: string[]): DiffLine[] => {

	const result: DiffLine[] = [];



	// 将字符串数组转换为字符串

	const originalText = originalLines.join('\n');

	const newText = newLines.join('\n');



	// 使用 diff 库计算差异

	const diffs = diffLines(originalText, newText);



	let originalLineNumber = 1;

	let newLineNumber = 1;



	diffs.forEach(diff => {

		if (diff.added) {

			// 添加的行

			const lines = diff.value.split('\n').filter((line, index, arr) =>

				// 过滤掉最后一个空行（如果存在）

				!(index === arr.length - 1 && line === '')

			);



			lines.forEach(line => {

				result.push({

					type: DiffLineType.ADDED,

					newLineNumber: newLineNumber++,

					content: line

				});

			});

		} else if (diff.removed) {

			// 删除的行

			const lines = diff.value.split('\n').filter((line, index, arr) =>

				// 过滤掉最后一个空行（如果存在）

				!(index === arr.length - 1 && line === '')

			);



			lines.forEach(line => {

				result.push({

					type: DiffLineType.DELETED,

					originalLineNumber: originalLineNumber++,

					content: line

				});

			});

		} else {

			// 未变化的行

			const lines = diff.value.split('\n').filter((line, index, arr) =>

				// 过滤掉最后一个空行（如果存在）

				!(index === arr.length - 1 && line === '')

			);



			lines.forEach(line => {

				result.push({

					type: DiffLineType.UNCHANGED,

					originalLineNumber: originalLineNumber++,

					newLineNumber: newLineNumber++,

					content: line

				});

			});

		}

	});



	return result;

};

那么接下来我们只要根据计算出的 diffLines 对删除行和新增行进行视觉展示即可。

我们封装一个 applyDiffDisplay 方法用来展示 diffLines 。

有以下步骤：

const applyDiffDisplay =

  (diffLines: DiffLine[]) => {

    // 先清除之前的展示

    clearDecorations();

    clearDiffOverlays();



    if (!initialSelection) return;



    const model = editorInstance.getModel();

    if (!model) return;



    // 获取语言ID用于语法高亮

    const languageId = getLanguageId();



    // 首先替换原始内容为新内容（包含unchanged的行）

    const newLines = diffLines

      .filter((line) => line.type !== DiffLineType.DELETED)

      .map((line) => line.content);

    const newContent = newLines.join('\n');



    // 执行替换

    editorInstance.executeEdits('ai-code-generation-diff', [

      {

        range: initialSelection,

        text: newContent,

        forceMoveMarkers: true

      }

    ]);



    // 计算新内容的范围

    const resultRange = new Range(

      initialSelection.startLineNumber,

      initialSelection.startColumn,

      initialSelection.startLineNumber + newLines.length - 1,

      newLines.length === 1

      ? initialSelection.startColumn + newContent.length

      : newLines[newLines.length - 1].length + 1

    );



    let currentLineNumber = initialSelection.startLineNumber;

    let deletedLinesGr0up: DiffLine[] = [];



    for (const diffLine of diffLines) {

      if (diffLine.type === DiffLineType.DELETED) {

        // 收集连续的删除行

        deletedLinesGr0up.push(diffLine);

      } else {

        if (deletedLinesGr0up.length > 0) {

          addDeletedLinesViewZone(deletedLinesGr0up, currentLineNumber - 1, languageId);

          deletedLinesGr0up = [];

        }



        if (diffLine.type === DiffLineType.ADDED) {

          // 添加绿色背景色

          const addedDecorations = editorInstance.deltaDecorations(

            [],

            [

              {

                range: new Range(

                  currentLineNumber,

                  1,

                  currentLineNumber,

                  model.getLineContent(currentLineNumber).length + 1

                ),

                options: {

                  className: 'added-line-decoration',

                  isWholeLine: true

                }

              }

            ]

          );

          decorationsRef.current.push(...addedDecorations);

        }



        currentLineNumber++;

      }

    }



    // 处理最后的删除行组

    if (deletedLinesGr0up.length > 0) {

      addDeletedLinesViewZone(deletedLinesGr0up, currentLineNumber - 1, languageId);

    }



    return resultRange;

  }

删除行的视觉呈现

删除行使用 ViewZone 插入到 originalLineNumber - 1 的位置， 对于删除行直接使用 ViewZone 自身的 domNode 进行展示了，因为不太需要考虑层级问题。

export const createDeletedLinesOverlayWidget = (

	editorInstance: editor.IStandaloneCodeEditor,

	deletedLines: DiffLine[],

	afterLineNumber: number,

	languageId: string,

	onDispose?: () => void

): { dispose: () => void } => {

	let domNode: HTMLDivElement | null = null;

	let reactRoot: any = null;

	let viewZoneId: string | null = null;



	domNode = document.createElement('div');

	domNode.className = 'deleted-lines-view-zone-container';



	reactRoot = createRoot(domNode);



	reactRoot.render(<DeletedLineViewZone lines={deletedLines} languageId={languageId} />);



	const heightInLines = Math.max(1, deletedLines.length);

	editorInstance.changeViewZones((changeAccessor) => {

		viewZoneId = changeAccessor.addZone({

			afterLineNumber,

			heightInLines,

			domNode: domNode!

		});

	});



	const dispose = () => {

		// 清除

	};



	return { dispose };

};

添加命令快捷键

使用 cmd + k 唤起弹窗

editorInstance.onKeyDown((e) => {

  if ((e.ctrlKey || e.metaKey) && e.keyCode === KeyCode.KeyK) {

    e.preventDefault();

    e.stopPropagation();



    const selection = editorInstance.getSelection();

    const position = selection ? selection.getPosition() : editorInstance.getPosition();



    if (!position) return;



    // 如果有选择范围，则将其传递给widget供后续替换使用

    const selectionRange = selection && !selection.isEmpty() ? selection : null;



    // 如果已经有viewZone，先清理

    if (activeCodeGenerationViewZone) {

      activeCodeGenerationViewZone.dispose();

      activeCodeGenerationViewZone = null;

    }



    // 创建新的ViewZone

    activeCodeGenerationViewZone = createCodeGenerationOverlayWidget(

      editorInstance,

      position,

      selectionRange,

      undefined, // widgetWidth

      () => {

        // 当viewZone被dispose时清理全局状态

        activeCodeGenerationViewZone = null;

      }

    );

  }

最终实现效果：

未来优化方向：

其他计划

• [已完成] 行内补全


• [已完成] 代码生成


• 行内补全的缓存设计


• 完善的上下文系统


• 实现 Agent 模式

在线预览

jackwang032.github.io/monaco-sql-…

仓库代码：github1s.com/JackWang032…

最后

欢迎关注【袋鼠云数栈UED团队】~

袋鼠云数栈 UED 团队持续为广大开发者分享技术成果，相继参与开源了欢迎 star

• 大数据分布式任务调度系统——Taier


• 轻量级的 Web IDE UI 框架——Molecule


• 针对大数据领域的 SQL Parser 项目——dt-sql-parser


• 袋鼠云数栈前端团队代码评审工程实践文档——code-review-practices


• 一个速度更快、配置更灵活、使用更简单的模块打包器——ko


• 一个针对 antd 的组件测试工具库——ant-design-testing

我们来想象一个场景：你正在一个电商网站上，精心挑选了半小时的商品，填好了复杂的收货地址，满心欢喜地点击提交订单 Button。

突然，页面Duang🎈地一下，跳转到了登录页，并提示你：“登录状态已过期，请重新登录”。

那一刻，你的内心是什么感受？我想大概率是崩溃的，并且想把这个网站拉进黑名单。

这就是一个典型的、因为Token过期处理不当，而导致的灾难级用户体验。作为一个负责任的开发者，这是我们绝对不能接受的。

今天就聊聊，我们团队是如何通过请求拦截和队列控制，来实现无感刷新Token的。让用户即使在Token过期的情况下，也能无缝地继续操作，就好像什么都没发生过一样。

先讲基础知识

为什么需要两个Token？

要实现无感刷新，我们首先需要后端同学的配合，采用双Token的认证机制。

流程是这样的：用户登录成功后，后端会同时返回accessToken和refreshToken。前端将accessToken存在内存（或LocalStorage）里，然后在后续的请求中，通过refreshToken来刷新。

解决思路，利用axios的请求拦截器

我们整个方案的核心，是利用axios（或其他HTTP请求库）提供的请求拦截器（Interceptor） 。它就像一个哨兵，可以在请求发送前和响应返回后，对请求进行拦截和改造。

我们的目标是：

这个过程对用户来说，是完全透明的。他们最多只会感觉到某一次API请求，比平时慢了一点点。

具体怎么实现？

下面是我们团队在项目中，实际使用的axios拦截器伪代码。

import axios from 'axios';



// 创建一个新的axios实例

const api = axios.create({

  baseURL: '/api',

  timeout: 5000,

});



// ------------------- 请求拦截器 -------------------

api.interceptors.request.use(config => {

  const accessToken = localStorage.getItem('accessToken');

  if (accessToken) {

    config.headers.Authorization = `Bearer ${accessToken}`;

  }

  return config;

}, error => {

  return Promise.reject(error);

});





// ------------------- 响应拦截器 -------------------



// 用于标记是否正在刷新token

let isRefreshing = false;

// 用于存储因为token过期而被挂起的请求

let requestsQueue = [];



api.interceptors.response.use(

  response => {

    return response;

  }, 

  async error => {

    const { config, response } = error;

    

    // 如果返回的HTTP状态码是401，说明access_token过期了

    if (response && response.status === 401) {

      

      // 如果当前没有在刷新token，那么我们就去刷新token

      if (!isRefreshing) {

        isRefreshing = true;



        try {

          // 调用刷新token的接口

          const { data } = await axios.post('/refresh-token', {

            refreshToken: localStorage.getItem('refreshToken') 

          });

          

          const newAccessToken = data.accessToken;

          localStorage.setItem('accessToken', newAccessToken);



          // token刷新成功后，重新执行所有被挂起的请求

          requestsQueue.forEach(cb => cb(newAccessToken));

          // 清空队列

          requestsQueue = [];



          // 把本次失败的请求也重新执行一次

          config.headers.Authorization = `Bearer ${newAccessToken}`;

          return api(config);



        } catch (refreshError) {

          // 如果刷新token也失败了，说明refreshToken也过期了

          // 此时只能清空本地存储，跳转到登录页

          console.error('Refresh token failed:', refreshError);

          localStorage.removeItem('accessToken');

          localStorage.removeItem('refreshToken');

          // window.location.href = '/login';

          return Promise.reject(refreshError);

        } finally {

          isRefreshing = false;

        }

      } else {

        // 如果当前正在刷新token，就把这次失败的请求，存储到队列里

        // 返回一个pending的Promise，等token刷新后再去执行

        return new Promise((resolve) => {

          requestsQueue.push((newAccessToken) => {

            config.headers.Authorization = `Bearer ${newAccessToken}`;

            resolve(api(config));

          });

        });

      }

    }

    

    return Promise.reject(error);

  }

);



export default api;

这段代码的关键点，也是面试时最能体现你思考深度的地方：

无感刷新Token这个功能，用户成功的时候，是感知不到它的存在的。

但恰恰是这种无感的细节，区分出了一个能用的应用和一个好用的应用。

因为一个资深的开发者，他不仅关心功能的实现，更应该关心用户体验和整个系统的健壮性。

希望这一套解决思路，能对你有所帮助🤞😁。

一、前言

在上一篇 《AI 应用开发入门：前端也可以学习 AI》中，我给大家分享了前端学习 AI 应用开发的入门相关知识。我相信很多同学，看完应该都有了一定的收获。未来我会把关于前端学习 AI 的文章都放在这个 《前端学习 AI 之路》 专栏进行更新~

本篇会更偏向实际的应用，我将会运用之前分享的技术和概念，给大家分享如何通过 nodejs + LLM 搭建一个简易的 AI Review 系统的。

在本篇你将收获到：

1. 设计 AI 应用的思路
2. 设计提示词的思路
3. 如何用 NodeJS 结合 LLM 分析代码

二、背景

我相信大家在团队中，都会有 Code Review 这个流程。但是有时候随着人手不够、项目周期紧张，就会出现 review 流程被忽视、或者 review 质量不高的问题。于是，我就在想，是否可以把这种费时、费精力且需要专注的事情，交给一个专门的“AI 员工”去完成呢？答案是可以的。

三、整体效果

目前在我们团队，已经全面的在使用 AI 进行 Review 了，涵盖了前端、后端大大小小 20 + 的项目。得益于在集团内可以使用像（“GPT-4.1、 Calude”）这样更大上下文、更强推理能力的模型，所以整体效果是非常不错的。有时候一些很细微的安全隐患、性能、业务逻辑等问题，AI 都能比人更容易发现。

下面是我用演示的项目呈现的效果，也就是我们即将动手搭建的这个项目。

3.1 评论模式

通过 AI 分析提交的代码，然后会在有问题的代码下，评论出问题类型以及问题的具体原因。

3.2 报告模式

还一种是报告的展示形式。它会在提交的 MR 下输出一个评审报告，列出所有问题的标题、所在位置、以及具体原因。但是，这两种模式实现的本质都一样，只不过是展示结果的方式有不同，这个看你个人喜欢。

四、思路分析

那这个 AI Code Review 应用要怎么实现呢？下面给大家分享一下具体的思路。

4.1 人为流程

首先要做的，就是分析你现有团队人工 review 代码的规范，然后总结出一个具体流程。为什么要这样做？因为让 AI 帮你做事的本质，就是让它模仿你做事。如果连你自己都不清楚具体的执行流程，就更别期待 AI 能把这个事情做好了。

下面是我举例的一个 review 流程，看完后你可以思考一下，自己平时是怎么 review 代码的，有没有一个固定的流程或者方案。如果有，则按照下面的这个“行为 + 目的”的格式记录下来。

1. 行为：收到的 MR 的提示了；目的：知道有需要 review 的 MR 提交

2. 行为：查看 commit message；目的：确认本次提交的主题是什么。

3. 行为：查看改动哪些文件；目的：确认改动范围，主要判断改了哪些业务模块、是否改了公共、或者高风险文件等

4. 行为：查看文件路径；目的：确认该文件关联的业务、所属的模块等信息，当做后续 diff 评审的前置判断信息。

5. 行为：查看 diff 内容；目的：判断改动代码的逻辑、安全、性能是否存在问题。结合相关的业务和需求信息，判断是否有实现不合理的地方。
6. 行为：在有问题的相关代码下，发出评论；目的：在有问题的代码下面，给出修改建议，让开发的同事能够注意和修改一下当前的问题。

4.2 程序流程

上面列举的是一个完整的人为评审代码的流程。但是，如果想让 AI 完全模仿，其实是存在一定的复杂性的。比如，人在评审某处 diff 时，会思考关联的业务、模块等前置信息，然后再做出评论。而不单单只是评审代码表面的编码问题。如果想要 AI 也这样做，还需要引入 RAG 等相关的技术，目的则是为了补充给更多的上下文信息。

为了不增加大家的实现和理解难度，本篇我们实现的是一个简化版本的 AI Code Review。下面是我梳理的 review 流程和与之对应的 AI 应用流程。

4.2 核心问题

这次搭建的 AI Code Review 应用，本质上是一个 NodeJS 服务。这个服务通过感知 MR 事件，获取 diff 交给 LLM 分析，得到结论以后，会输出评论到 GitLab。整体流程图如下：

所以，我们要面对这些核心问题是

1. node 服务如何感知 GitLab 的 MR 提交
2. 如何获取 MR 中每个文件改动的 diff
3. 如何让编写提示词，让大模型评审和分析并输出结构化的数据
4. 如何解析数据以及异常的处理
5. 如何发送评论到 gitlab
6. 如何推送状态到企微

接下来，我们带着上面的问题，来一步步实现这个 AI Code Review 应用。

五、具体实现

5.1 创建项目

创建一个 NestJS 的项目（用什么技术框架都可以，你可以使用你最熟悉的 Node 开发框架。重点是关注实现的核心步骤和思路，这个演示的项目我开源了，可以在 GitHub 上查看完整的代码）

nvm use 20

使用 nest 命令初始化一个项目

nest new mr-agent

5.2 实现 webhook 接口

首先我们来解决 node 服务如何感知 MR 事件的问题

Webhook

像 GitLab、GitHub 都会允许用户在项目中配置 webhook。它是干嘛的呢？ webhook 可以让外部的服务，感知到 git 操作的相关事件（如 push 、merge 等事件）。比如我在合并代码时，gitlab 就会把 MR 事件，通过这个 hook 发送到我们搭建的服务上。

以 GitLab 为例，它会允许开发者在每个项目中配置多个 webhook 接口。比如，咱们配置一个 http://example.com/webhook/trigger 的地址。当发生相关 git 事件时，GitLab 就会往这个地址推送消息。

代码实现

所以，我们要做的第一件事，就是定义一个接口 url，用于接收 GitLab 的 webhook 事件。下面的代码中，实现了一个处理/webhook/trigger路由的 controller，它的主要职责是接收 MR 事件并且解析 body 和 header 中的参数，代码如下（完整代码）

Body

body 中会包含很多有用的的信息，如 Git 仓库信息、分支信息、MR 信息、提交者信息等，这些数据是 GitLab 调用 webhook 接口时发送过来的，在后续的逻辑中，都会用到里面的数据。

• object_type/object_kind：描述的事件的类型，例如 merge 事件、push 事件等。
• project：主要是描述仓库相关的信息，例如项目 id、名称等
• object_attributes: 主要包含本次 MR 相关的信息，如目标分支、源分支、mr 的 id 等等
• user：提交者的信息

Header

header 中是我们自己目定义的配置信息，核心有三个

• x-ai-mode：评论的模式（report 报告模式、 comment 评论模式）
• x-push-url：用于推送状态的地址（推送到企微、或者飞书的机器人）
• x-gitlab-token：gitlab 中的 access token，用于后续 GitLab API 调用鉴权

调试问题

调试开发的这个接口确实是一个比较麻烦的问题。因为 GitLab 基本都是内网部署，想要真实调试接口，一是需要真实代码仓库，二是需要想办法把 GitLab 的请求转发到本地来。这里我给大家分享三个办法：

内网转发

使用内网转发的办法，第三方的例如 ngrok、localtunnel、frp 等。如果你们公司的部署平台本身支持流量转发到本地，那就更好了（我用的是这个办法）。

ApiFox、Postman

先将服务部署到你们公司 GitLab 可以访问的服务器上，手动触发 MR 事件

然后在日志上打印完整的 header 和 body，然后复制到 ApiFox、Postman 上在本地模拟请求

问 AI

😁 最后一个办法就是，根据你的场景，问问 AI 怎么做 

5.3 获取 diff 内容

在能够接受到 GitLab 发送的 MR 事件后，就要解决如何获取 diff 的问题。这一步很简单， 调用 GitLab 官方的 API 就可以。重点就是两个核心逻辑：

1. 获取全部文件的 diff 内容
2. 过滤非代码文件

获取 diff 内容

gitlab 的 api 路径一般是一样的。唯一的区别就是不同公司的部署域名不同。baseUrl 需要配置成你公司的域名，projectId 和 mrId 都可以在 body 中取到（完整代码）

调用成功以后，获取的数据如下，changes 中会包含每个文件的 diff

过滤文件

因为并不是所有的文件都需要让 LLM 进行 review ，例如像 package.json、package-lock.json 等等。所以需要把这部分非代码文件过滤出来。

5.4 设计提示词

有了每个文件的 diff 数据以后，就是解决如何分析 diff 内容并输出有效结论的问题。其实这个问题的本质，就是如何设计系统提示词。

提示词思路

首先我们先思考一下编写提示词的目的是什么？我们期望的是，通过提示词指引 LLM，当输入 diff 文本的时候，它能够分析里面的代码并输出结构化的数据。

我们希望 LLM 返回的是一个数组，数组的每一项是对每一个问题的描述，里面包含标题、文件路径、行号、具体的内容等，数据结构如下：

interface Review {

  // 表示修改后的文件路径

  newPath: string;

  // 表示修改前的文件路径

  oldPath: string;

  // 表示评审的是旧代码还是新代码，如果评审的是 + 部分的代码，那么 type 就是 new，如果评审的是 - 部分的代码，那么 type 就是 old。

  type: 'old' | 'new';

  // 如果是 old 类型，那么 startLine 表示的是旧代码的第 startLine 行，否则表示的是新代码的第 startLine 行

  startLine: number;

  // 如果是 new 类型，那么 endLine 表示的是旧代码的第 endLine 行，否则表示的是新代码的第 endLine 行

  endLine: number;

  // 对于存在问题总结的标题，例如(逻辑错误、语法错误、安全风险等)，尽可能不超过 6 个字

  issueHeader: string;

  // 清晰的描述代码中存在、需要注意或者修改的问题，并给出明确建议

  issueContent: string;

}



interface MRReview {

  reviews: Review[];

}

之所以需要这种结构化的数据，是因为后续在调用 GitLab API 发送评论的时候，需要用到这些参数。

整体思路确定好了，接下来我们就来编写具体的系统提示词。

角色设定

角色设定就是告诉 LLM 扮演什么角色以及它的具体要做什么事情

你是一个代码 MR Review 专家，你的任务是评审 Git Merge Request 中提交的代码，如果存在有问题的代码，你要提供有价值、有建设性值的建议。

注意，你评审时，应重点关注 diff 中括号后面带 + 或 - 的代码。

输入内容

上面有说到，我们不仅需要 LLM 分析代码的问题，还需要它把问题代码所在的文件路径、行号分析出来。

但是，如果你直接把原生的 diff 内容输入给它，它是不知道这些信息。因为原生的 diff 并没有具体的行号、新旧文件路径信息的。

@@ -1,16 +1,13 @@

import { Injectable } from '@nestjs/common';

   

-interface InputProps {

-  code_diff: string;

-  code_context: string;

-  rules?: string;

-}

+type InputProps = Record;



interface CallDifyParams {

所以我们需要扩展输入的 diff，给它增加新旧文件的路径、以及每一行具体的行号，例如 (1， 1) 表示的是当前行，是旧文件中的第 1 行，新文件中的第 1 行。这个后面会说如何扩展，这里我们只是要先设计好，并告诉 LLM 我们会输入什么格式的内容

## new_path: src/agent/agent.service.ts

## old_path: src/agent/agent.service.ts

@@ -1,16 +1,13 @@

(1, 1) import { Injectable } from '@nestjs/common';

(2, 2)  

(3, ) -interface InputProps {

(4, ) - code_diff: string;

(5, ) - code_context: string;

(6, ) - rules?: string;

(7, ) -}

( , 8) +type InputProps = Record;

(9, 9)  

(10, 10) interface CallDifyParams {

有了这些完善的信息，LLM 才知道有问题的代码在哪个文件以及它所在的具体行号

加解释

diff 经过我们的扩展以后，就不再是标准的描述 diff 的 Unified Format 格式了，所以必须向 LLM 解释一下格式的含义，增强它对输入的理解，避免它随便臆想。

我们将使用下面的格式来呈现 MR 代码的 diff 内容:



## new_path: src/agent/agent.service.ts

## old_path: src/agent/agent.service.ts

@@ -1,16 +1,13 @@

(1, 1) import { Injectable } from '@nestjs/common';

(2, 2)  

(3, ) -interface InputProps {

(4, ) - code_diff: string;

(5, ) - code_context: string;

(6, ) - rules?: string;

(7, ) -}

( , 8) +type InputProps = Record;

(9, 9)  

(10, 10) interface CallDifyParams {



- 以 ”## new_path“ 开头的行内容，表示修改后的文件路径

- 以 ”## old_path“ 开头的行内容，表示修改前的文件路径

- @@ -1,16 +1,13 @@ 是统一差异格式(Unified Diff Format)中的hunk header，用于描述文件内容的具体修改位置和范围

- 每一行左侧括号内的两个数字，左边表示旧代码的行号，右边表示新代码的行号

- 括号后的 + 表示的是新增行

- 括号后的 - 表示的是删除行

- 引用代码中的变量、名称或文件路径时，请使用反引号（`）而不是单引号（'）。

加限制

加限制的主要目的是指引 LLM 按照固定的数据类型进行输出。这里我们会告诉 LLM 具体的 TS 类型，避免它输出一些乱七八糟的类型，导致后续在代码中解析和使用的时候报异常。例如，数字变成字符串、字符串变成数组等。

你必须根据下面的 TS 类型定义，输出等效于MRReview类型的YML对象：



```ts

interface Review {

  // 表示修改后的文件路径

  newPath: string;

  // 表示修改前的文件路径

  oldPath: string;

  // 表示评审的是旧代码还是新代码，如果评审的是 + 部分的代码，那么 type 就是 new，如果评审的是 - 部分的代码，那么 type 就是 old。

  type: 'old' | 'new';

  // 如果是 old 类型，那么 startLine 表示的是旧代码的第 startLine 行，否则表示的是新代码的第 startLine 行

  startLine: number;

  // 如果是 new 类型，那么 endLine 表示的是旧代码的第 endLine 行，否则表示的是新代码的第 endLine 行

  endLine: number;

  // 对于存在问题总结的标题，例如(逻辑错误、语法错误、安全风险等)，尽可能不超过 6 个字

  issueHeader: string;

  // 清晰的描述代码中存在、需要注意或者修改的问题，并给出明确建议

  issueContent: string;

}



interface MRReview {

  reviews: Review[];

}

```

在限制的类型中，最好是增加一些注解，让 LLM 能够理解每个字段的含义。

加示例

加示例的主要目的是告诉 LLM 按照固定的文件格式进行输出，这样我们就可以直接拿 LLM 的输出，进行标准化的解析，转换成实例的数据进行使用，伪代码如下：

// 调用 LLM 的接口

const result = await callLLM('xxxxx');



// 解析数据

const data = yaml.load(result);



// 操作数据

data.reviews.forEach(() => {  })

提示词描述如下

输出模板（注意，我只需要 yaml 格式的内容。yaml 内容的前后不要有其他内容）:



```yaml

reviews:

  - newPath: |

      src/agent/agent.service.ts

    oldPath: |

      src/agent/agent.service.ts

    startLine: 1

    endLine: 1

    type: |

      old

    issueHeader: |

      逻辑错误

    issueContent: |

      ...

  - newPath: |

      src/webhook/decorators/advanced-header.decorator.ts

    oldPath: |

      src/webhook/decorators/commmon-header.decorator.ts

    startLine: 1

    endLine: 1

    type: |

      new

    issueHeader: |

      性能风险

    issueContent: |

      ...

```

这里简单说一下，为什么选择 yaml 而不是 json。因为在实践的过程中，我们发现 json 解析异常的概率会比 yaml 高很多，因为 json 的 key 和 value 是需要双引号("")包裹的，如果 issueContent 中包含了代码相关的内容且存在一些双引号、单引号之类的符号，就很容易导致报错，而且比较难通过一些替换规则进行兜底处理。

最后完整的提示词这里：提示词

调试

这里再告诉大家一个提示词的调试技巧，你可以先在 Coze、Dify 这样的平台上，通过工作台不断调试你的提示词，直到它能够稳定的输出你满意的结果。

5.5 扩展、组装 diff

上面我们有说到，通过 GitLab 获取的原始 diff 是没有新旧文件路径和具体的新旧行号的，这个需要通过代码计算来补全这些信息。这一小节，我们就来解决 diff 的扩展、组装问题。

扩展

扩展主要做两个事：

• 在 diff 头部加新旧文件的路径
• 在每一行加新旧文件中的行号

加路径比较简单，可以在获取每个文件的 diff 数据的时候，拿到新旧文件的路径的，取值后加上即可。

 加行号稍微麻烦一点，我们需要将当前文件的 diff 按照 hunk 拆分成不同的块，然后会根据 hunk head 计算每行在新旧文件中的真实行号。

为了防止有些同学不清楚 diff 格式的结构，我这里简单标注一下。 在下面这个 diff 中，像 “@@ -1,16 +1,13 @@” 这样的内容就是 Hunk Head，用于描述后续 diff 内容在新旧文件中的起始行号。用框住的第一个 hunk 为例：

• -1,16: 表示 import { Injectable } from '@nestjs/common'; 是在旧文件中的第 1 行，改动范围是往后的一共 16 行，需要忽略 “+” 加号开头的行。
• +1,13：表示是import { Injectable } from '@nestjs/common';在新文件中的第 1 行，改动范围是往后的一共 13 行，需要忽略 “-” 加号开头的行。

然后图中被我用红框标注的连续代码片段就是 hunk，它一般由 hunk header + 连续的代码组成。一个文件的 diff 可能会有多个 hunk。

• hunk 中 “+” 开头的行，表示新文件中增加的行
• “-” 开头的行，表示旧文件中被删除的行 

这里需要先遍历每个文件的 diff，然后按 hunk head 来分割内容块。

const hunks = splitHunk(diffFile.diff);

代码如下：

逻辑是将 diff 按 “\n” 分割成包含所有行的数组，然后遍历每一行。每当遍历到一个 hunk head 就创建一个新的 hunk 结构，然后通过正则提取里面的起始行号，并将后续遍历到的行都保存起来，直到它遇到一个新的 hunk head。

接着就是遍历 hunk，计算每个 hunk 中每一行的具体行号。

comptuedHunkLineNumer 的代码如下：

核心逻辑是：

1. 使用 oldLineNumber、newLineNumber 两个独立计数器，记录新旧文件的当前行号
2. 遍历到 “-” 开头的行，oldLineNumber + 1，记录行号（oldLineNumber + 1， ）
3. 遍历到 “+” 开头的行，newLineNumber + 1，记录行号（ ， newLineNumber + 1）
4. 遍历常规的行，oldLineNumber 和 newLineNumber 都 + 1，记录行号（oldLineNumber + 1， newLineNumber + 1）

为了让你更清晰理解这个逻辑，我在 diff 中标注一下。下面是计算旧文件中的行号，我们只会对“-”开头的行和普通的行进行计数，忽律 “+” 开头的行。

计算新文件中的行，此时我将不计算 “-” 开头的行。所以type InputProps = Record;这行代码，在合并后的新文件中，真正的行号是在第 15 行。

处理后 diff 的每一行，都会带上新旧文件中的行号

@@ -1,16 +1,13 @@

(1, 1)    import { Injectable } from '@nestjs/common';

(2, 2)    

(3, )    -interface InputProps {

(4, )    -  code_diff: string;

(5, )    -  code_context: string;

(6, )    -  rules?: string;

(7, )    -}

( , 8)   +type InputProps = Record;

(9, 9)    

(10, 10)  interface CallDifyParams {

(11, 11)    input: InputProps;

(12, 12)    query: string;

(13, 13)    conversation_id?: string;

(14, 14)    user: string;

( , 15)  +  apiKey: string;

(16, 16)  }

(17, 17)  

组装

得到每个文件扩展的 diff 以后，便是将 commit message 和所有文件 diff 拼接到一个字符串中，后续会把这个拼接好的字符串直接输入给 LLM 进行分析。

commit message: feat: 调整 review 触发逻辑，增加请求拦截器



##new_path: src/agent/agent.service.ts

##old_path: src/agent/agent.service.ts

@@ -1,16 +1,13 @@

(1, 1)    import { Injectable } from '@nestjs/common';

(2, 2)    

(3, )    -interface InputProps {

(4, )    -  code_diff: string;

(5, )    -  code_context: string;

(6, )    -  rules?: string;

(7, )    -}

( , 8)   +type InputProps = Record;



## new_path: src/webhook/decorators/advanced-header.decorator.ts

## old_path: src/webhook/decorators/advanced-header.decorator.ts

@@ -0,0 +1,152 @@

( , 1)     +import {

( , 2)     +  createParamDecorator,

( , 3)     +  ExecutionContext,

( , 4)     +  BadRequestException,

( , 5)     +} from '@nestjs/common';

( , 6)     +

( , 7)     +/**

( , 8)     + * 高级 Header 装饰器，支持类型转换和验证

( , 9)     + */

( , 10)    +export const AdvancedHeader = createParamDecorator(

5.6 对接 LLM

现在我们已经有了系统提示词、处理好的 diff 内容，接着就是如何调用 LLM 分析结果。

申请 DeepSeek

演示的案例中，我用的是 DeepSeek-v3 的模型。如果能够使用 GPT-4.1 或者 Calude 模型的同学，你可以优先选择使用这两个模型。

这里你需要去到 DeepSeek 官网申请一个 API Key

然后去充值个几块钱，你就可以使用 DeepSeek 这个模型了。

具体申请和使用步骤，官网文档都讲得很清楚了，这里不过多赘述。

调用 LLM

申请完 DeepSeek 的 API Key 以后，就可以通过接口调用了

这里主要关注一下调用接口的入参：

• model: 如果是 deepseek 的话，你选择 deepseek-chat还是 deepseek-reasoner都可以
• messages: 这里我们输入两个 message，一个是系统提示词，一个是扩展的 diff
• temperature：设置成 0.2，提高输出的精确性

如果一切调用成功的话，你应该会得到 LLM 一个这样的回复：

```yaml

reviews:

  - newPath: |

      src/agent/agent.service.ts

    oldPath: |

      src/agent/agent.service.ts

    startLine: 8

    endLine: 8

    type: |

      new

    issueHeader: |

      类型定义不严谨

    issueContent: |

      将 `InputProps` 从具体的接口类型改为 `Record`，虽然提升了灵活性，但丢失了原有的类型约束，容易导致后续代码中出现属性拼写错误或类型不一致的问题。建议保留原有字段定义，并在需要扩展时通过继承或联合类型实现更好的类型安全。

  - newPath: |

      src/webhook/webhook.controller.ts

    oldPath: |

      src/webhook/webhook.controller.ts

    startLine: 38

    endLine: 40

    type: |

      new

    issueHeader: |

      参数注入冗余与未使用参数

    issueContent: |

      在 `trigger` 方法中注入了 `@GitlabToken()`、`@QwxRobotUrl()` 等参数，但实际方法体内并未使用这些参数，而是继续从 headers 中解析相关信息（已被删除）。建议移除未用到的装饰器参数，或者直接替换原有 header 获取逻辑，避免混乱和冗余。

```