AI 助理
备案控制台
文档
输入文档关键字查找
首页 SOFAStack API 统一网关 快速入门 HTTP 转 SOFARPC 入门

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. 进入金融分布式架构控制台。

  2. 左侧导航栏单击 API统一网关 > API 发布 > 系统集群。

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

  4. 在新弹出窗口中，您需要配置以下信息：

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

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

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

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

      • IP 地址或域名：

        • IP 地址格式为 （1~255）.（0~255）.（0~255）.（0~255）。

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

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

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

      1

  5. 单击 确定。

步骤三：创建 API 分组

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

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

  3. 在新弹出窗口中，输入 API 分组信息：

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

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

      2

  4. 单击 确定。

步骤四：创建并发布 API

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

  2. 在新页面中，选择 HTTP API 类型，单击 创建。

  3. 在 定义 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

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

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

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

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

    • 超时时间：必填，API 请求超时时间，单位为毫秒（ms），保持默认即可。

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

    • 系统集群：必选，选择步骤二创建的系统集群，即 sofarpc。

      1

  5. 单击 创建。

  6. 创建完成后，单击 立即发布 发布该 API。

步骤五：创建应用

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

  2. 在 创建应用 窗口，选择 应用类型 为 应用。

  3. 输入 应用名称，用于识别应用。本例使用 hello。

    5

  4. 单击 确定。

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

步骤六：创建授权对象

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

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

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

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

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

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

      11

  3. 单击 确定。

步骤七：绑定授权对象

  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>
    public class GatewayTest {
    private String subAppAccessKey = "${gateway.accessKey}";

    private String subAppSecretKey = "${gateway.secretKey}";

    private String gatewayUrl = "http://mvwmni87dqwc****.apigateway.inc.alipay.net";

    private ApiClient apiClient;

    @Before
    public void initClient() {
        // 初始化请求客户端
        ApiSecretKey apiSecretKey = new ApiSecretKey(subAppAccessKey, subAppSecretKey);
        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}"}

上一篇：HTTP API 入门下一篇：操作指南
文档推荐