UnoAPI 是干嘛的？
简而言之，UnoAPI 的核心功能是：自动生成前端项目中的 API 层代码。
❓ 什么是“API 层”代码？
以常见的前端开发模式为例：当需要调用一个“获取用户列表”的接口时，开发者通常会在 src/api 目录下的 user.ts 文件中编写如下代码：
import { GetUserListQuery, UserInfo } from './model';
/**
* 获取用户列表
*/
export function getUserList(query: GetUserListQuery) {
return request<UserInfo[]>({
url: 'xxx',
method: 'GET',
query,
});
}
将所有与“用户”相关的接口集中管理在同一个文件中，便于在业务代码中复用，并天然支持 Tree Shaking。
在业务组件中的调用方式如下：
import * as userApi from '@/api/user';
const userList = await userApi.getUserList({ xx: 'xxx' });
因此，这里所说的 API 层代码通常包括：
getUserList 请求函数GetUserListQuery 入参类型定义UserInfo 出参类型定义
UnoAPI 的作用，就是基于接口文档自动生成上述这些格式固定的代码和类型定义。
如何使用？
UnoAPI 设计为 “开箱即用”且对项目“零侵入” 的工具，旨在作为纯粹的开发辅助。你可以随时启用或停用，而不会在项目中留下任何必须的依赖或配置。
目前主要提供 CLI 命令行使用方式。
三种使用方式
1️⃣ 通过 npx 直接运行（无需安装）
npx @unoapi/cli -i <在线或本地的OpenAPI JSON文档URL/路径>
2️⃣ 全局安装后使用
# 全局安装
npm install @unoapi/cli -g
# 使用
uno -i <在线或本地的OpenAPI JSON文档URL/路径>
3️⃣ 使用配置文件（推荐用于常规项目）
对于需要重复使用的场景，可以创建配置文件来管理参数。
# 生成默认配置文件
uno init
# 使用配置文件运行（无需额外参数）
uno
无论采用哪种方式，都需要提供一个符合 OpenAPI 3.1 规范的 JSON 格式文档作为输入源。
核心参数说明
-i, --input：指定在线或本地的 OpenAPI JSON 文档路径。-o, --output：指定生成代码的输出目录或文件。--func：自定义生成的 API 函数名称。--only-model：仅生成 TypeScript 类型定义文件。--all：生成文档中的所有接口，而非交互式选择。
配置文件详解
通过 uno init 生成的配置文件允许进行更细致的控制：
input：文档地址，支持 URL 或本地路径，也支持异步函数以便处理需要鉴权的文档。output：代码输出目录。typeMapping：自定义类型映射规则。onlyModel：设为 true 时只生成类型定义。imports：在生成的 API 函数顶部插入的导入语句，通常用于引入项目自定义的 request 函数，这对统一项目请求风格非常重要。ignores：通过正则表达式匹配，忽略不需要生成的接口或类型。funcTpl：自定义 API 函数模板。如果默认生成的函数不符合你的项目规范，可以利用此字段，根据提供的 ApiContext 上下文对象，返回一个符合团队风格的函数代码字符串。
🚀 快速体验
为了直观感受生成效果，可以直接运行以下命令（使用一个公开的钉钉接口文档）：
npx @unoapi/cli -i https://unoapi.codingmo.com/api/dd-openapi-v31.json
执行后，CLI 会以交互形式让你选择需要生成的接口：
选择完成后，工具会自动在指定目录生成对应的 TypeScript 文件与代码：
为什么要用 UnoAPI？
手动编写 API 层代码存在两个普遍问题：重复性高和易出错。定义接口的入参、出参类型是一项繁琐且容易遗漏的工作。UnoAPI 通过解析后端提供的标准 OpenAPI 文档，自动化完成这部分编码，能显著提升开发效率并降低因手误导致的类型错误。
同时，它也有助于统一团队的代码规范，避免在赶工时直接使用 any 类型或省略类型定义等不良实践。
当然，如果你的项目现有 API 层架构与本文描述的模式迥异，那么这款工具可能并不适用。
常见问题解答
1. 使用时遇到问题怎么办？
UnoAPI 是一个开源项目，欢迎在 GitHub 仓库提交 Issue 或 Pull Request。请注意，维护者可能无法保证所有问题都能得到即时响应与修复。
2. UnoAPI 稳定吗？
目前版本仍处于早期阶段，无法保证绝对的稳定性与兼容性。功能细节可能随着版本迭代进行调整。但得益于其“零侵入”的设计，即使生成代码后不再使用该工具，或新版本存在变动，也不会对现有项目运行造成任何影响。
3. 不想用了怎么办？
直接停止使用即可。UnoAPI 不会在项目中添加任何运行时依赖，生成的代码是纯静态的 TypeScript 文件，如同手动编写的一样。配置文件也可随时安全删除。
4. VS Code 扩展会更新吗？
短期内暂无更新 VS Code 扩展的计划。除非能找到比 CLI 方式体验显著提升的交互模式，否则开发重心将放在核心命令行工具上。
后续计划
项目已完全开源，更新频率将取决于社区反馈和参与度。实际使用中遇到的问题将是驱动功能迭代的最佳方向。
发表于