anl

# 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)!