Документы

СусликСВЕТ

Привет, ребята, во-первых, я хотел бы поблагодарить вас за то, что вы решили использовать наш проект. Хоть он и маленький, но мы сделали это с большим энтузиазмом! Чтобы начать использовать его, вам сначала необходимо установить go, предположим, что он у вас уже есть. Затем установите основные модули фреймворка: req и router

go get github.com/BrunoCiccarino/GopherLight/router
go get github.com/BrunoCiccarino/GopherLight/req

Уже скачано? Уф! Теперь мы можем сделать наш первый Hello World.

package main

import (
    "fmt"
    "github.com/BrunoCiccarino/GopherLight/router"
    "github.com/BrunoCiccarino/GopherLight/req"
)


func main() {
    app := router.NewApp()

    // Define a route that responds to a GET request at "/hello".
    app.Get("/hello", func(r *req.Request, w *req.Response) {
        w.Send("Hello, World!")
    })

    fmt.Println("Server listening on port 3333")
    app.Listen(":3333")
}

Довольно просто, правда? И с GopherLight мы можем сделать гораздо больше. Продолжайте читать, чтобы получить полную информацию о методах HTTP и наших инструментах запросов и ответов.

Поддерживаемые методы HTTP
Вот список методов HTTP, которые вы можете использовать с router.App. Каждый из них позволяет вам настраивать маршруты для обработки различных типов запросов. Давайте погрузимся!

ПОЛУЧАТЬ

• Использование: app.Get(путь, обработчик)

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

ПОЧТА

• Использование: app.Post(путь, обработчик)

Отправляет данные для создания нового ресурса.
Пример: отправка формы или добавление нового элемента в список.

ПОМЕЩАТЬ

Использование: app.Put(путь, обработчик)

Обновляет или заменяет ресурс. Это действие «перезаписи».
Пример: обновление полного профиля пользователя.

УДАЛИТЬ

Использование: app.Delete(путь, обработчик)

Удаляет ресурс.
Пример: удаление пользователя или сообщения.

ПЛАСТЫРЬ

Использование: app.Patch(путь, обработчик)

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

ПАРАМЕТРЫ

Использование: app.Options(путь, обработчик)

Возвращает разрешенные методы HTTP для URL-адреса, в основном для предварительных запросов CORS.

ГОЛОВА

Использование: app.Head(путь, обработчик)

Как GET, но без тела ответа. Используйте его, чтобы проверить, существует ли ресурс.

ПОДКЛЮЧИТЬ И ПРОСЛЕДОВАТЬ

Использование: app.Connect(путь, обработчик), app.Trace(путь, обработчик)

Расширенные методы: CONNECT устанавливает туннель (для SSL), а TRACE предназначен для отладки и возврата запроса.

Работа с req.Request и req.Response

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

Запрос

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

• Параметры запроса: получите параметры запроса с помощью .QueryParam("key").
• Заголовки: доступ к заголовкам с помощью .Header("key").
• Тело как строка: возьмите тело запроса с помощью .BodyAsString().

Пример:

app.Get("/greet", func(r *req.Request, w *req.Response) {
    name := r.QueryParam("name")
    if name == "" {
        name = "stranger"
    }
    w.Send("Hello, "   name   "!")
})

Ответ

Объект Response помогает отправить ответ обратно клиенту. Вот что вы можете сделать:

• Отправить текст: .Send(строка данных) возвращает обычный текст.
• Установить статус: .Status(code) устанавливает статус HTTP.
• Отправить JSON: .JSON(data) сериализует объект Go в JSON и отправляет его.
• Обработка ошибок: .JSONError(message) отправляет ответ об ошибке в формате JSON.

Пример:

app.Get("/user", func(r *req.Request, w *req.Response) {
    user := map[string]string{"name": "Gopher", "language": "Go"}
    w.JSON(user)
})

Промежуточное ПО

У нас есть готовый набор промежуточного программного обеспечения, позволяющего добавить серьезную функциональность в ваше веб-приложение Go. Каждое из этих промежуточных программ несет в себе свою магию — безопасность, ведение журналов, таймауты и многое другое! Давайте разберем их один за другим. ?

Промежуточное программное обеспечение аутентификации (JWT)

Наше AuthMiddleware помогает защитить ваши маршруты с помощью веб-токенов JSON (JWT). Он гибкий и позволяет настраивать секретный ключ, обработку ошибок и метод извлечения токенов.

Настраивать
Для начала настройте параметры JWT с помощью JWTConfig:

• SecretKey: секретный ключ для подписи JWT.
• SigningMethod: алгоритм подписи JWT.
• ErrorHandler: собственный обработчик ошибок для обработки ошибок аутентификации (необязательно).
• TokenExtractor: извлекает токен из заголовка запроса (необязательно).

Пример

import (
    "github.com/BrunoCiccarino/GopherLight/middleware"
)

config := middleware.JWTConfig{
    SecretKey: []byte("your_secret_key"),
}
app.Use(middleware.NewAuthMiddleware(config))

Промежуточное программное обеспечение CORS

Нужно разрешить запросы из разных источников? Без проблем! Наше CORSMiddleware настраивает параметры совместного использования ресурсов между источниками (CORS), чтобы сделать ваш API доступным из других доменов.

Параметры конфигурации

• AllowOrigin: установите значение «*», чтобы разрешить любой источник или указать домен (например, «http://example.com»).
• AllowMethods: какие методы HTTP разрешены? Распространенные варианты включают «GET», «POST» и т. д.
• AllowHeaders: укажите, какие заголовки могут использовать клиенты.
• AllowCredentials: установите значение true, если вы хотите, чтобы файлы cookie или HTTP-аутентификация были включены.
• ExposeHeaders: позволяет клиенту читать определенные заголовки из ответа.
• MaxAge: время кэширования (в секундах) для предполетных запросов.

Пример

corsOptions := middleware.CORSOptions{
    AllowOrigin: "*",
    AllowMethods: []string{"GET", "POST"},
}
app.Use(middleware.CORSMiddleware(corsOptions))

Промежуточное ПО CSRF

Наше CSRFMiddleware защищает от подделки межсайтовых запросов путем проверки токена CSRF, отправляемого с каждым запросом. Используйте GenerateCSRFToken(), чтобы создать безопасный токен, а затем проверьте его с помощью собственной функции isValidToken.

Пример

app.Use(middleware.CSRFMiddleware(func(token string) bool {
    return token == "your_valid_token"
}))

И не забудьте сгенерировать токены с помощью:

csrfToken := middleware.GenerateCSRFToken()

Промежуточное программное обеспечение для ведения журналов

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

Пример

app.Use(middleware.LoggingMiddleware)

Каждый запрос будет регистрироваться следующим образом:

• Начало: записывает время начала запроса.
• Завершено: регистрируется завершение запроса, включая продолжительность.

Промежуточное ПО тайм-аута

Избегайте бесконечных ожиданий, установив ограничения по времени на обработку запросов с помощью TimeoutMiddleware. Это промежуточное программное обеспечение отменит запрос, если он не будет завершен вовремя, отправив клиенту статус 504 Gateway Timeout.

Пример

import (
    "time"
    "github.com/BrunoCiccarino/GopherLight/middleware"
)

timeout := 2 * time.Second
app.Use(middleware.TimeoutMiddleware(timeout))

Интерфейс плагина

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

Метод регистрации
Вот волшебная часть интерфейса плагина:

type Plugin interface {
    Register(route func(method, path string, handler func(req *req.Request, res *req.Response)))
}

Метод Register принимает функцию маршрута, которая позволяет вам определять новые маршруты в вашем плагине, указав:

• метод: метод HTTP (например, «GET», «POST» и т. д.)
• путь: путь маршрута (например, «/my-plugin-route»)
• обработчик: функция, выполняемая при прохождении маршрута. Эта функция получает:
  • req: объект запроса с доступом к параметрам, заголовкам и телу запроса.
  • res: объект ответа для отправки данных обратно клиенту.

Пример плагина

Предположим, вы хотите создать плагин, который добавляет простую конечную точку /hello-plugin для приветствия пользователей. Вот как будет выглядеть плагин:

package main

import (
    "github.com/BrunoCiccarino/GopherLight/plugins"
    "github.com/BrunoCiccarino/GopherLight/req"
)

type HelloPlugin struct{}

// Register adds a new route for the HelloPlugin.
func (p *HelloPlugin) Register(route func(method, path string, handler func(req *req.Request, res *req.Response))) {
    route("GET", "/hello-plugin", func(req *req.Request, res *req.Response) {
        res.Send("Hello from the HelloPlugin!")
    })
}

Добавление плагина в ваше приложение

Чтобы загрузить плагин, просто создайте экземпляр и вызовите «Регистрация» в основных настройках приложения:

package main

import (
    "github.com/BrunoCiccarino/GopherLight/router"
)

func main() {
    app := router.NewApp()
    helloPlugin := &HelloPlugin{}
    helloPlugin.Register(app.Route)

    app.Listen(":3333")
}

Настройка ваших плагинов

Каждый плагин может добавлять столько маршрутов, сколько необходимо. Просто вызовите маршрут несколько раз в функции Register, чтобы определить дополнительные конечные точки. Используйте различные HTTP-методы, пути и обработчики, чтобы формировать функциональность вашего плагина так, как вы хотите.