About Teletype
Join
IT и коты
@itandcats
May 2

Как создать REST API на Go (Golang): подробный гайд

REST API — это способ взаимодействия приложений через HTTP-запросы. Сегодня мы рассмотрим, как быстро и понятно реализовать простой REST API на Go, используя популярный фреймворк Gin.

🐹 Почему Go отлично подходит для REST API?

  • Быстрая производительность: Go — компилируемый язык, что даёт высокую скорость работы API.
  • Простота и понятность кода: минималистичный и ясный синтаксис.
  • Встроенные инструменты для веб-разработки: простота работы с HTTP-запросами и ответами.
  • Легко поддерживать и масштабировать: отлично подходит для микросервисов и крупных API.

📦 Устанавливаем Go и Gin

Убедись, что Go установлен:

go version

Подробнее по установке можно найти тут: Golang для новичков: основные понятия и примеры кода

Инициализируй новый проект:

mkdir rest-api
cd rest-api
go mod init rest-api

Установи Gin — веб-фреймворк для Go:

go get github.com/gin-gonic/gin

🧑‍💻 Создаём первое REST API приложение

Создай файл main.go:

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()

    r.GET("/hello", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "Привет, REST API!"})
    })

    r.Run(":8080") // запуск сервера на порту 8080
}

Давай разберём по частям, что здесь происходит:

  • package main
    Объявляем пакет приложения (main). Go запускает приложение именно из функции main внутри пакета main.
  • import "github.com/gin-gonic/gin"
    Подключаем фреймворк Gin, который позволяет легко создавать веб-приложения.
  • func main()
    Это точка входа. С неё Go начинает выполнять программу.
  • r := gin.Default()
    Создаём объект Gin с дефолтными настройками. Он предоставляет маршрутизацию, обработку middleware, логирование и восстановление после ошибок.
  • r.GET("/hello", func(c *gin.Context)
    Мы объявляем HTTP GET-маршрут по адресу /hello.
    Если сервер получит GET-запрос по этому адресу, то выполнит код внутри этой функции.
  • c.JSON(200, gin.H{"message": "Привет, REST API!"})
    Возвращаем клиенту HTTP-ответ в формате JSON с кодом 200 (OK).
    gin.H — это сокращённая форма записи map[string]interface{}, позволяющая легко создавать JSON-ответы.
  • r.Run(":8080")
    Запускаем HTTP-сервер на порту 8080. Теперь приложение слушает и обрабатывает запросы, приходящие на этот порт.

Таким образом, всего в несколько строчек кода ты получил работающий REST API, готовый принимать и обрабатывать HTTP-запросы! 🎉

▶️Запусти сервер командой:

go run main.go

Теперь открой браузер или выполни запрос через curl:

curl http://localhost:8080/hello

Ты увидишь ответ:

{"message":"Привет, REST API!"}

⚙️ CRUD операции через REST API

Создадим простое CRUD API для сущности "Задачи" (tasks). Для этого добавим структуру данных и endpoints.

Файл main.go:

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

// Структура задачи
type Task struct {
    ID     string `json:"id"`
    Title  string `json:"title"`
    Status string `json:"status"`
}

// Имитация БД
var tasks = []Task{
    {ID: "1", Title: "Написать код", Status: "todo"},
    {ID: "2", Title: "Выпить кофе", Status: "done"},
}

func main() {
    r := gin.Default()

    // Получение всех задач
    r.GET("/tasks", func(c *gin.Context) {
        c.JSON(http.StatusOK, tasks)
    })

    // Получение задачи по ID
    r.GET("/tasks/:id", func(c *gin.Context) {
        id := c.Param("id")
        for _, t := range tasks {
            if t.ID == id {
                c.JSON(http.StatusOK, t)
                return
            }
        }
        c.JSON(http.StatusNotFound, gin.H{"message": "задача не найдена"})
    })

    // Создание задачи
    r.POST("/tasks", func(c *gin.Context) {
        var newTask Task
        if err := c.BindJSON(&newTask); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"message": "неверные данные"})
            return
        }
        tasks = append(tasks, newTask)
        c.JSON(http.StatusCreated, newTask)
    })

    // Удаление задачи по ID
    r.DELETE("/tasks/:id", func(c *gin.Context) {
        id := c.Param("id")
        for i, t := range tasks {
            if t.ID == id {
                tasks = append(tasks[:i], tasks[i+1:]...)
                c.JSON(http.StatusOK, gin.H{"message": "задача удалена"})
                return
            }
        }
        c.JSON(http.StatusNotFound, gin.H{"message": "задача не найдена"})
    })

    r.Run(":8080")
}

🔥 Примеры использования API (через curl)

После того как ты запустил своё API, важно протестировать его работу. Самый простой и универсальный способ проверить REST API — использовать команду curl. Это консольная утилита, с помощью которой ты можешь отправлять HTTP-запросы к своему серверу и видеть ответы прямо в терминале.

Ниже представлены простые примеры, которые помогут тебе понять, как взаимодействовать с API, получать данные, добавлять новые элементы или удалять существующие. Каждый из запросов демонстрирует одну из основных операций REST API: GET, POST и DELETE.

📌 Получить все задачи:

curl http://localhost:8080/tasks

📌 Получить задачу по ID:

curl http://localhost:8080/tasks/1

📌 Создать новую задачу:

curl -X POST http://localhost:8080/tasks \
-H "Content-Type: application/json" \
-d '{"id":"3", "title":"Выучить Go", "status":"in progress"}'

📌 Удалить задачу по ID:

curl -X DELETE http://localhost:8080/tasks/2

📖 Добавляем автоматичесую документацию через OpenAPI и Swagger

OpenAPI (раньше назывался Swagger) — это стандарт для описания REST API.
Он позволяет задокументировать, какие есть endpoints у твоего API, какие запросы они принимают и какие ответы отправляют. Это нужно для:

  • удобного взаимодействия с твоим API (для фронтенда и других команд),
  • автоматической генерации документации и клиентского кода,
  • тестирования и изучения API.

Swagger — это инструменты и UI для удобного просмотра и взаимодействия с OpenAPI-документацией прямо в браузере.

🔧 Добавляем OpenAPI/Swagger в REST API на Go (с Gin)

Самый популярный способ сделать это — использовать библиотеку swaggo/gin-swagger.

🚀 Шаг 1: Устанавливаем инструменты

Сначала поставим необходимые пакеты:

go install github.com/swaggo/swag/cmd/swag@latest
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

🚀 Шаг 2: Документируем наш API с помощью комментариев

Добавь комментарии в файл main.go:

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    swaggerFiles "github.com/swaggo/files"
    _ "rest-api/docs"
)

// @title           Пример REST API
// @version         1.0
// @description     Это простой пример REST API на Go с Gin и Swagger

// @host      localhost:8080
// @BasePath  /

func main() {
    r := gin.Default()

    // @Summary      Скажи Привет
    // @Description  Возвращает приветственное сообщение
    // @Tags         пример
    // @Produce      json
    // @Success      200  {object}  map[string]string
    // @Router       /hello [get]
    r.GET("/hello", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "Привет, REST API!"})
    })

    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run(":8080")
}

🚀 Шаг 3: Генерируем документацию (OpenAPI schema)

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

swag init

Эта команда создаст папку docs с файлом swagger.json.

🌐 Проверяем Swagger UI

Запусти приложение:

go run main.go

Открой браузер и перейди по ссылке:

http://localhost:8080/swagger/index.html

Теперь ты видишь удобную и красивую документацию, где можно протестировать API прямо из браузера.

🔍 Что именно мы сделали?

  • Добавили специальные комментарии в код, которые понимает инструмент swag.
  • Используя эти комментарии, инструмент автоматически создал OpenAPI спецификацию в формате JSON.
  • Gin-swagger предоставляет красивый UI (Swagger UI), чтобы изучать и тестировать API интерактивно.

🐾 Кошачий пример про OpenAPI:

Swagger UI — это как меню в кафе с картинками блюд. Ты точно знаешь, что можно заказать (API endpoints), какие ингредиенты нужны (параметры запросов), и что получишь в итоге (ответы API).

🚧 Что ещё можно улучшить?

  • ✅ Подключить настоящую базу данных (например, PostgreSQL, MongoDB).
  • ✅ Добавить валидацию данных.
  • ✅ Настроить логирование и мониторинг.
  • ✅ Защитить API авторизацией (JWT или OAuth).

🐾 Кошачий пример REST API

Представь, что твоё REST API — это котик-официант:

  • GET — спросить меню (прочитать данные),
  • POST — сделать заказ (создать данные),
  • PUT/PATCH — изменить заказ (обновить данные),
  • DELETE — отменить заказ (удалить данные).

✅ Итог

Ты создал простое REST API на Go за несколько минут, использовав удобный и быстрый фреймворк Gin. Go отлично подходит для создания эффективных, масштабируемых и легко поддерживаемых веб-приложений.

Теперь ты можешь дальше улучшать API, подключать базы данных и внедрять в свои проекты! 🐹✨🚀

#golang#web#api
IT и коты
May 2, 16:01
0 views
0 reactions
0 replies
0 reposts