# an-cli

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

## Описание

an-cli - это инструмент командной строки для фронтенд-разработки, включающий следующие две команды:

[Команда anl type](#команда-anl-type): Инструмент командной строки для автоматической генерации определений типов TypeScript и функций запросов API на основе Swagger JSON.

[Команда anl lint](#команда-anl-lint): Генерирует конфигурации eslint, stylelint, prettier, commitLint и VSCode для проектов React или Vue.

## Особенности

- `anl type`

  - 🚀 Автоматический разбор документации Swagger JSON
  - 📦 Генерация файлов определения типов TypeScript
  - 🔄 Генерация типобезопасных функций запросов API
  - 🎯 Поддержка параметров пути, запроса и тела запроса
  - 📝 Автоматическая генерация определений перечислений
  - 🎨 Поддержка форматирования кода
  - ⚡️ Поддержка загрузки файлов
  - 🛠 Настраиваемые параметры генерации кода

- `anl 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                                | Да           | URL документации 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. Убедитесь, что URL документации Swagger JSON доступен
2. Пути в файле конфигурации должны быть относительно корневой директории проекта
3. Генерируемые файлы перезапишут существующие файлы с тем же именем
4. Рекомендуется добавить генерируемые файлы в систему контроля версий

## Часто задаваемые вопросы

1. Не удается отформатировать сгенерированные файлы типов

   - Проверьте, установлен ли prettier
   - Убедитесь, что в корневой директории проекта есть файл конфигурации prettier

2. Ошибка в пути импорта функций запроса
   - Проверьте правильность настройки requestMethodsImportPath
   - Убедитесь, что файл с методами запроса существует

# Команда anl lint

### Обзор функциональности

Предоставляет возможность настройки различных инструментов линтинга для фронтенд-проекта одной командой, включая:

- Проверка кода с ESLint
- Форматирование кода с Prettier
- Стандартизация сообщений коммитов с CommitLint
- Настройка редактора VSCode

### Использование

```bash
$ anl lint
```

### Подробности конфигурации

#### 1. Конфигурация ESLint

- Автоматическая установка необходимых зависимостей
- Поддержка фреймворков React/Vue
- Автоматическая генерация `.eslintrc.js` и `.eslintignore`
- Интеграция с TypeScript

#### 2. Конфигурация Prettier

- Автоматическая установка зависимостей prettier
- Генерация файла конфигурации `.prettierrc.js`
- Стандартные настройки включают:
  - Ширина строки: 80
  - Отступы табуляцией
  - Использование одинарных кавычек
  - Скобки для стрелочных функций
  - Другие правила форматирования кода

#### 3. Конфигурация CommitLint

- Установка зависимостей commitlint
- Настройка git hooks с помощью husky
- Генерация `commitlint.config.js`
- Стандартизация сообщений git commit

#### 4. Конфигурация VSCode

- Создание `.vscode/settings.json`
- Настройка автоматического форматирования
- Установка инструмента форматирования по умолчанию
- Поддержка обновления существующих конфигураций

# Лицензия

ISC License

# Руководство по содействию

Приветствуются [Issue](https://github.com/bianliuzhu/an-cli/issues) и [Pull Request](https://github.com/bianliuzhu/an-cli/pulls)!