nei-ts-helper

- 有啥用
- 咋用呢
- 配置文件
- 命令行参数
- 咋运作的
- 流程
- 几个概念
- 生成代码
- 最佳实践
- 待做

有啥用

使用 TypeScript 开发项目本身是一件非常愉悦的事情，但是总会有些麻烦的事情打破这份愉悦，业务开发中最常见的问题：我要对接口 请求&返回 数据写声明吗？any 处理起来非常方便，但是没有了数据的提示和检查，可是看着臭长的接口返回完全提不起写声明的兴趣┓( ´∀ )┏(尤其遇到喜欢频繁改动接口数据的后端就更痛苦了)

nei-ts-helper 可以帮助你摆脱这些无趣的事情，它帮助你从 NEI 平台定义的接口转化为 Typescript 声明代码

咋用呢

nei-ts-helper 是一个命令行工具，它根据配置文件自动生成 Typescript 声明至指定文件夹

1. 安装 nei-ts-helper

`bash
npm i nei-ts-helper --save-dev
// or
yarn add nei-ts-helper --dev
`

2. 在根目录新建配置文件 nei-ts-helper.js / nei-ts-helper.ts

如：
`ts
import { defineConfig } from 'nei-ts-helper/lib'

export default defineConfig({
indentSize: 2,
root: 'typings',
version: 2,
apiList: {
urls: {
GetDomainList: 'xxxxx'
},
output: {
'domain-list.ts': [
'GetDomainList'
]
}
}
})
`

`js
module.exports = {
indentSize: 2,
root: 'typings',
version: 2,
apiList: {
urls: {
GetDomainList: 'xxxxx'
},
output: {
'domain-list.ts': [
'GetDomainList'
]
}
}
}
`

详细配置文件书写见下面

3. 添加 scripts

`json
"nei": "nei-ts-helper -all"
`

4. 添加 NEI 访问令牌

它使用 NEI 提供的 openApi 获取接口相关信息，所以我们需要创建一个访问令牌

5. 根目录运行 npm run nei

根据命令行提示填入访问令牌，选择保存将会自动存储在 系统 HOME 下的 .nei-ts-helper 文件夹

配置文件

可以使用 -c / —config 手动指定配置文件，默认会自动读取当前运行环境目录下的 nei-ts-helper.ts / nei-ts-helper.js，配置文件导出一个配置对象，字段参数如下：

- 声明
`tsx
interface ApiConfigV2 {
urls: {
[key: string]: T;
},
output: {
[key: string]: ApiConfigV2['urls'][string][];
}
}

interface ConfigV2 {
apiList: ApiConfigV2;
/* 输出文件目录 /
root: string;
/* 缩进空格数，默认2 /
indentSize?: number;
version: 2;
}
`
- apiList

接口配置

- urls: 接口的 NEI 链接，key 是接口名，value 是 NEI 链接
- output: 输出文件，key 是输出文件名，value 是接口名数组

- root

输出文件基础目录

- indentSize

缩进空格数，默认2

- version

配置版本后，当前固定为 2

推荐使用 ts 格式文件编写，导入相应声明获得配置文件格式的校验

命令行参数

* 只生成部分声明

`bash
nei-ts-helper [-pf / --part-file ]
`

-pf/--part-file 参数后传入需要生成声明的文件名(对应 nei config 中的output )

如以下命令仅会生成包含在 home.ts 和 active.ts 文件中的声明

`bash
nei-ts-helper -pf home.ts active.ts
`

* 生成全部声明

`bash
nei-ts-helper -all
`

现在支持拆分多个文件编写 TS 声明配置。因此如果需要一次性生成全部声明，需要使用 -all 参数。会遍历并执行当前目录下所有的配置文件

* -ouc/--only-update-config

只更新配置文件，不生成文件声明

咋运作的

原理十分简单，就是调用 NEI openApi 接口获取接口参数，通过字符串拼接的形式生成声明代码

核心代码在 src/core 目录下，分为三个模块

read-config

读取&解析配置文件

fetch-interface

调用 NEI openApi 接口获取接口参数

generator

生成 TypeScript 声明代码的核心逻辑

$3

!process

$3

我们将 NEI 中一个字段的数据类型分为

1. 基础类型

String，Number，Boolean，Variable，File，UNKNOWN

我们将它和 TypeScript 中的类型一一对应

2. 复合类型

基础类型的组合，包括

- 匿名复合类型
!anoInterface
- 具名复合类型
!independInterface
3. 枚举类型

NEI 获取的接口声明类型我们称为 ParamInterface ，其中可能包含基础类型和复合类型字段，对于复合类型字段需要根据 type 到 DataType 类型中查找

对于一个接口我们最关心的是两个参数 pid 和 id

- 根据 pid 获取该项目的 DataType 数据
- 根据 id 获取该接口的 ParamInterface 数据

$3

处理 TypeScript 声明代码的生成，本质是对复合类型递归遍历为基础类型的生成，通过 NEI 基础类型到 TypeScript 基础类型的映射关系完成 声明的生成

1. 基础类型代码生成主要是两个函数 productSingleStatement 和 productUnionStatement
2. 复合类型代码生成主要是两个函数
- productIndependentInterface
具名复合类型 通过该方法生成独立的声明
- productAnonymousInterface`
匿名复合类型 通过该方法生成声明

最佳实践

只使用基于「自动生成的声明」二次封装的声明
* 自动生成的声明，名称/存储位置都可能发生改变，直接引用的方式修改成本大
* 接口生成的声明往往层级嵌套深，二次封装简化使用的同时还可以语义化重命名

待做

- [ ] 非请求的测试
- [x] 部分接口更新
- [ ] 更新是否覆盖原有接口数据