文档

HTTP 转 SOFARPC 入门

更新时间:
一键部署

本文介绍如何快速创建并发布一个 HTTP API 类型的 API 服务,通过 API 网关进行协议转换,使用 SOFARPC 协议将请求转发到后端业务系统集群。

操作步骤

说明

建议您先阅读 快速入门概述,了解 API 网关的角色及完整使用流程。

入门流程

示例工程

为方便快速体验 API 网关 HTTP 转换 SOFARPC 的 API 服务,您可以单击此处下载本文涉及的 示例工程

步骤一:编写 SOFARPC Server

SOFARPC Server 的编写没有特殊的要求,按照 SOFARPC 的标准教程即可,此处简单编写一个 UserService。

说明

关于如何创建 SOFABoot 工程,参见 新建工程

public interface SampleService {
    User message();
}

public class SampleServiceImpl implements SampleService {

    @Override
    public User message() {
        User user = new User();
        user.setAge(18);
        user.setName("tom");
        return user;
    }
}

public class User {
    private String name;
    private int age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

将该 service 发布为 SOFARPC 服务:

    <bean id="sampleService" class="com.alipay.gateway.endpoint.impl.SampleServiceImpl"/>

    <!-- 发布 RPC 服务 -->
    <sofa:service ref="sampleService" interface="com.alipay.xxxxxxxx.SampleService">
        <sofa:binding.bolt/>
    </sofa:service>
说明

网关现已支持 HTTP Header 转 SOFARPC Baggage 透传功能,在 HTTP-SOFARPC 的转换中,把约定好的 HTTP Header 中的传参形式加入到 Baggage 参数中:

request.getHeaderParams().put("baggage_context.透传参数名称","透传数据")

然后在 SOFARPC 服务中,可以通过 Baggage 函数获取对应的参数值。

RpcInvokeContext context = RpcInvokeContext.getContext();
context.getRequestBaggage("透传参数名称")

步骤二:创建系统集群

  1. 进入 API 网关控制台页面,左侧导航栏选择 API 发布 > 系统集群

  2. 在系统集群列表页面,单击右上方的 创建系统集群 按钮。

  3. 在新弹出窗口中,您需要配置以下信息:

    • 系统集群名称:必填,用于识别系统集群。根据本示例,此处可使用 sofarpc

    • 协议类型:支持 HTTP、SOFARPC。根据本示例,此处需选择 SOFARPC

    • 地址配置方式:选择 手动配置,即手动配置系统集群的 IP 地址或域名。

    • IP地址/域名:格式为 地址:端口。本示例中,IP 地址使用 127.0.0.1,端口号使用 12200

      • IP 地址或域名:

        • IP 地址格式为 (1~200).(0~200).(0~200).(0~200)

        • 域名可以包含字母、数字或者半角的连接符(-),总共不超过 200 个字符。

      • 端口:HTTP 默认端口为 80,SOFARPC 默认端口为 12200。端口号范围为 1-65535。

    • 描述:选填,用于描述系统集群的作用等,64 个字符以内,可为空。

      1

  4. 单击 确定

步骤三:创建 API 分组

  1. 登录 API 网关控制台页面。

  2. 在左侧导航栏单击 API 发布 > API 分组,进入分组列表。

  3. 单击 API 分组列表右上方的 创建分组 按钮。

  4. 在新弹出窗口中,输入 API 分组信息:

    • 分组名称:必填,用于识别 API 分组。支持英文字母、中文、数字、下划线(_)、连接符(-),32 个字符以内。本示例使用 sofarpc

    • 描述:选填,用于描述 API 分组的作用等,64 个字符以内,可为空。

      2

  5. 单击 确定

步骤四:创建并发布 API

  1. 登录 API 网关控制台。

  2. 在左侧导航栏单击 API 发布 > API 管理 页,单击列表右上方的 创建 API

  3. 在新页面中,选择 HTTP API 类型,单击 创建

  4. 定义 API 步骤中,您需要配置以下信息:

    • API 分组:必选,选择上一步创建的 API 分组。

    • API 名称:必填,用于识别 API,支持英文字母、中文、数字、下划线(_)、连接符(-),32 个字符以内。本示例使用 sofarpc

      说明

      同一个 API 分组下,API 名称不能相同。

    • 描述:选填,用于描述 API 的作用等,64 个字符以内。

    • API 授权应用类型:必选,指定可以订阅并调用该 API 的应用类型。根据本示例,选择 应用

    • 请求路径:必填,针对应用设置的请求资源的 URL,通过请求路径可以定位到要请求的资源。根据本示例,输入 /sofarpc

    • 路径匹配规则:选择 绝对匹配,即调用时完全匹配以上填写的路径。详见 路径匹配规则

    • 方法:必填。后端调用 SOFARPC 的接口必须传递参数,所以这里需要选择 POST。请勿选择 GET 方法。

      说明

      由于 SOFARPC 需要通过 payload 信息进行反序列化操作,而 GET 请求无法携带有效 payload,故当前不支持 HTTP GET 转 SOFARPC 请求。

    • 报文类型:表示请求和响应中的媒体类型信息。此处选择 application/json

    • 报文编码:表示客户端接受什么字符集的文本内容。此处选择 UTF-8

    • 安全认证:选择 密钥认证,表示订阅应用访问授权的 API 时需要使用密钥进行身份认证。

    • 请求参数:可选,详见 API 属性说明 > 请求参数

    • 响应参数:可选,详见 API 属性说明 > 响应参数

      3

  5. 单击 下一步,进入后端配置页面,您需要选择 后端配置类型 并输入后端配置信息。根据本示例,需选择 系统集群 并配置具体集群信息。

    • 协议类型:必选,表示网关接收到请求后转发给的后端服务使用的通信协议类型。根据本示例,此处选择 SOFARCPC

    • 接口名称:即 API 接口名称,支持英文字母、数字、小数点(.)、冒号(:)、@,以小写字母作为开头。根据本示例,此处输入 com.alipay.xxxxxxxx.SampleService

    • 方法名:即 API 服务方法名,支持英文字母、数字组成,以字母作为开头。根据本示例,此处输入 message

    • 超时时间:必填,API 请求超时时间,单位为毫秒(ms),保持默认即可。

    • 路由策略:必选,表示当网关接收到语法后使用的路由策略。本例中选择 根据请求路径路由,即直接转发。

    • 系统集群:必选,选择步骤二创建的系统集群,即 sofarpc

      1

  6. 单击 创建。

  7. 创建完成后,单击 立即发布 发布该 API。

步骤五:创建应用

  1. 登录 API 网关控制台。

  2. 在左侧导航栏单击 API 订阅 > 应用管理 页,单击列表右上方的 创建应用

  3. 创建应用 窗口,选择 应用类型应用

  4. 输入 应用名称,用于识别应用。本例使用 hello

    5

  5. 单击 确定

应用添加完成后,订阅者需在应用详情页,获取该应用 APPID。获取 APPID 后,需将 APPID 提供给想要订阅的 API 的发布者,获得该 API 的访问授权。

步骤六:创建授权对象

  1. 登录 API 网关控制台。

  2. 在左侧导航栏单击 API 发布 > 授权管理 页,单击列表右上方的 创建授权对象

  3. 创建授权对象 窗口中,配置订阅方应用的授权信息。

    • 应用来源:必选。此处选 内部系统 即可,表示授权给当前租户的当前环境下的应用订阅。

    • 应用名称:输入其上一步创建的应用名称,如 hello,系统会自动获取其 APPID 与类型。

    • 所属公司/部门:用于识别应用所属的公司或部门,可为空。

    • 描述:输入对该授权对象的备注信息,可为空。

      11

  4. 单击 确定

步骤七:绑定授权对象

  1. API 管理 页面,找到待订阅 API,进入其详情页。

  2. 授权对象 标签页下,单击 绑定授权对象

  3. 添加授权对象 窗口中,找到刚刚创建的授权应用。

    12

  4. 勾选该应用,单击 确定,完成 API 授权。

步骤八:编写 API 调用代码

  1. 获取如下服务配置信息:

    • 在订阅方应用详情页获取该应用的密钥(Access Key/Secret Key)。

      1

    • 在 API 详情页获取该 API 的域名(host)、请求路径(path)与方法(method)。

      11

  2. 编写调用代码,示例如下:

    说明

    如果 API 开启了密钥认证,您还需要在工程中配置相应的 Access Key 和 Secret Key,推荐使用启动参数和环境变量的形式。

    # 客户端请求的ak、sk,就是应用的密钥信息
    gateway.accessKey=<SOFA_ACCESS_KEY_ID>
    gateway.secretKey=<SOFA_ACCESS_KEY_SECRET>
    apigateway.url=<yourGatewayURL>
       @Value("${gateway.accessKey}")
       private String accessKey;
    
       @Value("${gateway.secretKey}")
       private String secretKey;
    
       @Value("${apigateway.url}")
       private String gatewayurl;
    
        @Before
        public void initClient() {
            // 初始化请求客户端
            ApiSecretKey apiSecretKey = new ApiSecretKey(gateway.accessKey, gateway.secretKey);
            List<ApiSecretKey> secretKeys = new ArrayList<>();
            secretKeys.add(apiSecretKey);
            apiClient = new DefaultApiClient(gatewayUrl, secretKeys);
        }
    
        @Test
        public void testNoSignHttp() {
            ParamPostRequest request = new ParamPostRequest();
            request.setPath("sofarpc");
    
            // 是否对响应进行签名校验
            request.setClientCheckSign(false);
    
            ApiResponse response = apiClient.execute(request);
    
            System.out.println(JSON.toJSONString(response));
        }
    }
  3. 发起调用后,可得出以下结果:

    {"body":"{\"name\":\"tom\",\"age\":18}"}

  • 本页导读 (0)
文档反馈