Retrofit & Dio Networking

Priority: P0 (CRITICAL)

Type-safe REST API communication using Dio and Retrofit.

Structure

infrastructure/
├── data_sources/
│   ├── remote/       # Retrofit abstract classes
│   └── local/        # Cache/Storage
└── network/
    ├── dio_client.dart    # Custom Dio setup
    └── interceptors/      # Auth, Logging, Cache

Implementation Workflow

1. Define Retrofit clients — Create abstract classes with @RestApi() and HTTP annotations (@GET, @POST). Methods return Future<DTO>.
2. Create DTOs — Use @freezed and @JsonSerializable for all request/response bodies.
3. Map to domain — Data sources must map DTOs to Domain Entities (e.g., userDto.toDomain()).
4. Guard enums — Always use @JsonKey(unknownEnumValue: Status.unknown) to prevent crashes from new backend values.
5. Add auth interceptor — Inject Authorization: Bearer <token> in onRequest.
6. Handle token refresh — On 401, lock Dio, call refreshToken(), update stored token, retry via dio.fetch(err.requestOptions).
7. Map failures — Convert DioException to typed Failure objects (ServerFailure, NetworkFailure).

Retrofit Client & Safe Enum DTO Examples

See implementation examples for RestClient definitions and safe enum DTO patterns.

Anti-Patterns

• ❌ jsonDecode(response.body) — use Retrofit's generated mappers, never manual JSON parsing
• ❌ Static global Dio instance — inject Dio via DI; avoid global singletons
• ❌ try-catch inside Retrofit interface methods — let the repository layer handle exceptions
• ❌ Enum fields without unknownEnumValue — new backend values will crash the app

Reference & Examples

For RestClient definitions and Auth Interceptor implementation: See references/REFERENCE.md.

Related Topics

feature-based-clean-architecture | error-handling