Serviço de banco de dados personalizado

About 6 min...

O Waline classifica as operações de banco de dados em algumas operações básicas, como CRUD, e toda a lógica de nível superior é construída pela combinação dessas operações. Por meio do modo adaptador, diferentes tipos de serviços de armazenamento de banco de dados só precisam implementar essas operações atômicas de baixo nível para que toda a lógica do sistema funcione.

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

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

O Waline fornece a opção model para personalizar o modelo de banco de dados, e passa a usar de forma uniforme o modelo recebido nas operações de banco de dados. Resta apenas implementar essa classe 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
  }
}

A estrutura acima é a base que a classe CustomModel precisa implementar, incluindo os métodos básicos select, add, update, delete e count. O Waline é desenvolvido com base no framework ThinkJS, e as operações de banco de dados de baixo nível usam a sintaxe de operação de banco de dados fornecida pelo framework. Antes de implementar esses métodos, você precisa ter noções básicas da sintaxe de consultas condicionais de banco de dados.

Consultas condicionais

Para a sintaxe completa de consultas condicionais, consulte a documentação do ThinkJS; a implementação do Waline é um subconjunto dela.

É possível passar várias condições de consulta por meio do objeto, e o padrão é a igualdade. Quando o valor é um array bidimensional, a primeira posição recebe o operador de comparação e a segunda corresponde ao valor, como em {user_id: ['!=', 0]}. Atualmente são suportadas as operações !=, >, IN, NOT IN e LIKE.

Assim como no MySQL, na operação LIKE definimos o modo da busca difusa pela posição do %:

content%: busca por conteúdo que começa com content
%content: busca por conteúdo que termina com content
%content%: busca por conteúdo que contém content

O objeto de consulta condicional aceita várias condições de consulta. Por padrão, a relação entre elas é AND, e a palavra-chave especial _logic pode ser usada para defini-las como OR. Quando houver AND e OR ao mesmo tempo, podemos usar a palavra-chave especial _complex.

Talvez o texto não seja muito claro. Vejamos alguns exemplos de consultas usadas no projeto para fixar melhor a ideia.

Consulta simples:

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";

Consulta 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');

Consulta LIKE

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

Consulta com múltiplas condições

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";

Consulta composta

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'));

Se você tiver mais familiaridade com TypeScript, as definições de tipo para consultas condicionais estão aqui.

Implementar a consulta

Os métodos select, update, delete e count do adaptador são complexos justamente por causa da consulta condicional. Depois de entender a sintaxe de consulta condicional da seção anterior, o restante da lógica é apenas a operação no banco de dados.

O método select() tem um segundo argumento {desc, limit, offset, field}, que também é fácil de entender:

desc: campo pelo qual ordenar em ordem decrescente de valor
limit: quantidade de registros retornados
offset: a partir de qual registro os dados são retornados
field: campos a retornar; por padrão, todos os campos são retornados

O método update() precisa ser compatível com cenários em que o parâmetro data pode ser uma função de cálculo, como somar 1 ao número de visualizações da página:

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

Quanto ao tipo de retorno: select() sempre retorna um array; add() e update() precisam incluir os dados completos do registro indexado.

Referência

Com base na lógica acima, além de implementar o serviço de armazenamento de bancos de dados profissionais, a equipe oficial também implementou, de forma bem interessante, um serviço de armazenamento no GitHub. Armazenamos os dados no GitHub na forma de um arquivo CSV, obtemos o conteúdo do CSV a cada consulta e filtramos os dados finais em JS de acordo com a consulta condicional, retornando o resultado. A implementação oficial é mostrada abaixo e pode servir de referência.

//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: A área de comentários é apenas para demonstração. Se você tiver alguma dúvida, vá para Github Discussion para perguntar.