Communitygithub.com

Criar DTO ou Objeto de Dados

Uma coleção crescente de habilidades de alta qualidade para assistentes de codificação com IA. Aprimore Codex, Claude Code, Cursor, Gemini CLI e agentes compatíveis com conhecimento especializado para Laravel, arquitetura de software, depuração, testes, segurança, qualidade de código, documentação e melhores práticas de engenharia.

O que é Criar DTO ou Objeto de Dados?

Esta skill capacita assistentes de codificação com IA (como Claude Code, Cursor, Codex e Gemini CLI) a criar Data Transfer Objects (DTOs) ou objetos de dados robustos e reutilizáveis em projetos Laravel. Ela é ideal quando dados precisam cruzar fronteiras do sistema — por exemplo, entre controllers, jobs, APIs, Livewire ou comandos — ou quando os mesmos dados são consumidos por múltiplos pontos finais. A skill padroniza o uso do pacote Spatie Laravel Data, promovendo classes `final readonly` com imutabilidade e tipagem moderna do PHP. Ela fornece um workflow claro que orienta desde a inspeção das convenções existentes até a aplicação de atributos específicos (`#[MapInputName]`, `#[WithCast]`, `#[ValidationAttribute]`, etc.) e a criação de construtores nomeados quando útil. Além disso, enfatiza que DTOs devem ser agnósticos ao cliente (não depender de Livewire, Blade ou controllers), colocar regras de validação próximas aos dados e incluir testes obrigatórios para construção, validação e serialização. A skill também inclui uma checklist de revisão e exemplos práticos (bom e ruim) para garantir que os desenvolvedores sigam as melhores práticas de arquitetura e segurança.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add AlizHarb/agent-skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Criar DTO ou Objeto de Dados faz?

Quando Usar

Use esta habilidade quando dados cruzarem uma fronteira ou precisarem ser reutilizados por web, API, Livewire, jobs, comandos ou integrações.

Entradas Necessárias

  • Campos, tipos, regras de validação, limites de origem, consumidores de saída, valores padrão e necessidades de serialização.

Fluxo de Trabalho

  1. Inspecione as convenções existentes de objetos de dados.
  2. Use Spatie Laravel Data por padrão, agora que está instalado. Se um estilo diferente de dados já existir em um módulo próximo, siga a convenção local.
  3. Prefira final readonly class com promotion de propriedades do construtor para DTOs imutáveis.
  4. Use atributos do Spatie Data onde eles se encaixam na propriedade:
    • #[MapInputName]
    • #[MapOutputName]
    • #[WithCast]
    • #[WithTransformer]
    • #[Computed]
    • #[ValidationAttribute] ou atributos de validação do pacote
    • #[DataCollectionOf]
    • #[Lazy]
    • #[Hidden]
    • #[LoadRelation] e #[LoadMissing]
    • #[Inject] ou atributos de injeção de propriedade quando o pacote ou a convenção do projeto os utiliza
  5. Use enums para conjuntos fechados e constantes de classe tipadas para contratos escalares reutilizáveis.
  6. Mantenha os DTOs agnósticos ao cliente.
  7. Adicione construtores nomeados como fromArray, fromRequest ou fromModel apenas quando forem úteis.
  8. Coloque regras de validação próximas aos DTOs quando a convenção do projeto suportar.
  9. Evite lógica de persistência, autorização ou fluxo de trabalho.
  10. Adicione testes para construção, regras de validação, serialização e casos de borda.

Arquivos Que Podem Ser Criados

  • app/Data/*.php, app/DTOs/*.php ou o equivalente local existente.
  • Testes para DTOs.

Arquivos Que Podem Ser Modificados

  • Form Requests, Actions, Resources, componentes Livewire, controllers, jobs e testes.

Regras de Arquitetura

  • DTOs representam contratos de entrada ou saída.
  • DTOs suportam reúso em API e UI.
  • DTOs não devem depender de Livewire, Blade, controllers ou respostas.
  • DTOs devem usar tipagem moderna do PHP em vez de arrays não estruturados sempre que prático.
  • Use coleções/recursos do Spatie Data quando um recurso precisar de formas de dados aninhadas, transformadas ou reutilizáveis.
  • Prefira atributos de validação do Spatie Data em vez de validação de array ad hoc dentro de código reutilizável.

Requisitos de Teste

  • Teste campos obrigatórios, conversão de tipos, valores padrão, dados inválidos e serialização se exposta.

Requisitos de Segurança

  • Não confie na construção do DTO como autorização.
  • Evite incluir campos sensíveis em DTOs de saída, a menos que seja explicitamente intencionado.

Checklist de Revisão

  • O DTO é estável e agnóstico ao cliente?
  • Os campos são tipados?
  • As regras de validação estão próximas o suficiente para permanecerem sincronizadas?

Exemplos

Bom Exemplo

namespace App\Data;

use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Required;
use Spatie\LaravelData\Attributes\Validation\Max;

final readonly class RegisterUserData extends Data
{
    public function __construct(
        #[Required, Max(255)]
        public string $name,

        #[Required, Email]
        public string $email,
    ) {}
}

Mau Exemplo

// ❌ Pouca segurança de tipos, sem contexto de validação, difícil de reutilizar em jobs em segundo plano.
class RegisterController extends Controller
{
    public function store(Request $request)
    {
        $this->action->handle($request->all());
    }
}

Habilidades Relacionadas