UnoAPI 开源后续：它到底是用来干嘛的？

上一篇介绍开源的文章被微信推了一把，让很多人都了解到了 UnoAPI 这款工具。故此我有必要说清楚这款工具的前因后果，以及被吐槽最多的问题：UnoAPI 到底是干嘛的？

这一篇文章将详细解释关于 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,
  });
}

所有与“用户”相关的接口请求，我都会放在src/api/user.ts中，这样做的好处是：在业务代码中的任何地方都可以使用这个接口，并且完全支持Tree Shaking。

在业务代码中使用：

import * as userApi from '@/api/user';

const userList = await userApi.getUserList({ xx: 'xxx' });

所以，API 层的代码就是指：

• getUserList 函数
• GetUserListQuery 入参类型
• UserInfo 出参类型

👉 UnoAPI 就是用来自动生成这些代码的。

如何使用？

UnoAPI 是“开箱即用”的，对项目也是“零侵入”。

"

这样设计的初衷就是：只把它作为一款辅助编码工具。想用就用，不想用就不用，项目中不会残留任何痕迹。

目前，只提供 CLI 命令行使用方式，除非你想基于core包做二次开发。

UnoAPI 使用非常灵活，下面介绍几种使用方式：

1️⃣ 不安装使用

npx @unoapi/cli -i 在线或本地的JSON文档

2️⃣ 全局安装使用

# 全局安装
npm install @unoapi/cli -g

# 使用
uno -i 在线或本地的JSON文档

3️⃣ 配置文件

如果你真的想使用它，大多数情况你都需要创建一个配置文件：

# 创建配置文件
uno init

# 使用时可以不用带参数
uno

以上这些使用方式，你唯一且必须提供的就是一个OpenAPI JSON 格式的文档，目前只支持 3.1 版本。

👉 uno 参数说明

• -i, --input：在线或本地的 OpenAPI JSON 文档
• -o, --output：指定代码输出目录或文件
• --func：自定义 API 函数名称
• --only-model：只生成 ts 类型定义文件
• --all：生成所有接口

👉 配置文件字段说明

• input：在线或本地的 OpenAPI JSON 文档，同时支持异步函数，需要鉴权的文档可以在函数中手动处理
• output：代码输出目录
• typeMapping：自定义类型映射
• onlyModel：只生成 ts 类型定义文件
• imports：函数头部导入代码，通常是你的request函数
• ignores：匹配的接口和类型，不会生成代码
• funcTpl：自定义 API 函数

如果默认生成的 API 函数不是你想要的，就可以通过funcTpl字段来自定义符合你们项目风格的 API 函数。funcTpl接收一个接口上下文ApiContext字段，返回一个 API 函数代码的字符串。

🚀 快速体验

为了能够快速体验到效果，我特地准备了一个在线的接口文档（钉钉公开接口文档），你什么都不用做，只需复制下面的命令，查看效果：

npx @unoapi/cli -i https://unoapi.codingmo.com/api/dd-openapi-v31.json

然后选择一个接口：

最后就会自动生成这些文件和代码：

为什么要用 UnoAPI？

API 层的代码通常格式固定、类型定义繁琐，而这些完全可以基于后端接口文档自动生成，能够极大提升我们的编码效率和出错概率。

就像你手动编码，不也是参照后端接口文档来的吗？UnoAPI 也是一样，通过解析接口文档来实现自动编码。

同时，它也能统一编码风格，避免人为偷懒。现实中，很多接口代码的现状：出、入参定义不全，甚至使用any省略；

"

❌ 当然，如果你项目的 API 层代码风格与上面所说的完全不一样，那这款工具肯定不适合你。

解答一些问题

这些是根据之前大家吐槽的问题进行了整理：

1. 使用时遇到问题怎么办？

这是一个开源项目，你有任何问题都可以去 GitHub 上提 issue，也可以提 PR，但我不能保证及时更新与修复。

2. UnoAPI 稳定吗？

目前无法保证稳定性。自己使用场景有限，无法覆盖各种情况。

新版本也可能会随时调整一些细节，也会增加或删减一些功能，但是每一个版本都是在 npm 仓库定死的，这个我没法改。

其实这个并不重要，因为它对你的项目没有任何侵入、更不会造成任何损失。

3. 我不想用了怎么办？

还是那句话：设计这款工具的初衷就是“辅助编码”，对项目没有任何“侵入性”。如果在使用中遇到问题或者不想用了，不用就行了。

如果你在项目中创建了配置文件，可以直接删除，不删除也不会有任何影响。

4. VS Code 扩展会更新吗？

VS Code 扩展目前还没有想到好的交互方式，如果不能相较 CLI 端带来更好的使用体验，那就暂时不会更新。

为什么会有 UnoAPI？

这些都是我自己在接口联调时遇到的一些问题：每次都要写很多重复代码，也很容易写错或写漏字段。于是就慢慢产生了一个想法：为什么不能写一个脚本自动做这些事情呢？

后来经过慢慢的整理思路，并创建了这个 UnoAPI 合集：用于记录和分享这款工具的诞生过程。

起初更多是为了分享技术，没想过把它作为一款生产力工具来推广。

前面的文章关注度一直不高，上一篇文章主要是为了实现之前说好要开源的承诺，就匆匆忙忙整理了代码、随便写了一篇文章，都准备断更了，没想到反而引起了大家的注意。

现在，我也需要换一个角度来重新审视这个 UnoAPI 合集：不再分享技术实现了，认真思考一下如何将它变成一个真正有价值的工具吧。

后续计划

项目已开源，如果参与的人比较多，更新可能会频繁一些；如果没啥关注度，就看自己的心情更新了。

有问题，才有更新的方向，全凭我自己臆想，估计也很难持续下去。