优雅的调用RESTful API

2020-04-25 本文已影响0人大哥你先走

代码量越少越优雅，实现越简单越优雅，下面介绍如何优雅的实现API调用。

1 单资源访问

下面以华为云IoT平台提供的查询订阅API为例说明不同方式调用单资源API的异同。订阅API的详细信息可以从这里获取。API的简单定义如下：

请求方法	GET
URI	/v5/iot/{project_id}/subscriptions/{subscription_id}
传输协议	HTTPS

1.1 API的常规调用方式：

// 第一步构建client
OkHttpClient client = new OkHttpClient.Builder()
        .build();

// 第二步构建请求
Request request = new Request.Builder()
        .url("https://iotda.cn-north-4.myhuaweicloud.com//v5/iot/project_id/subscriptions/subscription_id")
        .get()
        .addHeader("X-Auth-Token","token")
        .build();

// 第三步调用请求
Response response = client.newCall(request).execute();

// 第四步处理响应
System.out.println(response);

1.2 API调用的四个步骤：

1、构建一个HTTP/HTTPS client，client可共享。

2、构建HTTP request，不同的API对应不同的request，每个API都需要构建独立的HTTP Request，request在不同API之间不可共享。

3、发送请求并获取响应，这部分逻辑由client负责，应用代码无需处理。

4、响应处理，主要工作就是反序列化，反序列化的代码可以共享。

是否有改进的地方？

HTTP/HTTPS client的构建不可缺少，步骤一不存在改进的地方（说的是简化代码方面的改进）。
HTTP/HTTPS Request必不可少，但是构建的方法可以更加优雅，更加简单，是一个改进点。
请求发送由client负责，不存在改进的地方。
响应处理必不可少，但是响应的反序列化工作可以更简单优雅，减少自研代码量。

找到了优化的地方，就可以行动了，光说不干，用于会止步不前。Wait！Wait！Wait！难道我们是第一个想优化API调用的人吗？当然不是，square已经提供了一个优雅的解决方案，那就是retrofit项目。下面使用retrofit重构上面的API调用，看看retrofit的效果如何？

1.3 Retrofit重写API调用

引入retrofit

MAVEN

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>2.8.1</version>
</dependency>
<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>converter-jackson</artifactId>
  <version>2.8.1</version>
</dependency>

GRADLE（不会GRADLE都无法在社区混了，建议大家学习一下）

implementation 'com.squareup.retrofit2:retrofit:2.8.1'
implementation 'com.squareup.retrofit2:converter-jackson:2.8.1'

定义API接口：

public interface IoTSubscriptionService {
    @GET("/v5/iot/{project_id}/subscriptions/{subscription_id}")
    Call<SubscriptionDTO> getSubscription(@Header("X-Auth-Token") String token,
                                          @Path("project_id") String projectId,
                                          @Path("subscription_id") String subscriptionId);
}

创建`Retrofit` 实例

Retrofit retrofit = new Retrofit.Builder()
            .client(HttpsClientFactory.getHttpsClient())
            .addConverterFactory(JacksonConverterFactory.create())
            .baseUrl(ApplicationConf.getEndpoint())
            .build();

实例化API接口并调用

IoTSubscriptionService subService = retrofit.create(IoTSubscriptionService.class);
Call<SubscriptionDTO> response = subService.getSubscription("token", "project_id", "subscriptionId");

使用Retrofit可以像调用Java的interface一样调用API，是不是有一种RPC调用风格的感觉？

使用Retrofit和不适用Retrofit调用API的异同之处

构造HTTP Client的基本工作必不可少。
使用Retrofit，可以简化响应的反序列化，Retrofit提供了各种开箱即用的转换器。
使用Retrofit可以让URL更短（baseUrl只需要定义一次）。
调用风格不同，Retrofit提供一种类似Java Interface的调用风格，这对于开发人员使用更加友好，客户端代码也更加优雅。

Retrofit可以让API的调用更加简单更加优雅，下面详细介绍Retrofit的使用。

1.4 Retrofit

Retrofit是类型安全的HTTP client，可用于Android和Java平台。

1.4.1 API声明

Retrofit通过接口方法和方法参数上的注解了解应该如何处理请求。

请求方法

接口中的每个方法都必须有一个HTTP注解，注解包括请求方法和相对URL。Retrofit提供8种注解：HTTP, GET, POST, PUT, PATCH, DELETE, OPTIONS 和HEAD。资源的相对URL在注解中指定。

@GET("users/list")

支持在URL中指定默认查询参数。

@GET("users/list?sort=desc")

URL 操作

请求的URL可以使用URL上的替换块和方法的参数来动态更新。URL的替换块用{} 表示，对应的值必须使用注解@Path 指定，而且名字必须相同，这和基于Spring MVC开发API时的使用方法一致。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);

支持增加单个请求参数：

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

支持通过Map添加多个请求参数：

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

请求体

使用@Body 注解可以将一个对象指定为HTTP请求的body。

@POST("users/new")
Call<User> createUser(@Body User user);

默认使用Retrofit 实例提供的转换器对body进行转换，如果Retrofit 没有添加转换器，作为body体对象的类型只能是Retrofit 定义的RequestBody 类型。

FORM ENCODED AND MULTIPART

可以声明方法用来支持发送form-encoded和multipart数据。

当方法上有@FormUrlEncoded 注解时，数据会以form-encoded的形式发送。数据的每一个key-value对通过@Field 注解指定，其中包括名字和对应的值。

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

方法上有 @Multipart 注解时，支持以Multipart 的方式发送数据，数据的每一部分用@Part 表示。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

Multipart 的part使用 Retrofit 的一个转换器转换，或者实现RequestBody 来自定义序列化。

操作header

可以使用 @Headers 注解为方法增加静态header值。

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);

同名的header不会互相覆盖，而且全部包含在request中。

可以使用@Header 注解动态更新request的header，对应的参数必须通过@Header 提供。如果参数为null，则该header被忽略，否则调用参数的toString方法并替换header。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

支持通过Map 提供多个header：

@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headers)

每个请求都需要添加的header或请求参数，应该通过OkHttp的拦截器实现，参考拦截器.

同步VS. 异步

Call 实例支持同步调用和异步调用，每个Call 实例只能被调用一次，调用clone() 方法可以创建一个继续使用的新的实例。在Android系统，主线程负责回调。在JVM中，执行HTTP请求的线程负责回调。

1.4.2 Retrofit 配置

Retrofit 负责将API声明的接口转换为调用对象。默认Retrofit 使用系统的默认配置，但是支持自定义。

转换器

默认，Retrofit 只能将HTTP的body序列化为OkHttp的ResponseBody 类型，而且@Body 只能接受ResponseBody 类型的参数。

向Retrofit 添加转换器可以支持其他类型的序列化和反序列化。为了使用方便Retrofit 提供了6个开箱即用的模块，这些模块都是对流行的序列化库的封装。

Gson: com.squareup.retrofit2:converter-gson
Jackson: com.squareup.retrofit2:converter-jackson
Moshi: com.squareup.retrofit2:converter-moshi
Protobuf: com.squareup.retrofit2:converter-protobuf
Wire: com.squareup.retrofit2:converter-wire
Simple XML: com.squareup.retrofit2:converter-simplexml
JAXB: com.squareup.retrofit2:converter-jaxb
Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

自定义转换器

如果你需要交互的API使用一种Retrofit不支持的内容格式，比如YAML,txt或自定义格式，或者使用其他的库实现已有的格式，可以自定义一个转换器。如定义转换器非常的简单，只要扩展Converter.Factory 类，并将自定义的实例传递给Retrofit即可。

2 多资源访问

当检索多个资源时，服务端返回的数据量可能超过客户端的处理能力，而且单次返回的数据量太大会增加客户端和服务器的压力，增加数据传输占用的带宽。分页查询可以有效的降低服务端和客户端的压力，但是编写分页查询的代码十分的枯燥无味，尤其对于SDK的开发者。

2.1 分页查询的流程

以获取Kubernetes集群内所有pod为例，说明分页查询的流程，假设集群内共有1253个pods，每次查询服务端最多返回500个pods：

1、查询集群内所有的pods，每次获取500 pods

GET /api/v1/pods?limit=500
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "ENCODED_CONTINUE_TOKEN",
    ...
  },
  "items": [...] // returns pods 1-500
}

2、继续获取500个pods

GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "ENCODED_CONTINUE_TOKEN_2",
    ...
  },
  "items": [...] // returns pods 501-1000
}

3、继续获取余下所有的pod

GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
---
200 OK
Content-Type: application/json
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion":"10245",
    "continue": "", // continue token is empty because we have reached the end of the list
    ...
  },
  "items": [...] // returns pods 1001-1253
}

2.2 封装分页查询

从分页查询的流程可以看出，分页查询就是一次一次向服务端发送请求获取数据，直到服务端返回所有的数据。分页查询的流程和Java中的Iterator 迭代数据的流程十分的相似。下面考虑将分页查询封装为一个Iterator 对象，通过Iterator 的next() 方法不断获取服务器的数据。由于很难构造一个大的Kubernetes集群，分页查询的封装还是以IoT平台”查询设备列表“这个API为例说明。

public interface IoTDeviceService {
    @GET("/v5/iot/{project_id}/devices?limit=50")
    Call<DevicesDTO> queryDeviceList(@Header("X-Auth-Token") String token,
                                     @Path("project_id") String projectId,
                                     @Query("app_id") String appId,
                                     @Query("marker") String marker);
}

将分页查询封装为Iterator ：

private static class LazyIterator implements Iterator<Device> {
        private static final Logger log = LoggerFactory.getLogger(LazyIterator.class);
        private IoTDeviceService deviceService = IoTServiceFactory.getIoTDeviceService();
        private String appId;
        private String projectId;
        private String token;
        private List<Device> currentList = new ArrayList<>(50);
        private int pos;
        private String marker;
        private long totalCount = Long.MAX_VALUE;
        private long alreadyCount = 0L;

        LazyIterator(String appId, String projectId, String token) {
            this.appId = appId;
            this.projectId = projectId;
            this.token = token;
        }

        @Override
        public boolean hasNext() {
            return alreadyCount < totalCount;
        }

        @Override
        public Device next() {
            if (!currentList.isEmpty() && pos < currentList.size()) {
                alreadyCount++;
                return currentList.get(pos++);
            } else {
                Call<DevicesDTO> response = deviceService.queryDeviceList(token, projectId, appId, marker);
                try {
                    DevicesDTO devicesDTO = response.execute().body();
                    if (devicesDTO != null) {
                        PageDTO pageDTO = devicesDTO.getPage();
                        this.marker = pageDTO.getMarker();
                        if (totalCount == Long.MAX_VALUE) {
                            this.totalCount = pageDTO.getCount();
                        }
                        List<DeviceDTO> devices = devicesDTO.getDevices();
                        currentList.clear();
                        pos = 0;
                        devices.forEach(deviceDTO -> {
                            Device device = new Device();
                            device.setDeviceId(deviceDTO.getDeviceId());
                            device.setNodeId(deviceDTO.getNodeId());
                            device.setAppId(deviceDTO.getAppId());
                            device.setProductId(deviceDTO.getProductId());
                            currentList.add(device);
                        });
                    }
                } catch (IOException e) {
                    log.error("io exception = {}", e.toString());
                }
            }
            alreadyCount++;
            return currentList.get(pos++);
        }
    }

优雅的调用RESTful API

1 单资源访问

1.1 API的常规调用方式：

1.2 API调用的四个步骤：

是否有改进的地方？

1.3 Retrofit重写API调用

引入retrofit

定义API接口：

创建`Retrofit` 实例

实例化API接口并调用

1.4 Retrofit

1.4.1 API声明

请求方法

URL 操作

请求体

FORM ENCODED AND MULTIPART

操作header

同步VS. 异步

1.4.2 Retrofit 配置

转换器

自定义转换器

2 多资源访问

2.1 分页查询的流程

2.2 封装分页查询

猜你喜欢

热点阅读

优雅的调用RESTful API

1 单资源访问

1.1 API的常规调用方式：

1.2 API调用的四个步骤：

是否有改进的地方？

1.3 Retrofit重写API调用

引入retrofit

定义API接口：

创建Retrofit 实例

实例化API接口并调用

1.4 Retrofit

1.4.1 API声明

请求方法

URL 操作

请求体

FORM ENCODED AND MULTIPART

操作header

同步VS. 异步

1.4.2 Retrofit 配置

转换器

自定义转换器

2 多资源访问

2.1 分页查询的流程

2.2 封装分页查询

猜你喜欢

热点阅读

创建`Retrofit` 实例