tanukirpc

Tanukirpc

tanukirpc -это практическая, быстро развивающаяся, безопасная типа и простая в использовании библиотеку RPC/маршрутизатора для GO. Эта библиотечная база на go-chi/chi .

Установка

go get -u github.com/mackee/tanukirpc

Использование

Это простой пример того, как использовать tanukirpc .

 package main

import (
	"fmt"
	"net/http"

	"github.com/mackee/tanukirpc"
)

type helloRequest struct {
	Name string `urlparam:"name"`
}

type helloResponse struct {
	Message string `json:"message"`
}

func hello ( ctx tanukirpc. Context [ struct {}], req helloRequest ) ( * helloResponse , error ) {
	return & helloResponse {
		Message : fmt . Sprintf ( "Hello, %s!" , req . Name ),
	}, nil
}

func main () {
	r := tanukirpc . NewRouter ( struct {}{})
	r . Get ( "/hello/{name}" , tanukirpc . NewHandler ( hello ))

	if err := r . ListenAndServe ( context . Background (), ":8080" ); err != nil {
		fmt . Println ( err )
	}
}

Функции

• ⭕ Запрос/обработчик ответов с ответом
• ⭕ Параметр URL, строка запроса, JSON, форма или пользовательская привязка
• ⭕ Проверка запроса с помощью Go-Playground/Validator
• ⭕ Пользовательская обработка ошибок
• ⭕ Инъекция реестра
  • Для инъекции зависимости
• ⭕ Команда сервера разработки, которая автоматически перезапускается при изменениях файлов
  • Используйте команду tanukiup
• ⭕ Сгенерировать клиент -код TypeScript
  • Используйте команду gentypescript
• ⭕ Отложить крючки для очистки
• ⭕ Управление сессиями
• ⭕ Поток аутентификации
  • ⭕ OpenID Connect

Инъекция реестра

Инъекция реестра является уникальной особенностью tanukirpc . Вы можете ввести объект реестра в функцию обработчика.

Кроме того, реестр может быть сгенерирован для каждого запроса. Для получения более подробной информации, пожалуйста, см.

Вариант использования

• Соединение базы данных
• Регистратор
• Информация об аутентификации
• Привязка ресурса с помощью параметра пути. Примеры можно найти в _example/todo.

Запрос привязки

tanukirpc поддерживает следующие привязки запроса по умолчанию:

• Параметр URL (например, A /entity/{id} Path): используйте тег urlparam Struct
• Строка запроса: используйте тег query Struct
• JSON ( application/json ): используйте тег json struct
• Форма ( application/x-www-form-urlencoded ): Используйте тег form Struct
• Сырое тело: используйте тег структуры rawbody с [] байтом или io.readcloser
  • Также поддерживайте голый [] байт или io.readcloser

Если вы хотите использовать другие привязки, вы можете реализовать интерфейс tanukirpc.Codec и указать его, используя опцию tanukirpc.WithCodec при инициализации маршрутизатора.

 tanukirpc . NewRouter ( YourRegistry , tanukirpc . WithCodec ( yourCodec ))

Проверка запроса

tanukirpc автоматически валидация go-playground/validator , когда содержит validate тега struct в запросе struct.

 type YourRequest struct {
    Name string `form:"name" validate:"required"`
}

Если вы хотите использовать пользовательскую проверку, вы можете реализовать интерфейс tanukirpc.Validatable в вашем запросе. tanukirpc вызовет метод Validatable.Validate после привязки запроса и перед вызовом функции обработчика.

Обработка ошибок

tanukirpc имеет обработчик ошибок по умолчанию. Если вы хотите использовать пользовательскую обработку ошибок, вы можете реализовать интерфейс tanukirpc.ErrorHooker и использовать его с помощью опции tanukirpc.WithErrorHooker при инициализации маршрутизатора.

Ответ с кодом состояния

Если вы хотите вернуть ответ с определенным кодом состояния, вы можете использовать tanukirpc.WrapErrorWithStatus .

 // this handler returns a 404 status code
func notFoundHandler ( ctx tanukirpc. Context [ struct {}], struct {}) ( * struct {}, error ) {
    return nil , tanukirpc . WrapErrorWithStatus ( http . StatusNotFound , errors . New ( "not found" ))
}

Кроме того, вы можете использовать функцию tanukirpc.ErrorRedirectTo . Эта функция возвращает ответ с кодом состояния 3xx и заголовком Location .

 // this handler returns a 301 status code
func redirectHandler ( ctx tanukirpc. Context [ struct {}], struct {}) ( * struct {}, error ) {
    return nil , tanukirpc . ErrorRedirectTo ( http . StatusMovedPermanently , "/new-location" )
}

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

Вы можете использовать tanukirpc с Go-Chi/Chi/Middleware или func (http.Handler) http.Handler в стиле Middlewares. Горилла/Хэндлеры также включены в это.

Если вы хотите использовать промежуточное программное обеспечение, вы можете использовать *Router.Use или *Router.With .

команда tanukiup

Команда tanukiup очень полезна во время разработки. Когда вы запускаете свой сервер через команду tanukiup , он обнаруживает изменения файла, запускает сборку и перезапускает сервер.

Использование

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

$ go run github.com/mackee/tanukirpc/cmd/tanukiup -dir ./...

• Опция -dir указывает каталог, который следует наблюдать. Добавляя ... до конца, он рекурсивно включает в себя все подкатарии в сфере часов. Если вы хотите исключить определенные каталоги, используйте опцию -ignore-dir . Вы можете указать несколько каталогов, предоставив значения, разделенные запятыми, или используя опцию несколько раз. По умолчанию сервер будет перезагружаться при обновлении файлов с расширением .go .

• Параметр -addr позволяет команде tanukiup действовать в качестве самого сервера. После создания и запуска приложения сервера, созданного с tanukirpc , он прокси запрашивает этот процесс. Приложение должно быть начато с *tanukirpc.Router.ListenAndServe ; В противном случае опция -addr не будет функционировать. Только пути, зарегистрированные в tanukirpc.Router , будут прокси -прокси в приложении сервера.

• Кроме того, существует вариант, называемый -catchall-target , который можно использовать в сочетании с -addr . Эта опция позволяет прокси -запросам на пути, которые не зарегистрированы в tanukirpc.Router к другому адресу сервера. Это особенно полезно при работе с сервером разработки фронта (например, WebPack, VITE).

Кроме того, он обнаруживает go:generate строки для команды gentypescript , упомянутой позже, и автоматически запускает их перед перезапуском.

Генерация клиентского кода

Сервер веб-приложений, использующий tanukirpc , может генерировать код на стороне клиента на основе типа информации каждой конечной точки.

gentypescript генерирует код на стороне клиента специально для TypeScript. Используя сгенерированную реализацию клиента, вы можете отправлять и получать запросы API с безопасностью типа для каждой конечной точки.

Чтобы сгенерировать клиент -код, сначала позвоните genclient.AnalyzeTarget с маршрутизатором в качестве аргумента, чтобы четко определить целевой маршрутизатор.

Далее, добавьте следующее: генерируйте линию:

 //go:generate go run github.com/mackee/tanukirpc/cmd/gentypescript -out ./frontend/src/client.ts ./

Опция -out указывает имя выходного файла. Кроме того, добавьте ./ чтобы указать пакет, который будет проанализирован.

Когда вы запустите go generate ./ В пакете, содержащем этот файл, или когда вы запускаете сервер через вышеупомянутую команду tanukiup , будет создан клиент TypeScript.

Для более подробного использования см. В каталоге _Example/TODO.

Отложить крючки

tanukirpc поддерживает отложенные крючки для очистки. Вы можете зарегистрировать функцию, которая будет вызвана после выполнения функции обработчика.

 func ( ctx * tanukirpc. Context [ struct {}], struct {}) ( * struct {}, error ) {
    ctx . Defer ( func () error {
        // Close the database connection, release resources, logging, enqueue job etc...
    })
    return & struct {}{}, nil
}

Управление сеансом

tanukirpc предоставляет удобные утилиты для управления сеансами. Вы можете использовать пакет gorilla/sessions или другие библиотеки управления сеансами.

Чтобы начать работу, создайте сеанс -магазин и оберните его с помощью tanukirpc/auth/gorilla.NewStore .

 import (
    "github.com/gorilla/sessions"
    "github.com/mackee/tanukirpc/sessions/gorilla"
    tsessions "github.com/mackee/tanukirpc/sessions"
)

func newStore ( secrets [] byte ) (tsessions. Store , error ) {
    sessionStore := sessions . NewCookieStore ( secrets )
    store , err := gorilla . NewStore ( sessionStore )
    if err != nil {
        return nil , err
    }
    return store , nil
}

В RegistryFactory вы можете создать сеанс, используя tanukirpc/sessions.Store .

 type RegistryFactory struct {
    Store tsessions. Store
}

type Registry struct {
    sessionAccessor tsessions. Accessor
}

func ( r * RegistryFactory ) NewRegistry ( w http. ResponseWriter , req * http. Request ) ( * Registry , error ) {
	accessor , err := r . Store . GetAccessor ( req )
	if err != nil {
		return nil , fmt . Errorf ( "failed to get session accessor: %w" , err )
	}

    return & Registry {
        sessionAccessor : accessor ,
    }, nil
}

func ( r * Registry ) Session () tsessions. Accessor {
    return r . sessionAccessor
}

Тип Registry реализует интерфейс tanukirpc/sessions.RegistryWithAccessor .

Поток аутентификации

tanukirpc поддерживает поток аутентификации OpenID Connect. Вы можете использовать функцию tanukirpc/auth/oidc.NewHandlers для создания обработчиков для этого потока, которая включает набор обработчиков для облегчения аутентификации пользователей.

Требования

tanukirpc/auth/oidc.Handlers требует Registry , который реализует интерфейс tanukirpc/sessions.RegistryWithAccessor . Для получения более подробной информации обратитесь к разделу «Управление сеансами».

Использование

 oidcAuth := oidc . NewHandlers (
    oauth2Config , // *golang.org/x/oauth2.Config
    provider ,     // *github.com/coreos/go-oidc/v3/oidc.Provider
)
router . Route ( "/auth" , func ( router * tanukirpc. Router [ * Registry ]) {
    router . Get ( "/redirect" , tanukirpc . NewHandler ( oidcAuth . Redirect ))
    router . Get ( "/callback" , tanukirpc . NewHandler ( oidcAuth . Callback ))
    router . Get ( "/logout" , tanukirpc . NewHandler ( oidcAuth . Logout ))
})

Лицензия

Авторские права (с) 2024- Макки

Лицензирован по лицензии MIT.