Retrofit – Java(Android) 的REST 接口封装类库汇总

Retrofit 和Java领域的ORM概念类似， ORM把结构化数据转换为Java对象，而Retrofit 把REST API返回的数据转化为Java对象方便操作。

同时还封装了网络代码的调用。

例如：public interface GitHubService {@GET("/users/{user}/repos")List<Repo> listRepos(@Path("user") String user);}定义上面的一个REST API接口。

该接口定义了一个函数 listRepos , 该函数会通过HTTP GET请求去访问服务器的/users/{user}/repos路径并把返回的结果封装为List<Repo> Java对象返回。

其中URL路径中的{user}的值为listRepos 函数中的参数 user的取值。

然后通过RestAdapter 类来生成一个GitHubService 接口的实现；GitHubService service = restAdapter.create(GitHubService.class);获取接口的实现后就可以调用接口函数来和服务器交互了；List<Repo> repos = service.listRepos("octocat");从上面的示例可以看出， Retrofit 使用注解来声明HTTP请求1.支持 URL 参数替换和查询参数2.返回结果转换为Java对象(返回结果可以为JSON, protocol buffers)3.支持 Multipart请求和文件上传具体使用文档函数和函数参数上的注解声明了请求方式请求方式每个函数都必须带有 HTTP 注解来表明请求方式和请求的URL路径。

类库中有5个HTTP 注解: GET , POST , PUT , DELETE , 和HEAD。

注解中的参数为请求的相对URL路径。

@GET("/users/list")在URL路径中也可以指定URL参数@GET("/users/list?sort=desc")URL处理请求的URL可以根据函数参数动态更新。

一个可替换的区块为用{ 和} 包围的字符串，而函数参数必需用@Path 注解表明，并且注解的参数为同样的字符串@GET("/group/{id}/users") //注意字符串idList<User> groupList(@Path("id") int groupId); //注意 Path注解的参数要和前面的字符串一样 id还支持查询参数@GET("/group/{id}/users")List<User> groupList(@Path("id") int groupId, @Query("sort") String sort);请求体（Request Body）通过@Body 注解可以声明一个对象作为请求体发送到服务器。

@POST("/users/new")void createUser(@Body User user, Callback<User> cb);对象将被RestAdapter 使用对应的转换器转换为字符串或者字节流提交到服务器。

FORM ENCODED AND MULTIPART 表单和Multipart函数也可以注解为发送表单数据和multipart 数据使用@FormUrlEncoded 注解来发送表单数据；使用@Field 注解和参数来指定每个表单项的Key，value为参数的值。

@FormUrlEncoded@POST("/user/edit")User updateUser(@Field("first_name") String first, @Field("last_name") String last);使用@Multipart 注解来发送multipart数据。

使用@Part 注解定义要发送的每个文件。

@Multipart@PUT("/user/photo")User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString des cription);Multipart 中的Part使用RestAdapter 的转换器来转换，也可以实现TypedOutput 来自己处理序列化。

异步VS 同步每个函数可以定义为异步或者同步。

具有返回值的函数为同步执行的。

@GET("/user/{id}/photo")Photo listUsers(@Path("id") int id);而异步执行函数没有返回值并且要求函数最后一个参数为Callback对象@GET("/user/{id}/photo")void listUsers(@Path("id") int id, Callback<Photo> cb);在 Android 上，callback对象会在主(UI)线程中调用。

而在普通Java应用中，callback 在请求执行的线程中调用。

服务器结果转换为Java对象使用RestAdapter的转换器把HTTP请求结果（默认为JSON）转换为Java对象，Java对象通过函数返回值或者Callback接口定义@GET("/users/list")List<User> userList();@GET("/users/list")void userList(Callback<List<User>> cb);如果要直接获取HTTP返回的对象，使用Response 对象。

@GET("/users/list")Response userList();@GET("/users/list")void userList(Callback<Response> cb);项目主页：http://square.github.io/retrofit/参考项目：http://square.github.io/okhttp/Android 示例项目：https:///goodev/RetrofitDemo定义一个注解，用来对bean进行要序列化的字段[java]view plaincopy1.import ng.annotation.Documented;2.import ng.annotation.ElementType;3.import ng.annotation.Retention;4.import ng.annotation.RetentionPolicy;5.import ng.annotation.Target;6.7./**8. * 用于Gson命名策略的注解9. */10.@Documented11.@Retention(RetentionPolicy.RUNTIME)12.@Target(ElementType.FIELD)13.public@interface ParamName {14.15. String value();16.}将注解对需要网络传输bean进行标注：[java]view plaincopy1.public class requestBean implements Parcelable {2.public static final int RESPONSE_OK = 1;3.@ParamName("id")4.private String mId;5.@ParamName("name")6.private String mName;7.@ParamName("result")8.private int mResult;9.@ParamName("message")10.private String mMessage;11.public int getResult() {12.return mResult;13.}14.public String getMessage() {15.return mMessage;16.}17.public String getId()18.{19.return mId;20.}21.public String getName()22.{23.return mName;24.}25.public boolean succeed() {26.return getResult() == RESPONSE_OK;27.}28.}把定义好的注解封装进gson[java]view plaincopy1.import com.google.gson.FieldNamingPolicy;2.import com.google.gson.FieldNamingStrategy;3.import com.google.gson.Gson;4.import com.google.gson.GsonBuilder;5.6.import com.newandbie.privatecustomize.Config;7.import com.newandbie.privatecustomize.annotate.ParamName;8.import com.newandbie.privatecustomize.model.Gender;9.10.import ng.reflect.Field;11.12./**13. * 自定义的Gson14. */15.public class GsonUtils {16.17.public static Gson newInstance() {18. GsonBuilder builder = new GsonBuilder();19.20. builder.setFieldNamingStrategy(new AnnotateNaming());21.22.return builder.create();23. }24.25.private static class AnnotateNaming implements FieldNamingStrategy {26.27.@Override28.public String translateName(Field field) {29. ParamName a = field.getAnnotation(ParamName.class);30.return a != null ? a.value() : FieldNamingPolicy.IDENTITY.translateName(field);31. }32. }33.}[java]view plaincopy1.import com.squareup.okhttp.Cache;2.import com.squareup.okhttp.OkHttpClient;3.5.6.import java.io.File;7.import java.io.IOException;8.import java.util.concurrent.TimeUnit;9.10./**11. * OkHttpClient自定义工具类12. */13.public class OkHttpUtils {14.15.private static OkHttpClient singleton;16.17.public static OkHttpClient getInstance(Context context) {18.if (singleton == null) {19.synchronized (OkHttpUtils.class) {20.if (singleton == null) {21. File cacheDir = new File(context.getCacheDir(), Config.RESPONSE_CACHE);22.23. singleton = new OkHttpClient();24.try {25. singleton.setCache(new Cache(cacheDir, Config.RESPONSE_CACHE_SIZE));26. } catch (IOException e) {27. e.printStackTrace();28. }29. singleton.setConnectTimeout(Config.HTTP_CONNECT_TIMEOUT,LISECONDS);30. singleton.setReadTimeout(Config.HTTP_READ_TIMEOUT, TimeULISECONDS);31. }32. }33. }34.return singleton;35. }36.}定义Retrofit工具将以上两个工具配置到RetrofitUtils[java]view plaincopy1.import android.content.Context;2.3.import retrofit.RestAdapter;5.import retrofit.converter.GsonConverter;6.7.public class RetrofitUtils {8.9.private static RestAdapter singleton;10.11.public static <T> T createApi(Context context, Class<T> clazz) {12.if (singleton == null) {13.synchronized (RetrofitUtils.class) {14.if (singleton == null) {15. RestAdapter.Builder builder = new RestAdapter.Builder();16. builder.setEndpoint(ip地址);//设置远程地址17. builder.setConverter(new GsonConverter(GsonUtils.newInstance()));18. builder.setClient(new OkClient(OkHttpUtils.getInstance(context)));19. builder.setLogLevel(20. Config.DEBUG ? RestAdapter.LogLevel.FULL : RestAdapter.LogLevel.NONE);21. singleton = builder.build();22. }23. }24. }25.return singleton.create(clazz);26. }27.}那么工具集准备好了，使用retrofit放在父类以便子类调用[java]view plaincopy1.import retrofit.Callback;2.import retrofit.RetrofitError;3.import retrofit.client.Response;/**4. * 界面的基类5. */6.public class BaseActivity extends ActionBarActivity {7.8.....9.11. * 创建API实例12. *13. * @param cls Api定义类的类型14. * @param <T> 范型15. * @return API实例16. */17.public <T> T createApi(Class<T> cls) {18.return RetrofitUtils.createApi(this, cls);19. }20.21.22.public static abstract class ActivityCallback<T>23.implements Callback<T> {24. <span style="white-space:pre"> </span>//软引用，缓存引用对象25.private final WeakReference<BaseActivity> mRef;26.27.28.public ActivityCallback(BaseActivity activity) {29. mRef = new WeakReference<BaseActivity>(activity);30. }31.32.33.public Activity getActivity() {34.return mRef.get();35. }36.37.38.@Override39.public void failure(RetrofitError error) {40.final BaseActivity activity = mRef.get();41.42.43. Response response = error.getResponse();44.if (response != null) {45. Toast.makeText(activity, activity.getString(R.string.server_error),46. Toast.LENGTH_SHORT).show();47. Log.e(getLogTag(),48."code:" + response.getStatus() + ", reason:" + response.getReason());49. error.printStackTrace();50. }51.53.54.55. }56.57......58.59.}定义下面的一个REST API接口。