Apipie
это не просто еще одна обертка над axios
. В первую очередь apipie
предоставляет единый стандарт описания запросов к серверу с хуками и мета данными, которые позволяют вам выполнять побочные действия как перед, так и после выполнения запроса. Более того декларативное описание позволяет добиться выразительной структуры запросов.
Основная идея декларации взята из VueRouter, поэтому тут есть meta
, hooks
, children
, name
. Однако реализация хуков позаимствованна у koa-middleware, а параметры запроса задаются в options
, как при задании параметров с помощью axios
. Версии v0.12 были добавлены params
и data
, которые позволяют явно указать, что запросы требуют axios.options.params
и axios.options.data
.
Кроме того, добавлен некоторый синтаксический сахар: url
и method
.
В версии v0.9 был переписан движок (позже была v0.10 с фиксами), который конструировал объект по декларации, теперь он не обсчитывает все пути при инициализации, а делает это лениво и только те узлы, которые необходимы для выполнения запроса, при этом кешируя промежуточные результаты.
Хуки описываются точно так же как и в koa-middlewares
. Однако стоит отметить несколько отличий:
- context состоит из
meta
,response
,options
- хуки исполняются в виде цепочки промисов (Promise chaining), а это значит, что каждый хук ДОЛЖЕН возвращать промис (используйте async/await для этого)
Настройки запроса через options
почти полностью взяты у axios, однако стоит акцентировать внимание на url
. Apipie
внутри использует path-to-regexp, поэтому теперь поддерживаются пути вида /something/:id/
. Для этого нужно передать при вызове метода url_params: { id: /* something */ }
.
Каждый хук имеет доступ к meta
. В декларации каждый метод может добавлять какое-нибудь поле.
{
name: 'user',
meta: { something1: true },
hook: async (ctx, next) => {
ctx.meta.something1 // true
await next()
},
children: [
{
name: 'get',
meta: { something2: false },
hook: async (ctx, next) => {
ctx.meta.something1 // true
ctx.meta.something2 // false
await next()
}
]
}
Это хук, который будет применен первым к каждой записи. Передается во втором параметре статической функции create
в поле globalHook
.
Допустим вы определили такую декларацию:
{
name: 'user', // Further you'll use it as `api.user()` for sending request
url: '/user/:id',
method: 'get'
}
Теперь вы можете его вызвать внутри Vue
как:
const user_id = 123;
this.$api.user({ url_params: { id: user_id } }) // GET: /user/123
Объект, который вы передаете как аргумент при вызове содержит 3 поля:
{
url_params, // Те переменные и их значения, что будут подставлены в путь
params, // Параметры запроса как в params в axios
data // Данные, которые необходимо передать
}
Часто придется писать такие простые запросы:
{ name: 'test', options: { url: '/test', method: 'get' } }
Вместо этого можно использовать более красивый синтаксис для декларации этого же самого запроса:
{ name: 'test', url: '/test', method: 'get' }
Контекст состоит из 5 полей:
{
meta,
options,
response,
name,
fullName // Array, например для api.user.settings fullName = [ 'user', 'settings' ]
}
Хочется сразу видеть, что запрос требует params
и/или data
.
Если при декларировании указать params: true
, то при вызове метода будет сделана проверка, что params
передана в параметрах вызова, если ее нет, то будет вызвано исключение.
Аналогичный механиз применяется и для валидации data
.
Для валидации url_params
не нужно ничего довольнительно добавлять, вы это уже сделали, когда воспользовалиись именованными параметрами при указании пути: url: '/test/:id1/:id2'
. При вызове будет проверено не только начиличие переданных параметров в { url_params: {...} }
, но проверено на соответсвие с тем, что указано в декларации, в данном примере ожидаются id1
и id2
. Если валидация выявит ошибку, то будет сгенерировано исключение, с описанием ожидаемых именованных параметров и переданных. Более того, вы можете использовать больше возможностей, такие как опциональные именованные параметры, безымяные параметры, и многое другое, что может pathToRegexp.
Из примера все станет ясно:
{
url: '/root',
children: [
{ url: 'path', method: 'get' } // GET: /root/path
{ url: '/path', method: 'get' } // GET: /path
]
}
type: String
- наименование метода
type: Object
- объект с данными, доступ к которым есть в хуках
type string
- url запроса, в том числе поддерживает именованные параметры
type string
- тип метода, как axios options method
type Object
- смотри axios request-config
type: Function: (ctx, next) => Promise
- функция. Чтобы прервать исполнение цепочки используйте throw
.
type: Array<Object>
- список дочерних API.
type: Boolean
- флаг необходимости проверки передаваемых данных при вызове
type: Boolean
- флаг необходимости проверки передаваеммых параметров при вызове
type: Function: (records, options)
- возвращает js объект, полученный из трансформирования декларации
records
- объект с декларациями запросов
options:
{
axios
}
type: Function: (ctx, next) => Promise