Gerando UIs de CRUD Dinâmicas no React a partir de Metadados do Banco

Telas administrativas se repetem: listagem com filtros, formulário de criação, edição, exclusão. Escrever cada uma à mão significa dezenas de componentes quase idênticos, cada um com seus pequenos desvios e bugs. A alternativa é uma UI guiada por schema (schema-driven UI): o schema descreve a entidade e a interface é derivada dele.

Neste artigo vou mostrar como projetar uma biblioteca interna com essa ideia usando JSON Schema, mantendo a tipagem com TypeScript e gerando consultas complexas a partir de query params.


Por que schema-driven?

  • Menos código repetido: uma nova entidade vira um schema, não um conjunto de telas.
  • Consistência: todas as telas se comportam da mesma forma.
  • Uma fonte da verdade: validação, formulário, tabela e tipos nascem do mesmo lugar.
  • Evolução centralizada: melhorar o componente de data melhora todas as telas.

O custo é uma biblioteca para manter e uma camada de abstração. Vale a pena quando você tem muitas entidades parecidas, que é o caso típico de um backoffice.


JSON Schema como fonte da verdade

O JSON Schema é um padrão maduro, com validadores e ferramentas em várias linguagens, o que permite compartilhá-lo entre backend e frontend. Os metadados podem vir do banco (colunas, tipos, nulabilidade, constraints) e ser convertidos em schema, ou ser mantidos como arquivos versionados.

{
  "$id": "veiculo",
  "type": "object",
  "required": ["placa", "tipo"],
  "properties": {
    "placa": { "type": "string", "pattern": "^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$", "title": "Placa" },
    "tipo": { "type": "string", "enum": ["TRUCK", "CARRETA", "VUC"], "title": "Tipo" },
    "capacidadeKg": { "type": "number", "minimum": 0, "title": "Capacidade (kg)" },
    "ativo": { "type": "boolean", "title": "Ativo", "default": true }
  }
}

Dele derivamos quase tudo:

  • Formulário: string vira input, enum vira select, boolean vira switch, format: "date" vira datepicker.
  • Validação: o mesmo schema valida no cliente (Ajv) e no servidor.
  • Colunas da tabela: as properties viram colunas, com title como cabeçalho.
  • Filtros: o tipo do campo define quais operadores fazem sentido (texto: contém; número: maior/menor; enum: está em).
  • Tipos TypeScript: a tipagem é gerada ou inferida do schema, sem duplicação.

Mantendo a tipagem com TypeScript

Existem duas abordagens principais:

1. Inferência em tempo de compilação com json-schema-to-ts. O schema precisa ser declarado as const:

import type { FromSchema } from 'json-schema-to-ts';

export const veiculoSchema = {
  $id: 'veiculo',
  type: 'object',
  required: ['placa', 'tipo'],
  properties: {
    placa: { type: 'string', title: 'Placa' },
    tipo: { type: 'string', enum: ['TRUCK', 'CARRETA', 'VUC'], title: 'Tipo' },
    capacidadeKg: { type: 'number', title: 'Capacidade (kg)' },
    ativo: { type: 'boolean', title: 'Ativo' },
  },
} as const;

export type Veiculo = FromSchema<typeof veiculoSchema>;
// { placa: string; tipo: 'TRUCK' | 'CARRETA' | 'VUC'; capacidadeKg?: number; ativo?: boolean }

2. Geração de código com json-schema-to-typescript, útil quando os schemas vêm do backend e você quer gerar arquivos .d.ts no build.

Com qualquer uma delas, o componente genérico recebe o tipo e o compilador cobra consistência:

type SchemaFormProps<T> = {
  schema: JSONSchema;
  defaultValues?: Partial<T>;
  onSubmit: (values: T) => Promise<void>;
};

Um renderizador por tipo

O coração da biblioteca é um registro que mapeia tipos de campo para componentes:

const registry: Record<string, React.FC<FieldProps>> = {
  string: TextField,
  number: NumberField,
  boolean: SwitchField,
  enum: SelectField,
  date: DateField,
};

function resolverTipo(def: JSONSchema) {
  if (def.enum) return 'enum';
  if (def.format === 'date') return 'date';
  return def.type as string;
}

export function SchemaForm<T>({ schema, onSubmit, defaultValues }: SchemaFormProps<T>) {
  const methods = useForm<T>({ defaultValues, resolver: ajvResolver(schema) });

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        {Object.entries(schema.properties).map(([name, def]) => {
          const Field = registry[resolverTipo(def)];
          return <Field key={name} name={name} schema={def} required={schema.required?.includes(name)} />;
        })}
        <Button type="submit">Salvar</Button>
      </form>
    </FormProvider>
  );
}

Extensões para casos fora do padrão

Nem toda tela cabe no padrão. Use propriedades customizadas (prefixo x-, que o JSON Schema permite) para ajustar a UI sem quebrar a validação:

{
  "motorista": {
    "type": "string",
    "title": "Motorista",
    "x-component": "AsyncSelect",
    "x-source": "/motoristas",
    "x-order": 2
  },
  "observacao": { "type": "string", "x-hidden": true }
}

E permita overrides por entidade, para substituir um campo ou uma coluna por um componente próprio. O objetivo é cobrir 80% das telas e não bloquear os outros 20%.


Consultas complexas via query params

A parte que mais ganha valor é a listagem. Em vez de criar um endpoint por filtro, o front traduz o que o usuário escolhe na UI em query params padronizados:

GET /veiculos?filter[tipo]=in:TRUCK,CARRETA
             &filter[capacidadeKg]=gte:20000
             &filter[placa]=like:ABC
             &sort=-capacidadeKg
             &page=2&pageSize=20

No frontend

O estado dos filtros vive na URL, o que permite compartilhar, favoritar e recarregar a página sem perder o contexto:

function serializarFiltros(filtros: Filtro[]) {
  const params = new URLSearchParams();
  for (const { campo, operador, valor } of filtros) {
    params.set(`filter[${campo}]`, `${operador}:${Array.isArray(valor) ? valor.join(',') : valor}`);
  }
  return params;
}

No backend

Um parser converte os parâmetros em uma query, sempre validando contra o schema:

const operadores = {
  eq: (q, c, v) => q.where(c, v),
  ne: (q, c, v) => q.whereNot(c, v),
  gte: (q, c, v) => q.where(c, '>=', v),
  lte: (q, c, v) => q.where(c, '<=', v),
  in: (q, c, v) => q.whereIn(c, v.split(',')),
  like: (q, c, v) => q.whereILike(c, `%${v}%`),
};

function aplicarFiltros(query, filtros, schema) {
  for (const [campo, expr] of Object.entries(filtros)) {
    if (!(campo in schema.properties)) throw new BadRequest(`Campo inválido: ${campo}`);

    const [op, valor] = expr.split(/:(.+)/);
    if (!(op in operadores)) throw new BadRequest(`Operador inválido: ${op}`);

    operadores[op](query, campo, coagir(valor, schema.properties[campo]));
  }
  return query;
}

Relacionamentos e condições compostas

Para consultas mais ricas, a mesma ideia se estende:

  • Filtros em relações: filter[motorista.nome]=like:João, que o parser resolve com JOIN apenas se a relação estiver declarada no schema.
  • Grupos OR: filter[or][0][tipo]=eq:VUC&filter[or][1][capacidadeKg]=gte:20000.
  • Seleção de campos: fields=placa,tipo para reduzir o payload.
  • Paginação por cursor em tabelas grandes, no lugar de OFFSET, que degrada com páginas profundas.

Cuidados inegociáveis

  1. Whitelist de campos e operadores definida pelo schema, de modo que o usuário só filtra e ordena o que você permitiu (e idealmente só por colunas indexadas).
  2. Queries parametrizadas por meio de um query builder, nunca concatenando strings, para evitar SQL injection.
  3. Limite de paginação (pageSize máximo) e limite de profundidade/quantidade de filtros para impedir consultas que derrubam o banco.
  4. Coerção de tipos guiada pelo schema: "20000" na URL vira number antes de chegar à query.
  5. Autorização aplicada antes dos filtros do usuário (por exemplo, restringir ao tenant), nunca depois.

Juntando as peças: uma tela de CRUD

Com tudo isso, uma tela completa passa a ser pouco mais que configuração:

export function VeiculosPage() {
  return (
    <CrudPage
      schema={veiculoSchema}
      endpoint="/veiculos"
      columns={['placa', 'tipo', 'capacidadeKg', 'ativo']}
      filters={['tipo', 'capacidadeKg', 'placa']}
    />
  );
}

O CrudPage cuida da listagem, filtros na URL, paginação, formulário em modal, validação e mensagens de erro. O que sobra para a equipe é o que realmente é específico do negócio.


Armadilhas que vi no caminho

  • Abstração vazando: se toda tela precisa de override, o schema está pobre ou a biblioteca está rígida demais. Meça quantas telas precisam fugir do padrão.
  • Schema virando linguagem de programação: evite colocar lógica dentro do schema. Condicionais complexas devem ser exceções tratadas em código.
  • Performance de formulários grandes: use bibliotecas com inputs não controlados (como React Hook Form) e memoize os campos.
  • Mensagens de erro genéricas: traduza as mensagens do validador para o idioma e o vocabulário do usuário.

Conclusão

Uma UI guiada por schema transforma a criação de telas administrativas em uma atividade declarativa: descreva a entidade, e a interface, a validação, os tipos e até a API de consulta decorrem dela. O ganho de velocidade é grande, mas o maior valor é a consistência e a manutenção centralizada. Comece pequeno, com um registro de campos e uma listagem filtrável, e deixe as necessidades reais das telas guiarem a evolução da biblioteca.