Integ Docs | API

Appearance

Git Workflow и Husky ​

Описание Git workflow, автоматизированных проверок (hooks) и процесса коммитов.

Обзор ​

Проект использует Husky для автоматизации проверок перед коммитами и пушами. Это обеспечивает консистентность кода и предотвращает попадание ошибок в репозиторий.

mermaid
flowchart LR
    A["Редактирование кода"] --> B["git add"]
    B --> C["git commit"]
    C --> D["pre-commit hook"]
    D -->|Ошибки| E["Исправить и повторить"]
    D -->|OK| F["Коммит создан"]
    F --> G["git push"]
    G --> H["pre-push hook"]
    H -->|Ошибки| I["Исправить и повторить"]
    H -->|OK| J["Push успешен"]

Pre-Commit Hook ​

Выполняется при git commit, проверяет и модифицирует staged файлы.

Этапы ​

bash
# 1. Удаление комментариев
npm run removeComments:staged

Удаляет все комментарии из TypeScript файлов перед коммитом.

bash
# 2. Удаление return types
npm run removeReturnTypes:staged

Удаляет явные типы возвращаемых значений (TypeScript сам выведет).

bash
# 3. Форматирование Prettier
npx pretty-quick --staged

Переформатирует staged файлы согласно Prettier конфигурации.

bash
# 4. ESLint проверка
npx lint-staged

Запускает ESLint на staged файлах и автоматически исправляет возможные ошибки.

Пример выполнения ​

bash
$ git commit -m "feat: add new feature"

# Husky запускает pre-commit hook...
npm run removeComments:staged   # ✓
npm run removeReturnTypes:staged # ✓
npx pretty-quick --staged        # ✓
npx lint-staged                  # ✓

# Коммит создан успешно!

Если ошибки ​

bash
$ git commit -m "feat: add new feature"

# ...
npx lint-staged

# ✘ ESLint ошибка на lines 10-15
# Автоматическое исправление...
# ✓ Исправлено

# Вам нужно добавить изменения и повторить коммит
$ git add .
$ git commit -m "feat: add new feature"
# ... теперь OK

Pre-Push Hook ​

Выполняется при git push, проверяет всё приложение перед отправкой.

Этапы ​

bash
# 1. TypeScript проверка типов
npm run typecheck

Проверяет все TypeScript файлы на ошибки типизации.

bash
# 2. ESLint полная проверка
npm run lint

Полная проверка всего кода ESLint (не только staged файлы).

bash
# 3. Тестовая сборка
npm run build:dev

Проверяет, что приложение собирается без ошибок.

Пример выполнения ​

bash
$ git push origin feature-branch

echo "Running pre-push checks..."

echo "TypeScript type check..."
npm run typecheck              # ✓

echo "Linting code..."
npm run lint                   # ✓

echo "Testing build..."
npm run build:dev              # ✓

echo "All checks passed!"

# Push успешен!

Если ошибки ​

bash
$ git push origin feature-branch

echo "Running pre-push checks..."

echo "TypeScript type check..."
npm run typecheck              # ✘ Error TS2322 on line 45

# Push отменен!
# Исправьте ошибку, коммитьте и повторите push

Конфигурация Husky ​

Инициализация ​

bash
# Первый раз (при клонировании)
npm run prepare  # Инициализирует Husky

Структура ​

.husky/
├── _/                    # Внутренние файлы Husky
├── pre-commit            # Pre-commit hook
└── pre-push              # Pre-push hook

Pre-commit файл ​

bash
#!/bin/sh
npm run removeComments:staged
npm run removeReturnTypes:staged
npx pretty-quick --staged
npx lint-staged

Pre-push файл ​

bash
#!/bin/sh
echo "Running pre-push checks..."

echo "TypeScript type check..."
npm run typecheck || exit 1

echo "Linting code..."
npm run lint || exit 1

echo "Testing build..."
npm run build:dev || exit 1

echo "All checks passed!"

Workflow разработчика ​

1. Создание фичи ​

bash
git checkout -b feature/my-feature

2. Редактирование кода ​

bash
# Редактируете файлы...
code src/app/users/users.service.ts

# Проверка локально
npm start

# Проверка линтера
npm run lint:fix

3. Коммит ​

bash
git add .
git commit -m "feat: add user activation"

# Husky автоматически:
# ✓ Удалит комментарии
# ✓ Удалит return types
# ✓ Переформатирует (Prettier)
# ✓ Проверит ESLint
# ✓ Создаст коммит

# Если ошибки - исправьте и повторите:
# git add .
# git commit -m "feat: add user activation"

4. Push ​

bash
git push origin feature/my-feature

# Husky автоматически:
# ✓ Проверит TypeScript
# ✓ Запустит ESLint на всем коде
# ✓ Соберет приложение
# ✓ Отправит на сервер

# Если ошибки - исправьте локально:
# npm run lint:fix
# npm run typecheck
# git add .
# git commit -m "fix: resolve linting issues"
# git push origin feature/my-feature

5. Pull Request ​

После push можно создать Pull Request в GitHub/GitLab.

Полезные команды ​

Пропустить hook (НЕ рекомендуется!) ​

bash
# Пропустить pre-commit
git commit --no-verify -m "feat: skip checks"

# Пропустить pre-push
git push --no-verify

Исправление последнего коммита ​

bash
# Добавить изменения в последний коммит
git add .
git commit --amend --no-edit

# Изменить сообщение коммита
git commit --amend -m "feat: new message"

Просмотр истории ​

bash
# Логмосмотр со всеми деталями
git log --oneline --graph --all

# Показать последние 10 коммитов
git log -10

Troubleshooting ​

Husky не запускается ​

Проблема: Hooks не выполняются при коммите

Решение:

bash
# Переинициализировать Husky
npm run prepare

# Или явно включить permissions
chmod +x .husky/pre-commit
chmod +x .husky/pre-push

ESLint ошибки не исправляются ​

Проблема: lint-staged не может автоматически исправить

Решение:

bash
# Исправить вручную
npm run lint:fix

# Добавить и повторить коммит
git add .
git commit -m "feat: fix linting issues"

TypeScript ошибки при pre-push ​

Проблема: Push отменяется из-за типов

Решение:

bash
# Проверить ошибки
npm run typecheck

# Исправить их в коде

# Коммитить исправления
git add .
git commit -m "fix: resolve TypeScript errors"

# Повторить push
git push origin feature-branch

Build ошибки при pre-push ​

Проблема: npm run build:dev падает

Решение:

bash
# Локально протестировать сборку
npm run build:dev

# Исправить ошибки

# Коммитить исправления
git add .
git commit -m "fix: resolve build errors"

# Повторить push
git push origin feature-branch

Best Practices ​

✅ Правильно ​

  1. Регулярные коммиты - Коммитьте часто, небольшие логичные chunks
  2. Описательные сообщения - feat: add user auth вместо update code
  3. Исправляйте локально - Запускайте npm run lint:fix перед коммитом
  4. Уважайте hooks - Не пропускайте их с --no-verify

❌ Неправильно ​

  1. Большие коммиты - Избегайте коммитов с 100+ изменениями
  2. Неясные сообщения - fix или update без деталей
  3. Пропуск проверок - git commit --no-verify
  4. Игнорирование ошибок - Не исправляйте ошибки ESLint/TypeScript

Commit Message Format ​

Рекомендуемый формат:

<type>(<scope>): <subject>

<body>

<footer>

Типы ​

  • feat - Новая фича
  • fix - Исправление бага
  • docs - Документация
  • style - Форматирование, отсутствующие точки с запятой и т.д.
  • refactor - Рефакторинг кода
  • perf - Улучшение производительности
  • test - Добавление или обновление тестов
  • chore - Изменения конфигурации, зависимостей

Примеры ​

feat(auth): add JWT token refresh mechanism

Implement automatic token refresh when token expires.
Adds refresh_token to login response.

Closes #123
fix(integrations): handle network timeout in gateway service

Previously gateway service would hang indefinitely on network timeout.
Now properly catches timeout errors and returns null.
docs(architecture): update module documentation

Updated modules.md with current architecture.
Added business logic flows.

Следующие шаги ​