UnoAPI 附加篇：丢掉繁琐！让工具变得更加“人性化”

目前，UnoAPI 在前端接口生成方面还存在几个小问题，有点强迫症的我实在忍不了，还是花了一些时间进行了一些优化。

‼️ 问题：

1. 使用流程“繁琐”：必须先初始化配置、下载文档后，才能正常使用uno api命令；
2. 对项目有一定的“侵入性”：必须在项目根目录生成配置文件unoapi.config.ts，还需要安装@unoapi/core依赖包；
3. 不够轻便：这里的“轻便”是指，能够一键使用、用完即可弃，对项目没有任何污染。
4. 不够灵活：不要 api 函数代码，只生成 model 代码。

归根结底，就是：我很懒，我希望只需要一条命令就可以体验“接口代码自动生成”的功能。

# 零侵入、快速体验
npx @unoapi/cli -u https://unoapi.codingmo.com/api-json

# 零侵入、安装体验
npm i @unoapi/cli -g
uno -u https://unoapi.codingmo.com/api-json

这才是一款合格的工具本身应该有的样子。

设计调整

1️⃣ 支持在线使用

之前那套“繁琐”的使用流程的原因就是不支持在线使用。

起初想的是不要依赖于网络，用户必须先将文档下载到本地缓存起来，再使用。但是真实的开发环境基本上都离不开网络，离线使用应该作为次要功能保留。

如此，就可以调整一下uno api命令，增加一个参数-u, --openapi-url。然后在代码中判断：如果此参数存在，就临时远程下载文档。

if (options.openapiUrl) {
  try {
    consola.start('下载远程文档...', options.openapiUrl);
    doc = await downloadDoc(options.openapiUrl);
    consola.success('下载成功！');
  } catch {
    consola.error(new Error(`下载 OpenAPI JSON 文档失败，请检查 ${options.openapiUrl} 是否正确！`));
    process.exit(1);
  }
}

如果没有带--openapi-url参数，就退回之前的离线模式：从本地缓存文件中加载文档数据。

甚至还可以做一个兜底：如果本地没有缓存文件，就从配置文件中取openapiUrl参数在线下载。

2️⃣ 不依赖配置文件

其实之前的配置文件中，也只有openapiUrl是必填参数。现在此参数可通过命令行直接传递后，对unoapi.config.ts已经没有依赖了。

我们不需要将配置文件中所有的参数都拿到命令行中，只需要将一些常用的参数拿过来即可。

如何本地没有配置文件，调用loadConfig()函数返回内部默认的配置即可；如果存在配置文件，就进行合并。

命令行自带的参数，优先级最高，其次是配置文件，最后用默认配置兜底。

因为不依赖配置文件了，也就不再需要在项目中安装@unoapi/core依赖包了。因为之前配置文件依赖了@unoapi/core包中的defineUnoConfig函数。

import { defineUnoConfig } from '@unoapi/core';

export default defineUnoConfig({
  openapiUrl: 'https://api.example.com/openapi.json', // 支持返回 Promise 的回调函数
  // ...
}

3️⃣ 只生成 model 代码

很多情况下，生成的 api 函数代码很难通用，反而model 代码价值更高，因为 model 代码是严格根据接口数据来的。但手动写又特别繁琐，还容易出错，因此很多 ts 项目都是直接用any代替了。

对于 UnoAPI 来说，就特别简单，还能 100% 保证与后端接口保持绝对一致。

所以，我们在uno api与配置文件中增加一个参数--only-model。此参数为true时，则跳过 api 函数代码的写入。

if (!options.onlyModel) {
  await writeApiFile(genApi, { base: baseApiOutput, imports: config.imports });
}

“

这就体现了之前 core 子项目模块化、函数式设计的好处了，此时只需要不执行writeApiFile函数就行了。

4️⃣ 其他调整

将之前的uno update改成了uno download，让操作更加清晰：这条命令就是将远程文档下载到本地。

同时，也支持携带openapiUrl参数，也不需要依赖配置文件。

uno download https://unoapi.codingmo.com/api-json

如果想离线使用，就需要执行此命令。

调整后的结果

现在，不同命令之间不再相互依赖。

• uno init：生成配置文件，不再需要必须执行；
• uno download：下载文档到本地缓存，不强依赖配置文件，也不需要必须执行；
• uno api：生成代码的核心命令，其中api指令可省略。

支持的使用模式：

1. 无配置文件的在线模式

# 在线使用
uno -u https://unoapi.codingmo.com/api-json

2. 有配置文件的在线模式

# 生成配置文件
uno init https://unoapi.codingmo.com/api-json
# 在线使用
uno

3. 无配置文件的离线模式

# 下载文档
uno download https://unoapi.codingmo.com/api-json
# 离线使用
uno

4. 有配置文件的离线模式

# 生成配置
uno init https://unoapi.codingmo.com/api-json
# 下载文档
uno download
# 离线使用
uno

第一种使用方式是绝对零依赖、零侵入，也是我们这次调整的主要目标。这些命令都支持npx @unoapi/cli方式快速使用。

配置文件虽不是必须的，但如果想体验完整功能：比如自定义 api 函数，就必须使用配置文件。

uno api支持的参数：

• -u, --openapi-url：OpenAPI JSON 文档地址
• -o, --output：输出目录，默认 src/api
• --func：自定义 API 函数名称
• --only-model：只生成 model 代码
• --global-model：生成的 model 类型在全局声明
• --all：生成所有接口代码

总结

调整之后，使用简单多了，我自己是有点强迫症的，也非常讨厌“反人性化”的设计。

我是 UnoAPI 工具的开发者，同样也是一名使用者，不管是自己开发的工具，还是别人写的工具，不好用就是不好用。

如果在坐的各位有什么好的想法和建议，也欢迎评论区留言。