rest

func (*Context) Bind ¶

func (c *Context) Bind(obj interface{}) error

Bind разбирает данные запроса и заполняет ими указанный в параметре объект. Разбор осуществляется с помощью Encoder.

package main

import (
	"github.com/geotrace/rest"
)

var c = new(rest.Context)

func main() error {
	// инициализируем формат данных для разбора
	data := make(map[string]interface{})
	// читаем запрос и получаем данные в разобранном виде
	if err := c.Bind(&data); err != nil {
		return err
	}
	// возвращаем эти же данные в ответ
	return c.Send(data)
}

Output:

func (*Context) Data ¶

func (c *Context) Data(key interface{}) interface{}

Data возвращает пользовательские данные, сохраненные в контексте запроса с указанным ключем. Обычно эти данные используются, когда необходимо передать их между несколькими обработчиками.

func (*Context) Error ¶

func (c *Context) Error(code int, msg string) error

Error отправляет указанный текст как описание ошибки. В зависимости от флага EncodeError, данный текст будет отдан как описание или как JSON с кодом статуса. В отличии от обычных ошибок, на данный текст не распространяется правило отладки и текст будет отдан в неизменном виде, в не зависимости от установленного значения Debug.

func (*Context) Flush ¶

func (c *Context) Flush()

Flush отдает накопленный буфер с ответом. Используется для поддержки интерфейса http.Flusher.

func (*Context) Header ¶

func (c *Context) Header() http.Header

Header возвращает HTTP-заголовки ответа. Используется для поддержки интерфейса http.ResponseWriter.

func (*Context) Param ¶

func (c *Context) Param(key string) string

Param возвращает значение именованного параметра. Если параметр с таким именем не найден, то возвращается значение параметра из URL с тем же именем.

Разобранные параметры запроса пути сохраняются внутри Context и повторного его разбора уже не требует. Но это происходит только при первом к ним обращении.

func (*Context) Redirect ¶

func (c *Context) Redirect(url string) error

Redirect отсылает ответ с требованием временного перехода по указанному URL. Ошибка никогда не возвращается.

func (*Context) Send ¶

func (c *Context) Send(data interface{}) (err error)

Send отсылает переданные данные как ответ на запрос. В зависимости от типа данных, используются разные форматы ответов. Поддерживаются данные в формате string, error, []byte, io.Reader и nil. Все остальные типы данных приводятся к формату JSON.

Данный метод можно использовать только один раз: после того, как ответ отправлен, повторный вызов данного метода сразу возвращает ошибку.

package main

import (
	"os"

	"github.com/geotrace/rest"
)

var c = new(rest.Context)

func main() error {
	// открываем файл
	file, err := os.Open("README.md")
	if err != nil {
		return err
	}
	defer file.Close()
	// устанавливаем тип отдаваемых данных
	c.ContentType = "text/markdown; charset=UTF-8"
	// отдаем содержимое файла в качестве ответа
	return c.Send(file)
}

Output:

package main

import (
	"github.com/geotrace/rest"
)

var c = new(rest.Context)

func main() error {
	// отдаем ответ в формате JSON, беря идентификатор пользователя
	// из параметров пути или запроса
	return c.Send(rest.JSON{"user": c.Param("id")})
}

Output:

func (*Context) SetData ¶

func (c *Context) SetData(key, value interface{})

SetData сохраняет пользовательские данные в контексте запроса с указанным ключем.

Рекомендуется в качестве ключа использовать какой-нибудь приватный тип и его значение, чтобы избежать случайного затирания данных другими обработчиками: это гарантированно обезопасит от случайного доступа к ним. Но строки тоже поддерживаются. :)

package main

import (
	"fmt"

	"github.com/geotrace/rest"
)

var c = new(rest.Context)

func main() {
	type myKeyType byte     // определяем собственный тип данных
	var myKey myKeyType = 1 // генерируем уникальный ключ данных
	// сохраняем данные в контексте, используя уникальный ключ
	c.SetData(myKey, "Test data")
	// читаем данные с помощью ключа
	str := c.Data(myKey).(string)
	fmt.Println(str)
}

Output:

func (*Context) Status ¶

func (c *Context) Status(code int) *Context

Status устанавливает код HTTP-ответа, который будет отправлен сервером. Вызов данного метода не приводит к немедленной отправке ответа, а только устанавливает внутренний статус. Статус должен быть в диапазоне от 200 до 599, в противном случае статус не изменяется.

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

package main

import (
	"github.com/geotrace/rest"
)

var c = new(rest.Context)

func main() error {
	// возвращаем 201 код окончания
	return c.Status(201).Send(nil)
}

Output:

func (*Context) Write ¶

func (c *Context) Write(data []byte) (int, error)

Write записывает данные в качестве ответа сервера. Может вызываться несколько раз. Используется для поддержки интерфейса http.ResponseWriter.

При первом вызове (может быть не явный) автоматически устанавливается статус ответа. Если статус ответа был не задан, то будет использован статус 200 (ОК). Так же, если не был задан ContentType, то он будет определен автоматически на основании анализа первых байт данных.

func (*Context) WriteHeader ¶

func (c *Context) WriteHeader(code int)

WriteHeader записывает заголовок ответа. Вызов метода автоматически взводит внутренний флаг, что отправка ответа начата. После его вызова отсылка каких-либо данных другим способом, кроме Write, уже не поддерживается. Используется для поддержки интерфейса http.ResponseWriter.

func (Handler) ServeHTTP ¶

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP поддерживает интерфейс http.Handler для Handler, что позволяет использовать его с любыми совместимыми с http.Handler библиотеками.

package main

import (
	"net/http"
	"time"

	"github.com/geotrace/rest"
)

func main() {
	http.ListenAndServe(":8080",
		rest.Handler(func(c *rest.Context) error {
			return c.Send(rest.JSON{
				"user": "name",
				"date": time.Now().UTC(),
			})
		}))
}

Output:

func (JSONCoder) Bind ¶

func (j JSONCoder) Bind(c *Context, obj interface{}) error

Bind разбирает данные запроса в формате JSON и заполняет ими указанный в параметре объект.

Если Content-Type запроса не соответствует "application/json", то возвращается ошибка ErrUnsupportedMediaType. Так же может возвращать ошибку ErrLengthRequired, если не указана длина запроса, ErrRequestEntityTooLarge — если запрос превышает значение MaxBody, и ErrBadRequest — если не смогли разобрать запрос и поместить результат разбора в объект obj. Все эти ошибки поддерживаются методом Send и отдают соответствующий статус ответа на запрос.

func (JSONCoder) Encode ¶

func (JSONCoder) Encode(c *Context, obj interface{}) error

Encode кодирует и отправляет ответ с содержимым obj в формате JSON.

func (*ServeMux) Handle ¶

func (m *ServeMux) Handle(method, path string, handler Handler)

Handle регистрирует обработчик для указанного метода и пути. В описании пути можно использовать именованные параметры (начинаются с символа ':') и завершающий именованный параметр (начинается с '*'), который указывает, что path может быть длиннее. В последнем случае вся остальная часть пути будет включена в данный параметр. Параметр со звездочкой, если указан, должен быть самым последним параметром пути.

Если количество элементов пути в path больше 32768 или параметр со звездочкой используется не в самом последнем элементе пути, то возникает panic.

package main

import (
	"time"

	"github.com/geotrace/rest"
)

var mux rest.ServeMux

func main() {
	mux.Handle("GET", "/json/",
		func(c *rest.Context) error {
			return c.Send(rest.JSON{
				"user": "name",
				"date": time.Now().UTC(),
			})
		})
}

Output:

func (ServeMux) Handler ¶

func (m ServeMux) Handler(c *Context) error

Handler отвечает за подбор обработчика и его выполнение.

Если обработчик для данного пути и метода не найден, но есть обработчики для других методов, то возвращается статус http.StatusMethodNotAllowed и в заголовке передается список методов, которые можно применить к данному пути. В противном случае возвращается статус http.StatusNotFound.

func (*ServeMux) Handles ¶

func (m *ServeMux) Handles(paths Paths)

Handles добавляет сразу список обработчиков для нескольких путей и методов. Это, по сути, просто удобный способ сразу определить большое количество обработчиков, не вызывая каждый раз ServeMux.Handle.

package main

import (
	"net/http"

	"github.com/geotrace/rest"
)

type User struct{}

func (User) get(*rest.Context) error     { return nil }
func (User) post(*rest.Context) error    { return nil }
func secure(h rest.Handler) rest.Handler { return h }

var (
	user       User
	getMessage = func(*rest.Context) error { return nil }
	getFile    = getMessage
)

func main() {
	var mux rest.ServeMux
	mux.Handles(rest.Paths{
		"/user/:id": {
			"GET":  user.get,
			"POST": user.post,
		},
		"/message/:text": {"GET": getMessage},
		"/file/:name":    {"GET": secure(getFile)},
	})
	// т.к. поддерживается интерфейс http.Handler, то можно использовать
	// с любыми стандартными библиотеками
	http.ListenAndServe(":8080", mux)
}

Output:

func (ServeMux) ServeHTTP ¶

func (m ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP обеспечивает поддержку интерфейса http.Handler. Таким образом, данный ServeMux можно использовать как стандартный обработчик HTTP-запросов.

В процессе обработки запроса отслеживаются возвращаемые ошибки и перехватываются возможные вызовы panic. Если ответ на запрос еще не отправлялся, то в этих случаях в ответ будет отправлена ошибка.

package main

import (
	"net/http"
	"time"

	"github.com/geotrace/rest"
)

var mux rest.ServeMux

func main() {
	mux.Handles(rest.Paths{
		"/user/:id": {
			"GET": func(c *rest.Context) error {
				return c.Send(rest.JSON{
					"user": c.Param("id"),
					"date": time.Now().UTC(),
				})
			},
			"POST": rest.Data("OK", "text/plain"),
		},
		"/favicon.ico": {
			"GET": rest.File("./favicon.ico"),
		},
	})
	http.ListenAndServe(":8080", mux)
}

Output: