Do esquema do banco a um ponto de partida para o desenvolvedor

Começar uma integração ou uma API costuma envolver trabalho repetitivo: conferir nomes de colunas, identificar chaves, traduzir tipos do banco, declarar propriedades e escrever uma primeira estrutura de acesso a dados. A aba Generate code do dbSlice ajuda nesse começo usando o esquema do objeto de banco escolhido como referência.

O desenvolvedor continua responsável pela aplicação. Os artefatos gerados trazem definições de campos e exemplos de implementação; eles não definem um sistema completo, as suas regras de negócio, as suas permissões nem a sua arquitetura. O valor está num ponto de partida concreto, que dá para inspecionar, adaptar e incorporar a um projeto existente.

Este guia segue a tela fornecida, em que a origem é o perfil SQL Server MASTER, a tabela escolhida é app_user e o artefato é C# — .NET Minimal API CRUD. As opções foram conferidas com a implementação do aplicativo que acompanha a tela. A disponibilidade pode variar conforme a versão e a licença.

1. Comece pela tabela e depois escolha o artefato

O gerador parte de uma tabela, de uma view ou da estrutura do resultado de uma consulta. As entradas dele descrevem um objeto e os seus campos. Elas não descrevem uma aplicação de negócio inteira.

Para esses artefatos baseados em esquema, a geração usa metadados, e não exporta os registros da tabela. Uma tabela com um milhão de linhas não vira um milhão de linhas de código de API. A geração em si não cria uma API rodando nem executa no banco o SQL gerado.

O esquema do banco é uma boa referência para os campos possíveis e os tipos das propriedades. Ele não consegue dizer ao gerador se um e-mail foi verificado, se um usuário pode mudar uma permissão ou se uma conta pode ser excluída. Essas decisões são da aplicação.

2. Leia a tela Generate code

MASTER é o nome de um perfil de conexão nesta demonstração. Target object é um nome de entrada para o artefato, não uma segunda conexão de banco. Conforme o gerador, o nome influencia classes, identificadores SQL, rotas ou outros nomes gerados; confira o resultado depois de mudá-lo.

A prévia deixa o artefato disponível para revisão antes de entrar num projeto. Salvar um arquivo não instala dependências, não aplica mudanças no banco, não sobe um servidor nem publica uma aplicação.

Na implementação revisada, o modo de avaliação permite gerar C# DTO, C# Model e SQL DDL. Outras opções podem continuar visíveis, mas exigem ativação. Confira o estado mostrado na versão instalada.

3. Os 12 artefatos e onde ajudam

Escolha o menor artefato que ajuda na tarefa. Um modelo pode bastar quando a necessidade imediata é uma lista de campos e tipos. Um esqueleto de API é útil quando o passo seguinte é explorar uma interface HTTP para aquele objeto.

O exemplo HTML/IndexedDB usa o armazenamento do navegador; ele não é uma conexão direta do navegador com o banco de origem. As saídas SQL são texto gerado, e o DDL não deve ser tratado como uma migração completa de banco, com todos os relacionamentos, índices, triggers e objetos dependentes.

4. Exemplo: entenda os campos de app_user

A tabela sintética app_user usada na demonstração tem oito colunas. A definição dela no SQL Server dá ao desenvolvedor um inventário concreto de campos:

Essas colunas não aceitam nulo no esquema de demonstração. A coluna is_active tem uma constraint no banco que a restringe a 0 ou 1, mas o tipo dela no banco continua sendo SMALLINT. O gerador C# revisado mapeia esse tipo para int; escolher uma propriedade booleana na aplicação exige uma decisão explícita de conversão.

Do mesmo jeito, uma chave estrangeira inteira não vira automaticamente uma propriedade de navegação, uma política de autorização ou uma lista preenchida por outra API. O esquema fala do armazenamento. A aplicação acrescenta significado e comportamento.

5. Use modelos e DTOs como referência editável de campos

O gerador C# Model traz propriedades tipadas. O gerador DTO acrescenta atributos derivados do esquema, como anotações de chave, de coluna e de obrigatoriedade. São referências úteis, mas o desenvolvedor ainda deve revisar nomes, namespaces, convenções de nulo e validação.

Por exemplo, um desenvolvedor pode adaptar um subconjunto da tabela neste tipo de resposta:

// Developer-adapted example, not verbatim generator output.
public sealed class UserSummary
{
    public int Id { get; init; }
    public string Username { get; init; } = string.Empty;
    public string DisplayName { get; init; } = string.Empty;
    public bool IsActive { get; init; }
}

Esta resposta inclui de propósito só quatro campos. Ela também usa um booleano no nível da aplicação para o status. O mapeamento precisa traduzir o valor guardado para essa representação. Uma requisição de criação ou uma atualização administrativa separada pode precisar de outro conjunto de campos.

Gerar uma classe com todas as colunas da tabela é um apoio para descobrir o formato. Não é uma decisão de expor todas as colunas numa API pública. Em particular, company_id, permission_id e created_at precisam de tratamento explícito, e não de aceitação automática vinda de qualquer chamador.

O Rust segue o mesmo princípio: a estrutura gerada é um mapa inicial de tipos. O gerador Rust revisado usa tipos da biblioteca padrão e representa valores de data e decimais como strings, para não impor crates adicionais. Escolha tipos de data ou decimal mais ricos se o projeto precisar.

6. Os mapeadores deixam as atribuições visíveis

O artefato C# Mapper cria atribuições explícitas de propriedades entre as classes de modelo e de DTO geradas. Isso ajuda a definir qual propriedade de origem alimenta cada propriedade de destino, sem acrescentar uma biblioteca de mapeamento.

Depois de gerar, alinhe os namespaces e os nomes de tipo com as classes do seu projeto. Se o DTO foi reduzido, renomeado ou ganhou outro tipo, atualize o mapeamento dele. Acrescente de forma deliberada qualquer conversão ou normalização necessária.

Um método que copia propriedades não implementa validação de negócio. Também não se deve supor que um método de mapeamento gerado vire SQL do banco quando chamado dentro de uma consulta LINQ. Confira o comportamento da consulta com a tecnologia de acesso a dados usada pelo projeto.

7. Comece uma API sem confundir esqueleto com desenho da aplicação

A opção Minimal API mostrada na captura traz uma estrutura inicial para as operações em volta da tabela escolhida. A prévia inclui o registro das rotas e o SQL para listar, buscar, criar, atualizar e excluir registros.

Isso pode ajudar um programador a ligar os campos de uma tabela a um primeiro desenho de API: identificar a chave correspondente, ver os parâmetros candidatos, inspecionar como os valores chegam aos comandos do banco e decidir onde entram os tipos de requisição e de resposta.

Os próximos passos de desenho continuam explícitos:

• Decida quais operações a aplicação realmente precisa; uma rota DELETE genérica pode não servir para o ciclo de vida de uma conta.
• Separe os modelos de requisição e de resposta do formato completo de armazenamento.
• Defina autenticação, autorização e os limites de empresa ou de tenant.
• Implemente a validação e regras como quem pode atribuir permissões ou ativar uma conta.
• Configure o provider, as dependências, as configurações de conexão, as respostas de erro e o comportamento operacional para o projeto.
• Compile e teste a implementação adaptada, inclusive requisições recusadas e falhas do banco.

Isso faz parte de transformar um exemplo gerado num componente da aplicação. Um esqueleto de CRUD traz a mecânica inicial; ele não deduz as regras de gestão de contas a partir do nome app_user.

As mesmas expectativas valem para os artefatos de repositório, PHP e Node.js. Revise as notas de configuração geradas e os requisitos de provider. O fato de o dbSlice suportar um banco de origem não dispensa o projeto de destino do runtime, do pacote ou do driver adequado.

8. Um fluxo prático na interface

1. Abra Generate code e escolha a conexão de origem salva.
2. Clique em Connect, escolha Table e depois app_user.
3. Confirme id como chave e revise app_user em Target object.
4. Comece pelo C# Model para inspecionar os campos e os tipos candidatos.
5. Clique em Generate e leia a prévia, inclusive os nomes e os campos que aceitam nulo.
6. Use Save file ou Copy code para levar o artefato ao seu ambiente de desenvolvimento.
7. Escolha C# DTO ou C# Mapper se esses artefatos ajudarem no desenho do projeto.
8. Escolha C# — .NET Minimal API CRUD quando quiser revisar um ponto de partida de API.
9. Adapte o material gerado às convenções e às regras de negócio do projeto, e depois compile e teste.

Use uma tabela num primeiro exemplo simples. Views e consultas podem servir para uma projeção mais estreita, mas os metadados delas podem não identificar chaves e relacionamentos com a mesma clareza. Confirme a chave escolhida e não suponha que dá para gravar numa view ou numa consulta com join usando comandos CRUD genéricos.

9. Separe a geração da responsabilidade pelo código

Depois que um artefato entra num projeto, os desenvolvedores do projeto respondem pelo comportamento dele. Uma mudança posterior no esquema deve levar a uma comparação com a implementação existente, e não a uma sobrescrita automática do trabalho feito à mão.

Gere uma referência nova num lugar separado, compare campos e tipos e aplique as mudanças pertinentes pelo processo de revisão do projeto. Uma coluna nova no banco não pertence necessariamente a uma resposta de API existente, e uma mudança de nulo pode exigir mais do que atualizar a declaração de uma propriedade.

Os cabeçalhos gerados e os exemplos de configuração também devem ser revisados antes de compartilhar os arquivos. Mantenha as configurações de conexão e as credenciais reais no mecanismo de configuração do projeto, em vez de colocá-las em exemplos publicados ou no código versionado.

10. Onde o gerador poupa trabalho

O dbSlice ajuda a transformar um objeto do banco em algo com que o programador trabalha na hora: um inventário visível de campos, tipos candidatos da linguagem, propriedades de modelo, atribuições de mapeamento e padrões iniciais de operação no banco.

Esse é o papel pretendido do gerador: apoio ao desenvolvedor baseado no esquema da tabela. Ele reduz a configuração repetitiva e dá uma referência para o próximo passo da implementação. O programador traz o desenho da aplicação, o comportamento e as decisões que uma definição de tabela não consegue expressar.

Escopo deste guia

A lista de artefatos e os controles da tela foram conferidos com a captura fornecida e com o painel e os geradores de código que a acompanham. Os exemplos de campos usam o esquema sintético app_user deste conjunto de dados de documentação. O trecho UserSummary é uma adaptação ilustrativa de um desenvolvedor, não a saída exata do gerador.

Nenhuma API foi publicada nem conectada a um banco em uso para escrever este artigo. A captura original é usada como referência; os nomes de perfis de conexão sem relação com o tema não entram na publicação. Este guia documenta um fluxo de desenvolvimento, sem afirmar que os artefatos gerados formam um sistema completo ou pronto para produção.