dio 0.0.2

  • Readme
  • Changelog
  • Example
  • Installing
  • 50

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 #

dependencies:
  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/");
print(response.data);

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")
print(response.data.toString());
// Optionally the request above could also be done as
response=await dio.get("/test",data:{"id":12,"name":"wendu"})
print(response.data.toString());

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
//or
Options options= new Options(baseUrl:"https://www.xx.com/api" );
Dio dio = new Dio(options);

The core API in Dio instance is :

Future

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.

Future

Future

Future

Future

Future

Future

Future

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");
print(response.data);
print(response.headers);
print(response.request);
print(statusCode);

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.

dio.interceptor.request.onSend=null;
dio.interceptor.response.onSuccess=null;
dio.interceptor.response.onError=null;

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.
tokenDio.options=dio;
dio.interceptor.request.onSend = (Options options) async{
     // If no token, request token firstly and lock this interceptor
     // to prevent other request enter this interceptor.
     dio.interceptor.request.lock(); 
     // 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"];
     dio.interceptor.request.unlock() 
     return options; //continue   
 }

Handling Errors #

  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)
      }  
  }

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
dio.options.contentType=ContentType.parse("application/x-www-form-urlencoded");
//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.

0.0.1 #

  • Initial version, created by Stagehand

example/dio.dart

import 'dart:async';
import 'dart:io';
import 'package:dio/dio.dart';

main() async {
  var dio = new Dio();
  dio.options.baseUrl = "http://www.dtworkroom.com/doris/1/2.0.0/";
  dio.options.headers = {
    'XX': '8'
  };

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

  dio.interceptor.request.onSend = (Options options) async {
    // return ds.resolve(new Response(data:"xxx"));
    // return ds.reject(new Err(message: "eh"));
    return options;
  };


  Response<String> response= await dio.get("https://www.google.com/");
  print(response.data);

  response=await dio.download("https://www.google.com/","./xx.html",onProgress: (received,total){
    print('$received,$total');
  });

//  ds.get("/test",data:{'aa':8}).catchError((Err err){
//    print(err);
//  });

  print(response);

  //FormData.boundary = "----------------------------272264345542536768869165";
  FormData formData = new FormData.from({
    "name": "wendux /r/n xxx \r\n   \$%#@ ",
    "age": 25,
    "file": new UploadFileInfo(new File("./example/upload.txt"), "upload.txt")
  });
//
//  response = await dio.post("/token", data: formData);
//  print(response);

  //Response response= await ds.post("/test",data:formData);
  //print(response.toString());

  //new Timer(new Duration(seconds: 2),()=>ds.unlock());
  //Response response= await ds.get("/test",data:{'aa':8});
  //print(response.data);

}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dio: ^0.0.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dio/dio.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
100
Health:
Code health derived from static analysis. [more]
--
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
--
Overall:
Weighted score of the above. [more]
50
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Support Dart 2 in pubspec.yaml.

The SDK constraint in pubspec.yaml doesn't allow the Dart 2.0.0 release. For information about upgrading it to be Dart 2 compatible, please see https://dart.dev/dart-2#migration.

Maintenance issues and suggestions

Make sure dartdoc successfully runs on your package's source files. (-10 points)

Dependencies were not resolved.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.20.1 <2.0.0