Dart: Gerenciamento de Pacotes Dart

Q: P: Qual a diferença entre dependencies e dev_dependencies ?

R: dependencies são pacotes necessários em tempo de execução; dev_dependencies são necessários apenas durante o desenvolvimento (testes, geração de código, linting). Ao publicar um pacote, dev_dependencies não são repassados aos usuários.

Q: P: Qual a diferença entre ^ e >= ?

R: ^1.2.0 é equivalente a >=1.2.0 =1.2.0 não tem limite superior. ^ é mais seguro e recomendado.

Q: P: Qual a diferença entre dart pub upgrade e dart pub get ?

R: dart pub get busca dependências dentro das restrições do pubspec.yaml. dart pub upgrade tenta atualizar para as versões mais recentes dentro dessas restrições.

Última atualização: 2026-08-26

Gerenciamento de dependências é a cadeia de suprimentos do projeto — só gerenciando bem as dependências um projeto pode ser estável.

1. O que Você Aprenderá

Configuração completa do pubspec.yaml: dependencies / dev_dependencies / dependency_overrides
Sintaxe de restrição de versão: ^ / >= / any e Versionamento Semântico
Buscando, avaliando e selecionando pacotes no pub.dev
Hospedagem privada de pacotes e dependências git
Cenário do Bob: Configuração de dependências do DataPipeline

2. A História Real de um Desenvolvedor

(1) A Dor: Falha de Build Devido a Conflito de Versão de Dependência

A equipe da Alice usou http: ^1.1.0 no projeto DataPipeline, mas outra dependência, api_client, exigia http: >=0.13.0 <1.0.0. As restrições de versão eram incompatíveis, causando falha no dart pub get. Pior ainda, uma dependência atualizou silenciosamente uma versão menor, introduzindo uma quebra de compatibilidade que causou falha no build do CI. A equipe gastou 2 dias investigando.

(2) A Solução: Versionamento Semântico

Dart usa Versionamento Semântico (SemVer) e sintaxe de restrição de versão para tornar o gerenciamento de dependências previsível. ^1.2.0 significa >=1.2.0 <2.0.0, garantindo compatibilidade.

YAML

dependencies:
  http: ^1.2.0       # Compatível com 1.x, atualizações minor/patch seguras
  args: ^2.4.2        # Compatível com 2.x
  csv: ^6.0.0         # Compatível com 6.x

(3) Os Benefícios

Restrições de versão tornam as atualizações de dependências seguras e controláveis.
O sistema de avaliação de pub points do pub.dev ajuda a selecionar pacotes de qualidade.
dependency_overrides resolve temporariamente conflitos de versão.

3. Configuração Completa do pubspec.yaml

(1) Estrutura de Configuração

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: pubspec.yaml Completo

YAML

name: datapipeline
description: Uma ferramenta CLI para análise de dados de e-commerce processando pedidos em nível de milhão
version: 1.0.0
homepage: https://github.com/bob/datapipeline
repository: https://github.com/bob/datapipeline
documentation: https://datapipeline.dev/docs

environment:
  sdk: ^3.0.0

dependencies:
  # Análise de argumentos CLI
  args: ^2.4.2
  # Cliente HTTP para chamadas de API
  http: ^1.2.0
  # Análise de arquivos CSV
  csv: ^6.0.0
  # Suporte a banco de dados SQLite
  sqlite3: ^2.4.0
  # Utilitários de manipulação de caminho
  path: ^1.9.0
  # Framework de logging
  logging: ^1.2.0
  # Análise de configuração YAML
  yaml: ^3.1.2

dev_dependencies:
  # Framework de testes
  test: ^1.24.0
  # Executor de geração de código
  build_runner: ^2.4.0
  # Serialização JSON
  json_serializable: ^6.7.0
  # Regras de lint
  lints: ^3.0.0

dependency_overrides:
  # Temporário: resolver conflito de versão
  # transitive: ^1.0.0

executables:
  datapipeline: datapipeline

Campo	Obrigatório	Descrição
`name`	Sim	Nome do pacote (minúsculas + underscores)
`description`	Sim	Descrição do pacote (60-180 caracteres)
`version`	Não	Número de versão semântica
`environment`	Sim	Restrições de versão do SDK
`dependencies`	Não	Dependências de tempo de execução
`dev_dependencies`	Não	Dependências de tempo de desenvolvimento
`dependency_overrides`	Não	Forçar versão específica

4. Sintaxe de Restrição de Versão

(1) Versionamento Semântico

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: Sintaxe de Restrição de Versão

YAML

dependencies:
  # Sintaxe caret: ^1.2.3 = >=1.2.3 <2.0.0
  package_a: ^1.2.3

  # Sintaxe de intervalo
  package_b: ">=1.2.3 <2.0.0"

  # Versão mínima
  package_c: ">=1.2.3"

  # Qualquer versão (perigoso!)
  package_d: any

  # Versão exata
  package_e: "1.2.3"

  # Dependência git
  package_f:
    git:
      url: https://github.com/user/package_f.git
      ref: main

  # Dependência de caminho (desenvolvimento local)
  package_g:
    path: ../package_g

Sintaxe	Significado	Exemplo	Segurança
`^1.2.3`	`>=1.2.3 <2.0.0`	Mais comum	Alta
`>=1.2.3 <2.0.0`	Restrição de intervalo	Controle preciso	Alta
`>=1.2.3`	Versão mínima	Maior risco	Média
`any`	Qualquer versão	Não recomendado	Baixa
`1.2.3`	Versão exata	Fixada	Alta (não flexível)

(2) Regras de Resolução de Versão

Regra SemVer	Descrição	Exemplo
Versão Major	Mudanças de API incompatíveis	1.x → 2.x
Versão Minor	Novas funcionalidades compatíveis retroativamente	1.2 → 1.3

Versão Patch | Correções de bugs compatíveis retroativamente | 1.2.3 → 1.2.4 |

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: Conflito de Versão e Resolução

YAML

# Cenário: package_a requer http ^0.13.0, package_b requer http ^1.0.0
# Isso é um conflito de versão MAJOR - incompatível!

# Solução 1: Atualizar package_a para uma versão que suporte http ^1.0.0
# Solução 2: Usar dependency_overrides (último recurso)
dependencies:
  http: ^1.2.0

dependency_overrides:
  http: ^1.2.0  # Forçar versão específica

5. Avaliando Pacotes no pub.dev

(1) Critérios de Avaliação

Dimensão	Métrica	Peso
Pub Points	Suporte de plataforma/Documentação/Saúde de dependências	Alto
Likes	Reconhecimento da comunidade	Médio
Popularidade	Contagem de uso	Médio
Pub Verified	Publicador verificado	Alto
Atualizações Recentes	Atividade de manutenção	Alto
Plataforma	Plataformas suportadas	Conforme necessidade

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: Seleção de Pacotes do DataPipeline

YAML

# Critérios de seleção de pacotes do DataPipeline:
#
# args (pub points: 140/140, likes: 300+)
#   - Pacote oficial da equipe Dart
#   - API estável, bem documentado
#   - Perfeito para análise de argumentos CLI
#
# http (pub points: 140/140, likes: 1000+)
#   - Pacote oficial da equipe Dart
#   - Cliente HTTP padrão
#   - Suporta interceptadores e streaming
#
# csv (pub points: 130/140, likes: 100+)
#   - Pacote da comunidade
#   - Gerencia análise/escrita CSV
#   - Manutenção ativa
#
# json_serializable (pub points: 140/140, likes: 500+)
#   - Pacote do Google
#   - Geração de código para JSON
#   - Type-safe, compatível com AOT

6. Pacotes Privados e Dependências Git

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: Dependências Git

YAML

dependencies:
  # Repositório git público
  custom_client:
    git:
      url: https://github.com/bob/custom_client.git
      ref: v1.0.0  # Tag, branch ou commit

  # Repositório git privado (SSH)
  internal_sdk:
    git:
      url: git@github.com:bob/internal_sdk.git
      ref: main

  # Caminho específico dentro de um repositório git
  shared_utils:
    git:
      url: https://github.com/bob/monorepo.git
      path: packages/shared_utils
      ref: stable

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: Dependências de Caminho Local

YAML

# Para desenvolvimento e teste local
dependencies:
  core_lib:
    path: ../core_lib

  shared_models:
    path: ./packages/shared_models

Fonte de Dependência	Sintaxe	Cenário Aplicável
pub.dev	`package: ^1.0.0`	Dependências formais (recomendado)
Git	`git: url: ...`	Pacotes não publicados/privados
Caminho Local	`path: ../local`	Desenvolvimento/depuração, monorepo

7. Cenário do Bob: Configuração de Dependências do DataPipeline

▶ Exemplo

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

: Dependências Completas do Projeto

YAML

name: datapipeline
description: Ferramenta CLI de análise de e-commerce para processamento de pedidos em nível de milhão
version: 1.0.0

environment:
  sdk: ^3.0.0

dependencies:
  # Framework CLI
  args: ^2.4.2
  # Formatação de saída do console
  cli_util: ^0.4.1
  # Cliente HTTP
  http: ^1.2.0
  # Análise CSV
  csv: ^6.0.0
  # Serialização JSON
  json_annotation: ^4.8.0
  # Utilitários de caminho
  path: ^1.9.0
  # Logging
  logging: ^1.2.0
  # Configuração YAML
  yaml: ^3.1.2

dev_dependencies:
  # Testes
  test: ^1.24.0
  # Mocking
  mockito: ^5.4.0
  # Geração de código
  build_runner: ^2.4.0
  json_serializable: ^6.7.0
  # Linting
  lints: ^3.0.0
  # Cobertura
  coverage: ^1.6.0

8. Exemplo Completo: Gerenciamento de Dependências do DataPipeline

DART

// ============================================
// Demonstração de Gerenciamento de Dependências do DataPipeline
// Mostra como usar dependências principais
// ============================================

import 'package:args/args.dart';
import 'package:path/path.dart' as p;

const String version = '1.0.0';

class DataPipelineCli {
  final ArgParser parser;

  DataPipelineCli()
      : parser = ArgParser()
          ..addFlag('version', abbr: 'v', negatable: false, help: 'Mostrar versão')
          ..addFlag('help', abbr: 'h', negatable: false, help: 'Mostrar ajuda')
          ..addOption('input', abbr: 'i', help: 'Fonte de dados de entrada')
          ..addOption('output', abbr: 'o', defaultsTo: 'report.json', help: 'Caminho de saída')
          ..addOption('format', allowed: ['json', 'csv', 'html'], defaultsTo: 'json')
          ..addFlag('verbose', abbr: 'V', help: 'Logging detalhado')
          ..addOption('batch-size', defaultsTo: '10000', help: 'Registros por lote');

  Future<void> run(List<String> arguments) async {
    try {
      final results = parser.parse(arguments);

      if (results['help'] as bool) {
        _printHelp();
        return;
      }

      if (results['version'] as bool) {
        print('DataPipeline v$version');
        return;
      }

      final input = results['input'] as String?;
      final output = results['output'] as String;
      final format = results['format'] as String;
      final verbose = results['verbose'] as bool;
      final batchSize = int.parse(results['batch-size'] as String);

      if (input == null) {
        print('Erro: --input é obrigatório');
        _printHelp();
        return;
      }

      // Usar pacote path para caminhos multiplataforma
      final inputPath = p.normalize(input);
      final outputPath = p.normalize(output);
      final ext = p.extension(inputPath);

      print('=== DataPipeline v$version ===');
      if (verbose) {
        print('Entrada:    $inputPath (${ext.isEmpty ? "desconhecido" : ext})');
        print('Saída:      $outputPath');
        print('Formato:    $format');
        print('Tamanho lote: $batchSize registros');
        print('SDK:        ${_getSdkInfo()}');
      }

      print('Processando: $inputPath → $outputPath ($format)');
    } on FormatException catch (e) {
      print('Erro de argumento: ${e.message}');
      print(parser.usage);
    }
  }

  void _printHelp() {
    print('DataPipeline - Ferramenta CLI de análise de e-commerce');
    print('');
    print('Uso: datapipeline [opções]');
    print(parser.usage);
  }

  String _getSdkInfo() {
    // Em um projeto real, use dart:io Platform
    return 'Dart 3.x';
  }
}

void main(List<String> arguments) async {
  final cli = DataPipelineCli();
  await cli.run(arguments);
}

TEXT 📖 Somente leitura

> **Saída:** Execute no DartPad local ou com `dart run`. Todos os exemplos do curso Dart são baseados em Dart 3.x / Flutter 3.x. Os resultados podem variar ligeiramente dependente da versão do SDK.

Saída (dart run bin/main.dart -i orders.csv -o report.json -V):

TEXT 📖 Somente leitura

=== DataPipeline v1.0.0 ===
Entrada:    orders.csv (.csv)
Saída:      report.json
Formato:    json
Tamanho lote: 10000 registros
SDK:        Dart 3.x
Processando: orders.csv → report.json (json)

❓ Perguntas Frequentes

P: Qual a diferença entre dependencies e dev_dependencies? R: dependencies são pacotes necessários em tempo de execução; dev_dependencies são necessários apenas durante o desenvolvimento (testes, geração de código, linting). Ao publicar um pacote, dev_dependencies não são repassados aos usuários.

P: Qual a diferença entre ^ e >=? R: ^1.2.0 é equivalente a >=1.2.0 <2.0.0, limitando atualizações dentro de uma versão major. >=1.2.0 não tem limite superior. ^ é mais seguro e recomendado.

P: Qual a diferença entre dart pub upgrade e dart pub get? R: dart pub get busca dependências dentro das restrições do pubspec.yaml. dart pub upgrade tenta atualizar para as versões mais recentes dentro dessas restrições.

P: Devo commitar o pubspec.lock no controle de versão? R: Para projetos de aplicação (CLI, Flutter App), sim, para garantir que a equipe use versões idênticas. Para projetos de biblioteca (pacotes), não, para permitir que os usuários obtenham a versão compatível mais recente.

P: Como escolher um pacote no pub.dev? R: Verifique pub points (≥130 é bom), likes, data de atualização recente e se o publicador é verificado. Prefira pacotes oficiais do Dart/Google.

P: Quando devo usar dependency_overrides? R: Apenas temporariamente quando conflitos não puderem ser resolvidos através de restrições de versão normais. Uso a longo prazo mascara problemas subjacentes. Remova-o assim que o problema for resolvido.

P: Dependências git são seguras para produção? R: Não recomendado. Dependências git não têm garantia de versão, e ref pode sofrer force-push. Para releases formais, use pacotes versionados do pub.dev.

📖 Resumo

pubspec.yaml é o centro de configuração do projeto: gerencia dependências, versões e metadados.
Usar a sintaxe ^ para restrições de versão é mais seguro, permitindo atualizações automáticas dentro de uma versão major.
O sistema de avaliação de pub points do pub.dev ajuda a selecionar pacotes de qualidade.
Dependências git são para pacotes não publicados/privados, enquanto dependências de caminho são para desenvolvimento local.
dependencies vs dev_dependencies separa dependências de tempo de execução das de tempo de desenvolvimento.

📝 Exercícios

Básico (Dificuldade ⭐): Crie um projeto usando dart create, adicione as dependências args e path, execute dart pub get e inspecione o conteúdo do arquivo pubspec.lock.
Intermediário (Dificuldade ⭐⭐): Busque o pacote http no pub.dev, registre seus pub points, likes, versão mais recente e plataformas suportadas. Escreva um relatório de avaliação de seleção de pacote.
Desafio (Dificuldade ⭐⭐⭐): Crie um arquivo pubspec.yaml que inclua uma dependência git e uma dependência de caminho, simulando um cenário de desenvolvimento monorepo. Use dependency_overrides para resolver um conflito de versão hipotético.

← Lição Anterior | Próxima Lição →

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós