Почему Биго?
Beego, HTTP-фреймворк RESTful, создан для разработки веб-приложений и API-интерфейсов в Golang и следует архитектуре Model-View-Controller (MVC). Он поддерживает Swagger для автоматического создания документации, что упрощает нашу работу.
В этом посте я расскажу об основах фреймворка Beego и о том, как Swagger может помочь нам в документации.
Предпосылки
Давайте начнем
Предполагая, что вы успешно настроили 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.
Ссылки
- Https://tour.golang.org/welcome/1 (Чтобы изучить основы Голанга)
- Https://beego.me/docs/intro/ (документация Beego)
- Https://golang.org/doc/ (документация Golang)
- Https://solidgeargroup.com/best-practices-rest-api/ (передовой опыт разработки API)
P.S- Я заявляю все права на все изображения и фрагменты кода, используемые в этом сообщении в блоге, если не указано иное.
Благодарю вас!