dio 0.0.1
dio: ^0.0.1 copied to clipboard

outdated Dart 2 incompatible

A powerful Http client for Dart, which supports Interceptors, Global configuration, FormData and soon on.

dio #

A powerful Http client for Dart, which supports Interceptors, Global configuration, FormData, File downloading etc. and Dio is very easy to use.

Add dependency #

  dio: ^0.0.1

Super simple to use #

import 'package:dio/dio.dart';
Dio dio = new Dio();
Response<String> response=await dio.get("https://www.google.com/");

Table of contents #

Examples Dio APIs Request Options Response Schema Interceptors Handling Errors Using application/x-www-form-urlencoded format Sending FormData Transformer Set proxy and HttpClient config Features and bugs

Examples #

Performing a GET request:

Response response;
response=await dio.get("/test?id=12&name=wendu")
// Optionally the request above could also be done as
response=await dio.get("/test",data:{"id":12,"name":"wendu"})

Performing a POST request:

response=await dio.post("/test",data:{"id":12,"name":"wendu"})

Performing multiple concurrent requests:

response= await Future.wait([dio.post("/info"),dio.get("/token")]);

Downloading a file:

response=await dio.download("https://www.google.com/","./xx.html")

Sending FormData:

FormData formData = new FormData.from({
   "name": "wendux",
   "age": 25,
response = await dio.post("/info", data: formData)

Uploading multiple files to server by FormData:

FormData formData = new FormData.from({
   "name": "wendux",
   "age": 25,
   "file1": new UploadFileInfo(new File("./upload.txt"), "upload1.txt")
   "file2": new UploadFileInfo(new File("./upload.txt"), "upload2.txt")
response = await dio.post("/info", data: formData)

Dio APIs #

Creating an instance #

You can create instance of Dio with a optional Options object:

Dio dio = new Dio; // with default Options
Options options= new Options(baseUrl:"https://www.xx.com/api" );
Dio dio = new Dio(options);

The core API in Dio instance is :


response=await request("/test", data: {"id":12,"name":"xx"}, new Options(method:"GET"));

Request method aliases #

For convenience aliases have been provided for all supported request methods.








Request Options #

These are the available config options for making requests. Requests will default to GET if method is not specified.

  /// 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;

  /// Reserved, not support yet!
  int timeout;

  /// 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;

  /// Custom field that you can retrieve it later in [Interceptor]、[TransFormer] and the [Response] object.
  Map<String, dynamic> extra;

Response Schema #

The response for a request contains the following information.

  /// Response body. may have been transformed, please refer to [ResponseType].
  T data;
  /// Response headers.
  HttpHeaders headers;
  /// The corresponding request info.
  Options request;
  /// Http status code.
  int statusCode;

When request is succeed, you will receive the response as follows:

Response response=await dio.get("https://www.google.com");

Interceptors #

Each Dio instance has a RequestInterceptor and a ResponseInterceptor, by which you can intercept requests or responses before they are handled by then or catchError.

 dio.interceptor.request.onSend = (Options 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)`    
 dio.interceptor.response.onSuccess = (Response response) {
     // Do something with response data
     return response; // continue
 dio.interceptor.response.onError = (DioError e){
     // Do something with response error
     return DioError;//continue

If you may need to remove an interceptor later you can.


Resolve and reject the request #

In all interceptors, you can interfere with thire 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) .

 dio.interceptor.request.onSend = (Options options){
     return dio.resolve("fake data")    
 Response response= await dio.get("/test");
 print(response.data);//"fake data"

Supports Async tasks in Interceptors #

Interceptors not only support synchronous tasks , but also supports asynchronous tasks, for example:

  dio.interceptor.request.onSend = (Options options) async{
     //...If no token, request token firstly.
     Response response = await dio.get("/token");
     //Set the token to headers 
     options.headers["token"] = response.data["data"]["token"];
     return options; //continue   

Lock/unlock the interceptors #

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.

tokenDio=new Dio(); //Create a new instance to request the token.
dio.interceptor.request.onSend = (Options options) async{
     // If no token, request token firstly and lock this interceptor
     // to prevent other request enter this interceptor.
     // We use a new Dio(to avoid dead lock) instance to request token. 
     Response response = await tokenDio.get("/token");
     //Set the token to headers 
     options.headers["token"] = response.data["data"]["token"];
     return options; //continue   

Handling Errors #

  try {
    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) {
      } else{
        // Something happened in setting up or sending the request that triggered an Error  

Using application/x-www-form-urlencoded format #

By default, Dio serializes request data(except String type) to JSON. To send data in the application/x-www-form-urlencoded format instead, you can :

//Instance level
//or works once
dio.post("/info",data:{"id":5}, options: new Options(contentType:ContentType.parse("application/x-www-form-urlencoded")))    

Sending FormData #

You can also send FormData with Dio, which will send data in the multipart/form-data, and it supports upload files.

FormData formData = new FormData.from({
    "name": "wendux",
    "age": 25,
    "file": new UploadFileInfo(new File("./example/upload.txt"), "upload.txt")
response = await dio.post("/info", data: formData)

Note: Just the post method suppots FormData.

Transformer #

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 custom the transformation of request/response data, you can provide a TransFormer by your self, and replace the DefaultTransformer by setting the dio.transformer.

Set proxy and HttpClient config #

Dio use HttpClient to send http request, so you can config the dio.httpClient to support porxy, for example:

  dio.httpClient.findProxy = (uri) {
    //proxy all request to localhost:8888
    return "PROXY localhost:8888";

Features and bugs #

Please file feature requests and bugs at the issue tracker.

pub points



A powerful Http client for Dart, which supports Interceptors, Global configuration, FormData and soon on.

Repository (GitHub)
View/report issues


Packages that depend on dio