Estrutura do Projeto

Compreender a estrutura de projeto padrão no Vaden é fundamental para manter aplicações limpas e escaláveis. Abaixo está uma visão geral de como um projeto típico do Vaden é organizado.

meu_projeto_vaden/
├── bin/
│   └── server.dart               # Ponto de entrada do servidor (arquivo principal)
├── lib/
│   ├── config/                    # Arquivos de configuração da aplicação (ex: OpenAPI, configurações)
│   ├── src/                      # Código real da aplicação (controladores, serviços, etc)
│   └── vaden_application.dart    # Arquivo gerado pelo vaden_class_scanner
├── application.yaml              # Configuração do Vaden
├── pubspec.yaml                  # Gerenciador de dependências do projeto
└── build.yaml                    # Configuração do build_runner

bin/server.dart

Este é o ponto de entrada principal da sua aplicação. Ele carrega o vaden_application.dart gerado e inicia o servidor HTTP:

import 'package:my_vaden_project/vaden_application.dart';
import 'package:shelf/shelf_io.dart';

void main() async {
  final app = await createApplication();
  await serve(app.handler, 'localhost', 8080);
}

lib/vaden_application.dart

Este arquivo é gerado automaticamente pelo vaden_class_scanner. Ele escaneia todas as anotações (@Controller, @Service, @Bean, etc.) e compõe a instância completa da aplicação com roteamento, injeção de dependência e configuração de middleware. Você não deve editar este arquivo manualmente.

lib/config/

Esta pasta contém arquivos e classes de configuração. Por exemplo:

• openapi.dart – declara a estrutura da OpenAPI.
• app_config.dart – fornece beans usando @Configuration() e @Bean().
• settings.dart – carrega e representa configurações da aplicação a partir de YAML.

lib/src/

Aqui é onde reside a lógica de negócio real. É onde você define:

• controllers/ – manipuladores de rotas usando @Controller.
• services/ – serviços injetáveis usando @Service.
• repositories/ – lógica de persistência usando @Repository.
• dtos/ – estruturas de dados e DTOs usando @DTO.
• middlewares/ – interceptadores de requisição usando Middleware.
• guards/ – verificações de autorização usando Guard.

Você tem liberdade para organizar esta pasta de qualquer forma que se adeque à sua arquitetura.

application.yaml

Este arquivo opcional pode ser colocado na raiz do seu projeto e é usado para configurar configurações globais do Vaden. Funciona de forma semelhante a arquivos .env em outros frameworks, mas com sintaxe YAML.

Uso típico inclui:

• Declarar porta e host do servidor
• Definir provedor de armazenamento (local, s3, firebase)
• Configurar acesso ao banco de dados
• Fornecer metadados da OpenAPI

Exemplo:

server:
  port: 8080
  host: localhost

database:
  provider: postgres
  postgres:
    host: localhost
    port: 5432
    database: my_app
    username: user
    password: pass

openapi:
  title: My API
  version: 1.0.0
  description: Auto-generated by Vaden

Os valores em application.yaml são automaticamente carregados em ApplicationSettings, que pode ser injetado usando @Bean() para serviços baseados em configuração.