Correções orientadas a dados

Como mantenedor de um pacote, modificar ou descontinuar APIs públicas pode quebrar o código existente dos seus usuários. Para ajudar seus usuários a atualizar sem problemas, você pode fornecer correções orientadas a dados (data-driven fixes).

Correções orientadas a dados são regras de migração declarativas armazenadas diretamente dentro do seu pacote. Depois que os usuários atualizam para uma versão mais nova do seu pacote, eles podem aplicar essas migrações com o dart fix ou com as correções rápidas da IDE.

Para fornecer migrações automatizadas para o seu pacote, siga estes passos.

Adicione um arquivo chamado fix_data.yaml no diretório lib/ do seu pacote:

Se você tiver muitas correções, pode dividi-las em vários arquivos dentro do diretório lib/fix_data/.

No fix_data.yaml, especifique a versão do formato (version: 1) e uma lista transforms. Cada transformação descreve o elemento da API que mudou e as alterações a serem aplicadas.

Por exemplo, se você renomear oldMethod() para newMethod() na classe MyClass:

version: 1
transforms:
  - title: 'Rename oldMethod to newMethod'
    date: 2026-09-18
    element:
      uris: ['my_package.dart']
      method: 'oldMethod'
      inClass: 'MyClass'
    changes:
      - kind: 'rename'
        newName: 'newMethod'

• date: uma data no formato YYYY-MM-DD indicando quando a mudança foi introduzida.
• uris: uma lista de URIs de bibliotecas que exportam a API, relativas ao diretório lib/, como 'my_package.dart'.

Para garantir que suas regras de migração funcionem como esperado, configure pares de arquivos de teste e arquivos golden que contenham o código esperado depois de aplicar as migrações.

Crie um diretório test_fixes/ na raiz do seu pacote:

• my_api.dart: código escrito para a API antiga.
• my_api.dart.expect: o código esperado depois de aplicar o dart fix.

Por exemplo, emparelhe seus arquivos de teste da seguinte forma:

import 'package:my_package/my_package.dart';
​
void main() {
  MyClass().oldMethod();
}

import 'package:my_package/my_package.dart';
​
void main() {
  MyClass().newMethod();
}

Na raiz do seu pacote, execute o dart fix com --compare-to-golden:

$ dart fix test_fixes --compare-to-golden

Se a saída corresponder ao seu arquivo .expect, o comando termina com o código 0. Se houver diferença, ele exibe um diff e termina com um código diferente de zero, o que o torna ideal para suítes de testes de CI.

Para saber mais sobre todos os tipos de mudança suportados (como modificações de parâmetros e declarações substituídas), condições e templates de código, veja a especificação de Data-driven Fixes.