The Options class describes the http request information and configuration. Each Dio instance has a base config for all requests maked by itself, and we can override the base config with [Options] when make a single request. The [BaseOptions] declaration as follows:

{
/// Http method.
String method;
/// Request base url, it can contain sub path, like: "https://www.google.com/api/".
String baseUrl;
/// Http request headers.
Map<String, dynamic> headers;
/// Timeout in milliseconds for opening url.
int connectTimeout;
/// Whenever more than [receiveTimeout] (in milliseconds) passes between two events from response stream,
/// [Dio] will throw the [DioError] with [DioErrorType.RECEIVE_TIMEOUT].
/// Note: This is not the receiving time limitation.
int receiveTimeout;
/// Request data, can be any type.
T data;
/// If the `path` starts with "http(s)", the `baseURL` will be ignored, otherwise,
/// it will be combined and then resolved with the baseUrl.
String path="";
/// The request Content-Type. The default value is [ContentType.JSON].
/// If you want to encode request body with "application/x-www-form-urlencoded",
/// you can set `ContentType.parse("application/x-www-form-urlencoded")`, and [Dio]
/// will automatically encode the request body.
ContentType contentType;
/// [responseType] indicates the type of data that the server will respond with
/// options which defined in [ResponseType] are `JSON`, `STREAM`, `PLAIN`.
///
/// The default value is `JSON`, dio will parse response string to json object automatically
/// when the content-type of response is "application/json".
///
/// If you want to receive response data with binary bytes, for example,
/// downloading a image, use `STREAM`.
///
/// If you want to receive the response data with String, use `PLAIN`.
ResponseType responseType;
/// `validateStatus` defines whether the request is successful for a given
/// HTTP response status code. If `validateStatus` returns `true` ,
/// the request will be perceived as successful; otherwise, considered as failed.
ValidateStatus validateStatus;
/// Custom field that you can retrieve it later in [Interceptor]、[Transformer] and the [Response] object.
Map<String, dynamic> extra;
/// Custom Cookies
Iterable<Cookie> cookies;
}

For each dio instance, We can add one or more interceptors, by which we can intercept requests or responses before they are handled by then or catchError.

dio.interceptors.add(InterceptorsWrapper(
onRequest:(RequestOptions options){
// Do something before request is sent
return options; //continue
// If you want to resolve the request with some custom data，
// you can return a `Response` object or return `dio.resolve(data)`.
// If you want to reject the request with a error message,
// you can return a `DioError` object or return `dio.reject(errMsg)`
},
onResponse:(Response response) {
// Do something with response data
return response; // continue
},
onError: (DioError e) {
// Do something with response error
return e;//continue
}
));

In all interceptors, you can interfere with their execution flow. If you want to resolve the request/response with some custom data，you can return a Response object or return dio.resolve(data). If you want to reject the request/response with a error message, you can return a DioError object or return dio.reject(errMsg) .

You can lock/unlock the interceptors by calling their lock()/unlock method. Once the request/response interceptor is locked, the incoming request/response will be added to a queue before they enter the interceptor, they will not be continued until the interceptor is unlocked.

When the request interceptor is locked, the incoming request will pause, this is equivalent to we locked the current dio instance, Therefore, Dio provied the two aliases for the lock/unlock of request interceptors.

Because of security reasons, we need all the requests to set up a csrfToken in the header, if csrfToken does not exist, we need to request a csrfToken first, and then perform the network request, because the request csrfToken progress is asynchronous, so we need to execute this async request in request interceptor. The code is as follows:

You can create a CookieJar or PersistCookieJar to manage cookies automatically, and dio use the CookieJar by default, which saves the cookies in RAM. If you want to persists cookies, you can use the PersistCookieJar class, the example codes as follows:

var dio = new Dio();
dio.interceptors.add(CookieManager(CookieJar()))

PersistCookieJar is a cookie manager which implements the standard cookie policy declared in RFC. PersistCookieJar persists the cookies in files, so if the application exit, the cookies always exist unless call delete explicitly.

Note: In flutter, the path passed to PersistCookieJar must be valid(exists in phones and with write access). you can use path_provider package to get right path

try {
//404
await dio.get("https://wendux.github.io/xsddddd");
} on DioError catch(e) {
// The request was made and the server responded with a status code
// that falls out of the range of 2xx and is also not 304.
if(e.response) {
print(e.response.data)
print(e.response.headers)
print(e.response.request)
} else{
// Something happened in setting up or sending the request that triggered an Error
print(e.request)
print(e.message)
}
}

enum DioErrorType {
/// When opening url timeout, it occurs.
CONNECT_TIMEOUT,
///It occurs when receiving timeout.
RECEIVE_TIMEOUT,
/// When the server response, but with a incorrect status, such as 404, 503...
RESPONSE,
/// When the request is cancelled, dio will throw a error with this type.
CANCEL,
/// Default error type, Some other Error. In this case, you can
/// read the DioError.error if it is not null.
DEFAULT,
}

Transformer allows changes to the request/response data before it is sent/received to/from the server. This is only applicable for request methods 'PUT', 'POST', and 'PATCH'. Dio has already implemented a DefaultTransformer, and as the default Transformer. If you want to customize the transformation of request/response data, you can provide a Transformer by your self, and replace the DefaultTransformer by setting the dio.transformer.