Собственный сервис базы данных

Около 5 мин...

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

// index.js
const Application = require('@waline/vercel');

module.exports = Application({
  model: class CustomModel {},
});

Waline предоставляет параметр model для настройки модели базы данных, и все операции с базой данных единообразно выполняются через переданную модель. Остаётся только реализовать этот класс CustomModel.

class CustomModel {
  constructor(tableName) {
    this.tableName = tableName;
  }

  async select(where, { desc, limit, offset, field, order } = {}) {
    //to be implemented
  }

  async count(where = {}, options = {}) {
    //to be implemented
  }

  async add(data, { access } = { access: { read: true, write: true } }) {
    //to be implemented
  }

  async update(data, where) {
    //to be implemented
  }

  async delete(where) {
    //to be implemented
  }
}

Выше приведена базовая структура, которую должен реализовать класс CustomModel: в неё обязательно входят методы select, add, update, delete и count. Waline разработан на основе фреймворка ThinkJS, а операции с базой данных на нижнем уровне используют синтаксис, встроенный в этот фреймворк. Прежде чем реализовывать эти методы, нужно иметь базовое представление о синтаксисе условных запросов к базе данных.

Условные запросы

Полный синтаксис условных запросов описан в документации ThinkJS; реализация в Waline является его подмножеством.

В объект можно передать несколько условий запроса; по умолчанию используется сравнение на равенство. Если значение является двумерным массивом, первый элемент задаёт операцию сравнения, а второй соответствует значению, например {user_id: ['!=', 0]}. Сейчас поддерживаются операции !=, >, IN, NOT IN и LIKE.

Как и в MySQL, в операции LIKE режим нечёткого поиска задаётся положением %:

content% — поиск строк, начинающихся с content
%content — поиск строк, заканчивающихся на content
%content% — поиск строк, содержащих content

Объект условного запроса поддерживает несколько условий. По умолчанию они связываются через AND, а специальное ключевое слово _logic позволяет указать связь OR. Если нужны одновременно AND и OR, используется специальное ключевое слово _complex.

Возможно, по тексту это понять непросто, поэтому рассмотрим примеры запросов, используемых в проекте.

Обычный запрос:

const model = new CustomModel('Comment');
await model.select({
  url: '/',
  user_id: ['!=', 0],
  createdAt: ['>', '2023-04-16 00:00:00'],
});
// SELECT * FROM Comment WHERE url = '/' AND user_id != 0 AND createdAt > "2023-04-16 00:00:00";

Запрос IN / NOT IN

const model = new CustomModel('Users');
await model.select({ objectId: ['IN', [1, 2, 3, 4]] });
// SELECT * FROM Users WHERE objectId IN (1,2,3,4);

const model = new CustomModel('Comment');
await model.select({ status: ['NOT IN', ['waiting', 'spam']] });
// SELECT * FROM Comment WHERE status NOT IN ('waiting', 'spam');

Запрос LIKE

const model = new CustomModel('Comment');
await model.select({ content: ['LIKE', '%content%'] });
// SELECT * FROM Comment WHERE content LIKE "%content%";

Запрос с несколькими условиями

const model = new CustomModel('Comment');
await model.select({
  url: '/',
  user_id: ['!=', 0],
  createdAt: ['>', '2023-04-16 00:00:00'],
  _logic: 'OR',
});
// SELECT * FROM Comment WHERE url = '/' OR user_id != 0 OR createdAt > "2023-04-16 00:00:00";

Составной запрос

const model = new CustomModel('Comment');
await model. select({
  url: '/',
  _complex: {
    user_id: 0,
    status: ['NOT IN', ['waiting', 'spam']]
    _logic: 'OR'
  }
});
// SELECT * FROM Comment WHERE url = '/' AND ( user_id = 0 OR status NOT IN ('waiting', 'spam'));

Тем, кто хорошо знаком с TypeScript, пригодятся определения типов для условных запросов.

Реализация запросов

Методы select, update, delete и count в адаптере на самом деле сложны именно в части условных запросов. После освоения синтаксиса из предыдущего раздела остальная логика — это уже непосредственно операции с базой данных.

У метода select() есть второй аргумент {desc, limit, offset, field}. Его тоже несложно понять:

desc: указывает поле, по которому данные сортируются по убыванию значения этого поля
limit: указывает количество возвращаемых записей
offset: указывает, начиная с какой записи возвращать данные
field: указывает поля, данные которых нужно вернуть; по умолчанию возвращаются все поля

Метод update() должен поддерживать сценарии, когда входной параметр data является функцией вычисления, например для увеличения счётчика просмотров страницы на 1:

const model = new CustomModel('Count');
await model.update((thread) => ({ view: thread.view + 1 }), { url: '/' });

Типы возвращаемых данных: select() всегда возвращает массив, а add() и update() должны возвращать полные данные записи.

Пример для справки

Опираясь на описанную логику, разработчики Waline, помимо сервисов хранения на профессиональных базах данных, реализовали довольно любопытный сервис хранения на GitHub. Данные хранятся в GitHub в виде CSV-файла: при каждом запросе читается содержимое CSV-файла, затем в JS данные фильтруются по условиям запроса, и результат возвращается. Ниже приведена официальная реализация — возможно, она будет полезна как образец.

//source code: https://github.com/walinejs/waline/blob/main/packages/server/src/service/storage/github.js

const path = require('path');

const { parseString, writeToString } = require('fast-csv');

const Base = require('./base');

const CSV_HEADERS = {
  Comment: [
    'objectId',
    'user_id',
    'comment',
    'insertedAt',
    'ip',
    'link',
    'mail',
    'nick',
    'pid',
    'rid',
    'status',
    'ua',
    'url',
    'createdAt',
    'updatedAt',
  ],
  Counter: ['objectId', 'time', 'url', 'createdAt', 'updatedAt'],
  Users: [
    'objectId',
    'display_name',
    'email',
    'password',
    'type',
    'url',
    'avatar',
    'label',
    'github',
    'twitter',
    'facebook',
    'google',
    'weibo',
    'qq',
    'createdAt',
    'updatedAt',
  ],
};

class Github {
  constructor(repo, token) {
    this.token = token;
    this.repo = repo;
  }

  // content api can only get file < 1MB
  async get(filename) {
    const resp = await fetch(
      'https://api.github.com/repos/' + path.join(this.repo, 'contents', filename),
      {
        headers: {
          accept: 'application/vnd.github.v3+json',
          authorization: 'token ' + this.token,
          'user-agent': 'Waline',
        },
      },
    )
      .then((resp) => resp.json())
      .catch((e) => {
        const isTooLarge = e.message.includes('"too_large"');

        if (!isTooLarge) {
          throw e;
        }

        return this.getLargeFile(filename);
      });

    return {
      data: Buffer.from(resp.content, 'base64').toString('utf-8'),
      sha: resp.sha,
    };
  }

  // blob api can get file larger than 1MB
  async getLargeFile(filename) {
    const { tree } = await fetch(
      'https://api.github.com/repos/' + path.join(this.repo, 'git/trees/HEAD') + '?recursive=1',
      {
        headers: {
          accept: 'application/vnd.github.v3+json',
          authorization: 'token ' + this.token,
          'user-agent': 'Waline',
        },
      },
    ).then((resp) => resp.json());

    const file = tree.find(({ path }) => path === filename);

    if (!file) {
      const error = new Error('NOT FOUND');

      error.statusCode = 404;
      throw error;
    }

    return fetch(file.url, {
      headers: {
        accept: 'application/vnd.github.v3+json',
        authorization: 'token ' + this.token,
        'user-agent': 'Waline',
      },
    }).then((resp) => resp.json());
  }

  async set(filename, content, { sha }) {
    return fetch('https://api.github.com/repos/' + path.join(this.repo, 'contents', filename), {
      method: 'PUT',
      headers: {
        accept: 'application/vnd.github.v3+json',
        authorization: 'token ' + this.token,
        'user-agent': 'Waline',
      },
      body: JSON.stringify({
        sha,
        message: 'feat(waline): update comment data',
        content: Buffer.from(content, 'utf-8').toString('base64'),
      }),
    });
  }
}

module.exports = class extends Base {
  constructor(tableName) {
    super();
    this.tableName = tableName;

    const { GITHUB_TOKEN, GITHUB_REPO, GITHUB_PATH } = process.env;

    this.git = new Github(GITHUB_REPO, GITHUB_TOKEN);
    this.basePath = GITHUB_PATH;
  }

  async collection(tableName) {
    const filename = path.join(this.basePath, tableName + '.csv');
    const file = await this.git.get(filename).catch((e) => {
      if (e.statusCode === 404) {
        return '';
      }
      throw e;
    });

    return new Promise((resolve, reject) => {
      const data = [];

      data.sha = file.sha;

      return parseString(file.data, {
        headers: file ? true : CSV_HEADERS[tableName],
      })
        .on('error', reject)
        .on('data', (row) => data.push(row))
        .on('end', () => resolve(data));
    });
  }

  async save(tableName, data, sha) {
    const filename = path.join(this.basePath, tableName + '.csv');
    const csv = await writeToString(data, {
      headers: sha ? true : CSV_HEADERS[tableName],
      writeHeaders: true,
    });

    return this.git.set(filename, csv, { sha });
  }

  parseWhere(where) {
    const _where = [];

    if (think.isEmpty(where)) {
      return _where;
    }

    const filters = [];

    for (let k in where) {
      if (k === '_complex') {
        continue;
      }

      if (k === 'objectId') {
        filters.push((item) => item.id === where[k]);
        continue;
      }
      if (think.isString(where[k])) {
        filters.push((item) => item[k] === where[k]);
        continue;
      }
      if (where[k] === undefined) {
        filters.push((item) => item[k] === null || item[k] === undefined);
      }
      if (!Array.isArray(where[k]) || !where[k][0]) {
        continue;
      }

      const handler = where[k][0].toUpperCase();

      switch (handler) {
        case 'IN':
          filters.push((item) => where[k][1].includes(item[k]));
          break;
        case 'NOT IN':
          filters.push((item) => !where[k][1].includes(item[k]));
          break;
        case 'LIKE': {
          const first = where[k][1][0];
          const last = where[k][1].slice(-1);
          let reg;

          if (first === '%' && last === '%') {
            reg = new RegExp(where[k][1].slice(1, -1));
          } else if (first === '%') {
            reg = new RegExp(where[k][1].slice(1) + '$');
          } else if (last === '%') {
            reg = new RegExp('^' + where[k][1].slice(0, -1));
          }
          filters.push((item) => reg.test(item[k]));
          break;
        }
        case '!=':
          filters.push((item) => item[k] !== where[k][1]);
          break;
        case '>':
          filters.push((item) => item[k] >= where[k][1]);
          break;
      }
    }

    return filters;
  }

  where(data, where) {
    const filter = this.parseWhere(where);

    if (!where._complex) {
      return data.filter((item) => filter.every((fn) => fn(item)));
    }

    const logicMap = {
      and: Array.prototype.every,
      or: Array.prototype.some,
    };
    const filters = [];

    for (const k in where._complex) {
      if (k === '_logic') {
        continue;
      }

      filters.push([...filter, ...this.parseWhere({ [k]: where._complex[k] })]);
    }

    const logicFn = logicMap[where._complex._logic];

    return data.filter((item) => logicFn.call(filters, (filter) => filter.every((fn) => fn(item))));
  }

  async select(where, { desc, limit, offset, field, order } = {}) {
    const instance = await this.collection(this.tableName);
    let data = this.where(instance, where);

    if (desc) {
      data.sort((a, b) => {
        if (['insertedAt', 'createdAt', 'updatedAt'].includes(desc)) {
          const aTime = new Date(a[desc]).getTime();
          const bTime = new Date(b[desc]).getTime();

          return bTime - aTime;
        }

        return a[desc] - b[desc];
      });
    }

    data = data.slice(limit || 0, offset || data.length);
    if (field) {
      field.push('id');
      const fieldObj = {};

      field.forEach((f) => (fieldObj[f] = true));
      data = data.map((item) => {
        const ret = {};

        for (const k in item) {
          if (fieldObj[k]) {
            ret[k] = item[k];
          }
        }

        return ret;
      });
    }

    return data.map(({ id, ...cmt }) => ({ ...cmt, objectId: id }));
  }

  async count(where = {}, { group } = {}) {
    const instance = await this.collection(this.tableName);
    const data = this.where(instance, where);

    if (!group) {
      return data.length;
    }

    const counts = {};

    for (let i = 0; i < data.length; i++) {
      const key = group.map((field) => data[field]).join();

      if (!counts[key]) {
        counts[key] = { count: 0 };
        group.forEach((field) => {
          counts[key][field] = data[field];
        });
      }
      counts[key].count += 1;
    }

    return Object.keys(counts);
  }

  async add(
    data,
    // { access: { read = true, write = true } = { read: true, write: true } } = {}
  ) {
    const instance = await this.collection(this.tableName);
    const id = Math.random().toString(36).substr(2, 15);

    instance.push({ ...data, id });
    await this.save(this.tableName, instance, instance.sha);

    return { ...data, objectId: id };
  }

  async update(data, where) {
    delete data.objectId;

    const instance = await this.collection(this.tableName);
    const list = this.where(instance, where);

    list.forEach((item) => {
      if (typeof data === 'function') {
        data(item);
      } else {
        for (const k in data) {
          item[k] = data[k];
        }
      }
    });
    await this.save(this.tableName, instance, instance.sha);

    return list;
  }

  async delete(where) {
    const instance = await this.collection(this.tableName);
    const deleteData = this.where(instance, where);
    const deleteId = deleteData.map(({ id }) => id);
    const data = instance.filter((data) => !deleteId.includes(data.id));

    await this.save(this.tableName, data, instance.sha);
  }
};

TIPS: Область комментариев предназначена только для демонстрации. Если у вас есть вопросы, пожалуйста, перейдите на Github Discussion чтобы задать их.