# RESTFUL 网路请求框架 Retrofit

Retrofit 是一个高质量高效率的 HTTP 请求库，和 OkHttp 同样出自 Square 公司。Retrofit 内部依赖于 OkHttp，它将 OKHttp 底层的代码和细节都封装了起来，功能上做了更多的扩展，比如返回结果的自动解析，网络引擎的切换，拦截器......

有了 Retrofit 之后对于一些请求我们就只需要一行代码或者一个注解、大大简化了网络请求的代码量。

retrofit 注解驱动型上层网络请求框架，使用注解来简化请求，大体分为以下几类：

使用示例：

	interface ApiService{
	@GET("user/query")
	Call<User> queryUser(@Query("userId") String userId);
	}

	val mApi = retrofit.create(ApiService.class);
	val response = mApi.queryUser("100086").execute()

retrofit注解

注解	说明
@GET	get 请求
@POST	post 请求
@PUT	put 请求
@DELETE	delete 请求
@PATCH	patch 请求，该请求是对 put 请求的补充，用于更新局部资源
@HEAD	head 请求
@OPTIONS	option 请求
@HTTP	通用注解，可以替换以上所有的注解，其拥有三个属性：method，path，hasBody

注解	说明
@Headers	用于添加固定请求头，可以同时添加多个。通过该注解添加的请求头不会相互覆盖，而是共同存在
@Header	作为方法的参数传入，用于添加不固定值的 Header，该注解会更新已有的请求头

名称	说明
@Body	多用于 post 请求发送非表单数据，比如想要以 post 方式传递 json 格式数据
@Filed	多用于 post 请求中表单字段，Filed 和 FieldMap 需要 FormUrlEncoded 结合使用
@FiledMap	和 @Filed 作用一致，用于不确定表单参数
@Part	用于表单字段，Part 和 PartMap 与 Multipart 注解结合使用，适合文件上传的情况
@PartMap	用于表单字段，默认接受的类型是 Map，可用于实现多文件上传
@Path	用于 url 中的占位符
@Query	用于 Get 中指定参数
@QueryMap	和 Query 使用类似
@Url	指定请求路径

名称	说明
@FormUrlEncoded	表示请求发送编码表单数据，每个键值对需要使用 @Field 注解
@Multipart	表示请求发送 multipart 数据，需要配合使用 @Part
@Streaming	表示响应用字节流的形式返回。如果没使用该注解，默认会把数据全部载入到内存中。该注解在在下载大文件的特别有用

	public interface ApiService {

	@GET("user/query")
	Call<User> queryUser(@Query("userId") String userId);

	// 使用 @Headers 添加多个请求头
	@Headers({"User-Agent:android", "apikey:123456789", })
	@GET("user/query")
	Call<User> queryUser(@Query("userId") String userId);

	// 多个参数的情况下可以使用 @QueryMap，但只能用在 GET 请求上
	@GET("user/query"")
	Call<User> queryUser(@QueryMap Map<String, String> params);

	/**
	* 很多情况下，我们需要上传 json 格式的数据。当我们注册新用户的时候，因为用户注册时的数据相对较多
	* 并可能以后会变化，这时候，服务端可能要求我们上传 json 格式的数据。此时就要 @Body 注解来实现。
	* 直接传入实体，它会自行转化成 Json, @Body 只能用在 POST 请求上
	*
	* 字符串提交
	*/
	@POST("user/update")
	Call<User> update(@Body News post);

	/**
	* 表单提交（键值对提交）
	*/
	@POST()
	@FormUrlEncoded
	Call<User> executePost(@FieldMap Map<String, Object> maps);


	/**
	* 表单上传文件（键值对提交、同时上传文件）
	*/
	@Multipart
	@POST("upload/upload")
	Call<> register(@Filed String openId, @PartMap Map<String, MultipartBody.Part> map);


	}

在 Android Studio 中使用，先添加依赖：

	compile 'com.squareup.retrofit2:retrofit:2.3.0'
	compile 'com.squareup.retrofit2:converter-gson:2.3.0' //json 转换

	val retrofit = new Retrofit.Builder()
	.client(okhttpClient)
	.baseUrl("http://123.56.232.18:8080/serverdemo/")
	.addConverterFactory(GSONConverterFactory.create())
	.build();

	val mApi = retrofit.create(ApiService.class);