Настройка проекта TypeScript с нуля

внешний интерфейс TypeScript

предисловие

Эта статьяАлгоритмы и реализация TypeScriptПредставьте общий процесс настройки среды проекта TypeScript. В основном он включает следующее содержимое конфигурации:

  • Git Commit Message
  • TypeScript
  • ESLint
  • Prettier
  • Lint Staged
  • Jest
  • Npm Script Hook
  • Vuepress
  • Github Actions

Если вы хорошо знакомы с некоторыми из приведенных выше конфигураций, вы можете пропустить чтение. Если вы не уверены, стоит ли продолжать чтение некоторой информации о конфигурации, вы можете передатьИнженерные проблемычтобы решить, продолжать ли читать соответствующий контент.

Алгоритмы и реализация TypeScriptМодификация текущей конфигурации находится вfeat/frameworkНа ветке я надеюсь, что студенты, которым просто интересно, могут запустить волну.учебная документацияЭто по-прежнему старая версия учебного документа, и в будущем она будет постоянно обновляться.

Советы: Если вы хотите создать простую и удобную в использовании библиотеку функций инструмента на основе TypeScript в своем проекте, вы можете использовать некоторые зрелые скаффолдинги с нулевой конфигурацией, такие какtsdx,microbundleтак же какtypescript-starterЖдать. Если функция не соответствует потребностям вашего проекта, вы также можете настроить команду на основе этих инструментов, таких какts-lib-scripts.

проблема конфигурации

Я надеюсь, что вы сможете понять некоторые из следующих вопросов после прочтения этой статьи (вероятно, это станет вопросом интервью в инженерной конфигурации, детали определяют успех или неудачу):

  • Как стандартизировать инструкции Git по фиксации (информация о фиксации) при использовании Git?
  • Кратко опишите структуру спецификации фиксации, которая соответствует спецификации Angular?
  • Как информация о фиксации связана с проблемами Github?
  • Как создать журнал версий при разработке некоторых пакетов библиотек?
  • Как TypeScript автоматически генерирует файлы объявлений для пакетов библиотек?
  • Использует ли TypeScript в настоящее время TSLint или ESLint для проверки кода и почему?
  • Перечислите все инструменты сборки, которые вы знаете, и расскажите об их плюсах и минусах? Как следует выбирать эти строительные инструменты в различных сценариях?
  • Каковы ограничения поддержки TypeScript в Babel?
  • Перечислите известные вам функции ESLint?
  • Как я могу убедиться, что я создаю и загружаю код без сообщений об ошибках ESLint?
  • В чем разница между Эсвет и красивее? Будет ли проблема, когда две работают вместе?
  • Какие два типа правил проверки есть в линтерах?
  • Как эффективно определить правила формата, которые могут конфликтовать между ESLint и Prettier? Как решить такие конфликты правил?
  • Какова роль git hook в проекте?
  • Каковы функции клиентских и серверных хуков в git hook?
  • Какие хуки обычно используются в git hook?
  • pre-commitа такжеcommit-msgВ чем разница между крючками? Для чего можно использовать каждый?
  • Каков принцип создания git-хуков с помощью таких инструментов, как husky и gook?
  • Как разработать общий git-хук?
  • Можно ли разрабатывать git-хуки с помощью сценариев Node? Как это сделать?
  • Какова функция lint-staged?
  • В чем разница между пользователем и рабочей областью в конфигурации VS Code?
  • Могут ли плагины VS Code действовать только в текущем проекте?
  • Расскажите, что вы понимаете в скриптах npm, какие у него функции?
  • Какие типы тестов вы знаете о тестировании?
  • Какие фреймворки для тестирования вы знаете?
  • Что такое e2e-тест? Какие существуют тестовые фреймворки для e2e?
  • Теперь предположим, что существует алгоритм сортировки вставками, как я могу провести модульное тестирование этого алгоритма?
  • Предположим, вы реализуете библиотеку компонентов React или Vue для разработки демонстрационного документа. Как бы вы ее разработали? Какие функции должны выполнять разработанные документы?
  • Как вы разрабатывали документацию по API при разработке пакета инструментов?
  • Как ESLint печатает в реальном времени ошибку проверки при обновлении тепла (горячая замена модуля) в обычном проекте строительных лесов?
  • Каковы особенности Vuepress?
  • Какие инструменты CI/CD вы знаете? Сталкивались ли вы с подобным процессом в проекте?
  • В чем разница между CI и CD?
  • Каковы характеристики Github Actions?

Кроме того, если вас интересуют другие сопутствующие знания (не связанные с этой статьей), я надеюсь, что вы сможете продолжить изучение:

  • Характерные функции?
  • В чем разница между CommonJS и модулем ES?
  • Что делает встряска дерева? Когда я могу использовать способность Tree Shake?
  • Как импортировать пакет библиотеки модуля ES? Какие аспекты следует учитывать на уровне сборки и на уровне файла описания пакета?
  • Расскажите о своем понимании файлов объявлений TypeScript? Как идентифицировать файл объявления извне при создании пакета библиотеки? Каковы преимущества при наружном использовании?
  • Как учитывать элегантный дизайн введения по запросу и полное введение при создании наборов инструментов?
  • Какие способы создания библиотек инструментов вы знаете?
  • Особенности Vue CLI 3.x понимание этого? Как на основе Vue CLI 3.x адаптироваться к командным проектам?
  • Знаешь реактивные скрипты?
  • Какие этапы проектирования можно включить в проектирование поля инженерной конфигурации (например, разница между react-scripts и vue ui в дизайне и паттернах использования)?
  • Мониторинг инженерной конфигурации (использование информации о версии, анализ отчетов об ошибках совместимости версий, использование функционального анализа и т. д.)?

Советы: На некоторые вопросы можно ответить в этой статье, а на некоторые вопросы можно ответить, прочитав или просмотрев исходный код самостоятельно (автор тоже новичок в области инженерной настройки, и вышеперечисленные вопросы тоже задают себе).

структура конфигурации

Следует отметить, что в инструкциях по настройке в документе могут быть опущены некоторые подробные шаги (такие как установка некоторых зависимых пакетов npm, описания некоторых файлов конфигурации и т. д.) Если вы хотите узнать больше подробностей, вы можете просмотреть отправку Commit. информация о каждой конфигурации:

  • Инициализация проекта (afaa458)
  • framework:Добавлена ​​возможность фиксации спецификации Git Commit Message (d04e259)
  • framework:Добавлена ​​возможность компилировать TypeScript (ebecee9)
  • framework:Добавлена ​​возможность проверки кода ESLint (dca67d4)
  • framework:Добавлена ​​возможность автоматического форматирования Prettier (7f3487a)
  • framework:Добавлена ​​возможность проверки поэтапной загрузки Lint (b440186)
  • framework:Добавлены возможности модульного тестирования Jest (6f086f2)
  • framework:Добавлена ​​возможность перехвата скриптов Npm (93e597a)
  • framework:Добавлены возможности презентации Vuepress (66e38d1)
  • framework:Добавлена ​​возможность действий Github (1cc85a4)

Советы: Все вышеперечисленное используетсяnpm run changelogАвтоматически сгенерированная информация журнала версий, вы также можете передать репозиторийCHANGELOG.mdсмотреть.

Git Commit Message

CommitizenЭто инструмент CLI, который конкретно подал Git, как настроитьВведение в использование набора инструментов Cz(Эта статья была очень подробной и ясной о настройке Commit Message, поэтому я не буду здесь слишком подробно рассказывать об этом). В основном в этом проекте используются следующие инструменты:

После настройки выдаются следующие функции:

  • использоватьgit czзаменятьgit commitОтправить информацию о сообщениях, которая соответствует угловой спецификации
  • Код будет передан перед отправкойhuskyСотрудничайте с git hook, чтобы проверить информацию о представлении.Если информация о представлении не соответствует спецификации Angular, представление не будет выполнено.
  • воплощать в жизньnpm run changelogбудет автоматически сгенерирован в корневом каталогеCHANGELOG.mdЖурнал версий

Советы: хаски означает хаски на китайском языке, вы можете себе представить, почему этот инструмент называется хаски, означает ли это, что он вас укусит (или больше 🐶 гав!), как только он укусит ваш код и отправит его, это будет очень интересная вещь, в последующей настройке инструмента мы еще встретимся с лайкой, чтобы посмотреть, что она будет кусать!

Например, когда вы отправляете сообщение фиксации, которое не соответствует спецификации (в настоящее время отправка завершается неудачно):

PS C:\Code\Git\algorithms> git commit -m "这是一个不符合规范的 Commit Message"
husky > commit-msg (node v12.13.1)
⧗   input: 这是一个不符合规范的 Commit Message
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky > commit-msg hook failed (add --no-verify to bypass)

Советы: Если вы не знаете, что такое CLI (интерфейс командной строки), ознакомьтесь с ним.Публикуйте с помощью NPM и используйте инструменты CLI.

TypeScript

Фон TypeScript

В реализации библиотеки функций инструмента используется TypeScript.Помимо автоматического создания файлов объявления ts для улучшения внешних подсказок, он также позволяет избежать некоторых непредсказуемых сообщений об ошибках, вызванных динамической природой JavaScript (подробности см.Top 10 JavaScript errors from 1000+ projects (and how to avoid them)), что делает дизайн алгоритма более строгим. Существует множество способов сборки TypeScript, в дополнение к собственному компилятору tsc он также включает Webpack, Rollup, Babel, Gulp и т. д. (Дополнительную информацию об интеграции инструментов сборки см.Integrating with Build Tools):

  • Webpack в основном используется для модульного построения страничных приложений.Использование Webpack для сборки увеличит размер библиотеки сборки.Поэтому использование Webpack для производства простых библиотек инструментов - это полностью "убийство цыплят".
  • Rollup — очень хороший легкий выбор для создания библиотек инструментов, он содержитTree Shakingи построитьES ModuleЕго особенности делают его широко используемым tsdx, microbundle и даже Vue.
  • Для использования Babel TypeScript@babel/preset-typescriptУдалите теги типов TypeScript, но не выполняйте проверку компиляции типов.Дополнительную информацию об ограничениях Babel на поддержку TypeScript см.@babel/plugin-transform-typescript - CaveatsилиBabel 7 or TypeScript.
  • Gulp — это очень легкий инструмент сборки, а также официально рекомендуемый инструмент сборки для TypeScript.TypeScript - Building, можно посмотреть простую конфигурацию GulpTypeScript — Глоток.

Поскольку библиотека функций алгоритма очень проста и проста, ее можно собрать с помощью инструмента Gulp, официально рекомендованного TypeScript.

Советы: Дополнительные инструменты сборки, о которых нужно узнатьesbuild,parcelтак же какbackpackЖдать. Конечно, если вы хотите узнать больше о различиях между этими инструментами сборки и о том, как их выбрать в какой среде проекта, вы можете сами поискать сравнение или различие инструментов сборки фронтенда, Вот статья, которую я лично думаю, хорошо резюмирует.Фронтальная конструкция: справочник по выбору 13 популярных инструментов в 3 категориях.

Конфигурация TypeScript

Этот проект создаст и выведет набор инструментов CommonJS (пакет npm) для внешнего использования.Использование TypeScript для разработки и вывода файла декларации поможет внешним лучше использовать пакет ресурсов для запросов API. Компиляция TypeScript использует инструмент Gulp, рекомендованный официальной документацией, и сотрудничает сgulp-typescriptа такжеtsconfig.jsonконфигурационный файл. Создайте новый в корневом каталогеtsconfig.jsonфайл и добавьте следующую конфигурацию:

{
  "compilerOptions": {
    // 指定 ECMAScript 目标版本 "ES3"（默认）， "ES5"， "ES6" / "ES2015"， "ES2016"， "ES2017" 或 "ESNext"。
    "target": "ES5",
    // 构建的目标代码删除所有注释，除了以 /!* 开头的版权信息
    "removeComments": true,
    // 可配合 gulp-typescript 生成相应的 .d.ts 文件
    "declaration": true,
    // 启用所有严格类型检查选项。启用 --strict 相当于启用 --noImplicitAny, --noImplicitThis, --alwaysStrict， --strictNullChecks, --strictFunctionTypes 和 --strictPropertyInitialization
    "strict": true,
    // 禁止对同一个文件的不一致的引用
    "forceConsistentCasingInFileNames": true,
    // 报错时不生成输出文件
    "noEmitOnError": true
  }
}

Советы: здесь ничего новогоmoduleИнформация о конфигурации, поскольку спецификация CommonJS выводится по умолчанию, можно просмотреть дополнительную информацию о конфигурации TypeScript.Официальная документация TypeScript / Параметры компиляции. Если разница между модулями CommonJS и ES не ясна, вот вам очень хорошая документация:ES modules: A cartoon deep-dive,ES6 modules. Если вы хотите узнать, как предоставить внешний модуль ES MOSSpkg.module.

При этом создайте новый в корневом каталогеgulpfile.jsдокумент:

const gulp = require("gulp");
const ts = require("gulp-typescript");
const tsProject = ts.createProject("tsconfig.json");

// 输出 CommonJS 规范到 dist 目录下
gulp.task("default", function () {
  const tsResult = tsProject.src().pipe(tsProject());
  return tsResult.js.pipe(gulp.dest("dist"));
});

существуетpackage.jsonДобавлен скрипт скрипта npm для:

"scripts": {
  "build": "rimraf dist && gulp"
},

вrimfafдля очистки перед строительствомdistСодержимое файла каталога. в это время вsrcДобавьте исходный код TypeScript в каталог и используйте егоnpm run buildКоманда может собрать проект и вывести объектный код спецификации CommonJS вdistПод содержанием.

Кроме того, этот проект надеется быстро сгенерировать файл объявления для запроса внешнего кода, и вы все еще можете использоватьgulp-typescriptИнструмент автоматически генерирует файлы объявлений. существуетgulpfile.jsДобавлена ​​следующая конфигурация в

const gulp = require("gulp");
const ts = require("gulp-typescript");
const tsProject = ts.createProject("tsconfig.json");
const merge = require("merge2");

// 输出 CommonJS 规范到 dist 目录下
gulp.task("default", function () {
  const tsResult = tsProject.src().pipe(tsProject());

  return merge([
    tsResult.dts.pipe(gulp.dest("types")),
    tsResult.js.pipe(gulp.dest("dist")),
  ]);
});

Исправлятьbuildкоманда, чтобы сделать его одновременно удаляемым перед сборкойtypesсодержание:

"scripts": {
  "build": "rimraf dist types && gulp",
},

выполнить сноваnpm run buildбудет сгенерирован в корневом каталоге проектаtypesПапка, в которой в основном хранятся автоматически сгенерированные файлы объявлений TypeScript.

Следует отметить, что при публикации npm-пакета по умолчанию будут опубликованы все файлы текущего проекта, но есть надежда, что опубликованный пакет будет содержать только скомпилированные файлы, необходимые пользователям.distа такжеtypes, так что можно пройтиpackage.jsonсерединаfiles(используется для указания того, какие файлы включены в опубликованный пакет npm) информация поля для управления:

"files": [
  "dist",
  "types"
],

Советы: некоторые файлы в опубликованных пакетах npm будут игнорироваться.filesКонфигурация полевой информации, включаяpackage.json,LICENSE,README.mdЖдать.

В дополнение к этому, если вы хотите, чтобы опубликованный пакет npm прошелrequire('algorithms-utils')илиimportУкажите, когда форма вводитсяdist/index.jsфайл, который необходимо настроитьpackage.jsonсерединаmainПолевая информация:

"main": "dist/index.js"

Советы: Не рекомендуется использовать метод полного импорта для инструментария, его можно импортировать по запросу с помощью определенных методов инструмента.

ESLint

ESLint Фон

Инструменты проверки кода TypeScript в основном включают TSLint и ESLint. Ранние проекты TypeScript обычно использовали TSLint для проверки. TSLint и TypeScript используют для компиляции один и тот же формат AST, но основная проблема в том, что проект поддерживает экосистему JavaScript недостаточно дружелюбно, поэтому команда TypeScript объявила о полном переходе на ESLint в 2019 году (подробности см. официальный репозиторий TypeScript..eslintrc.jsonконфигурация), больше причин для перехода на ESLint можно найти здесь:

TypeScript и ESLint используют разные AST для синтаксического анализа, поэтому для поддержки проверки кода TypeScript в ESLint необходимо сделать дополнительныепользовательский парсер(Пользовательские парсеры, функциональные возможности пользовательского парсера ESLint должны основываться наESTree), чтобы иметь возможность анализировать синтаксис TypeScript и превращать его в AST, совместимый с ESLint.@typescript-eslint/parserРожденный в этом контексте, он обрабатывает все специфичные для ESLint настройки и вызовы.@typescript-eslint/typescript-estreeСгенерируйте ASTree-совместимый AST (обратите внимание, что он совместим не только с ESLint, но и с Prettier).

@typescript-eslintпринимаетLernaРепозиторий структуры Monorepo для проектирования, в дополнение к упомянутым выше пакетам npm, также содержит следующие два важных пакета npm:

Советы: Если вы используете TSLint и хотите обеспечить совместимость с ESLint или перейти на ESLint (сосуществуют TSLint и ESLint), см.Migrating from TSLint to ESLint. Кроме того, описанные выше пакеты выпущены в одной версии (для совместимости при совместном использовании), и требуют дополнительного внимания.@typescript-eslintДополнительные сведения о поддержке версий TypeScript и ESLint см. в репозитории @typescript-eslint/parser.

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

Как можно понять из вводной информации, для совершенно нового проекта TypeScript (напрямую отказывающегося от TSLint) необходимо включить парсер @typescript-eslint/parser, который анализирует AST, и плагин @typescript-eslint/eslint-plugin, который использует правила проверки.Установить в проекте:

npm i --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Новое в корневом каталоге.eslintrc.jsconfig и задайте следующую конфигурацию:

module.exports = {
  root: true,
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
};

в:

  • parser: '@typescript-eslint/parser': Анализ синтаксиса TypeScript с помощью ESLint.
  • plugins: ['@typescript-eslint']: Загрузить плагин в ESLint@typescript-eslint/eslint-plugin, который можно использовать для настройки правил проверки TypeScript.
  • extends: [ ... ]: используется в ESLintОбщая конфигурация правила,вeslint:recommendedрекомендуемая конфигурация правила проверки, встроенная в ESLint (также известная как лучшая практика правил),plugin:@typescript-eslint/recommendedпохоже наeslint:recommendedTypeycript рекомендуется конфигурация правил валидации.

Советы: Если вы немного прочитаете рекомендуемый исходный код, вы обнаружите, что внутреннее устройство можно понимать как набор рекомендуемых правил проверки. Итак, если вы хотите, чтобы база@typescript-eslint/eslint-pluginДля пользовательских правил вы можете обратиться кTypeScript Supported Rules.

После завершения настройкиpackage.jsonУстановите команду проверки в

"scripts": {
  "lint": "eslint src",
}

Если в это времяsrcНеправильный синтаксис написан в каталоге, выполнитьnpm run lintБудет выведено сообщение об ошибке:

> eslint src


C:\Code\Git\algorithms\src\greet.ts
  2:16  warning  Missing return type on function  @typescript-eslint/explicit-module-boundary-types

✖ 1 problem (0 errors, 1 warning)

Советы: сообщения об ошибках выводятсяESLint FormattersСгенерируйте, просмотрите исходный код ESLint и выполните отладку, чтобы обнаружить, что значение по умолчаниюstylish formatter.

Плагин ESLint

Без использования плагинов сложно обнаружить, что в коде могут быть ошибки форматирования TypeScript, потому что при написании кода помимо ручного выполненияnpm run lintНет оперативной информации в режиме реального времени, кроме (конечно, вы также можетеgulpОтслеживайте изменения файлов и выполняйтеnpm run lint). Чтобы видеть сообщения об ошибках TypeScript в режиме реального времени, вы можете обрабатывать их с помощью плагина VS Code. После установки плагина ESLint код может запрашиваться в режиме реального времени, как показано на следующем рисунке:

Конечно, чтобы информация о проверке не появлялась в файлах, которые не нуждаются в проверке, можно передать.eslintignoreфайл для конфигурации (например, ниже приведены некоторые файлы конфигурации, не требующие проверки формата):

# gulp
gulpfile.js

# eslint
.eslintrc.js

# commitizen
commitlint.config.js

# jest
jest.config.js

# build
dist

В этот момент можно обнаружить, что предыдущее выполнениеlintОшибки команд могут отображаться в режиме реального времени в редакторе VS Code в виде плагина. Кроме того, некоторые ошибки проверки формата ESLint (такие как;и т. д.) можно автоматически отформатировать, настроив Save Auto Fix. Конкретную конфигурацию кода VS см.Плагин ESLintДокументация гласит, что здесь необходимо следую конфигурацию:

"editor.codeActionsOnSave": {
  "source.fixAll": true,
  "source.fixAll.eslint": true
}

Советы: Конфигурация VS Code делится на два типа (пользовательская и рабочая область).Приведенная выше общая конфигурация в основном помещается в пользовательскую, а в рабочую область для обработки могут быть помещены разные конфигурации для разных проектов.

ESLint обеспечивает сборку

Плагин VS Code не гарантирует, что код загружается или создается без каких-либо сообщений об ошибках, и для предотвращения ошибок по-прежнему требуются дополнительные процессы. Выполнение проверки ESLint перед сборкой может гарантировать отсутствие сообщения об ошибке во время сборки.После сбоя проверки ESLint операция построения исходного кода не разрешена:

"scripts": {
  "lint": "eslint src --max-warnings 0",
  "build": "npm run lint && rimraf dist types && gulp",
}

Необходимо обратить внимание на строгий контроль верификации при построении, как только lint выдает предупреждение или ошибку, построение будет немедленно прекращено (подробности см.Код выхода ESLint).

Советы: нужно обратить внимание на оболочку в&&а также&есть разница,&&В основном используется для вторичного выполнения.Только предыдущее задание успешно выполнено, следующее задание будет выполнено.&В основном используется для одновременного выполнения, что означает, что два скрипта выполняются одновременно. Команда для сборки здесь должна подождатьlintВыполнение команды может осуществляться только после прохождения, один разlintЕсли это не удается, команда сборки больше не будет выполняться.

ESLint обеспечивает загрузку кода

Хотя сценарии проверки ESLint и подключаемые модули VS Code могут быть настроены, некоторые проверки правил ESLint не могут быть отформатированы и восстановлены с помощью автоматического исправления сохранения (например, правила качества), поэтому требуется уровень гарантии, чтобы гарантировать, что весь код будет отправлен перед отправкой. Код может пройти проверку ESLint, эта конфигурация будет объяснена в Lint Staged.

Prettier

Красивый фон

Prettier — это инструмент для единого стиля форматирования кода. Если вы не знаете, зачем вам нужно использовать Prettier, вы можете проверитьWhy Prettier?. Многие люди могут задаться вопросом, ESLint смог стандартизировать наш стиль кода, зачем нам Prettier? существуетPrettier vs LintersРазница между ними подробно описана в разделе Линтеры имеют два типа правил:

Проверка правил ESLint также включаетправила форматированияа такжеправила качества, но в большинстве случаев толькоправила форматированияв состоянии пройти--fixили функция Sava Auto Fix плагина VS Code для исправления в один клик, в то время какправила качестваЭто больше касается поиска возможных ошибок в коде для предотвращения ошибок кода, а такие правила часто нужно исправлять вручную. следовательноправила форматированияне требуется, иправила качестватребуется для. Разница между Prettier и ESLint заключается в том, что Prettier фокусируется на унифицированныхправила форматирования, тем самым смягчая ESLintправила форматирования, и дляправила качестваОставьте это профессиональному ESLint для обработки. Подводя итог, можно сказать следующее: Prettier для форматирования и линтеры для отлова ошибок (ESLint обязателен, Prettier необязателен!)

Обратите внимание, что если ESLint (TSLint) используется вместе с Prettierправила форматированияСуществуют дублирования и конфликты, которые делают ваше форматирование одним щелчком веселым при использовании Sava Auto Fix в редакторе. На этом этапе им должно быть позволено разделить правила и функции, на которых они сосредоточены, и использовать ESLint для проверки.правила качества, используя проверку Prettierправила форматирования, более подробную информацию можно посмотретьIntegrating with Linters.

Советы: при использовании ESLint в VS Code для соответствия соответствующим правилам желтая волнистая линия и красное имя файла будут генерироваться для напоминаний об ошибках. Prettier предпочитает, чтобы вы не знали о правилах форматирования, чтобы вы не чувствовали себя обремененными каким-либо использованием. Если вы хотите узнать больше о Prettier, вы также можете ознакомиться с идеями Prettier.Option Philosophy, лично думаю, что понимание дизайна продуктафилософияМожет лучше помочь вам использовать продукт.

Более красивая конфигурация

Сначала установите зависимости, необходимые Prettier:

npm i  prettier eslint-config-prettier --save-dev

в:

  • eslint-config-prettier: Он используется для решения проблем, которые легко возникают при совместном использовании ESLint и Prettier.правила форматированияПроблема конфликта, ее роль заключается в закрытии некоторых правил форматирования, настроенных в ESLint, в дополнение к закрытию@typescript-eslint/eslint-plugin,eslint-plugin-babel,eslint-plugin-react,eslint-plugin-vue,eslint-plugin-standardИ другие правила оформления.

Теоретически включение ESLint в проектextendsНабор правил с проверкой правила формата установлен в , затем вам нужно пройтиeslint-config-prettierПлагин отключает потенциально конфликтующие правила форматирования:

{
  "extends": [
    "plugin:@typescript-eslint/recommended",
    // 用于关闭 ESLint 相关的格式规则集，具体可查看 https://github.com/prettier/eslint-config-prettier/blob/master/index.js
    "prettier",
    // 用于关闭 @typescript-eslint/eslint-plugin 插件相关的格式规则集，具体可查看 https://github.com/prettier/eslint-config-prettier/blob/master/%40typescript-eslint.js
    "prettier/@typescript-eslint",
  ]
}

После завершения настройки можно пройтиИнтерфейс командной строкиБеги красивее:

"scripts": {
  "prettier": "prettier src test --write",
},

--writeАргумент похож на Eslint--fix(Все равно нужно быть осторожным при использовании этого параметра в ESLint. Рекомендуется использовать функцию Save Auto Fix VS Code), которая в основном используется для автоматического исправления ошибок формата. Код ошибки формата записи на данный момент:

import great from "@/greet";

// 中间这么多空行
export default {
  great,
};

воплощать в жизньnpm run prettierСделайте исправление формата:

PS C:\Code\Git\algorithms> npm run prettier

> algorithms-utils@1.0.0 prettier C:\Code\Git\algorithms
> prettier src test --write

src\greet.ts 149ms
src\index.ts 5ms
test\greet.spec.ts 11ms

Восстановленный формат файла выглядит следующим образом:

import great from "@/greet";

export default {
  great,
};

Обратите внимание, что если некоторые наборы правил не имеют соответствующихeslint-config-prettierЗакройте конфигурацию, тогда вы можете сначала пройтиCLI helper toolОпределяет наличие дублирующихся наборов правил форматирования, которые затем можно настроить вручную.eslintrc.jsбыть закрытым в виде:

PS C:\Code\Git\algorithms> npx eslint --print-config src/index.ts | npx eslint-config-prettier-check
No rules that are unnecessary or conflict with Prettier were found.

например поставитьeslint-config-prettierКонфигурация удаляется, а в это время проверяются повторяющиеся правила:

PS C:\Code\Git\algorithms> npx eslint --print-config src/index.ts | npx eslint-config-prettier-check
The following rules are unnecessary or might conflict with Prettier:

- @typescript-eslint/no-extra-semi
- no-mixed-spaces-and-tabs

The following rules are enabled but cannot be automatically checked. See:
https://github.com/prettier/eslint-config-prettier#special-rules

- no-unexpected-multiline

Предположим, в этот моментeslint-config-prettierНет аналогичного набора закрытых правил форматирования (например, настроенного в этом проекте).plugin:jest/recommendedМогут быть конфликты правил), тогда вы можете настроить.eslintrc.jsСама форма вручную закрывает соответствующие конфликтующие правила форматирования.

Советы: ESLint может поддерживать проверку разных правил для разных файлов, поэтому--print-configПроверка правила конфликтующего формата соответствует только одному файлу. Поскольку обычный проект представляет собой набор правил, соответствующих всему проекту, все правила для всего проекта должны только проверять, есть ли у файла конфликт правил формата.

Красивый плагин

Через интерфейс командной строки--writeФормат может быть автоматически восстановлен в виде формата, но аналогично ESLint, мы предпочитаем, чтобы проект мог автоматически форматировать код, сохраняя его при редактировании в реальном времени (призрак знает--fixтак же как--writeКакой файл в формате, я конечно надеюсь сразу воспринять изменения форматирования кода невооруженным глазом), в это время можно настроить VS CodePrettier - Code formatterПодключаемый модуль называется Save Auto Fix, и конкретную конфигурацию можно найти в документации к подключаемому модулю.

Prettier обеспечивает загрузку кода

Как и ESLint, хотя скрипт автоматического восстановления формата Prettier и подключаемый модуль VS Code могут быть настроены, он не может гарантировать пропуск формата. Поэтому необходим уровень гарантии, чтобы гарантировать, что форматирование Prettier может быть выполнено до отправки кода. Эта конфигурация будет в Lint Staged Объяснено в , также можно просмотреть дополнительные схемы конфигурацииPrettier - Pre-commit Hook.

Lint Staged

Линт постановочный фон

Используется в сообщении Git CommitcommitlintИнструмент сотрудничает с husky, чтобы предотвратить создание нерегулярных сообщений Git Commit, тем самым не позволяя пользователям отправлять неправильный код Git.Принцип заключается в отслеживании сценария выполнения Git Hook (который будет выполнять такие команды, какcommit,push,mergeВыполнить соответствующий хук скрипта до или после триггера). Git Hook на самом деле является очень полезным инструментом для ограничения проекта.Его функции включают, но не ограничиваются:

  • Спецификация Git Commit Message обеспечивает унификацию
  • Правила ESLint унифицированы, чтобы предотвратить отправку кода, не соответствующего спецификации.
  • Красивее автоматическое форматирование (аналогично формату стиля дополнительно включает стиль)
  • Отправьте стабильность кода, убедитесь, что все тестовые примеры пройдены перед отправкой
  • Отправить уведомление по электронной почте
  • Интеграция с CI (серверные хуки)

В Git Hook есть много хуков, но в клиенте часто используются следующие хуки:

  • pre-commit: в ГитpreПерехватчики серии позволяют завершить предстоящую операцию Git, в то время какpostСерия часто используется в качестве поведения уведомления.pre-commitХук набирает сообщение коммита (rungit commitилиgit cz) перед запуском, в основном используется для проверки текущего моментального снимка кода, который необходимо отправить, например пропусков отправки, тестовых случаев и кода. Git прервет коммит, если хук выйдет с ненулевым значением. Конечно, вы также можете настроить параметры командной строки.git commit --no-verifyОбход операции хука.
  • commit-msg: этот хук вызывается после того, как пользователь вводит сообщение фиксации, получая текущийCommit MessageПуть к временному файлу сообщения используется в качестве единственного параметра, поэтому этот хук можно использовать для проверки сообщения Commit Meesage (этот хук используется в Git Commit Message, чтобы проверить, соответствует ли сообщение фиксации спецификации Angular). крючок иpre-commitТочно так же выход из Git с ненулевым значением приведет к отмене фиксации.

В дополнение к вышеупомянутым часто используемым ловушкам на стороне клиента, есть две часто используемые ловушки на стороне сервера:

  • pre-receive: Хук будет получен в удаленном репозиторииgit pushВыполняется при отправке кода (обратите внимание, что это не локальный репозиторий), этот хук будет болееpre-commitБольше связывания (всегда найдется тот или иной разработчик, которому не нравится множество обнаружений, выполняемых при фиксации кода, и они могут обойти эти ловушки).pre-receiveХуки можно использовать для обеспечения канонической проверки при получении кода, если разработчик использует обходной путь.pre-commitЕсли вы отправляете кучу 💩 одного и того же кода с помощью хука, вы можете отклонить отправку кода, установив этот хук. Конечно, наиболее часто используемая операция этого хука — проверка наличия разрешения на отправку кода, небыстрое слияние вперед и т. д.
  • post-receive: Этот хук выполняется после успешной отправки кода. Он подходит для отправки уведомлений по электронной почте или запуска CI.

Советы: Для получения дополнительной информации о Git Hook вы можете проверить егоОфициальная документация Git HookилиGit Hooks: настройте свой рабочий процесс.

Следует отметить, что после инициализации Git по умолчанию используется.git/hooksКаталог для создания примеров сценариев оболочки для всех хуков Git, эти сценарии можно настроить. Для фронтенд-разработки очень недружелюбно изменять эти образцы скриптов, чтобы адаптировать их к фронтенд-проектам (большинство студентов, изучающих фронтенд-разработку, вообще не разрабатывают скрипты Shell, хотя это очень эффективно для создания инструментов), поэтому в сообществе появились подобные улучшения, они выбрасывают простые конфигурации хуков (напр.ghooksсуществуетpackage.jsonв простомНастройка свойства хука), в то время как внутри он позволяет выполнять внешние настроенные хуки, заменяя пример скрипта хука Git, например.husky, призраки иpre-commitЖдать.

Советы: Git Hook также может настраивать языковое окружение для выполнения скрипта.Например, для фронтенда, конечно, хочется использовать привычный Node для оформления скрипта.В таком случае его можно установить в шапке файла скрипта .#! /usr/bin/env nodeИспользуйте Node в качестве внешнего интерпретатора для исполняемых файлов, если вы видели его раньше.Публикуйте с помощью NPM и используйте инструменты CLIВы можете быть относительно знакомы с этим парсером среды, но вот пример с использованием интерпретатора Node:ghooks - hook.template.raw, Реализация gooks очень проста, и заинтересованные студенты могут внимательно прочитать реализацию некоторого исходного кода.

Цель введения Git Hook — дать всем ясно понять, что использование Hook может сделать много вещей во фронтенд-инжиниринговых проектах (это должно было быть представлено в Git Commit Message, но, поскольку в этом разделе цитировалась другая статья, поэтому Поместите эту информацию в этом разделе для научно-популярных).

Как упоминалось ранее, использование Git Hook можно использовать для ограничений спецификации ESLint, поэтому вы должны быть в состоянии догадаться об использованииpre-commitХуки (конечно, вам нужно использовать инструмент улучшения Git Hook, который всегда выбран в этом проектеhusky) С помощью ESLint вы можете проверить правила кода проекта перед отправкой инструкций, но если проект становится все больше и больше, время проверки ESLint может становиться все больше и больше, что может быть относительно болезненным для частых отправителей кода. поэтому можно использоватьlint-stagedИнструмент (по названию этого инструмента можно догадаться, что lint — это код, помещенный в промежуточную область Git Stage,edНа английском это сделано) для уменьшения количества инструментации кода.

Поэтапная конфигурация Lint

использоватьcommitlintИнструменты могут предотвращать создание нестандартных сообщений Git Commit, тем самым не позволяя пользователям фиксировать код Git. Однако, если вы хотите запретить разработчикам отправлять код, не соответствующий правилам ESLint, во время совместной работы, вы можете передатьlint-stagedинструменты для достижения.lint-stagedВы можете использовать ESLint для проверки информации о коде в промежуточной области Git до того, как пользователь зафиксирует код (до того, как будет сгенерирована информация Git Commit Message) (git addПосле кода модификации), если есть код 💩, который не соответствует правилам проверки, поведение отправки может быть прекращено. должен быть в курсеlint-stagedПолный код проекта не проверяется (полное вычисление контрольной суммы ESLint может быть относительно трудоемким процессом для крупных проектов), а только код добавляется в промежуточную область Git. Выполните следующую команду, чтобы автоматически сгенерировать информацию об элементе конфигурации в соответствии с официальной документацией:

npx mrm lint-staged

Следует отметить, что сгенерированный по умолчанию файл конфигурации предназначен для среды JavaScript и изменен вручную.package.jsonИнформация о конфигурации для адаптации TypeScript:

// 我们的哈士奇再次上场，这次它是要咬着你的 ESLint 不放了，这里我简称它的动作为 "咬 💩" ~~~
"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  // 这里需要注意 ESLint 脚本的 --max-warnings 0
  // 否则就算存在 warning 也不会终止提交行为
  // 这里追加了 Prettier 的自动格式化，确保代码提交之前所有的格式能够修复
  "*.ts": ["npm run lint", "npm run prettier"]
}

На этом этапе, если код, который необходимо отправить, имеет 💩 , при отправке появится сообщение об ошибке, и отправка будет принудительно прекращена:

husky > pre-commit (node v12.13.1)
[STARTED] Preparing...
[SUCCESS] Preparing...
[STARTED] Running tasks...
[STARTED] Running tasks for *.ts
[STARTED] npm run lint-strict
[FAILED] npm run lint-strict [FAILED]
[FAILED] npm run lint-strict [FAILED]
[SUCCESS] Running tasks...
[STARTED] Applying modifications...
[SKIPPED] Skipped because of errors from tasks.
[STARTED] Reverting to original state because of errors...
[SUCCESS] Reverting to original state because of errors...
[STARTED] Cleaning up...
[SUCCESS] Cleaning up...

× npm run lint-strict:
ESLint found too many warnings (maximum: 0).
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! algorithms-utils@1.0.0 lint-strict: `eslint src --max-warnings 0 "C:/Code/Git/algorithms/src/greet.ts"`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the algorithms-utils@1.0.0 lint-strict script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\子弈\AppData\Roaming\npm-cache\_logs\2020-07-11T07_25_39_102Z-debug.log

> algorithms-utils@1.0.0 lint-strict C:\Code\Git\algorithms
> eslint src --max-warnings 0 "C:/Code/Git/algorithms/src/greet.ts"


C:\Code\Git\algorithms\src\greet.ts
  2:16  warning  Missing return type on function  @typescript-eslint/explicit-module-boundary-types
  2:34  warning  Argument 'name' should be typed  @typescript-eslint/explicit-module-boundary-types

✖ 2 problems (0 errors, 2 warnings)

husky > pre-commit hook failed (add --no-verify to bypass)

хрипpackage.jsonнастроен вpre-commitа такжеcommit-msgдваГит хуки,Приоритетное использованиеpre-commitХук выполняет проверку ESLint и прекращает работу, если проверка не удалась. Если проверка прошла успешно, он продолжит выполнениеcommit-msgПроверьте сообщение GIT Commit. Например, следующее является примером прохождения проверки ESLINT, но проверка сообщений о передаче сообщений:

PS C:\Code\Git\algorithms> git commit -m "这是一个不符合规范的 Commit Message"
// pre-commit 钩子 ESLint 校验通过
husky > pre-commit (node v12.13.1)
[STARTED] Preparing...
[SUCCESS] Preparing...
[STARTED] Running tasks...
[STARTED] Running tasks for *.ts
[STARTED] npm run lint-strict
[SUCCESS] npm run lint-strict
[SUCCESS] Running tasks for *.ts
[SUCCESS] Running tasks...
[STARTED] Applying modifications...
[SUCCESS] Applying modifications...
[STARTED] Cleaning up...
[SUCCESS] Cleaning up...
// commit-msg 钩子 Git Commit Message 校验失败
husky > commit-msg (node v12.13.1)
⧗   input: 这是一个不符合规范的 Commit Message
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky > commit-msg hook failed (add --no-verify to bypass)

Jest

Тестовый фон

Если концепции и рамки тестирования не совсем ясны, вот несколько рекомендуемых статей для просмотра:

Кроме того, вот некоторые рекомендации сообщества для некоторых дополнительных советов по тестированию:

Поскольку это всего лишь модульный тест пакета библиотеки инструментов среды Node, после сравнения различных тестовых фреймворков я решил использоватьJestДля модульного теста:

  • Встроенная библиотека утверждений позволяет использовать «из коробки» (отitприбытьexpect, Шума за весь инструментарий в одном месте)
  • Тест Jest может надежно выполняться параллельно, и, чтобы обеспечить ускоренный процесс тестирования, Jest терпит неудачу до первого запуска тестовых случаев.
  • Встроенная отчетность о покрытии, дополнительная настройка не требуется
  • Отличное сообщение об ошибке

Советы: Фреймворков для фронтенд-тестирования много, по сравнению с простым юнит-тестированием e2e-тестирование будет более сложным (будь то поддержка фреймворка для тестирования и проектирование тест-кейсов). Я использовал инструмент управления тестированием Karma с Mocha для тестирования среды браузера, а также я использовал PhantomJS и Nightwatch (все они используют мех), и больше всего впечатляет использованиеtestcafeФреймворк для тестирования (комплексная официальная документация API), если вам интересно, вы также можете узнать о немcypressКаркас тестирования.

Конфигурация шутки

Модульные тесты этого проекта в основном используютJestтестовая структура. Если Jest должен поддерживать TypeScript, его можно использовать в форме Babel.Подробнее см.Jest - Using TypeScript, но использование Babel будет иметь некоторые ограничения (подробнее см.Babel 7 or TypeScript). Поскольку этот проект не использует Babel для транспиляции и надеется полностью поддерживать проверку типов, он принимаетts-jestДелайте модульные тесты. Следуйте официальному руководству по установке зависимостей и инициализации проекта:

npm install --save-dev jest typescript ts-jest @types/jest
npx ts-jest config:init

ах корневой каталогject.config.jsВнесите изменения в конфигурацию Jest в файле:

module.exports = {
  preset: "ts-jest",
  testEnvironment: "node",
  // 输出覆盖信息文件的目录
  coverageDirectory: "./coverage/",
  // 覆盖信息的忽略文件模式
  testPathIgnorePatterns: ["<rootDir>/node_modules/"],
  // 如果测试覆盖率未达到 100%，则测试失败
  // 这里可用于预防代码构建和提交
  coverageThreshold: {
    global: {
      branches: 100,
      functions: 100,
      lines: 100,
      statements: 100,
    },
  },
  // 路径映射配置，具体可查看 https://kulshekhar.github.io/ts-jest/user/config/#paths-mapping
  // 需要配合 TypeScript 路径映射，具体可查看：https://www.tslang.cn/docs/handbook/module-resolution.html
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
};

Обратите внимание, что сопоставление путей также необходимо настроить.tsconfig.jsonсерединаpathsинформацию и позаботьтесь о том, чтобы включить тестовый код в каталог сборки TypeScript. После завершения настройкиpackage.jsonНастройте тестовую команду в:

"scripts": {
  "lint": "eslint src --max-warnings 0",
  "test": "jest --bail --coverage",
  "build": "npm run lint && npm run jest && rimraf dist types && gulp",
}

Необходимо обратить внимание на эту информацию о конфигурации в Jest (дополнительную информацию о конфигурации можно просмотретьJest CLI Options):

  • bailЭффект конфигурации относительно аналогичен эффекту в ESLint.max-warnings,Установить какtrueЭто означает, что как только будет обнаружена ошибка модульного тестового примера, остальные тестовые случаи будут остановлены, чтобы предотвратить необходимость ждать завершения выполнения всех тестовых случаев, когда запущено слишком много вариантов использования.
  • coverageВ основном используется для генерации в текущем корневом каталогеcoverageОтчет о тестовом покрытии кода, который также можно загрузитьcoverallsЗначки отображаются для проектов Github.

Советы: в параметрах командной строки JestfindRelatedTestsдоступен для другаpre-commitХуки для запуска минимального количества модульных тестов, которые можно использовать сlint-stagedРеализовать функцию аналогичную ESLint, подробнее можно посмотретьlint-staged - Use environment variables with linting commands.

в текущем корневом каталогеtestновый каталогgreet.spec.tsФайл, следующий дизайн и тестовый код:

import greet from "@/greet";

describe("src/greet.ts", () => {
  it("name param test", () => {
    expect(greet("world")).toBe("Hello from world 1");
  });
});

Советы: есть два стиля размещения тестовых файлов, один новый.testпапку, а затем сосредоточить весь тестовый код вtestДругой - создать новый в каталоге того же уровня каждого файла исходного кода.__test__каталог для ближайшего теста. Большинство проектов могут иметь тенденцию использовать первую структуру каталогов (вы можете найти некоторые проекты с открытым исходным кодом на github для просмотра, здесьts-testИспользуется вторая тестовая структура). Кроме того, следует отметить, что Jest настраиваетtestMatchилиtestRegexВы можете заставить проект распознавать определенный файл формата для запуска в качестве тестового файла (этот проект использует конфигурацию по умолчанию для распознавания суффикса как.specфайл для модульного тестирования).

Jest обеспечивает сборку

в одиночку, выполнивnpm run testКоманда для выполнения модульного теста, вот модульный тест при выполнении команды сборки (все случаи модульного тестирования должны быть гарантированно пройдены до сборки). Если тест не пройден, то следует предотвратить продолжение сборки, например, с поведением неудачной сборки:

PS C:\Code\Git\algorithms> npm run build

> algorithms-utils@1.0.0 build C:\Code\Git\algorithms
> npm run lint-strict && npm run jest && rimraf dist types && gulp


> algorithms-utils@1.0.0 lint-strict C:\Code\Git\algorithms
> eslint src --max-warnings 0


> algorithms-utils@1.0.0 jest C:\Code\Git\algorithms
> jest --coverage

 PASS  dist/test/greet.spec.js
 FAIL  test/greet.spec.ts
  ● src/greet.ts › name param test

    expect(received).toBe(expected) // Object.is equality

    Expected: "Hello from world 1"
    Received: "Hello from world"

      3 | describe("src/greet.ts", () => {
      4 |   it("name param test", () => {
    > 5 |     expect(greet("world")).toBe("Hello from world 1");
        |                            ^
      6 |   });
      7 | });
      8 |

      at Object.<anonymous> (test/greet.spec.ts:5:28)

----------|---------|----------|---------|---------|-------------------
| File       | % Stmts   | % Branch   | % Funcs   | % Lines   | Uncovered Line #s   |
| ---------- | --------- | ---------- | --------- | --------- | ------------------- |
| All files  | 100       | 100        | 100       | 100       |
| greet.ts   | 100       | 100        | 100       | 100       |
| ---------- | --------- | ---------- | --------- | --------- | ------------------- |
Test Suites: 1 failed, 1 passed, 2 total
Tests:       1 failed, 1 passed, 2 total
Snapshots:   0 total
Time:        3.45 s
Ran all test suites.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! algorithms-utils@1.0.0 jest: `jest --coverage`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the algorithms-utils@1.0.0 jest script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\子弈\AppData\Roaming\npm-cache\_logs\2020-07-12T13_42_11_628Z-debug.log
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! algorithms-utils@1.0.0 build: `npm run lint-strict && npm run jest && rimraf dist types && gulp`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the algorithms-utils@1.0.0 build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\子弈\AppData\Roaming\npm-cache\_logs\2020-07-12T13_42_11_673Z-debug.log

Следует отметить, что из-за параллели (&&) выполняет скрипт, поэтому, когда выполняется команда сборки (npm run build) сначала выполнит проверку ESLint и выйдет из сборки, если проверка ESLint не пройдена, в противном случае продолжите модульное тестирование Jest. Если модульные тесты не пройдены, выйдите из сборки, только если оба проходят исходную сборку.

Jest гарантирует, что код загружен

В дополнение к предотвращению безответственной сборки кода также необходимо предотвратить безответственную фиксацию кода. Сотрудничатьlint-stagedВы можете запретить удаленную отправку кода, который не выполняет модульные тесты:

"scripts": {
  "lint": "eslint src --max-warnings 0",
  "test": "jest --bail --coverage",
},
"lint-staged": {
  "*.ts": [
    "npm run lint",
    "npm run test"
  ]
}

На этом этапе, если модульный тест неверен, отправка кода будет остановлена:

husky > pre-commit (node v12.13.1)
[STARTED] Preparing...
[SUCCESS] Preparing...
[STARTED] Running tasks...
[STARTED] Running tasks for *.ts
[STARTED] npm run lint
[SUCCESS] npm run lint
[STARTED] npm run jest
[FAILED] npm run jest [FAILED]
[FAILED] npm run jest [FAILED]
[SUCCESS] Running tasks...
[STARTED] Applying modifications...
[SKIPPED] Skipped because of errors from tasks.
[STARTED] Reverting to original state because of errors...
[SUCCESS] Reverting to original state because of errors...
[STARTED] Cleaning up...
[SUCCESS] Cleaning up...

× npm run jest:
FAIL test/greet.spec.ts
  src/greet.ts
    × name param test (4 ms)

  ● src/greet.ts › name param test

    expect(received).toBe(expected) // Object.is equality

    Expected: "Hello from world 1"
    Received: "Hello from world"

      3 | describe("src/greet.ts", () => {
      4 |   it("name param test", () => {
    > 5 |     expect(greet("world")).toBe("Hello from world 1");
        |                            ^
      6 |   });
      7 | });
      8 |

      at Object.<anonymous> (test/greet.spec.ts:5:28)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        1.339 s, estimated 3 s
Ran all test suites related to files matching /C:\\Code\\Git\\algorithms\\src\\index.ts|C:\\Code\\Git\\algorithms\\test\\greet.spec.ts/i.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! algorithms-utils@1.0.0 jest: `jest --bail --findRelatedTests --coverage "C:/Code/Git/algorithms/src/index.ts" "C:/Code/Git/algorithms/test/greet.spec.ts"`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the algorithms-utils@1.0.0 jest script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\子弈\AppData\Roaming\npm-cache\_logs\2020-07-12T14_33_51_183Z-debug.log

> algorithms-utils@1.0.0 jest C:\Code\Git\algorithms
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the algorithms-utils@1.0.0 jest script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\子弈\AppData\Roaming\npm-cache\_logs\2020-07-12T14_33_51_183Z-debug.log

> algorithms-utils@1.0.0 jest C:\Code\Git\algorithms
> jest --bail --findRelatedTests --coverage "C:/Code/Git/algorithms/src/index.ts" "C:/Code/Git/algorithms/test/greet.spec.ts"

----------|---------|----------|---------|---------|-------------------
| File       | % Stmts   | % Branch   | % Funcs   | % Lines   | Uncovered Line #s   |
| ---------- | --------- | ---------- | --------- | --------- | ------------------- |
| All files  | 0         | 0          | 0         | 0         |
| ---------- | --------- | ---------- | --------- | --------- | ------------------- |
husky > pre-commit hook failed (add --no-verify to bypass)
git exited with error code 1

Советы: Чтобы узнать больше о экологии «шума», вы можете проверить этоawesome-jest.

Whest поддержка Eslint

srcИсходный код в каталоге настроен@typescript-eslint/eslint-pluginМожно выполнить ESLint-проверку рекомендуемых правил, чтобыtestТестовый код в каталоге может выполнять проверку ESLint в соответствии с рекомендуемыми правилами Jest, которые можно настроить с помощьюeslint-plugin-jestподдерживать (ts-jestВ проекте используется этот подключаемый модуль для проверки ESLint, подробности можно просмотреть в файле конфигурации.ts-jest/.eslintrc.js), здесь по-прежнему используется рекомендуемая конфигурация правила:

module.exports = {
  root: true,
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    // 新增推荐的 ESLint 校验规则
    // 所有规则集查看：https://github.com/jest-community/eslint-plugin-jest#rules（recommended 标识表明是推荐规则）
    "plugin:jest/recommended",
  ],
};

Чтобы проверить, действует ли рекомендуемое правило, вы можете найти его здесь.no-identical-titleПравила проверки:

import greet from "@/greet";
describe("src/greet.ts", () => {
  it("name param test", () => {
    expect(greet("world")).toBe("Hello from world 1");
  });
});

// 这里输入了重复的 title
describe("src/greet.ts", () => {
  it("name param test", () => {
    expect(greet("world")).toBe("Hello from world 1");
  });
});

Нужно обратить внимание на модификациюpackage.jsonДиапазон проверки ESLint в:

"scripts": {
  // 这里对 src 和 test 目录进行 ESLint 校验
  "lint": "eslint src test --max-warnings 0",
},

воплощать в жизньnpm run lintПроверка формата для модульного тестирования:

PS C:\Code\Git\algorithms> npm run lint

> algorithms-utils@1.0.0 lint C:\Code\Git\algorithms
> eslint src test --max-warnings 0


C:\Code\Git\algorithms\test\greet.spec.ts
  9:10  error  Describe block title is used multiple times in the same describe block  jest/no-identical-title

✖ 1 problem (1 error, 0 warnings)

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! algorithms-utils@1.0.0 lint: `eslint src test --max-warnings 0`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the algorithms-utils@1.0.0 lint script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\子弈\AppData\Roaming\npm-cache\_logs\2020-07-13T02_25_12_043Z-debug.log

На этом этапе вы обнаружите, что ESLint выдает соответствующее сообщение об ошибке. Следует отметить, что подсказка об ошибке будет сгенерирована в VS Code в режиме реального времени после использования этой проверки ESLint (под соответствующим кодом будет красная волнистая линия, а соответствующая информация о правиле всплывающей подсказки будет сгенерирована после мышь перемещается в дополнение к текущему каталогу проекта Соответствующее имя файла также станет красным),Последующие коммиты Git, а также сборки Build завершатся ошибкой.!

Советы: Если вы хотите, чтобы код, протестированный Jest, требовал некоторых соглашений о форматировании, вы можете посмотретьeslint-plugin-jest-formattingплагин.

Npm Script Hook

Когда вы смотрите на интерфейсные проекты с открытым исходным кодом, вы можете найти первоеpackage.jsonсерединаmain,binтак же какfilesПолевая информация, такая какscriptsИнформация о поле скрипта используется для понимания процесса разработки, сборки, тестирования и установки проекта. Возможности сценариев npm очень мощны, и вы можете использовать сценарии для создания любых инструментов обработки, необходимых вашему проекту. В этой статье мы не будем слишком много рассказывать о функциях npm-скриптов, просто объясним используемые в них функции.крюкФункция.

Некоторые скриптовые команды, используемые в настоящее время в этом проекте, следующие (на данный момент скриптов относительно немного, и определения вполне ясны):

"lint": "eslint src test --max-warnings 0",
"test": "jest --bail --coverage",
"build": "npm run lint && npm run prettier && npm run test && rimraf dist types && gulp",
"changelog": "rimraf CHANGELOG.md && conventional-changelog -p angular -i CHANGELOG.md -s"

смотреть наbuildscript, вы обнаружите, что эта команда script содержит большое количество вторичных сценариев выполнения, но настоящий иbuildтолько соответствующиеrimraf dist types && gulpэти два скрипта. Здесь через хук скрипта npmpreа такжеpostРазделите функции скрипта, чтобы сделать семантику скрипта более понятной (конечно, когда скриптов становится все больше и больше, это может легко увеличить когнитивную нагрузку разработчиков). npm в дополнение к указанию некоторых специальных обработчиков сценариев (например,prepublish,postpublish,preinstall,postinstallд.), вы также можете добавить в любой скриптpreа такжеpostХуки, где одновременно выполняемые скрипты упрощаются с помощью пользовательских хуков:

"lint": "eslint src test --max-warnings 0",
"test": "jest --bail --coverage",
"prebuild": "npm run lint && npm run prettier && npm run test",
"build": "rimraf dist types && gulp",
"changelog": "rimraf CHANGELOG.md && conventional-changelog -p angular -i CHANGELOG.md -s"

В этот момент, если вы выполнитеnpm run buildЭта команда на самом деле аналогична выполнению следующей команды:

npm run prebuild && npm run build

Если сценарии, разработанные позже, имеют много вторичных исполнений, они будут разработаны с помощью хука сценариев npm.

Советы: Вы можете задаться вопросом, что должно быть похоже наpreinstallилиpreuninstallТакие крючки, например, см.husky - package.json, лайка принесла некоторые побочные эффекты при установке скрипта Git Hook (конечно можно пройтиpreinstallзапускает логику, внедренную скриптом Git Hook). Если вы не хотите использовать хаски, вам нужно очистить имплантированный скрипт после удаления, чтобы не мешать оригинальной функции Git Hook. Конечно, если вы хотите узнать больше о скриптах npm, вы можете проверитьnpm-scriptsилиРуководство по скриптам npm.

Vuepress

фон vuepress

Библиотеки общих компонентов или библиотеки инструментов необходимы для разработки презентационного документа (обеспечивают хороший опыт разработки). Общая библиотека инструментов может использоватьtsdoc,jsdocилиesdocТакие инструменты, как VS Code, могут автоматически генерировать документы API, но они часто должны соответствовать некоторым спецификациям аннотаций. Эти спецификации аннотаций могут в некоторой степени усложнить разработку. Конечно, их также можно передать плагинам VS Code одним щелчком мыши. поколение, напримерDocument This For jsdocилиTSDoc Comment.

Библиотека компонентов Element UI принимаетvue-markdown-loader(Преобразование файла Markdown в компонент Vue с помощью markdown-it) Демонстрационный дизайн компонента, но конфигурация относительно сложна. Легче всего сотрудничатьVuepressДля дизайна это очень мощно, но предполагается, что вы знакомы с Vue, потому что вы можете использовать синтаксис Vue в Markdown. Конечно, если это демонстрация библиотеки компонентов React, вы можете использоватьdumiСоздайте демонстрационную документацию по компонентам (я не знаю, что нет более полезного генератора документации по компонентам React, такого как Vuepress, вы также можете узнать больше о документации по React).react-markdown,react-staticЖдать).

Поскольку Vuepress ранее использовался для разработки демонстрационного документа библиотеки компонентов Vue, он по-прежнему используется здесь для разработки документа API пакета библиотеки инструментов (если вы хотите автоматически сгенерировать документ API, вы также можете использовать инструмент tsdoc) . Основные особенности разработки документов с помощью Vuepress заключаются в следующем:

  • Вы можете использовать Vue непосредственно в Markdown (вы также можете настроить компонент просмотра документа Vue)
  • Множество встроенных расширений Markdown.
  • Создайте собственную конфигурацию с помощью Webpack
  • Тема по умолчанию поддерживает возможность поиска
  • Плагины Vuepress могут быть установлены (последующая поддержкаLatexтипографика может быть сгенерирована с использованием существующих возможностей плагина)
  • Отзывчивый по умолчанию

Конфигурация Vuepress

по словам официальногоНачать быстроДокументация по установке зависимостей и настройке скриптов npm scripts:

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
}

Следите за официальным сайтом VuepressСоглашение о конфигурацииПринципы презентации документаСтруктура каталоговДизайн, официальные документы могут быть сложными для понимания сразу, вы можете сначала создать простейший каталог:

.
├── docs
│   ├── .vuepress
│   │   └── config.js       # 配置文件
│   └── README.md           # 文档首页
└── package.json

согласно сТема по умолчанию/Главнаясуществуетdocs/README.mdДля оформления главной страницы:

---
home: true
# heroImage: /hero.png
heroText: algorithms-utils
tagline: 算法与 TypeScript 实现
actionText: 开始学习
actionLink: /guide/
features:
  - title: 精简理论
    details: 精简《算法导论》的内容，帮助自己更容易学习算法理论知识。
  - title: 习题练习
    details: 解答《算法导论》的习题，帮助自己更好的实践算法理论知识。
  - title: 面题精选
    details: 搜集常见的面试题目，提升自己的算法编程能力以及面试通过率。
footer: MIT Licensed | Copyright © 2020-present 子弈
---

согласно снастроитьправильноdocs/.vuepress/config.jsфайл для базовой конфигурации:

const packageJson = require("../../package.json");

module.exports = {
  // 配置网站标题
  title: packageJson.name,
  // 配置网站描述
  description: packageJson.description,
  // 配置基本路径
  base: "/algorithms/",
  // 配置基本端口
  port: "8080",
};

через это времяnpm run docs:devПредварительный просмотр документа разработки:

PS C:\Code\Git\algorithms> npm run docs:dev

> algorithms-utils@1.0.0 docs:dev C:\Code\Git\algorithms
> vuepress dev docs

wait Extracting site metadata...
tip Apply theme @vuepress/theme-default ...
tip Apply plugin container (i.e. "vuepress-plugin-container") ...
tip Apply plugin @vuepress/register-components (i.e. "@vuepress/plugin-register-components") ...
tip Apply plugin @vuepress/active-header-links (i.e. "@vuepress/plugin-active-header-links") ...
tip Apply plugin @vuepress/search (i.e. "@vuepress/plugin-search") ...
tip Apply plugin @vuepress/nprogress (i.e. "@vuepress/plugin-nprogress") ...

√ Client
  Compiled successfully in 5.31s

i ｢wds｣: Project is running at http://0.0.0.0:8080/
i ｢wds｣: webpack output is served from /algorithms-utils/
i ｢wds｣: Content not from webpack is served from C:\Code\Git\algorithms\docs\.vuepress\public
i ｢wds｣: 404s will fallback to /index.html
success [23:13:14] Build 10b15a finished in 5311 ms!
> VuePress dev server listening at http://localhost:8080/algorithms-utils/

Эффект следующий:

Конечно, в дополнение к домашней странице, разработанной выше, в этом проекте также будет дизайнПанель навигации,Боковая панель,использоватьплагин,использовать компонентыЖдать. Вот фокусСборка веб-пакетаконфигурация.

Для использования в документах MarkdownsrcКод TypeScript для каталога, прямо здесь.vuepress/config.jsфайл для обработки конфигурации:

const packageJson = require("../../package.json");
const sidebar = require("./config/sidebar.js");
const nav = require("./config/nav.js");
const path = require("path");

module.exports = {
  title: packageJson.name,
  description: packageJson.description,
  base: "/algorithms/",
  port: "8080",

  themeConfig: {
    nav,
    sidebar,
  },

  plugins: [
    "vuepress-plugin-cat",
    [
      "mathjax",
      {
        target: "svg",
        macros: {
          "*": "\\times",
        },
      },
    ],
    // 增加 Markdown 文档对于 TypeScript 语法的支持
    [
      "vuepress-plugin-typescript",
      {
        tsLoaderOptions: {
          // ts-loader 的所有配置项
        },
      },
    ],
  ],

  chainWebpack: (config) => {
    config.resolve.alias.set("image", path.resolve(__dirname, "public"));

    // 在文档中模拟库包的引入方式
    // 例如发布了 algorithms-utils 库包之后，
    // import greet from 'algorithms-utils/greet.ts' 在 Vuepress 演示文档中等同于
    // import greet from '~/src/greet.ts',
    // 其中 ~ 在这里只是表示项目根目录
    config.resolve.alias.set(
      "algorithms-utils",
      path.resolve(__dirname, "../../src")
    );
  },
};

Советы: Конфигурация Webpack здесь используетwebpack-chainЦепные операции, если вы хотите использовать метод конфигурации объектов Webpack, вы можете просмотретьVuepress — Процесс сборки — configurewebpack.

На этом этапе дизайн документа презентации, представленный TypeScript, может быть выполнен в документе Markdown Vuepress:

# Test vuepress

::: danger 测试 Vuepress
引入 greet.ts 并进行调用测试。
:::

<template>
  <collapse title="查看答案">{{msg}}</collapse>
</template>

<template>
  <div>{{msg}}</div>
</template>

<script lang="ts">
  import greet from 'algorithms-utils/greet'
  const msg = greet('ziyi')
  export default {
    data() {
      return {
         msg
      }
    },
  }
</script>

Запустите Vuepress и посмотрите демо:

Можно найти, что введено в Markdownsrc/greet.tsКод вступает в силу и, наконец, проходитnpm run docs:buildВы можете создавать статические ресурсы для демонстрационных документов для развертывания и доступа.

Советы: Для получения дополнительной информации о конфигурации Vuepress этого проекта вы можете просмотреть информацию о фиксации.Кроме того, если вы хотите узнать больше об экосистеме Vuepress, например о любых интересных плагинах или темах, вы можете просмотретьawesome-vuepressилиСообщество Vuepress.

Документация Инструменты и спецификации

Обычно при написании документов многие студенты не обращают внимания на чистоту документов, ведь написание документов и написание кода требует некоторых спецификаций формата.markdownlintЭто инструмент проверки формата Markdown, аналогичный ESLint, с помощью которого мы можем лучше стандартизировать документы, которые пишем. Конечно, проверка формата Markdown не требует таких жестких ограничений, как проверка ESLint или Prettier, ее можно просто запросить и сохранить автоисправление.

Установив плагин Vs CodemarkdownlintИ выполните настройку Save Auto Fix (какие правила явно указаны в плагине, который можно исправить). После завершения установки просмотрите только что выполненный тестовый файл:

На этом этапе вы обнаружите, что плагин вступает в силу, но вставка html в Markdown является необходимой возможностью (возможность, поддерживаемая Vuepress, заключается в использовании Vue в Markdown), поэтому вы можете передать.markdownlintrcФайл заблокирует соответствующие правила.

Советы: если вы хотите иметь возможность выполнять проверку формата Markdown перед отправкой кода или созданием документа, вы можете попробовать его интерфейс командной строки.markdownlint-cli.除此之外，如果对文档的设计没有想法或者不清楚如何书写好的技术文档，可以查看Обмен навыками написания технических статей, вы обязательно что-то выиграете.

Github Actions

Фон CI/CD

Предпосылка: люди могут быть относительно незнакомы с CI/CD и просто играли с Travis, Gitlab CI/CD и Jenkins.

Предыстория CI/CD не будет здесь подробно описана Заинтересованные студенты могут ознакомиться со следующими хорошими статьями:

существуетВведение в CI/CD с GitLab (китайская версия)Вы можете четко понять обязанности и функции CI и CD:

Функции, доступные на каждом этапе Gitlab, можно более четко увидеть на следующей диаграмме:

Поскольку этот проект опирается на Github, он не может использовать возможности интеграции Gitlab по умолчанию. Предыдущий проект Github использовал Travis для интеграции CI / CD проекта, Теперь, из-за более удобных действий Github, мы решили использовать действия, которые поставляются с Github для интеграции возможностей CI / CD (если вы хотите узнать больше об этих CI/CD Пожалуйста, погуглите разницу сами). Преимущества Github Actions:

  • Повторно используемые действия (в прошлом вам нужно было писать сложные сценарии, но теперь вы можете повторно использовать сценарии, написанные другими, что можно просто понимать как плагин сценария CI)
  • поддержите большеwebhook, это конечно уникальная конкурентоспособность экосистемы Github

Конечно некоторыеограничение, эти ограничения в основном связаны со временем выполнения и количеством раз. Следует отметить, что аналогично Jenkins и т. д. поддерживают локальное подключение, Github Actions также поддерживает подключение к локальному компьютеру для запуска рабочего процесса, поэтому некоторые ограничения могут не ограничиваться локальным запуском.

Советы: функции CI / CD, используемые в этом проекте, относительно просты.Если вы хотите узнать более общие действия, вы можете проверитьОфициальные действияа такжеawesome-actions. В последнее время я использую Jenkins для автоматизации построения и оптимизации внешнего интерфейса, и позже может быть опубликована простая обучающая статья (конечно, использование будет отличаться от обычного объяснения).

Конфигурация действий Github

Конфигурация этого проекта может включать следующие три аспекта:

  • Автоматически обновлять процесс статического ресурса
  • Процесс публикации пакета библиотеки
  • Отправить запрос на слияние

Здесь мы в основном объясняем процесс автоматического обновления статических ресурсов, который можно условно разделить на следующие шаги (далее — все операции на сервере Github, который вы можете понимать как новую сервисную среду):

  • Извлеките текущий код репозитория Github и переключитесь на соответствующую ветку.
  • Установите среду Node и Npm
  • Установить зависимости проекта
  • Статические ресурсы для создания пакетов библиотек и демонстраций
  • Публикация статических ресурсов для презентационных документов

просмотревОфициальные действияа такжеawesome-actions, найдите требуемые Действия:

  • Checkout: Перетащите код репозитория с Github на сервер Github.$GITHUB_WORKSPACEПод содержанием
  • cache: кэш нпм
  • setup-node: Установите среду Node и Npm.
  • actions-gh-pages: Публикуйте статические ресурсы на Github.

Советы: Доступно множество действий, вот простой процесс.

существует.github/workflowsдобавить подmian.ymlКонфигурационный файл:

# 以下都是官方文档的简单翻译
# 当前的 yml（.yaml） 文件是一个 workflow，是持续集成一次运行的一个过程，必须放置在项目的 .github/workflow 目录下
# 如果不清楚 .yml 文件格式语法，可以查看 https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes
# 初次编写难免会产生格式问题，可以使用 VS Code 插件进行格式检测，https://marketplace.visualstudio.com/items?itemName=OmarTawfik.github-actions-vscode

# 具体各个配置属性可查看 https: //docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

# workflow 的执行仍然会受到一些限制，例如
#  - 每个 job 最多执行 6 小时（本地机器不受限制）
#  - 每个 workflow 最多执行 72 小时
#  - 并发 job 的数量会受到限制
#  - 更多查看 https: //docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#usage-limits

# name: 当前 workflow 的名称
name: Algorithms

# on:  指定 workflow 触发的 event
#
#      event 有以下几种类型
#         - webhook
#         - scheduled
#         - manual
on:
  # push: 一个 webhook event，用于提交代码时触发 workflow，也可以是触发列表，例如 [push, pull_request]

  #        workflows 触发的 event 大部分是基于 webhook 配置，以下列举几个常见的 webhook:
  #           - delete:  删除一个 branch 或 tag 时触发
  #           - fork / watch:  某人 fork / watch 项目时触发（你问有什么用，发送邮件通知不香吗？）
  #           - pull_request:  提交 PR 时触发
  #           - page_build:  提交 Github Pages-enabled 分支代码时触发
  #           - push:  提交代码到特定分支时触发
  #           - registry_package:  发布或跟新 package 时触发
  #           更多 webhook 可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows
  #           从这里可以看出 Git Actions 的一大特点就是 Gihub 官方提供的一系列 webhook
  push:
    # branches: 指定 push 触发的特定分支，这里你可以通过列表的形式指定多个分支
    branches:
      - feat/framework
    #
    # branches 的指定可以是通配符类型，例如以下配置可以匹配 refs/heads/releases/10
    # - 'releases/**'
    #
    # branches 也可以使用反向匹配，例如以下不会匹配 refs/heads/releases/10
    # - '!releases/**'
    #
    # branches-ignore:  只对 [push, pull_request] 两个 webhook 起作用，用于指定当前 webhook 不触发的分支
    # 需要注意在同一个 webhook 中不能和 branches 同时使用
    #
    # tags:  只对 [push, pull_request] 两个 webhook 起作用，用于指定当前 webhook 触发的 tag
    #
    # tags:
    #   - v1             # Push events to v1 tag
    #   - v1.*           # Push events to v1.0, v1.1, and v1.9 tags
    #
    # tags-ignore:  类似于 branches-ignore
    #
    # paths、paths-ignore...
    #
    # 更多关于特定过滤模式可查看 https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
    #
    # 其他的 webhook 控制项还包括 types（不是所有的 webhook 都有 types），例如已 issues 为例，可以在 issues 被 open、reopened、closed 等情况下触发 workflow
    # 更多 webhook 的 types 可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows#webhook-events
    #
    # on:
    #   issues:
    #     types:  [opened, edited, closed]

  # 除此之外如果对于每个分支有不同的 webhook 触发，则可以通过以下形式进行多个 webhook 配置
  #
  # push:
  #   branches:
  #     - master
  # pull_request:
  #   branches:
  #     - dev
  #
  # 除了以上所说的 webhook event，还有 scheduled event 和 manual event
  # scheduled event:  用于定时构建，例如最小的时间间隔是 5 min 构建一次
  # 具体可查看 https: //docs.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events

# env:  指定环境变量（所有的 job 生效，每一个 job 可以独立通过 jobs.<job_id>.env、jobs.<job_id>.steps.env 配置）
# defaults / defaults.run: 所有的 job 生效，每一个 job 可以独立通过 jobs.<job_id>.defaults 配置
# deafults
# defaults.run

# jobs: 一个 workflow 由一个或多个 job 组成
jobs:
  # job id: 是 job 的唯一标识，可以通过 _ 进行连接，例如:  my_first_job，例如这里的 build 就是一个 job id
  build_and_deploy:
    # name: 在 Github 中显示的 job 名称
    name: Build And Deploy
    #
    # needs: 用于继发执行 job，例如当前 job build 必须在 job1 和 job2 都执行成功的基础上执行
    # needs: [job1, job2]
    #
    # runs-on: job 运行的环境配置，包括:
    #   - windows-latest
    #   - windows-2019
    #   - ubuntu-20.04
    #   - ubuntu-latest
    #   - ubuntu-18.04
    #   - ubuntu-16.04
    #   - macos-latest
    #   - macos-10.15
    #   - self-hosted（本地机器，具体可查看 https: //docs.github.com/en/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow）
    runs-on: ubuntu-latest
    #
    # outputs:  用于输出信息
    #
    # env:  用于设置环境变量
    #
    # defaults:  当前所有 step 的默认配置
    #
    # defaults.run

    # if: 满足条件执行当前 job

    # steps:  一个 job 由多个 step 组成，step 可以
    #   - 执行一系列 tasks
    #   - 执行命令
    #   - 执行 action
    #   - 执行公共的 repository
    #   - 在 Docker registry 中的 action
    steps:
      #
      # id: 类似于 job id
      #
      # if:  类似于 job if
      #
      # name:  当前 step 的名字
      - name: Checkout
        #
        # uses: 用于执行 action
        #
        #       action: 可以重复使用的单元代码
        #          - 为了 workflow 的安全和稳定建议指定 action 的发布版本或 commit SHA
        #          - 使用指定 action 的 major 版本，这样可以允许你接收 fixs 以及 安全补丁并同时保持兼容性
        #          - 尽量不建议使用 master 版本，因为 master 很有可能会被发布新的 major 版本从而破坏了 action 的兼容性
        #          - action 可能是 JavaScript 文件或 Docker 容器，如果是 Docker 容器，那么 runs-on 必须指定 Linux 环境
        #
        #         指定固定 commit SHA
        #         uses:  actions/setup-node@74bc508
        #         指定一个 major 发布版本
        #         uses:  actions/setup-node@v1
        #         指定一个 minor 发布版本
        #         uses:  actions/setup-node@v1.2
        #         指定一个分支
        #         uses:  actions/setup-node@master
        #         指定一个 Github 仓库子目录的特定分支、ref 或 SHA
        #         uses:  actions/aws/ec2@master
        #         指定当前仓库所在 workflows 的目录地址
        #         uses:  ./.github/actions/my-action
        #         指定在 Dock Hub 发布的 Docker 镜像地址
        #         uses:  docker: //alpine: 3.8
        #         A Docker image in a public registry
        #         uses:  docker: //gcr.io/cloud-builders/gradle

        # checkout action 主要用于向 github 仓库拉取源代码（需要注意 workflow 是运行在服务器上，因此需要向当前 github 拉取仓库源代码）
        # 它的功能包括但不限于
        #   - Fetch all history for all tags and branches
        #   - Checkout a different branch
        #   - Checkout HEAD^
        #   - Checkout multiple repos (side by side)
        #   - Checkout multiple repos (nested)
        #   - Checkout multiple repos (private)
        #   - Checkout pull request HEAD commit instead of merge commit
        #   - Checkout pull request on closed event
        #   - Push a commit using the built-in token

        # checkout action:  https: //github.com/actions/checkout
        uses: actions/checkout@v2
        # with: action 提供的输入参数
        with:
          # 指定 checkout 的分支、tag 或 SHA
          # 更多 checkout action 的配置可查看 https: //github.com/actions/checkout#usage
          ref: feat/ci
        # args: 用于 Docker 容器的 CMD 指令参数
        # entrypoint: Docker 容器 action（覆盖 Dockerfile 的 ENTRYPOINT） 和 JavaScript action 都可以使用
      #
      # run: 使用当前的操作系统的默认的 non-login shell 执行命令行程序
      # 运行单个脚本
      # run: npm install
      # 运行多个脚本
      # run: |
      #   npm ci
      #   npm run build
      #
      # working-directory: 用于指定当前脚本运行的目录
      # working-directory: ./temp
      #
      # shell: 可以指定 shell 类型进行执行，例如 bash、pwsh、python、sh、cmd、powershell
      # shell: bash
      #
      # env: 除了可以设置 workflow 以及 job 的 env，也可以设置 step 的 env（可以理解为作用域不同，局部作用域的优先级更高）
      #
      # comtinue-on-error: 默认当前 step 失败则会阻止当前 job 继续执行，设置 true 时当前 step 失败则可以跳过当前 job 的执行

      - name: Cache
        # cache action: https://github.com/actions/cache
        # cache 在这里主要用于缓存 npm，提升构建速率
        uses: actions/cache@v2
        # npm 缓存的路径可查看 https://docs.npmjs.com/cli/cache#cache
        # 由于这里 runs-on 是 ubuntu-latest，因此配置 ~/.npm
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      # github-script action: https://github.com/actions/github-script
      # 在 workflow 中使用 Script 语法调用 Github API 或引用 workflow context

      # setup-node action: https://github.com/actions/setup-node
      # 配置 Node 执行环境（当前构建的服务器默认没有 Node 环境，可以通过 Action 安装 Node）
      # 需要注意安装 Node 的同时会捆绑安装 npm，如果想了解为什么会捆绑，可以 Google 一下有趣的故事哦
      # 因此使用了该 action 后就可以使用 npm 的脚本在服务器进行执行啦
      # 这里也可以尝试 v2-beta 版本哦
      - name: Set Node
        uses: actions/setup-node@v1
        with:
          # 也可以通过 strategy.matrix.node 进行灵活配置
          # 这里本地使用 node 的 12 版本构建，因此这里就进行版本固定啦
          node-version: "12"

      - run: npm install
      - run: npm run build
      - run: npm run docs:build

      - name: Deploy
        # 用于发布静态站点资源
        # actions-gh-pages action: https://github.com/peaceiris/actions-gh-pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          # GTIHUB_TOKEN：https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token
          # Github 会在 workflow 中自动生成 GIHUBT_TOKEN，用于认证 workflow 的运行
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # 静态资源目录设置
          publish_dir: ./docs/.vuepress/dist
          # 默认发布到 gh-pages 分支上，可以指定特定的发布分支
          publish_branch: gh-pages1 # default: gh-pages
          full_commit_message: ${{ github.event.head_commit.message }}
    #
    # timeout-minutes: 一个 job 执行的最大时间，默认是 6h，如果超过时间则取消执行
    #
    # strategy.matrix: 例如指定当前 job 的 node 版本列表、操作系统类型列表等
    # strategy.fail-fast
    # strategy.max-parallel
    # continue-on-error:  一旦当前 job 执行失败，那么 workflow 停止执行。设置为 true 可以跳过当前 job 执行
    # container: Docker 容器配置，包括 image、env、ports、volumes、options 等配置
    #
    # services: 使用 Docker 容器 Action 或者 服务 Action 必须使用 Linux 环境运行

Советы: Конкретный процесс настройки здесь не описан.Для получения дополнительной информации вы можете просмотреть информацию по ссылке, размещенной в файле конфигурации.

После загрузки файла конфигурации CI Github автоматически создаст следующее:

Вы можете просмотреть информацию о каждой сборке во время сборки или после завершения сборки.Если первоначальная сборка не удалась, вы можете узнать причину сбоя с помощью информации о сборке и повторно изменить конфигурацию сборки, чтобы попытаться построить снова. Кроме того, Github будет уведомлять вас по электронной почте о каждом сбое сборки:

Если сборка прошла успешно, каждый раз, когда вы отправляете новый код, служба Github будет выполнять ряд процессов и автоматически обновлять сайт статического ресурса.

Суммировать

Я надеюсь, что после прочтения этого документа, если вы захотите использовать некоторые из этих инструментов, вы сможете выработать следующие привычки:

  • Прочитайте документацию по инструменту, чтобы понять различия между разными инструментами с одинаковыми функциями.

Прочтите официальные документы Github README и документы официального сайта, соответствующие инструменту, чтобы понять основную философию, основные функции и основные проблемы разработки инструмента. Интерфейсные инструменты расцветают, и одна и та же функция может быть реализована с помощью множества различных инструментов. Если вы хотите использовать соответствующие инструменты в своем проекте, вам необходимо знать различия между этими инструментами. Полное прочтение соответствующих официальных документов поможет вам понять их основные функции и различия.

  • Изучив различия каждого инструмента, выберите инструмент, который, по вашему мнению, подходит для практики.

По мере практики вы все больше и больше будете знакомиться с использованием этого инструмента. На этом этапе, если вы столкнетесь с некоторыми проблемами или захотите реализовать определенные функции, будет относительно легко прочитать весь документ. Конечно, если вы столкнулись с некоторыми сообщениями об ошибках, которые не могут быть устранены, в первый раз вам следует выполнить поиск проблем Github, соответствующих текущему инструменту. Кроме того, вы также можете отслеживать исходный код инструмента в соответствии с неправильной информацией о стеке, и после понимания исходного кода причина сообщения об ошибке может быть более ясной.

  • Выполнив два вышеуказанных шага, вы должны обобщить навыки использования инструмента.В настоящее время чтение документации по инструменту может дать разные результаты.

ссылка на документацию

Категории