rest

README

RESTfull support

Documentation

Overview

Обработка прикладных HTTP запросов

Описание структур для API и инициализация

Описание структур для API и инициализация

Index

• Constants
• Variables
• func BadRequest(msg string, v ...any) (code int, err error)
• func CheckPeriod(from time.Time, to time.Time, maxPeriod time.Duration, stdPeriod time.Duration) (normFrom time.Time, normTo time.Time, code int, err error)
• func Enumerate(e Enumerator) (err error)
• func Handler(h *stdhttp.HTTP, id uint64, prefix string, urlPath string, ...) (basePath string, processed bool)
• func Init(cfg any, hh *stdhttp.HTTP, basePath string, defaultDB string, ...) (err error)
• func InternalServerError(msg string, v ...any) (code int, err error)
• func ModuleRegistration(handler API) (err error)
• func NotAllowed(msg string, v ...any) (code int, err error)
• func NotFound(msg string, v ...any) (code int, err error)
• func NotImplemented(msg string, v ...any) (code int, err error)
• func ParseTime(s string) (t time.Time, err error)
• func Start() (err error)
• type API
• type Enumerator
• type ExecResult
• type FieldDef
• type FuncAfter
• type FuncBefore
• type FuncInit
• type Info
• type ProcOptions
  • func (proc *ProcOptions) Create() (headers misc.StringMap, result any, code int, err error)
  • func (proc *ProcOptions) Delete() (headers misc.StringMap, result any, code int, err error)
  • func (proc *ProcOptions) Get() (headers misc.StringMap, result any, code int, err error)
  • func (proc *ProcOptions) Others() (headers misc.StringMap, result any, code int, err error)
  • func (proc *ProcOptions) Update() (headers misc.StringMap, result any, code int, err error)

Constants

const (
	FlagLogUnknownParams = 0x00000001 // Логировать полученные query параметры, которые не описаны в методе
	//FlagDynamic          = 0x00000002 // Разрешить обработку с использованием этого пути как базового. Например Path="xxx/yyy", будет обрабатывать и запросы типа "xxx/yyy/zzz/qqq"
	//FlagDontParseBody    = 0x00000004 // Не пытаться разбирать тело запроса
	FlagConvertReplyToJSON = 0x00000008 // Конвертировать ответ в json? Если он будет заранее подготовлен уже в таком формате, то НЕ СТАВИТЬ этот флаг!

	StatusProcessed = 999 // Специальный тип возврата, говорящий о том, что уже все ответы отправлены

	// Использовать по возможности стандартные имена!
	ParamCount      = "count"
	ParamPeriodFrom = "from" // включая
	ParamPeriodTo   = "to"   // НЕ включая
	ParamIDs        = "ids"
	ParamNames      = "names"

	// Стандартные Scope цепочек разбора пути, они же и суффиксы именён запросов в базу
	ScopeSelectAll          = "select.all"
	ScopeSelectID           = "select.id"
	ScopeSelectGUID         = "select.guid"
	ScopeSelectName         = "select.name"
	ScopeSelectPattern      = "select.pattern"
	ScopeSelectStatus       = "select.status"
	ScopeSelectObject       = "select.object"
	ScopeSelectObjectStatus = "select.object.status"
	ScopeInsert             = "insert"
	ScopeUpdateID           = "update.id"
	ScopeUpdateGUID         = "update.guid"
	ScopeDeleteID           = "delete.id"
	ScopeDeleteGUID         = "delete.giid"

	// Признак статуса
	StatusActive   = "active"
	StatusInactive = "inactive"

	ExprID      = "id"
	ExprGUID    = "guid"
	ExprName    = "name"
	ExprPattern = "pattern"

	// Стандартные регулярки для Expr
	REempty  = ``
	REany    = `.+`
	REid     = `\d+`
	REstatus = StatusActive + "|" + StatusInactive
	REguid   = `(?i)([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})`

	ExecResultName = "execResult"

	DefaultMaxCount  = 10000
	DefaultMaxPeriod = config.Duration(3600 * time.Second)
)

Variables

var (
	Log = log.NewFacility("api") // Log facility

)

Functions

func BadRequest

func BadRequest(msg string, v ...any) (code int, err error)

func CheckPeriod

func CheckPeriod(from time.Time, to time.Time, maxPeriod time.Duration, stdPeriod time.Duration) (normFrom time.Time, normTo time.Time, code int, err error)

func Enumerate

func Enumerate(e Enumerator) (err error)

func Handler

func Handler(h *stdhttp.HTTP, id uint64, prefix string, urlPath string, w http.ResponseWriter, r *http.Request) (basePath string, processed bool)

Обработчик прикладных HTTP запросов

func Init

func Init(cfg any, hh *stdhttp.HTTP, basePath string, defaultDB string, extraConfigs misc.InterfaceMap) (err error)

func InternalServerError

func InternalServerError(msg string, v ...any) (code int, err error)

func ModuleRegistration

func ModuleRegistration(handler API) (err error)

func NotAllowed

func NotAllowed(msg string, v ...any) (code int, err error)

func NotFound

func NotFound(msg string, v ...any) (code int, err error)

func NotImplemented

func NotImplemented(msg string, v ...any) (code int, err error)

func ParseTime

func ParseTime(s string) (t time.Time, err error)

Преобразовать строку во время

func Start

func Start() (err error)

Types

type API

type API interface {
	// Получение информации о методе
	Info() *Info

	// Вызывается перед обращением к базе, используется, например, для добавления дополнительных параметров или проверок
	// Если возвращает code != 0 или data != nil, то они и будут результатом
	Before(proc *ProcOptions) (result any, code int, err error)

	// Вызывается почле обращения к базе, используется, например, для обогащения результата
	// Если возвращает code != 0 или data != nil, то они и будут результатом
	After(proc *ProcOptions) (result any, code int, err error)
}

Интерфейс API метода

type Enumerator

type Enumerator func(path string, info *Info) (err error)

type ExecResult

type ExecResult struct {
	AffectedRows int64  `json:"affectedRows" comment:"Количеcтво затронутых записей"`
	Notice       string `json:"notice,omitempty" comment:"Предупреждения и замечания"`
}

type FieldDef

type FieldDef struct {
	JSONname string
	DBname   string
	Type     reflect.Kind
}

type FuncAfter

type FuncAfter func(proc *ProcOptions) (result any, code int, err error)

type FuncBefore

type FuncBefore func(proc *ProcOptions) (result any, code int, err error)

type FuncInit

type FuncInit func(info *Info) (err error)

type Info

type Info struct {
	Path          string        // Относительный (от базового) путь в URL
	Name          string        // Имя, желательно  чтобы по правилам имен переменных
	Summary       string        // Краткое описание
	Description   string        // Описание, по умолчанию сформированное из Summary и query параметров
	Flags         path.Flags    // Флаги
	Methods       *path.Set     // Цепочки обработки
	Config        any           // Кастомные параметры в конфиг файле
	CacheLifetime time.Duration // Время жизни кэша, если 0, то не использовать
	DBtype        string        // Тип базы. Если пусто, то по умолчанию из конфига
	DBidx         int           // Индекс базы
	QueryPrefix   string        // Префикс имени запроса в базу
	Init          FuncInit      // User defined Init
	Before        FuncBefore    // User defined Before query
	After         FuncAfter     // User defined After query

}

Информация о методе

type ProcOptions

type ProcOptions struct {
	LogFacility      *log.Facility       // Предпочтительная facility для логирования
	H                *stdhttp.HTTP       // HTTP листенер
	LogSrc           string              // Строка с ID запроса для MessageWithSource
	Info             *Info               // Информация о методе
	ID               uint64              // ID запроса
	Prefix           string              // Префикс пути запроса (при работе через прокси)
	Path             string              // Путь запроса
	R                *http.Request       // Запрос
	W                http.ResponseWriter // Интерфейс для ответа
	Chain            *path.Chain         // Обрабатываемая цепочка
	Scope            string              // Обрабатываемый Scope
	RawBody          []byte              // Тело запроса. В R.Body уже nil!
	PathParams       any                 // Path параметры
	QueryParams      any                 // Query параметры
	RequestParams    any                 // Request параметры
	DBqueryName      string              // Имя запроса к базе данных
	RequestBodyNames []string            // Для запросов в телом - полученные имена полей
	RequestBodyVals  []any               // и соответствующие им значения
	DBqueryVars      []any               // Переменные для заполнения запроса
	DBqueryResult    any                 // Результат выполненеия Query (слайс)
	Fields           misc.InterfaceMap   // Поля для insert или update
	Notices          *misc.Messages      // Предупреждения и замечания обработчика
	ExecResult       sql.Result          // Результат выполнения Exec
	Custom           any                 // Произвольные пользовательские данные
	// contains filtered or unexported fields
}

Опции запроса к методу

func (*ProcOptions) Create

func (proc *ProcOptions) Create() (headers misc.StringMap, result any, code int, err error)

Create -- создать

func (*ProcOptions) Delete

func (proc *ProcOptions) Delete() (headers misc.StringMap, result any, code int, err error)

Delete -- удалить

func (*ProcOptions) Get

func (proc *ProcOptions) Get() (headers misc.StringMap, result any, code int, err error)

Get -- получить данные

func (*ProcOptions) Others

func (proc *ProcOptions) Others() (headers misc.StringMap, result any, code int, err error)

Other -- другой запрос

func (*ProcOptions) Update

func (proc *ProcOptions) Update() (headers misc.StringMap, result any, code int, err error)

Update -- изменить