网络请求服务 | 文档中心

一、简介

C端 APP 提供了默认的网络请求服务，默认情况下是针对 XLINK 的接口使用。网络请求服务用于 SDK 统一发起接口请求，并返回统一的错误码格式及信息的 HTTP 请求处理服务。如果是需要发起 XLINK 相关的 API 请求，推荐优先使用网络请求服务。

网络请求服务默认将会使用授权服务中的用户授权信息，不再需要另行指定 Access-Token；网络请求服务也预定义了部分 XLINK 接口服务实现，可以通过接口直接进行 XLINK API 的调用，不用再另行定义接口并调用。

tips：默认情况下，网络请求服务在 SDK 初始化时一并初始化，不需要再另行注册初始化。

二、XLINK API 请求

如果需要发起 XLINK API 请求时，可以优先使用请求框架中提供的请求接口。以用户登录操作请求为例：

XLinkApiImplUser.postUserAuth(RequestUserAuth("企业ID","账号","密码",false))
    .asFlow()
    .onEach { println(it.accessToken) }
    .launchIn(GlobalScope)

tips：flow 为 kotlin 中提供的协程类，具体的使用请参考 kotlin 官方说明。

所有的 XLINK 接口遵循以下的命名规范：

可以直接调用的 API 接口为XLinkApiImpl前缀，后接相应的 API 模块名称，如用户相关接口为XLinkApiImplUser，设备相关接口为XLinkApiImplDevice
所有的请求参数类以Request前缀，后接 API 接口的相关描述，如用户登录授权请求参数为RequestUserAuth
所有的响应参数类以Response前缀，后接 API 接口的相关描述，与Request请求基本对应，如用户授权登录响应参数为ResponseUserAuth

注意在 XLINK API 发生变更时，相应的接口的参数和返回信息也可能会发生变更，使用 XLINK API 请求时，将会有以下的默认配置。

默认将会使用指定的路径进行请求，所有的请求路径在XLinkApiPath前缀，不同模块的名称作为后缀，如用户相关接口路径XLinkApiPathUser。
默认使用的路径为相对路径，将会拼接上网络请求服务配置的域名。域名信息在xlink_config.xf的初始化配置文件中定义。
默认请求接口都会使用授权信息中的数据，在请求时拼接上Access-Token的授权信息。

tips：XLINK API 接口的请求仅适用于 XLINK 平台的请求，并且初始化配置文件中使用的域名相应的 XLINK 平台域名，以确保服务接口可以正常调用。如需灵活或定制性更强的接口，请使用通用 HTTP 请求

三、通用的 HTTP 请求服务

网络请求服务允许发起任意类型的 HTTP 请求操作，包含 XLINK 平台的 API 与非 XLINK 平台的接口都是允许的。HTTP 请求默认是使用 retrofit 请求框架发起的请求。

//请求类
class Request(val userId:String)
//返回类
class Response{
    //此处使用的是 gson 的序列化
    @SerializedName("access_token")
    var accessToken:String=""
}

fun sendRequest(){
    val params = Request("用户ID")
    HttpRequest()
        //指定请求方式
        .post()
        //设置请求路径，可以是相对地址或绝对地址
        .setUrl("/v2/xlink/test/{path_1}")
        //设置header中的参数
        .addHeaderParams("Access-Token","授权信息")
        //设置路径中的参数
        .addPathParams("{path_1}","路径")
        //设置查询参数
        .addQueryParam("id","查询参数")
        //设置body
        .setBodyFormatByGson(params)
        .createExecutor<Response>()
        .asFlow()
        .onEach { println(it.accessToken) }
        .launchIn(GlobalScope)
}

一般情况下，参考上述的请求构建方式，即可发起一个 http 请求，满足大部分情况下的需求。

tips：XLINK API 请求时数据序列化依赖于 Gson，对于参数与返回数据序列化时，请使用 Gson 进行序列化标识

1、其它请求操作

HttpRequest 提供了多种场景的使用接口，根据接口的要求可以使用不同的功能。

1.1、设置完整的请求链接

如果需要使用完整的请求链接，而不需要拼接配置文件中定义好的 baseUrl 时，请使用以下方法。

HttpRequest()
    ...
    .setCompleteUrl("完整的URL")
    ...

1.2、设置 json 字符串形式的 body

如果请求的 body 比较复杂或者是临时性数据，不方便构建成一个对象时，可以直接设置字符串形式的 body。

HttpRequest()
    ...
    .setBodyAsJson("""{"参数":"值"}""")
    ...

2、构建定制的 XLINK API 请求

由于网络服务中包含了 XLINK API 的接口处理，其中就包含了 XLINK API 的路径定义。常用的一些 API 路径已经定义到接口中了。所以对于 XLINK API 的接口请求也可以通过通用 HTTP 请求构建出来，以下的处理方式适用于某些接口变更或参数定制性较强的场景。

下面以用户登录授权接口为例，该操作与XLinkApiImplUser.postUserAuth()的方法调用是相同的。

val request=RequestUserAuth("企业ID","账号","密码",false)
HttpRequest()
    .post()
    .setBodyFormatByGson(request)
    .createExecutor<ResponseUserAuth>()
    .asFlow()
    ...

上次更新：2024-05-09