Научитесь использовать Redis-подобное хранилище Cloudflare в своих рабочих процессах с большими ограничениями на использование для бесплатных учетных записей.

Это вторая часть серии статей о воркерах Cloudflare, другие статьи можно посмотреть здесь:

Шаг 1: Создавайте и размещайте API бесплатно с помощью Cloudflare Workers
Шаг 2: Как легко сохранять данные в Cloudflare Workers с помощью KV

В последней статье мы создали простой API с использованием воркеров Cloudflare для извлечения животных. Однако сам API в настоящее время использует фиктивные данные, которые отлично подходят для демонстрации функциональности, но бесполезны для реального API.

Вот где KV приходит от Cloudflare. Это простое хранилище ключей и значений с малой задержкой. Если вы когда-либо использовали Redis, вы сразу поймете, что он, по сути, предоставляет ту же функциональность, что и собственная реализация Cloudflare.

В этой статье я более подробно объясню, что такое KV и как вы можете использовать его в своих воркерах Cloudflare.

Что такое КВ?

Для тех, кто не знаком с Redis, KV предоставляет простой интерфейс CRUD для чтения и записи данных. Поскольку это хранилище ключей и значений, вы читаете и пишете, используя заданный ключ, и можете хранить любые данные, которые вам нравятся, под этим ключом, от простых строк до JSON.

Лучше всего то, что вы получаете довольно щедрый план использования в качестве бесплатного клиента. Вы можете отправить до 100 000 запросов на чтение, а также 1000 запросов на запись, перечисление и удаление (по 1000 на тип). Что касается памяти, вы можете хранить до 1 ГБ.

Если бы ваш API стал популярным, их цены были бы разумными за пределами бесплатного уровня. Это всего 0,50 доллара США за 10 миллионов чтений и 5 долларов США за миллион запросов для других типов.

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

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

Готовы добавить постоянство в свой API? Посмотрим как!

Создайте пространство имен KV

Прежде чем мы сможем использовать KV в вашем воркере, мы должны сначала создать то, что называется пространством имен KV. Это просто причудливое название для, ну, имени.

Чтобы создать новое пространство имен KV, выполните следующие действия:

  1. Перейдите на https://dash.cloudflare.com/ и войдите в свою учетную запись.
  2. Щелкните маленькую стрелку рядом с рабочими в левом меню и щелкните KV.
  3. Там будет кнопка с надписью «Создать пространство имен». Нажмите на нее.
  4. Введите описательное имя для вашего пространства имен и нажмите «Добавить».

Вот и все. Теперь вы создали пространство имен KV для хранения любых данных, которые вам нравятся. Запишите идентификатор (рядом с ним есть удобная кнопка копирования), так как он понадобится нам на следующем шаге.

Нам нужно предоставить вашему рабочему процессу доступ к пространству имен KV, прежде чем он сможет его использовать, поэтому давайте сделаем это дальше.

Привяжите свое пространство имен KV к работнику

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

Поскольку воркеры Cloudflare работают в бессерверной среде выполнения, привязка эффективно внедряет ваше пространство имен KV в ваш воркер Cloudflare всякий раз, когда он вызывается. Довольно круто, правда?

Привязать worker к пространству имен очень просто, откройте wrangler.toml и добавьте в конец следующие строки:

kv_namespaces = [
  { binding = "ANIMALS", id = "your-id-here" }
]

Вам нужно будет заменить your-id-here на идентификатор, указанный при создании пространства имен, который всегда доступен для просмотра на странице KV в панели инструментов Cloudflare.

Что касается binding, вы можете дать ему любое описательное имя, которое вам нравится, но это будет имя, которое вы используете в коде для доступа к вашему пространству имен KV.

На данный момент мы привязываем только одно пространство имен KV, но если вы хотите иметь несколько, kv_namespaces принимает массив объектов.

Работа с хранилищами данных разработки и производства

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

Инструментарий Cloudflare превосходен, поэтому, если бы вы сейчас развернули своего воркера с помощью npm run deploy , все бы работало нормально. Однако, если вы запустите npm start, чтобы запустить вашего рабочего в режиме разработки, это приведет к ошибке:

✘ [ERROR] In development, you should use a separate kv namespace than the one you'd use in production. Please create a new kv namespace with "wrangler kv:namespace create <name> --preview" and add its id as preview_id to the kv_namespace "ANIMALS" in your wrangler.toml

К счастью, это даже дает нам решение нашей проблемы и дает нам возможность попробовать альтернативный способ создания пространства имен KV с помощью интерфейса командной строки Wrangler.

Давайте сделаем, как описано в сообщении об ошибке, и выполним следующую команду:

wrangler kv:namespace create <name> --preview

Как и раньше, вам нужно дать ему описательное имя. Параметр --preview сообщает Wrangler, что это только для предварительного просмотра, что по сути является режимом разработки. После завершения он выведет ваше новое пространство имен KV для предварительного просмотра и его идентификатор. Теперь мы можем обновить wrangler.toml следующим образом:

kv_namespaces = [
  { binding = "ANIMALS", id = "production-id", preview_id = "preview-id" }
]

Я выделил жирным шрифтом изменение по сравнению с предыдущей строкой кода, по сути, мы предоставляем один дополнительный параметр, который является идентификатором для пространства имен предварительного просмотра KV. Когда ваш воркер запускается, правильное пространство имен KV будет использоваться в зависимости от того, в какой среде он работает, поэтому не нужно беспокоиться о коллизиях разработки и производства!

Теперь мы можем использовать пространство имен KV в коде. Давайте посмотрим, как это сделать.

Как получить доступ к вашему пространству имен KV в вашем коде

Теперь, когда наш рабочий процесс может получить доступ к пространствам имен KV, которые мы создали во время выполнения, как нам получить доступ к этому пространству имен?

Если вы привыкли к более традиционным рабочим процессам, вероятно, именно здесь вам придется настраивать соединения с именами пользователей и паролями, но это не относится к рабочим процессам Cloudflare.

Всю эту работу за нас делает Cloudflare, поэтому мы можем сосредоточиться на забавных вещах — например, на создании большего количества нашего API!

Давайте посмотрим на изменение кода, позволяющее нашему воркеру получить доступ к пространству имен KV:

src/index.ts

export interface Env {
   //This will be auto-populated with the KV Namespace that is bound in the wrangler.toml
   //and exposes all the methods you'll need (get, put, list etc.)
   ANIMALS: KVNamespace;
}
export default {
   async fetch(
      request: Request,
      env: Env,
      ctx: ExecutionContext
   ): Promise<Response> {
      return await router.handle(request, env)
   }
};

Я выделил жирным шрифтом важные строки, но только одна новая. Во-первых, в функции fetch, которая является точкой входа для нашего воркера, мы получаем параметр с именем env. Этот параметр содержит переменные среды, которые во многих случаях Cloudflare автоматически заполняет для нас.

Это относится к пространствам имен KV, поскольку Cloudflare заполнит env именем, используемым в вашей привязке. В моих примерах выше это было ANIMALS , поэтому я могу получить доступ к этому пространству имен KV, используя env.ANIMALS .

Поскольку это TypeScript, мы должны описать, что находится в env (который имеет тип Env, который вы можете видеть выше). В том же духе Cloudflare предоставляет типы, необходимые для взаимодействия со своими инструментами.

Поэтому в определенный нами интерфейс Env я добавил ANIMALS в качестве свойства с типом KVNamespace.

С этим изменением мы сможем получить доступ к пространству имен KV, используя env.ANIMALS, и вызывать в нем методы для чтения и записи данных. Теперь мы можем обновить код API, чтобы использовать пространство имен KV.

Обновите API для чтения и записи данных из пространства имен KV

Теперь мы создали пространство имен KV, разрешили доступ нашему рабочему процессу и сообщили нашему коду, что пространство имен KV существует. По сравнению с трудоемкой настройкой соединений с базой данных в обычном приложении это довольно просто, особенно если учесть, что оно автоматически обрабатывает различные среды для нас!

Продолжая пример построения API вокруг животных, давайте обновим реализацию API, чтобы иметь возможность возвращать животных из пространства имён KV, а также создавать новых и хранить их в пространстве имён KV.

Добавьте функции для чтения и записи данных

Я добавил весь код в src/index.ts для простоты, но вы, вероятно, захотите начать разбивать его на другие файлы, чтобы сделать его более аккуратным. Во-первых, давайте добавим несколько функций, которые помогут нам взаимодействовать с пространством имен KV:

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

Мы не можем хранить в KV нативные типы, такие как объекты, поэтому они должны быть сериализованы в JSON при хранении данных или десериализованы из JSON при чтении данных. Если вы храните простые строки, вы можете использовать значение как есть прямо из KV.

Я решил хранить все свои данные под одним ключом в виде массива объектов в JSON, но как вы упорядочиваете данные, зависит от вас. Например, я мог бы хранить каждое животное как отдельный ключ.

Как видите, KV имеет простой интерфейс, который предоставляет put для хранения данных и get для чтения данных. Они мне здесь не нужны, но вы также можете удалить данные с помощью delete и вывести список всех ключей, хранящихся в пространстве имен, с помощью list.

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

Обновите маршруты API

Последним шагом является обновление наших маршрутов API для использования вновь определенных методов. Этот код все еще находится в src/index.ts и довольно прост:

Первые две конечные точки существовали раньше; Я только что обновил их, чтобы считывать данные с KV. Последняя конечная точка, POST, является новой. Это позволяет нам отправить запрос POST /animals с телом JSON следующим образом:

{
 "name": "chicken",
 "type": "bird"
}

Как только запрос будет установлен, в KV будет создано новое животное. Затем вы можете увидеть всех животных, нажав GET /animals , и используя любой идентификатор, возвращенный в этом ответе, чтобы получить отдельное животное, нажав GET /animals/:id .

Если вы ищете удобное настольное приложение для взаимодействия с вашим API, я бы порекомендовал попробовать Postman.

Вот и все. Теперь вы можете запустить нашего воркера с помощью npm start (или развернуть его в рабочей среде с помощью npm run deploy ) и увидеть свой API в действии с хранилищем данных!

Краткое содержание

Надеюсь, если вы следовали этому примеру, у вас теперь есть API с работающим хранилищем данных, и, тем не менее, все это бесплатно с помощью Cloudflare (если только ваш API не станет чрезвычайно популярным, но это хорошая проблема!).

Вы можете столкнуться с разным временем задержки при использовании KV, так как ваши данные хранятся в центральных центрах обработки данных и кэшируются более локально. Таким образом, в зависимости от того, где он повторно пытается получить информацию, время отклика может варьироваться, но, по моему опыту, в производственной среде оно всегда находится в пределах 150 мс. Более того, чем чаще к вашим данным обращаются, тем больше вероятность того, что они будут возвращены из кэша.

Если вам нужны более сильные гарантии согласованности, которые дает KV, я бы порекомендовал взглянуть на их Durable Objects. Он не работает как согласованный в конечном счете, поскольку в каждый момент времени существует только один объект. Тем не менее, есть небольшие затраты.

Теперь я использую Cloudflare для быстрого и недорогого прототипирования API и веб-сайтов во всех своих небольших сторонних проектах. Я думаю, что их инструменты невероятно просты в использовании, а показатели их использования на бесплатном уровне невероятно щедры.

Для получения дополнительной информации я рекомендую прочитать KV docs или прочитать более подробно о том, как KV работает. Вы можете увидеть полный исходный код здесь, а изменения между этой версией API и предыдущей — здесь.

My book, Creating Software with Modern Diagramming Techniques, is out now!
Click here to learn how to create diagrams to communicate information more directly and clearly than words ever can. Using only text-based markup, powered by Mermaid, create meaningful and attractive diagrams to document your domain, visualize user flows, reveal system architecture at any desired level, and much more!