解放前端生产力:我如何用 LLM 和 Bun.js 构建一个 YApi to TypeScript 的自动化代码生成服务

引言:我们与 YApi 的"爱恨情仇"

在现代前后端分离的开发模式中,API 文档是连接前后端的桥梁。YApi 以其直观、易用的特性,成为了许多团队的首选。然而,对于前端开发者来说,一个普遍的痛点随之而来:我们不得不花费大量时间,手动将 YApi 上的接口定义,逐字逐句地翻译成项目中的 TypeScript 类型(Interfaces/Types)。

这项工作不仅枯燥、重复,而且极易出错。一个字段的拼写错误、一个数据类型的遗漏,都可能导致难以追踪的 Bug。当后端接口频繁变更时,这种维护成本更是呈指数级增长。我们不禁思考:这种高度模式化的重复性劳动,是否可以被彻底自动化?AI 大模型(LLM)能否理解 YApi 的 JSON 定义,并为我们编写出高质量、可维护的类型代码?

为了终结这场"爱恨情仇",yapi-mcp-server 诞生了。它是一个小巧而强大的命令行工具,旨在将 YApi 定义自动化生成为 TypeScript 代码。本文将完整分享它的设计思路、技术实现和开发过程中的心得体会。

一、项目核心特性

yapi-mcp-server 的核心目标是成为开发者工具箱中的一把利器,让类型定义不再成为开发的负担。

  • 核心功能:
    • 自动化生成: 一键连接指定的 YApi 项目,将接口定义智能地转换为强类型的 TypeScript 代码。
    • 基于 LLM: 利用大语言模型强大的代码理解和生成能力,确保生成的代码不仅语法正确,而且具有良好的可读性和风格。
    • MCP 服务: 项目本身被构建为一个标准的模型上下文协议(Model-Context Protocol)服务,这为未来连接不同的 AI 模型或扩展更多功能提供了无限可能。

二、技术选型与架构设计

为了快速实现并保持项目的简洁性,我选择了一套非常现代且高效的技术栈。

  • 为什么选择 Bun.js?

    • 极致性能: Bun 拥有闪电般的启动和执行速度,对于需要频繁调用的 CLI 工具来说,体验极佳。
    • 一体化工具链: 它原生支持 TypeScript,并且内置了打包器(Bundler)和任务运行器(Task Runner)。这意味着我无需再配置 tscwebpack/rollupnodemon,一个 bun 命令就能搞定开发、构建和运行,极大地简化了项目配置。
    • 拥抱现代: Bun 全面拥抱最新的 JavaScript API 和 Web 标准,让开发过程更加顺畅。
  • 核心依赖与它们扮演的角色:

    • @modelcontextprotocol/sdk:这是构建 MCP 服务的核心。它提供了一套标准化的方法来定义一个函数(Function),这个函数可以接收输入,并由背后的大语言模型来执行处理逻辑,最后返回结果。
    • axios:一个强大而经典的 HTTP 客户端。我用它来与 YApi 服务进行所有网络通信,例如登录、拉取接口数据等。
    • cookie:一个轻量级的库,专门用于解析和序列化 HTTP Cookie。这是成功模拟 YApi 登录并保持会话的关键。
  • 项目架构解析:

    • src/core/APIClient.ts YApi 的"适配器"。这个类封装了所有与 YApi 服务端的交互逻辑,包括登录、获取项目信息、拉取接口列表和获取单个接口的详细定义。它将原始的 HTTP 请求和响应,包装成对业务逻辑更友好的方法。
    • src/core/CookieManage.ts 独立的 Cookie 管理器。YApi 的接口数据大多需要登录后才能访问。这个模块专门负责从登录接口的响应头中捕获 _yapi_token_yapi_uid 这两个关键 Cookie,并在后续的所有请求中携带它们,以维持登录状态。
    • src/index.ts 项目的入口和大脑。它负责:
      1. 读取 .env 环境变量。
      2. 初始化 APIClient
      3. 定义核心的 MCP 函数,该函数接收一个 YApi 接口 ID 作为输入。
      4. 在该函数内部,调用 APIClient 获取接口数据,然后精心设计一个 Prompt,将接口数据和生成指令一同发送给 LLM,最终返回 LLM 生成的 TypeScript 代码。
      5. 启动整个 MCP 服务,等待客户端的调用。

三、开发中的关键挑战与解决方案

开发过程中并非一帆风顺,以下是几个关键挑战及其解决方案。

  • 挑战一:YApi 的登录认证

    • 问题: 如何在 Node.js 程序中模拟浏览器登录 YApi 并保持会 e 话?
    • 解决方案: 通过浏览器开发者工具分析 YApi 的登录流程,我发现登录请求会返回一个包含关键认证信息的 Set-Cookie 响应头。于是,我使用 axios 发送一个 POST 请求到 /api/user/login,并在 CookieManage.ts 中实现了一个 setCookie 方法,它专门解析 Set-Cookie 响应头,提取出 _yapi_token_yapi_uid 并保存起来。在后续所有对 YApi 的请求中,再将这些 Cookie 附加到请求头里,成功模拟了已登录的会话。
  • 挑战二:Prompt Engineering 的艺术

    • 问题: 如何设计 Prompt,才能让 LLM 稳定、可靠地生成我们期望的、格式统一的 TypeScript 代码?
    • 解决方案: 这是项目的核心。经过多次尝试,我总结出了一套行之有效的 Prompt 模板。关键在于:
      1. 明确角色: "你是一个专业的 TypeScript 开发工程师..."
      2. 清晰指令: "...你的任务是根据我提供的 YApi 接口的 JSON 数据,为这个接口生成请求参数(Request)和响应数据(Response)的 TypeScript Interface。"
      3. 提供上下文: 将从 YApi 获取的接口详情 JSON 完整地作为输入提供给模型。
      4. 定义输出格式和规则: 明确要求 Interface 的命名规范(如 GetUserInfoRequest)、添加 JSDoc 注释、处理可选字段和数组类型等细节。
      5. 给出示例(Few-shot Learning): 在 Prompt 中提供一两个简单的输入输出对,能极大地提升模型生成结果的准确性和稳定性。

四、如何使用

  • 快速上手指南:

    1. 全局安装: npm install -g @lstmxx/yapi-mcp-server
    2. 在你的项目根目录创建一个 .env 文件,配置 YApi 地址和凭据。
    3. 运行 yapi-mcp-server 启动服务。
    4. 使用任何 MCP 客户端(如 MCP Inspector)与服务交互,输入接口文档 url,即可获得生成的代码。效果如下图所示

五、总结与思考

yapi-mcp-server 是一个简单而纯粹的尝试,它展示了如何将大语言模型(LLM)作为一种强大的"代码生成"工具,嵌入到我们日常的开发工作流中,从而将开发者从繁琐、重复的劳动中解放出来。


希望这个项目能为你带来帮助,也欢迎社区的朋友们试用、反馈 Bug 或贡献代码!

相关推荐
小牛itbull12 小时前
初始化electron项目运行后报错 electron uninstall 解决方法
前端·javascript·electron
魁首13 小时前
初识 MCP (Model Context Protocol)
claude·gemini·mcp
闲蛋小超人笑嘻嘻13 小时前
前端面试十四之webpack和vite有什么区别
前端·webpack·node.js
用户40993225021213 小时前
银行转账不白扣钱、电商下单不超卖,PostgreSQL事务的诀窍是啥?
后端·ai编程·trae
rggrgerj14 小时前
Vue3 组件完全指南代码
前端·javascript·vue.js
golang学习记15 小时前
从0死磕全栈之Next.js App Router动态路由详解:从入门到实战
前端
huangql52015 小时前
基于前端+Node.js 的 Markdown 笔记 PDF 导出系统完整实战
前端·笔记·node.js
在逃的吗喽15 小时前
Vue3新变化
前端·javascript·vue.js
yqwang_cn15 小时前
打造优雅的用户体验:自定义jQuery工具提示插件开发全解析
前端·jquery·ux
小Tomkk15 小时前
AI 提效:利用 AI 从前端 快速转型为UI/UX设计师和产品
前端·人工智能·ui