Привет, мой друг.

Если вы ищете подробное руководство по Hello World, это не то место. Однако, если вы хотите посмеяться, посочувствовать или сопереживать трудностям среднего веб-разработчика, то вы попали в нужное место. Хорошо, на самом деле я беру свои слова обратно, это будет что-то вроде учебника Hello World и небольшой разглагольствования «я хочу, чтобы кто-то сказал мне это, прежде чем я потратил впустую все это время».

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

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

Примечание. Я разрабатываю операционную систему Mac. Я не берусь за разработку под Windows или Linux.

#0: Настройка

Давайте проверим, установлены ли у вас Node.js и npm. Если нет, то скачать его можно здесь. В настоящее время я использую Node 7.6.0, но можно загрузить и установить последнюю версию.

npm -v и node -v, чтобы проверить, есть ли у вас уже node или npm.

Теперь, чтобы установить наши зависимости:

  • npm install --save express pg
  • npm install -g swagger knex
  • swagger project create INSERT_NAME (используйте клавиши со стрелками и выберите Express с помощью клавиши ввода)

#1: Спланируйте, наметьте и доработайте архитектуру данных.

Пожалуйста. Пожалуйста. Пожалуйста, ради всего хорошего в этом мире. Пожалуйста, представьте себе, как будет выглядеть ваша архитектура данных. Во время создания этого проекта я неоднозначно относился к своим моделям данных и немного запутался с обменом данными от одной функции к другой. В результате я был вынужден снова и снова отступать и исправлять свою схему миграции (подробнее об этом ниже). Из-за того, что меня заставили исправить мою схему миграции, я был вынужден соответствующим образом настроить свой файл swagger.yaml. Независимо от того, возвращает ли ваш ответ примитивный или ссылочный тип данных, для разработчика было бы невероятно удобно, если бы он знал точно, что создавать в первую очередь, чтобы быть эффективным, а не эффективным. Поэтому спланируйте свою архитектуру данных соответствующим образом и накопите наименьшую сумму технического долга.

#2: Создайте базу данных и запустите сервер

Во-первых, наши миграции используют knexfile.js, который указывает различные параметры конфигурации.

Выполните следующую команду в терминале:

knex init, который создает наш knexfile.js с некоторой предустановленной конфигурацией

Вы можете удалить все и начать заново или просто удалить значения ключей development, test и production.

Для простой конфигурации используйте следующий формат в вашем knexfile.js:

Здесь мы указываем всем трем ключам использовать PostgreSQL в качестве клиента с подключением, указывающим на соответствующие базы данных. Возможно, вы уже заметили, что ключ production указывает на соединение process.env.DATABASE_URL. При развертывании в Heroku нам нужно будет установить некоторые переменные среды для производственной среды, и в этом случае соединение будет указывать на переменную среды Heroku DATABASE_URL. НЕ вставляйте URL своей базы данных. Оставьте его как есть. Меняйте только DATABASE_NAME в ключах разработки и тестирования.

ХОРОШО. Теперь, когда мы, надеюсь, находимся на той же странице, давайте сначала создадим нашу базу данных, выполнив следующую команду в терминале:

createdb DATABASE_NAME_dev для создания нашей базы данных среды разработки

createdb DATABASE_NAME_test для создания нашей базы данных тестовой среды

psql -l, чтобы проверить, была ли создана наша база данных. Здесь вы должны увидеть список ваших баз данных.

Я сделал ошибку, создав свои миграции еще до создания самой базы данных. Д’о.

Как только у нас будет knexfile.js, запустите эту команду на терминале:

  • knex migrate:make INSERT_SCHEMA_NAME

Вот пример схемы миграции:

Итак, здесь происходит несколько вещей. Мы возвращаем Promise в функциях exports.up и exports.down. Внутри самой функции мы используем параметр table, переданный через стрелочную функцию, для вызова построения схемы knex, такой как table.increments(), table.string() и table.integer().

После того, как вы настроили свою схему knex, пришло время выполнить миграцию. Если у вас еще нет PostgreSQL, простой способ установить его с помощью Homebrew, запустив brew install postgres

Если вы хотите больше узнать о том, что происходит под капотом, или если у вас возникли проблемы, вот подробное руководство по установке PostgreSQL (удачи, друг мой).

Теперь, когда у нас есть схемы миграции. Давайте на самом деле сделаем миграцию. Выполните следующую команду в терминале:

knex migrate:latest

На создание семян сейчас!

Выполните следующую команду в терминале:

knex seed:make 00_SEED_NAME для создания семени.

knex seed:make 01_NEXT_SEED_NAME для создания следующего семени и так далее...

Здесь я даю ему имя файла 00_SEED_NAME для запуска моих семян в указанном мной порядке. В противном случае мы не можем контролировать, в каком порядке knex запускает наши семена.

Вот пример:

Если вы еще не заметили, у меня есть .then() после knex.insert() в строке 25-27. Хотел бы я знать при создании моей базы данных этот невероятно цепляющий фрагмент кода. Честно говоря, я все еще пытаюсь понять, что именно здесь происходит. Короче говоря, я вполне могу ошибаться, поэтому отнеситесь к этому с долей скепсиса, я верю, что этот оператор knex соответствующим образом увеличивает первичный идентификатор моей таблицы базы данных всякий раз, когда удаление строки сопровождается оператором вставки ( Пожалуйста, поправьте меня в комментариях, если я ошибаюсь, я хотел бы знать, что здесь происходит, и ради всех остальных тоже).

Теперь, когда мы сделали наши семена, пришло время их запустить.

Выполните следующую команду в терминале:

knex seed:run

Здорово! Теперь у нас есть наши семена вместе с нашими миграциями. Никто никогда не поздравлял меня на этом этапе, но давайте поаплодируем созданию нашей первой (возможно, моей третьей или четвертой, но все же повода для радости) базы данных с успешными миграциями и семенами.

Чтобы запустить проект swagger, выполните в терминале следующую команду:

swagger project start (убедитесь, что мы находимся в каталоге проекта)

Чтобы убедиться, что ваш сервер работает правильно, вы должны увидеть что-то вроде этого:

Мы можем запустить любую команду, чтобы протестировать наш первый маршрут, который предоставляет нам Swagger.

В браузере: httpL://localhost:10010/hello?name=INSERT_NAME

OR

В терминале: curl https://127.0.0.1:10010/hello?name=INSERT_NAME

Теперь я надеюсь, что вы уже использовали свое собственное имя или какое-то родовое имя всякий раз, когда я писал INSERT_NAME или TABLE_NAME. Если нет, то не беспокойтесь. У вас просто будут странные имена баз данных и таблиц. Я не буду судить.

# 3: Настройте Swagger.yaml

  • Создайте наш первый маршрут GET

Теперь, когда у нас запущен сервер. Мы можем либо использовать собственный редактор Swagger, либо настроить swagger.yaml самостоятельно.

Чтобы использовать предоставленный swagger редактор маршрутов:

(Предположим, что наш сервер уже запущен)

Выполните следующую команду в терминале:

swagger project edit

OR

Чтобы настроить swagger.yaml с помощью нашего собственного текстового редактора:

Путь swagger.yaml равен /PROJECT_DIRECTORY/api/swagger

Единственным недостатком использования нашего собственного текстового редактора является то, что мы не можем выявлять небольшие синтаксические ошибки и ошибки отступов, к которым Swagger особенно придирчив. При использовании редактора проекта swagger он автоматически записывает и сохраняет любые изменения в наш собственный локальный файл swagger.yaml.

Теперь, когда мы открыли файл swagger.yaml, мы видим, что Swagger прописал для нас путь /hello.

Вот пример пути, который я написал, чтобы дать нам представление о том, насколько удобно создавать путь с помощью API-фреймворка Swagger:

Если в этот момент вы чувствуете себя подавленным, сделайте глубокий вдох. Это совершенно нормально, и я также чувствовал себя немного ошеломленным. Давайте по очереди.

  • В строке 46 x-swagger-router-controller ищет конкретный файл, расположенный в /PROJECT_DIRECTORY/api/controllers. Именно здесь мы создадим наш новый файл контроллера mySpecifiedFile.js позже.
  • В строке 49 в нашем файле контроллера mySpecifiedFile.js этот запрос GET ищет функцию, которая предоставит ответ сервера. Мы коснемся этого подробнее в №4.
  • Обратите внимание, что в строках 69 и 75 я использую $ref для ссылки на определение, указанное ниже. Здесь я могу установить соответствующие типы данных в соответствии с моделью данных.
  • ПЛАНИРУЙТЕ СВОЮ МОДЕЛЬ ДАННЫХ ПРАВИЛЬНО С ПЕРВОГО РАЗА или, по крайней мере, потратьте соответствующее количество времени на ее завершение. Я не могу не подчеркнуть, насколько это важно. Я сталкивался с бесчисленным количеством раз, когда мне приходилось откатывать мои миграции (knex migrate:rollback), исправлять сиды, перенастраивать путь и определение swagger.yaml и, наконец, писать соответствующий ответ с помощью Knex. Постарайтесь ограничить эти изменения, так как это вызовет много возвратов и ненужного стресса.

#4: Напишите логику функции с помощью Knex

  • создайте mySpecifiedFile.js и создайте mySpecifiedFunction

Теперь, когда у нас есть путь к Swagger, указанный для нас. Давайте на самом деле подключим его, чтобы дать какой-то ответ. Для краткости я не буду писать полный ответ. Я просто покажу, какая конфигурация необходима, чтобы запустить наш первый путь.

Вот пример нашей функции, которая обрабатывает путь:

Убедитесь, что вы правильно экспортировали mySpecifiedFunction в строке 12.

#5: Запустите сервер и проверьте, работает ли он

Хорошо, если вы зашли так далеко, я хотел бы лично поздравить вас с тем, что мы сделали наш первый маршрут Swagger. Идите вперед и проверьте это, зайдя на /PATH_NAME. Обратите внимание, что система проверки Swagger требует, чтобы вы отправили именно ту модель данных, которую вы указали в файле swagger.yaml. Если вы указали в ответах, что будете отправлять строку, отправьте строку в своем ответе. То же самое касается целых чисел, массивов и объектов.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Спасибо за уделенное время. Если у вас есть какие-либо предложения, улучшения или исправления выше, пожалуйста, дайте мне знать. Нам всем будет лучше быть как можно формально корректнее. Пожалуйста, оставьте любые вопросы или комментарии ниже, и я свяжусь с вами как можно скорее. Это моя первая статья на Medium, так что, пожалуйста, дайте мне знать.

Удачного кодирования!

Первоначально опубликовано на gist.github.com.