Visão geral do modelo de programação

O SDK do Rayfin usa um modelo de programação controlado por decoradores em que você define seu esquema de dados uma vez no TypeScript e recebe automaticamente APIs prontas para produção, clientes type-safe e infraestrutura.

Conceitos principais

O SDK do Rayfin combina três elementos principais:

• Esquema controlado por decoradores: use decoradores TypeScript para definir modelos de dados, permissões e relações.
• Geração automática de APIs: Suas classes decoradas se tornam endpoints GraphQL sem precisar escrever código de controlador.
• Clientes com tipagem segura: os clientes TypeScript gerados fornecem validação em tempo de compilação para consultas e mutações.

Como funciona

Quando você cria um aplicativo Fabric, o código flui por estes estágios:

1. Definir modelos de dados com decoradores

Você define sua estrutura de dados usando classes TypeScript e decoradores de @microsoft/rayfin-core:

import { entity, uuid, text, int } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @text({ optional: true }) description?: string;
  @int() price!: number;
}

2. Geração de esquema

A CLI do Rayfin (npx rayfin) analisa suas classes decoradas e gera:

• Esquema de banco de dados – Tabelas, colunas, restrições e índices
• Configuração da API – definições de ponto de extremidade do GraphQL
• Políticas de permissão – segurança em nível de linha e controle de acesso em nível de campo

4. Uso do cliente com segurança de tipo

As APIs do GraphQL estão disponíveis para executar operações CRUD em seu banco de dados. O SDK do Rayfin fornece, pronta para uso, uma operação do cliente de dados para ler, gravar ou excluir dados.

import { RayfinClient } from '@microsoft/rayfin-client';

const client = new RayfinClient();

// TypeScript knows about Product fields
const products = await client.data.products.query()
  .select(['id', 'name', 'price'])
  .execute();

// Compile-time error if field doesn't exist
const invalid = await client.data.products.query()
  .select(['nonexistentField'])  // ❌ TypeScript error
  .execute();

Referência do decorador

O SDK do Rayfin fornece decoradores para padrões comuns de modelagem de dados:

Decoradores de entidade

Decoradores de propriedades

Decoradores de permissão

Consulte Definir permissões de dados para obter detalhes de autorização.

Fluxo de trabalho de desenvolvimento

Um ciclo de desenvolvimento típico segue este padrão:

1. Definir ou modificar modelos de dados – Adicionar ou atualizar classes TypeScript com decoradores
2. Teste localmente com backend remoto - Execute npm run dev para testar as alterações no código do frontend com o backend do seu aplicativo no Fabric.
3. Implantar no Fabric - Execute npx rayfin up para implantar no serviço Fabric gerenciado e aplicar as alterações no esquema.

As alterações nos seus modelos TypeScript se propagam automaticamente em toda a stack — do schema do banco de dados aos endpoints da API e aos tipos do cliente.

Authorization

As permissões são definidas junto com seus modelos de dados usando o @role decorador:

@entity()
@role('authenticated', ['create', 'read', 'update', 'delete'], {
  policy: (claims, item) => claims.sub.eq(item.userId)
})
export class UserDocument {
  @uuid() id!: string;
  @text() userId!: string;
  @text() content!: string;
}

Essa abordagem garante:

• As regras de segurança residem ao lado dos dados protegidos
• Expressões de política de segurança de tipo capturam erros em tempo de compilação
• A refatoração de campos de entidade atualiza automaticamente as verificações de permissão

Conteúdo relacionado

• Visão geral dos modelos de dados
• Definir permissões de dados
• Consultar dados com o GraphQL