Algumas opções para desserializar JSON com Flutter
Compare decodificação manual, geração de código e outras abordagens para desserializar JSON em apps Flutter.
Em algum momento, a maioria dos apps precisa buscar dados em um endpoint online. Fazer uma requisição HTTPS get
para baixar um relatório do tempo ou o placar final da Copa do Mundo é bem simples, graças ao pacote
http do Dart:
import 'dart:async';
import 'package:http/http.dart' as http;
final response = await http.get(myEndpointUrl);
if (response.statusCode == 200) {
// use the data in response.body
} else {
// handle a failed request
}
Os dados em response.body provavelmente são uma string JSON, e há algum trabalho a fazer antes que ela esteja pronta para um widget. Primeiro, você precisa converter a string em uma representação mais gerenciável de JSON. Depois, é preciso convertê-la em um modelo ou em outra variável fortemente tipada, para que você possa usá-la de forma eficaz.
Felizmente, a equipe e a comunidade do Dart já vêm lidando com JSON há um tempo e podem oferecer soluções. Vou cobrir três, em ordem crescente de complexidade: construtores escritos à mão, json_serializable e built_value.
As chamadas para desserializar dados com as três abordagens são bem parecidas. Construtores escritos à mão e json_serializable resultam em linhas como esta:
final myObject = SimpleObject.fromJson(json.decode(aJsonString));
E uma chamada de desserialização para built_value fica assim:
final myObject = serializers.deserializeWith(
SimpleObject.serializer, json.decode(aJsonString));
A diferença real está em quanto código dentro dessa classe SimpleObject é gerado em seu nome e no que ele está fazendo.
Construtores escritos à mão
A abordagem menos complicada: nenhum código é gerado para você.
Você pode fazer o que quiser, mas fica responsável por mantê-lo.
json_serializable
Gera um construtor
fromJsone um métodotoJsonpara você.-
Você precisa incluir vários pacotes no projeto e usar
source_genpara gerar arquivos parciais antes de compilar o app. O código gerado pode ser difícil de personalizar.
built_value
-
Gera código para serialização, imutabilidade, métodos
toString, propriedadeshashCodee mais. É uma solução pesada, com muitas funcionalidades. -
Assim como
json_serializable, você precisa importar vários pacotes e usarsource_gen. Tem uma arquitetura de serialização extensível, baseada em plugins.
Tem opiniões sobre coisas como criação de instâncias e mutabilidade.
Como você verá, a biblioteca certa para você depende mesmo dos detalhes do seu projeto, principalmente do tamanho e do método de gerenciamento de estado. Um projeto hobby com um único mantenedor pode ir longe com construtores escritos à mão, enquanto um app construído por uma equipe grande e distribuída, que precisa de modelos imutáveis para manter a lógica limpa, pode se beneficiar muito de
built_value.
Por enquanto, porém, vamos começar do começo: fazer o parsing de JSON de uma string para uma representação mais conveniente em memória. Esta etapa é a mesma, independentemente do caminho que você escolher depois.
Parsing de JSON
A conversão de uma string JSON em um formato intermediário pode ser feita com a biblioteca dart:convert:
import 'dart:convert';
try {
final parsed = json.decode(aJsonStr);
} on FormatException catch (e) {
print("That string didn't look like Json.");
} on NoSuchMethodError catch (e) {
print('That string was null!');
}
Se a string contiver JSON válido, você receberá de volta uma referência dynamic para um List<dynamic>
ou um Map<String, dynamic>, dependendo de a string JSON conter um array ou um único objeto. Para coisas simples, como uma lista de inteiros, você praticamente já terminou nesse ponto. Provavelmente vai querer criar uma segunda referência, fortemente tipada, para os dados antes de usá-los:
final dynamicListOfInts = json.decode(aJsonArrayOfInts);
// Create a strongly typed list with references to the data that are casted
// immediately. This is probably the better approach for data model classes.
final strongListOfInts = List<int>.from(dynamicListOfInts);
// Or create a strongly typed list with references that will be lazy-casted
// when used.
final anotherStrongListOfInts = List<int>.from(dynamicListOfInts);
Payloads mais sofisticados são onde as coisas ficam interessantes. Converter um Map<String, dynamic>
em um objeto de modelo de verdade pode envolver casts, valores padrão, nulls e objetos aninhados. Há muitas formas de dar errado e muitos detalhes chatos que precisam ser atualizados se você decidir renomear ou adicionar/remover uma propriedade depois.
Construtores escritos à mão
Sempre é preciso começar por algum lugar, certo? Se você tem um app pequeno e os dados não são tão complicados, dá para ir longe escrevendo seus próprios
construtores factory
que recebem um parâmetro Map<String, dynamic>. Por exemplo, se você está buscando algo que se parece com isto:
{
"aString": "Blah, blah, blah.",
"anInt": 1,
"aDouble": 1.0,
"aListOfStrings": ["one", "two", "three"],
"aListOfInts": [1, 2, 3],
"aListOfDoubles": [1.0, 2.0, 3.0]
}
O código de uma classe correspondente pode ficar assim:
class SimpleObject {
const SimpleObject({
this.aString,
this.anInt,
this.aDouble,
this.aListOfStrings,
this.aListOfInts,
this.aListOfDoubles,
});
final String aString;
final int anInt;
final double aDouble;
final List<String> aListOfStrings;
final List<int> aListOfInts;
final List<double> aListOfDoubles;
factory SimpleObject.fromJson(Map<String, dynamic> json) {
if (json == null) {
throw FormatException("Null JSON provided to SimpleObject");
}
return SimpleObject(
aString: json['aString'],
anInt: json['anInt'],
aDouble: json['aDouble'],
aListOfStrings: json['aListOfStrings'] != null
? List<String>.from(json['aListOfStrings'])
: null,
aListOfInts: json['aListOfInts'] != null
? List<int>.from(json['aListOfInts'])
: null,
aListOfDoubles: json['aListOfDoubles'] != null
? List<double>.from(json['aListOfDoubles'])
: null,
);
}
}
O construtor factory nomeado fromJson é então usado assim:
final myObject = SimpleObject.fromJson(json.decode(aJsonString));
Por outro lado, você precisou escrever cerca de 20 linhas de código de construtor na mão e agora fica responsável por mantê-las. À medida que seu app cresce e suas classes de dados chegam a dezenas, você pode começar a pensar: “Puxa, escrever esses construtores JSON está ficando tedioso. Queria que fossem gerados automaticamente a partir das propriedades da classe.”
Acontece que, com a biblioteca json_serializable, eles podem ser.
Usando json_serializable
Antes de falar sobre json_serializable, precisamos dar um pequeno desvio para tratar de outro pacote.
O Flutter não oferece suporte a reflection no momento, então algumas técnicas disponíveis em outros contextos (como a capacidade de uma biblioteca JSON do Android de inspecionar classes em busca de anotações em tempo de execução) não funcionam para quem desenvolve com Flutter. O que eles
podem usar, porém, é um pacote do Dart chamado source_gen. Ele fornece utilitários e uma estrutura básica para geração automática de código-fonte.
Em vez de atualizar seu código diretamente, source_gen cria arquivos novos e separados ao lado deles. Por convenção, eles recebem um “g” no nome: então, se sua classe estiver em
model.dart, source_gen cria model.g.dart. Você pode referenciar esse arquivo no original usando a palavra-chave
part, e o compilador o incorpora.
O pacote json_serializable usa a API source_gen para gerar código de serialização. Ele escreve o construtor fromJson (assim como um método
toJson) para você.
O processo básico para colocá-lo para funcionar em um app é este:
-
Importe para o seu projeto os pacotes
json_serializableejson_annotation. Defina uma classe de dados como normalmente faria.
Adicione a anotação
@JsonSerializableà definição da classe.-
Adicione alguns detalhes extras para vincular essa classe ao código que
json_serializablecria para ela. Execute
source_genpara gerar o código.
Vou tratar cada um deles separadamente.
Importe o pacote json_serializable para o seu projeto
Você pode encontrar json_serializable no catálogo de pacotes do Dart. Basta
atualizar seu pubspec.yaml
conforme indicado, e pronto.
Defina uma classe de dados
Nada de surpreendente aqui. Crie uma classe de dados com propriedades básicas e um construtor. As propriedades que você pretende serializar devem ser tipos de valor ou outras classes feitas para funcionar com
json_serializable.
class SimpleObject {
SimpleObject({
this.aString,
this.anInt,
this.aDouble,
this.aListOfStrings,
this.aListOfInts,
this.aListOfDoubles,
});
final String aString;
final int anInt;
final double aDouble;
final List<String> aListOfStrings;
final List<int> aListOfInts;
final List<double> aListOfDoubles;
}
Adicione a anotação @JsonSerializable
O pacote json_serializable só gera código para classes marcadas com a anotação
@JsonSerializable:
import 'package:json_annotation/json_annotation.dart';
@JsonSerializable
class SimpleObject {
...
}
Vincule o código gerado ao seu
Em seguida, há três mudanças que conectam a definição da classe ao seu arquivo part correspondente:
import 'package:json_annotation/json_annotation.dart';
part 'simple_object.g.dart';
@JsonSerializable()
class SimpleObject extends Object with _$SimpleObjectSerializerMixin {
SimpleObject({
this.aString,
this.anInt,
this.aDouble,
this.aListOfStrings,
this.aListOfInts,
this.aListOfDoubles,
});
final String aString;
final int anInt;
final double aDouble;
final List<String> aListOfStrings;
final List<int> aListOfInts;
final List<double> aListOfDoubles;
factory SimpleObject.fromJson(Map<String, dynamic> json) =>
_$SimpleObjectFromJson(json);
}
A primeira delas é a declaração part, que diz ao compilador para incorporar simple_object.g.dart
(mais sobre isso daqui a pouco). Depois, há uma atualização na definição da classe para usar um mixin. Por fim, atualize a classe para usar o construtor
fromJson. As duas últimas mudanças referenciam código do arquivo gerado.
Execute o source_gen
Inicie a geração de código a partir da pasta do projeto com este comando:
flutter packages pub run build_runner build
Quando terminar, você terá um novo arquivo chamado simple_object.g.dart ao lado do original. O conteúdo fica assim:
part of 'simple_object.dart';
SimpleObject _$SimpleObjectFromJson(
Map<String, dynamic> json) =>
new SimpleObject(
aString: json['aString'] as String,
anInt: json['anInt'] as int,
aDouble: (json['aDouble'] as num)?.toDouble(),
aListOfStrings:
(json['aListOfStrings'] as List)?.map((e) => e as String)?.toList(),
aListOfInts:
(json['aListOfInts'] as List)?.map((e) => e as int)?.toList(),
aListOfDoubles: (json['aListOfDoubles'] as List)
?.map((e) => (e as num)?.toDouble())
?.toList());
abstract class _$SimpleObjectSerializerMixin {
String get aString;
int get anInt;
double get aDouble;
List<String> get aListOfStrings;
List<int> get aListOfInts;
List<double> get aListOfDoubles;
Map<String, dynamic> toJson() => <String, dynamic>{
'aString': aString,
'anInt': anInt,
'aDouble': aDouble,
'aListOfStrings': aListOfStrings,
'aListOfInts': aListOfInts,
'aListOfDoubles': aListOfDoubles
};
}
O primeiro método é chamado pelo construtor fromJson em SimpleObject, e o mixin fornece o novo método
toJson para SimpleObject. Os dois são simples de usar:
final myObject = SimpleObject.fromJson(json.decode(jsonString));
final myJsonStr = json.encode(myObject.toJson());
Em números, adicionar três linhas de código a simple_object.dart para json_serializable
economiza cerca de 20 linhas de código de construtor que, de outra forma, você teria que escrever. Você também pode regenerá-lo sempre que quiser renomear ou ajustar as propriedades, e ganha um método toJson de brinde. Nada mal.
E se você quiser serializar para mais de um formato? Ou para mais do que JSON? E se precisar de outras coisas, como objetos de modelo imutáveis? Para esses casos, existe
built_value.
Usando built_value
Muito mais do que apenas uma solução para automatizar a lógica de serialização, built_value (junto com seu pacote parceiro,
built_collection) foi projetado para ajudar você a criar classes que funcionam como tipos de valor. Por isso, as instâncias de classes criadas com
built_value são imutáveis. Você pode criar novas instâncias (inclusive cópias de instâncias existentes), mas, depois de construídas, suas propriedades não podem ser alteradas.
Para isso, built_value usa a mesma abordagem de geração de código-fonte que json_serializable, mas cria bem mais código. No arquivo gerado para uma classe
built_value, você vai encontrar:
Um operador de igualdade (
==)Uma propriedade
hashCodeUm método
toStringUma classe serializadora, se você quiser uma. Mais sobre isso abaixo.
Uma classe “builder” usada para criar novas instâncias
Isso soma várias centenas de linhas, mesmo para uma classe pequena como SimpleObject, então vou evitar mostrá-lo aqui. O arquivo da classe em si (o que você escreveria como desenvolvedor) fica assim:
import 'package:built_collection/built_collection.dart';
import 'package:built_value/built_value.dart';
import 'package:built_value/serializer.dart';
part 'simple_object.g.dart';
abstract class SimpleObject
implements Built<SimpleObject, SimpleObjectBuilder> {
static Serializer<SimpleObject> get serializer =>
_$SimpleObjectSerializer;
@nullable
String get aString;
@nullable
int get anInt;
@nullable
double get aDouble;
@nullable
BuiltList<String> get aListOfStrings;
@nullable
BuiltList<int> get aListOfInts;
@nullable
BuiltList<double> get aListOfDoubles;
SimpleObject._();
factory SimpleObject([updates(SimpleObjectBuilder b)]) =
_$SimpleObject;
}
As diferenças entre isso e a versão de SimpleObject com que começamos são:
Um arquivo part é declarado, assim como em
json_serializable.-
Uma interface,
Built<SimpleObject, SimpleObjectBuilder>, passa a ser implementada. Foi adicionado um getter estático para um objeto serializador.
-
As anotações de nulabilidade estão em todos os campos. Elas são opcionais, mas, para que este exemplo corresponda aos outros em funcionalidade, eu as adicionei.
-
Dois construtores (um privado e um factory) foram adicionados, e o original foi removido.
SimpleObject agora é uma classe abstrata!
As diferenças entre isso e a versão de SimpleObject com que começamos são:
Vamos começar pelo último ponto: SimpleObject virou uma classe abstrata. No arquivo gerado,
built_value define uma subclasse de SimpleObject chamada _$SimpleObject, e é ali que ela fornece grande parte da nova funcionalidade. É ali que você vai encontrar a nova propriedade hashCode, os novos métodos relacionados à imutabilidade e assim por diante. Toda vez que você cria uma instância de SimpleObject, na prática está obtendo _$SimpleObject por trás dos panos. Você nunca precisará referenciá-la pelo tipo derivado, então seu código de app continua usando SimpleObject para declarar e usar referências.
Isso é possível porque a instanciação de um novo SimpleObject é feita por meio de um construtor factory gerado, que você pode ver referenciado na última linha do arquivo acima. Para usá-lo, você passa um método que define propriedades em um
SimpleObjectBuilder (é o parâmetro “b” abaixo), que constrói a instância imutável do objeto para você:
final SimpleObject myObject = SimpleObject((b) => b
..aString = 'Blah, blah, blah'
..anInt = 1
..aDouble = 1.0
..aListOfStrings = ListBuilder<String>(['one', 'two', 'three'])
..aListOfInts = ListBuilder<int>([1, 2, 3])
..aListOfDoubles = ListBuilder<double>([1.0, 2.0, 3.0])
);
Você também pode rebuild para obter uma cópia modificada de uma instância existente:
final SimpleObject anotherObject = myObject.rebuild((b) => b
..aString = "An updated value"
);
Como você pode ver, o construtor de SimpleObject foi tornado privado com o uso de um underscore:
SimpleObject._();
Isso garante que o código do seu app não consiga instanciar diretamente uma instância de SimpleObject. Para obter uma, você precisa usar o construtor factory, que usa
SimpleObjectBuilder e sempre produz uma instância da subclasse _$SimpleObject.
Isso é ótimo, mas eu achei que estávamos falando de desserialização?
Estou chegando lá! Para serializar e desserializar instâncias, você precisará adicionar um pouco de código em algum lugar do app (criar um arquivo chamado
serializers.dart, por exemplo, é uma boa abordagem):
import 'package:built_collection/built_collection.dart';
import 'package:built_value/serializer.dart';
import 'package:built_value/standard_json_plugin.dart';
import 'simple_object.dart';
part 'serializers.g.dart';
@SerializersFor(const [
SimpleObject,
])
final Serializers serializers =
(_$serializers.toBuilder()..addPlugin(StandardJsonPlugin())).build();
Este arquivo faz duas coisas. Primeiro, usa a anotação @SerializersFor para instruir built_value
a criar serializadores para uma lista de classes. Neste caso, há apenas uma classe, então a lista é curta. Segundo, cria uma variável global chamada
serializers que referencia o objeto Serializers que cuida da serialização das classes
built_value. Ela é usada assim:
final myObject = serializers.deserializeWith(
SimpleObject.serializer, json.decode(aJsonString));
final String myJsonString = json.encode(serializers.serialize(myObject));
Assim como com json_serializable, transformar um objeto em JSON e vice-versa continua sendo quase uma operação de uma linha só, com o código gerado fazendo o trabalho pesado para você. Uma coisa importante a notar, porém, é este trecho de serializers.dart:
final Serializers serializers =
(_$serializers.toBuilder()..addPlugin(StandardJsonPlugin())).build();
built_value foi projetado para ser o mais extensível possível e inclui um sistema de plugins para definir formatos de serialização personalizados (você poderia, por exemplo, escrever um para traduzir de e para XML ou para seu próprio formato binário). Estou usando-o neste exemplo para adicionar um plugin chamado
StandardJsonPlugin porque, por padrão, built_value não usa o formato JSON baseado em mapas ao qual você provavelmente está acostumado.
Em vez disso, usa um formato baseado em listas. Por exemplo, um objeto simples com membros String, int e
double seria serializado assim:
[
"SimpleObject",
"aString",
"Blah, blah, blah",
"anInt",
1,
"aDouble",
2.0
]
Em vez de algo assim:
{
"$": "SimpleObject",
"aString": "Blah, blah, blah",
"anInt": 1,
"aDouble": 2.0
}
Há alguns motivos pelos quais built_value prefere o formato baseado em listas, que eu deixo para a
documentação do pacote, por questão de espaço. Para este exemplo, basta saber que você pode usar facilmente a serialização JSON baseada em mapas por meio do
StandardJsonPlugin, que vem como parte do pacote built_value.
Conclusão
Então esses são os pontos altos das três técnicas. Como mencionei no início deste artigo, escolher a certa depende principalmente de considerar o escopo do seu projeto, quantas pessoas estão trabalhando nele e quais outras necessidades você tem para seus objetos de modelo.
O próximo passo é começar a programar, então venha nos encontrar no Flutter Dev Google Group, no StackOverflow ou no The Boring Show, e nos conte como foi!