Почему Биго?

Beego, HTTP-фреймворк RESTful, создан для разработки веб-приложений и API-интерфейсов в Golang и следует архитектуре Model-View-Controller (MVC). Он поддерживает Swagger для автоматического создания документации, что упрощает нашу работу.

В этом посте я расскажу об основах фреймворка Beego и о том, как Swagger может помочь нам в документации.

Предпосылки

  • Пройдите настройку (следуйте этому)
  • Установка Beego (следуйте этому)

Давайте начнем

Предполагая, что вы успешно настроили Go и Beego, пора начинать!
Во-первых, я хочу, чтобы вы выполнили простую команду в терминале.

bee

Это должно вывести что-то вроде:

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

Давайте создадим новый API для этого руководства и назовем его test_api.

bee api test_api

Эта команда создаст каталог test_api со следующими папками и файлами:

-conf
-controllers
-main.go
-models
-routers
-tests

Короче говоря, маршрутизаторы - это место для указания ваших конечных точек, контроллеры - это мозг вашего API, модели предназначены для обработки данных, требуемых контроллерами, а conf - это файл конфигурации для хранения учетных данных и другой информации об API.

У нас уже будут конечные точки «пользователь» и «объект», созданные по умолчанию в файле router.go в каталоге маршрутизаторов.

Этот фрагмент кода указывает, что конечная точка v1/object обрабатывается ObjectController. Я создал test конечную точку, следуя аналогичным нормам для этого руководства. На данный момент мы можем игнорировать все остальные ключевые слова и сосредоточиться только на конечной точке и контроллере, обрабатывающем конечную точку.
Всякий раз, когда выполняется вызов конечной точки v1/test, будет выполняться логика внутри TestController.

Теперь нам нужно создать два новых файла: test.go в контроллерах и test.go в моделях.
test.go в контроллерах - это в основном TestController, а файл модели является моделью для этого конкретного контроллера.

Компоновка для всех контроллеров одинакова, поэтому мы можем использовать здесь код пользовательского контроллера и изменять его в соответствии с нашими потребностями. Переходя к функции Test(), всякий раз, когда эта функция выполняется, переменная Response вызывает функцию TestFunction в моделях и сохраняет полученные данные. Затем контроллер кодирует данные в форму JSON и возвращает их.

Это просто.
Но здесь важнее понимать комментарии, предшествующие TestFunction.
Эти комментарии действительно играют роль в API и документации.
Комментарии @Title и @Description сами описывают свои функции и используются для документации.
@Success и @Failure указывают ответы об успешном и неудачном выполнении конечной точки соответственно. Целое число после этих комментариев указывает код ответа, а значения, следующие за этими целыми числами, указывают тип возвращаемого значения. Эти комментарии также предназначены для документации.
Последний комментарий, @Router, указывает на конечную точку и ее функциональные возможности. /hello после @Router является дополнением к начальной конечной точке, указанной в router.go, то есть функция Test будет выполняться, когда конечная точка v1/test/hello будет вызвана. [get] означает, что HTTP-запрос является запросом GET.
Подробнее о HTTP-запросах здесь.
Подробное объяснение таких комментариев в рамках Beego можно получить здесь.

Переходя к коду модели:

Контроллер вызывает функцию TestFunction с типом возвращаемого значения struct Test. Он создает новую переменную для структуры, присваивает Response значение «Hello World» и возвращает структуру.
Здесь должны выполняться все операции с данными и их модификация.

Поздравляем! Мы завершили кодирование нашего API для этого руководства. Пришло время протестировать наш API и создать несколько документов.

bee run

Используйте эту команду в каталоге test_api, чтобы запустить наш локальный сервер для тестирования наших конечных точек. Теперь откройте браузер и введите:

http://localhost:8080/v1/test/hello

Результат должен быть:

{
  "Response": "Hello World"
}

Теперь перейдем к автогенерации документации, завершите сеанс сервера и используйте эту команду:

bee run -gendoc=true -downdoc=true

Теперь перейдите в браузер и введите:

http://localhost:8080/swagger/

Это автоматически сгенерированная документация нашего API. Мы видим документацию по нашей конечной точке.

Вуаля! Это конец этого урока. Надеюсь, вы узнали из этого что-то ценное. Я размещаю несколько важных ссылок ниже, чтобы вы могли стать лучше в разработке Beego.

Ссылки

P.S- Я заявляю все права на все изображения и фрагменты кода, используемые в этом сообщении в блоге, если не указано иное.

Благодарю вас!