rest

package module
v3.0.28 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2024 License: MIT Imports: 22 Imported by: 1

README

RESTfull support

Documentation

Overview

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

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

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

Index

Constants

View Source 
const (
	FlagLogUnknownParams   = 0x00000001 // Логировать полученные query параметры, которые не описаны в методе
	FlagConvertReplyToJSON = 0x00000008 // Конвертировать ответ в json? Если он будет заранее подготовлен уже в таком формате, то НЕ СТАВИТЬ этот флаг!

	// Использовать по возможности стандартные имена!
	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"
	ScopeInsert        = "insert"
	ScopeUpdateID      = "update.id"
	ScopeUpdateGUID    = "update.guid"
	ScopeUpdateName    = "update.name"
	ScopeDeleteID      = "delete.id"
	ScopeDeleteGUID    = "delete.guid"
	ScopeDeleteName    = "delete.name"

	// Признак статуса
	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"
	ExecResultRowName = "execResultRow"

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

	StatusProcessed = 999 // Специальный http status, говорящий о том, что все ответы уже отправлены
	StatusRetry     = 998 // Специальный http status, возвращаемый из After для повторного выполнения GET запроса (с возможно измененными там параметрами)
)

Variables

View Source 
var (
	ByRowDefautlBegin     = []byte{'['}
	ByRowDefautlEnd       = []byte{']'}
	ByRowDefaultDelimiter = []byte{','}
)
View Source 
var (
	Log = log.NewFacility("api") // Log facility

)

Functions

func AddTag 

func AddTag(tag *Tag) error

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 DelSubstArg added in v3.0.15 

func DelSubstArg(vars []any, name string) (result []any)

func Enumerate 

func Enumerate(e Enumerator) (err error)

func FindSubstArg 

func FindSubstArg(vars []any, name string) (subst *db.SubstArg)

func GetTagName 

func GetTagName(name string) string

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 HandlerEx 

func HandlerEx(find FindModule, extra any, h *stdhttp.HTTP, id uint64, prefix string, urlPath string, w http.ResponseWriter, r *http.Request) (basePath string, processed bool)

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 RemoveModuleRegistration 

func RemoveModuleRegistration(handler API) (err error)

func SetMaxShaperLen added in v3.0.24 

func SetMaxShaperLen(n int)

func Start 

func Start() (err error)

Types

type API 

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

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

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

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

type ByRow added in v3.0.25 

type ByRow struct {
	Begin []byte // Пишется один раз в начале
	End   []byte // Пишется один раз в конце

	Data []RowData

	RowNum  int  // Количество выданных строк (увеличивается в конце обработки строки)
	IsFinal bool // Финал, Tuner еще раз вызывается после завершения выборки, в первом параметре опять последнее значение
	// contains filtered or unexported fields
}

func NewByRow added in v3.0.25 

func NewByRow(proc *ProcOptions, tuner ByRowTuner) (br *ByRow, err error)

func (*ByRow) Close added in v3.0.25 

func (br *ByRow) Close() (err error)

func (*ByRow) Do added in v3.0.25 

func (br *ByRow) Do() (err error)

func (*ByRow) Flush added in v3.0.25 

func (br *ByRow) Flush() (err error)

func (*ByRow) Write added in v3.0.25 

func (br *ByRow) Write(p []byte) (n int, err error)

type ByRowTuner added in v3.0.25 

type ByRowTuner func(br *ByRow, row any) (err error)

type Enumerator 

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

type ExecResult 

type ExecResult struct {
	AffectedRows uint64          `json:"affectedRows" comment:"Количеcтво затронутых записей"`
	Rows         []ExecResultRow `json:"rows,omitempty" comment:"Созданные записи" ref:"execResultRow"`
	Notice       string          `json:"notice,omitempty" comment:"Сообщения"`
}

func (*ExecResult) AddRow added in v3.0.22 

func (r *ExecResult) AddRow(row ExecResultRow)

func (*ExecResult) Cleanup added in v3.0.27 

func (r *ExecResult) Cleanup()

func (*ExecResult) Error added in v3.0.22 

func (r *ExecResult) Error() (err error)

type ExecResultRow 

type ExecResultRow struct {
	ID      uint64 `json:"id,omitempty" comment:"ID созданной записи"`
	GUID    string `json:"guid,omitempty" comment:"GUID созданной записи"`
	Message string `json:"message,omitempty" comment:"Сообщения"`
	// contains filtered or unexported fields
}

func (*ExecResultRow) Error added in v3.0.21 

func (r *ExecResultRow) Error() (err error)

func (*ExecResultRow) IsEmpty added in v3.0.27 

func (r *ExecResultRow) IsEmpty() bool

func (*ExecResultRow) SetError added in v3.0.22 

func (r *ExecResultRow) SetError(err error)

type ExternalDocs 

type ExternalDocs struct {
	Description string
	URL         string
}

type FieldDef 

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

type FindModule 

type FindModule func(path string) (module *Module, basePath string, extraPath []string, found bool)

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 FuncResultTuner added in v3.0.21 

type FuncResultTuner func(proc *ProcOptions, result0 any, code0 int, err0 error) (result any, code int, err error)

type Info 

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

	ResultTuner FuncResultTuner // The last step result tuner
	// contains filtered or unexported fields
}

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

func (*Info) ShaperWorkers added in v3.0.24 

func (info *Info) ShaperWorkers(n int) (err error)

type Module 

type Module struct {
	RawURL      string
	RelativeURL string        // URL без учета базовой части
	Handler     API           // Интерфейс метода
	Info        *Info         // Информация о методе
	LogFacility *log.Facility // Log facility
}

Обработчик

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              // Путь запроса
	Tail             []string            // Остаток пути
	R                *http.Request       // Запрос
	W                http.ResponseWriter // Интерфейс для ответа
	Chain            *path.Chain         // Обрабатываемая цепочка
	ChainLocal       path.Chain          // Копия Chain для возможности ее модификации для работы с динамическими объектами. Рекомендуется использовать её, а не Chain.Parent
	Scope            string              // Обрабатываемый Scope
	RawBody          []byte              // Тело запроса. В R.Body уже nil!
	PathParams       any                 // Path параметры
	QueryParams      any                 // Query параметры
	QueryParamsFound misc.BoolMap        // Query параметры, присутствующие в запросе в явном виде
	RequestParams    any                 // Request параметры
	DBqueryName      string              // Имя запроса к базе данных
	DBqueryVars      []any               // Переменные для формирования запроса
	ResultAsRows     bool                // Возвращать для GET не готовый результат, а *sqlx.Rows, чтобы производить разбор самостоятельно. Актуально для больших результатов.
	DBqueryResult    any                 // Результат выполненения запроса (указатель на слайс) при ResultAsRows==false
	DBqueryRows      *sqlx.Rows          // Результат при ResultAsRows==true
	Fields           []misc.InterfaceMap // Поля (имя из sql запроса) для insert или update. Для select - список полей для выборки из базы, если нужны не все из объекта
	ExcludedFields   misc.StringMap      // Поля ([name]db_name), которые надо исключить из запроса
	Notices          *misc.Messages      // Предупреждения и замечания обработчика
	ExecResult       *ExecResult         // Результат выполнения Exec
	ExtraHeaders     misc.StringMap      // Дополнительные возвращаемые HTTP заголовки

	Extra  any // Произвольные данные от вызывающего
	Custom any // Произвольные пользовательские данные
	// contains filtered or unexported fields
}

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

func (*ProcOptions) Create 

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

Create -- создать

func (*ProcOptions) Delete 

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

Delete -- удалить

func (*ProcOptions) Get 

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

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

func (*ProcOptions) Others 

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

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

func (*ProcOptions) QueryParamFound added in v3.0.16 

func (po *ProcOptions) QueryParamFound(name string) bool

func (*ProcOptions) Update 

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

Update -- изменить

type RowData added in v3.0.26 

type RowData struct {
	Prefix    []byte // Дополнительный блок цикла, который может возвращаться из ByRowTuner и пишется перед основными данными
	Suffix    []byte // Дополнительный блок цикла, который может возвращаться из ByRowTuner и пишется после основных данных
	Delimiter []byte // Разделитель строк
	Data      any    // Основные данные цикла
}

type Tag 

type Tag struct {
	Name         string
	Aliases      []string
	Description  string
	ExternalDocs ExternalDocs
}

type Tags 

type Tags []*Tag

func GetTags 

func GetTags() Tags

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.