Programowanie · Budowanie i kod
flutter-implement-json-serialization
/flutter-implement-json-serialization
Pomaga pisać ręczne serializatory JSON z dart:convert i dopasowaniem wzorców Dart albo automatyzować serializację modeli.
Dla kogo
- Autor
- dhruvanbhalara ↗
- Repozytorium
- skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 30.08.2026
Ocena i bezpieczeństwo
100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 3
Przestarzałość
Brak sygnałów. Repozytorium zmienione 30.08.2026, bez odwołań do wycofanych modeli i API.
Licencja
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Pomaga pisać ręczne serializatory JSON z dart:convert i dopasowaniem wzorców Dart albo automatyzować serializację modeli.
Oryginalny opis (EN)
Use when writing manual JSON serializers with dart:convert and Dart pattern matching or automating model serialization.
Jak działa
- Contents
- Core Guidelines
- Dart 3 Pattern Matching in fromJson
- Background Parsing
- Manual vs Code-Gen Decision
- Workflow: Implementing a Serializable Model
- Workflow: Fetching and Parsing JSON
- Examples
Sekcje z nagłówków SKILL.md, w oryginale · 233 linii, 930 słów
Podgląd SKILL.md
---
name: flutter-implement-json-serialization
description: Use when writing manual JSON serializers with dart:convert and Dart pattern matching or automating model serialization.
metadata:
platforms: "flutter, dart"
languages: "dart"
category: "data"
---
## Contents
- [Core Guidelines](#core-guidelines)
- [Dart 3 Pattern Matching in fromJson](#dart-3-pattern-matching-in-fromjson)
- [Background Parsing](#background-parsing)
- [Manual vs Code-Gen Decision](#manual-vs-code-gen-decision)
- [Workflow: Implementing a Serializable Model](#workflow-implementing-a-serializable-model)
- [Workflow: Fetching and Parsing JSON](#workflow-fetching-and-parsing-json)
- [Examples](#examples)
## Core Guidelines
- **Import `dart:convert`**: Use `jsonEncode()` and `jsonDecode()` for manual serialization.
- **Type Safety**: Always cast `jsonDecode()` result to `Map<String, dynamic>` (objects) or `List<dynamic>` (arrays). Never work with raw `dynamic`.
- **Encapsulation**: Define `fromJson` factory constructor and `toJson` method within the model class.
- **Background Parsing**: Offload to a separate isolate via `compute()` if parsing takes > 16ms (large JSON payloads).
- **Error Handling**: Throw `FormatException` on invalid JSON. Never return `null` from `fromJson`.
## Dart 3 Pattern Matching in fromJson
Use `switch` expressions with destructuring for type-safe, concise deserialization:
```dart
import 'dart:convert';
class User {
final int id;
final String name;
final String email;
const User({required this.id, required this.name, required this.email});
factory User.fromJson(Map<String, dynamic> json) {
return switch (json) {
{
'id': final int id,
'name': final String name,
'email': final String email,
} =>
User(id: id, name: name, email: email),
_ => throw const FormatException('Invalid User JSON'),
};
}
Map<String, dynamic> toJson() => {
'id': id,
'name': name,
'email': email,
};
}
```
**Benefits over manual casting**:
- Compile-time type checking in destructuring patterns
- Single expression handles both extraction and validation
- `FormatException` thrown automatically on type mismatch
### Nested Objects
```dart
class Post {
final int id;
final String title;
final User author;
const Post({required this.id, required this.title, required this.author});
factory Post.fromJson(Map<String, dynamic> json) {
return switch (json) {
{
'id': final int id,
'title': final String title,
'author': final Map<String, dynamic> authorJson,
} =>
Post(id: id, title: title, author: User.fromJson(authorJson)),
_ => throw const FormatException('Invalid Post JSON'),
};
}
Map<String, dynamic> toJson() => {
'id': id,
'title': title,
'author': author.toJson(),
};
}
```
## Background Parsing
For large JSON payloads (thousands of objects), offload parsing to a background isolate:
```dart
import 'dart:convert';
import 'package:flutter/foundation.dart';
// MUST be a top-level function (not a method or closure)
List<User> parseUsers(String responseBody) {
final parsed = (jsonDecode(responseBody) as List<dynamic>)
.cast<Map<String, dynamic>>();
return parsed.map<User>((json) => User.fromJson(json)).toList();
}
Future<List<User>> fetchUsers(http.Client client) async {
final response = await client.get(Uri.parse('https://api.example.com/users'));
if (response.statusCode == 200) {
return compute(parseUsers, response.body);
} else {
throw Exception('Failed to load users: ${response.statusCode}');
}
}
```
**Rules**:
- The parsing function MUST be top-level or static (not an instance method).
- Use `compute()` for simple isolate tasks. For complex scenarios, use `Isolate.run()`.
- Threshold: parse > 10,000 items or > 1MB payload → use background isolate.
## Manual vs Code-Gen Decision
| Criteria | Manual (`dart:convert`) | Code-Gen (`json_serializable` / `freezed`) |
|---|---|---|
| **Model count** | < 5 models | > 5 models |
| **Nesting depth** | Shallow (1-2 levels) | Deep / complex hierarchies |
| **Dev dependency** | None | `build_runner`, `json_annotation` |
| **Type safety** | Dart 3 pattern matching | Generated code |
| **Boilerplate** | Manual per model | Auto-generated |
| **Build time** | None | Adds `build_runner` step |
| **Flexibility** | Full control over parsing | Constrained by annotations |
**Recommendation**: Start with manual serialization for prototypes and small models. Migrate to `json_serializable` or `freezed` when the model count exceeds 5 or nesting becomes complex. See `flutter-code-gen` skill for code generation workflows.
## Workflow: Implementing a Serializable Model
### Task Progress
- [ ] **Step 1**: Define model class with `final` properties and `const` constructor.
- [ ] **Step 2**: Implement `factory Model.fromJson(Map<String, dynamic> json)` using pattern matching.
- [ ] **Step 3**: Implement `Map<String, dynamic> toJson()` method.
- [ ] **Step 4**: Write unit tests for serialization round-trip (`fromJson(toJson(model)) == model`).
- [ ] **Step 5**: Run tests: `dart test` or `flutter test`.
- [ ] **Step 6**: Feedback Loop: fix type mismatch errors → re-run until green.
## Workflow: Fetching and Parsing JSON
### Task Progress
- [ ] **Step 1**: Execute HTTP request.
- [ ] **Step 2**: Validate response status code (200 → proceed, else → throw).
- [ ] **Step 3**: Determine parsing strategy:
- Small payload → parse synchronously on main thread.
- Large payload → use `compute(parseFunction, response.body)`.
- [ ] **Step 4**: Decode and map JSON to model via `fromJson`.
## Examples
### Synchronous HTTP Fetch + Parse
```dart
import 'dart:convert';
import 'package:http/http.dart' as http;
Future<User> fetchUser(http.Client client, int userId) async {
final response = await client.get(
Uri.parse('https://api.example.com/users/$userId'),
headers: {'Accept': 'application/json'},
);
if (response.statusCode == 200) {
final Map<String, dynamic> jsonMap =
jsonDecode(response.body) as Map<String, dynamic>;
return User.fromJson(jsonMap);
} else {
throw Exception('Failed to load user: ${response.statusCode}');
}
}
```
### List Parsing with Type Safety
```dart
Future<List<User>> fetchAllUsers(http.Client client) async {
final response = await client.get(
Uri.parse('https://api.example.com/users'),
);
if (response.statusCode == 200) {
final List<dynamic> jsonList = jsonDecode(response.body) as List<dynamic>;
return jsonList
.map((e) => User.fromJson(e as Map<String, dynamic>))
.toList();
} else {
throw Exception('Failed to load users');
}
}
```
### Unit Test for Serialization
```dart
import 'package:flutter_test/flutter_test.dart';
void main() {
group('$User', () {
test('fromJson creates valid User', () {
final json = {'id': 1, 'name': 'Alice', 'email': 'alice@test.com'};
final user = User.fromJson(json);
expect(user.id, 1);
expect(user.name, 'Alice');
expect(user.email, 'alice@test.com');
});
test('toJson returns valid map', () {
const user = User(id: 1, name: 'Alice', email: 'alice@test.com');
final json = user.toJson();
expect(json['id'], 1);
expect(json['name'], 'Alice');
});
test('round-trip serialization', () {
const original = User(id: 1, name: 'Alice', email: 'alice@test.com');
final json = original.toJson();
final restored = User.fromJson(json);
expect(restored.id, original.id);
expect(restored.name, original.name);
expect(restored.email, original.email);
});
test('throws FormatException on invalid JSON', () {
final invalidJson = {'id': 'not_an_int', 'name': 'Alice'};
expect(() => User.fromJson(invalidJson), throwsFormatException);
});
});
}
```
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · dhruvanbhalara/skills | 100 | MIT |
| flutter/agent-plugins | 100 | BSD-3-Clause |
Migawka bazy z 13.11.2026 · wersja paczki 9499ec3c3ea1 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100dart-n-flutter
Prowadzi pisanie kodu Dart i Flutter zgodnie z oficjalnymi zaleceniami dla plików .dart. - 90mobile-flutter
Pomaga pisać aplikacje Flutter i Dart: układy, formularze, routing go_router, HTTP, bazy lokalne i wtyczki. - 100dart-expert
Pomaga w Dart i Flutter przy aplikacjach mobilnych i wieloplatformowych, w tym widgetach i frameworku Flutter. - 95build-agent-dart
Agent budowania dla Dart i Fluttera: aplikacje mobilne, widgety, pakiety Dart i funkcje na iOS oraz Androidzie. - 100dart
Pomaga programować w Dart: null safety, async/await i future, streamy, dopasowanie wzorców, rekordy i konstruktory klas, także w aplikacjach Flutter i CLI. - 100flutter-handling-http-and-json
Wykonuje żądania HTTP i obsługuje serializację JSON w aplikacji Flutter przy integracji z REST API i parsowaniu danych strukturalnych.