# an-cli

[English](./README.en.md) | [Español](./README.es.md) | [العربية](./README.ar.md) | [Français](./README.fr.md) | [Русский](./README.ru.md) | [日本語](./README.jp.md) | 简体中文

## 说明

an-cli 是 前端命令行工具，包含以下两个命令

[anl type 命令](#anl type 命令)：基于 Swagger JSON 自动生成 TypeScript 类型定义和 API 请求函数的命令行工具。

[anl lint 命令](#anl lint 命令)：生成 react 或 vue 项目 eslint、stylelint、prettier、commitLint、VSCode相关配置

## 功能特点

- `anl type`

  - 🚀 自动解析 Swagger JSON 文档
  - 📦 生成 TypeScript 类型定义文件
  - 🔄 生成类型安全的 API 请求函数
  - 🎯 支持路径参数、查询参数和请求体
  - 📝 自动生成枚举类型定义
  - 🎨 支持代码格式化
  - ⚡️ 支持文件上传
  - 🛠 可配置的代码生成选项

- `anl lint`
  - 🔍 一键配置各种 lint 工具
  - 🎨 ESLint 配置自动化
  - 🎯Prettier 格式化配置
  - 🔄 CommitLint 提交规范
  - 📦 VSCode 编辑器配置

## 安装

> [!NOTE]
>
> 需要全局安装

```bash
$ npm install anl -g

$ yarn global add anl
```

## 使用说明

> [!TIP]
>
> 1. 如果初次使用，不清楚会产生什么结果，建议先执行命令，观察会在项目中发生什么变化，然后在结合文档，进一步修改配置，再次生成，最终达到自己理想中的样子
> 2. 或者跟着下面步骤 一步一步做，就会有收获

# anl type 命令

## 使用说明

1. 执行命令

```bash
$ anl type
```

2. 配置文件说明

- 首次执行 `anl type`, 命令，会在*项目根目录下*, _自动创建_ 以 `an.config.json` 为名的配置文件（手动创建也可以）。
- 执行 `anl type` 命令时，会找用户项目根目录下的 `an.config.json` 配置文件，并读取其配置信息，生成对应的axios封装、配置、接口列表、接口请求及响应类型
- 配置文件内的配置项是可自由修改的

3. `an.config.json`配置项示例

- 配置文件必须在项目根目录下，不可移动位置
- 配置文件名称不可更改
- 具体参数说明请看[配置项说明](#配置项说明)

```json
{
	"saveTypeFolderPath": "apps/types",
	"saveApiListFolderPath": "apps/api/",
	"saveEnumFolderPath": "apps/enums",
	"importEnumPath": "../../enums",
	"swaggerJsonUrl": "https://generator3.swagger.io/openapi.json",
	"requestMethodsImportPath": "./fetch",
	"dataLevel": "serve",
	"formatting": {
		"indentation": "\t",
		"lineEnding": "\n"
	},
	"headers": {},
	"includeInterface": [
		{
			"path": "/api/user",
			"method": "get"
		}
	],
	"excludeInterface": [
		{
			"path": "/api/admin",
			"method": "post"
		}
	]
}
```

3. 按照自己的需要更新配置文件，然后再次执行 `anl type` 命令，会依照配置文件中的指定配置信息生成，生成对应的类型信息

```bash
$ anl type
```

> [!NOTE]
>
> 如果不清楚这些配置，可以先执行 anl type 命令，将类型先生成，然后检查项目目录，结合配置项说明，调整配置项，再次生成，最终达到想要的效果

## 配置项说明

| 配置项                   | 类型                                  | 必填 | 说明                                                       |
| ------------------------ | ------------------------------------- | ---- | ---------------------------------------------------------- |
| saveTypeFolderPath       | string                                | 是   | 类型定义文件保存路径                                       |
| saveApiListFolderPath    | string                                | 是   | API 请求函数文件保存路径                                   |
| saveEnumFolderPath       | string                                | 是   | 枚举类型文件保存路径                                       |
| importEnumPath           | string                                | 是   | 枚举类型导入路径                                           |
| swaggerJsonUrl           | string                                | 是   | Swagger JSON 文档地址                                      |
| requestMethodsImportPath | string                                | 是   | 请求方法导入路径                                           |
| dataLevel                | 'data' \| 'serve' \| 'axios'          | 是   | 接口返回数据层级                                           |
| formatting               | object                                | 否   | 代码格式化配置                                             |
| headers                  | object                                | 否   | 请求头配置                                                 |
| includeInterface         | Array<{path: string, method: string}> | 否   | 需要包含的接口列表，如果设置了此项，则只会生成列表中的接口 |
| excludeInterface         | Array<{path: string, method: string}> | 否   | 需要排除的接口列表，如果设置了此项，则会排除列表中的接口   |

## 生成的文件结构

- 这个文件结构是根据配置文件生成的

```
project/
├── apps/
│   ├── types/
│   │   ├── models/          # 所有类型定义文件（不包含枚举类型）
│   │   ├── connectors/      # API 类型定义（接口定义文件）
│   │   └── enums/           # 枚举类型定义
│   └── api/
│       ├── fetch.ts         # 请求方法实现
│       └── index.ts         # API 请求函数
```

## 生成的代码示例

### 类型定义文件

```typescript
declare namespace UserDetail_GET {
	interface Query {
		userId: string;
	}

	interface Response {
		id: string;
		name: string;
		age: number;
		role: UserRole;
	}
}
```

### API 请求函数

```typescript
import { GET } from './fetch';

/**
 * 获取用户详情
 */
export const userDetailGet = (params: UserDetail_GET.Query) => GET<UserDetail_GET.Response>('/user/detail', params);
```

## 特性说明

### 类型解析

- 支持所有 OpenAPI 3.0 规范的数据类型
- 自动处理复杂的嵌套类型
- 支持数组、对象、枚举等类型
- 自动生成接口注释

### 文件上传

当检测到文件上传类型时，会自动添加对应的请求头：

```typescript
export const uploadFile = (params: UploadFile.Body) =>
	POST<UploadFile.Response>('/upload', params, {
		headers: { 'Content-Type': 'multipart/form-data' },
	});
```

### 错误处理

工具内置了完善的错误处理机制：

- 解析错误提示
- 类型生成失败警告
- 文件写入异常处理

### 接口过滤

工具支持通过配置来过滤需要生成的接口：

1. 包含特定接口

   - 通过 `includeInterface` 配置项指定需要生成的接口
   - 只会生成配置中指定的接口
   - 配置格式为包含 `path` 和 `method` 的对象数组

2. 排除特定接口
   - 通过 `excludeInterface` 配置项指定需要排除的接口
   - 会生成除了配置中指定接口之外的所有接口
   - 配置格式为包含 `path` 和 `method` 的对象数组

示例配置：

```json
{
	"includeInterface": [
		{
			"path": "/api/user",
			"method": "get"
		}
	],
	"excludeInterface": [
		{
			"path": "/api/admin",
			"method": "post"
		}
	]
}
```

注意：`includeInterface` 和 `excludeInterface` 不能同时使用，如果同时配置，会优先使用 `includeInterface`。

## 开发

```bash
# 安装依赖
npm install

# 开发模式
按 F5 进行调试

# 构建
npm run build

# 本地链接调试
npm run blink
```

## 注意事项

1. 确保 Swagger JSON 文档地址可访问
2. 配置文件中的路径需要是相对于项目根目录的路径
3. 生成的文件会覆盖已存在的同名文件
4. 建议将生成的文件加入版本控制

## 常见问题

1. 生成的类型文件格式化失败

   - 检查是否安装了 prettier
   - 确认项目根目录下是否有 prettier 配置文件

2. 请求函数导入路径错误
   - 检查 requestMethodsImportPath 配置是否正确
   - 确认请求方法文件是否存在

# anl lint 命令

### 功能概述

提供一键配置前端项目各种 lint 工具的功能，包括：

- ESLint 代码检查
- Prettier 代码格式化
- CommitLint 提交信息规范
- VSCode 编辑器配置

### 使用方法

```bash
$ anl lint
```

### 配置详情

#### 1. ESLint 配置

- 自动安装所需依赖
- 支持 React/Vue 框架
- 自动生成 `.eslintrc.js` 和 `.eslintignore`
- 集成 TypeScript 支持

#### 2. Prettier 配置

- 自动安装 prettier 相关依赖
- 生成 `.prettierrc.js` 配置文件
- 默认配置包括：
  - 行宽：80
  - Tab 缩进
  - 使用单引号
  - 箭头函数括号
  - 其他代码风格规范

#### 3. CommitLint 配置

- 安装 commitlint 相关依赖
- 配置 husky git hooks
- 生成 `commitlint.config.js`
- 规范化 git commit message

#### 4. VSCode 配置

- 创建 `.vscode/settings.json`
- 配置编辑器自动格式化
- 设置默认格式化工具
- 支持已有配置文件更新

# 许可证

ISC License

# 贡献指南

欢迎提交 [Issue](https://github.com/bianliuzhu/an-cli/issues) 和 [Pull Request](https://github.com/bianliuzhu/an-cli/pulls)！