文档

MPC API

更新时间:

快速开始指导您注册并发布一个供移动端调用的 MPC 类型的 API 服务。整体过程分为 6 步:

  1. 服务端开发

  2. 注册 API 分组

  3. 创建 API

  4. 配置 API 服务

  5. 测试 API 服务

  6. 生成客户端 SDK

服务端开发

引入网关二方包

在项目的主 pom.xml 文件中引入如下二方包(如原工程已经有依赖,请忽略)。其中 mobilegw-unify 系列依赖请使用最新版本,当前最新版本为 1.0.5.20201010。

<!-- mobilegw unify dependency-->
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-spi-mpc</artifactId>
    <version>${the-lastest-version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-spi-adapter</artifactId>
    <version>${the-lastest-version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-log</artifactId>
    <version>${the-lastest-version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.hybirdpb</groupId>
    <artifactId>classparser</artifactId>
    <version>1.2.2</version>
</dependency>
<dependency>
    <groupId>com.alipay.mpaaschannel</groupId>
    <artifactId>common</artifactId>
    <version>2.4.2019040801</version>
</dependency>
<dependency>
    <groupId>com.alipay.mpaaschannel</groupId>
    <artifactId>tenant-client</artifactId>
    <version>2.4.2019040801</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.5</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.72_noneautotype</version>
</dependency>
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>hessian</artifactId>
    <version>3.3.6</version>
</dependency>

定义服务接口并实现接口

  1. 按照业务需求,定义服务接口:com.alipay.xxxx.MockRpc

    说明
    • 方法定义中的入参尽量定义为 VO,这样后期添加参数,就可以直接在 VO 中添加,而不改变方法的声明格式。

    • 服务接口定义的相关规范,请参见 业务接口定义规范

  2. 提供该接口的实现 com.alipay.xxxx.MockRpcImpl

定义 OperationType

在服务接口的方法上添加 @OperationType 注解,定义发布服务的接口名称。@OperationType 有 3 个参数成员,为便于维护,请填写完整:

  • value:接口唯一标识;在网关全局唯一,尽量定义详细,否则可能会和其他业务方的 value 值一样,导致无法注册服务。定义规则:组织.产品域.产品.子产品.操作

  • name:接口中文名称。

  • desc:接口描述。

示例如下:

public interface MockRpc {

    @OperationType(value="com.alipay.mock", name="MPC mock 接口", desc="复杂 mock 接口")
    Resp mock(Req s);

    @OperationType(value="com.alipay.mock2", name="xxx", desc="xxx")
    String mock2(String s);
}

public static class Resp {
    private String msg;
    private int    code;

    // ignore getter & setter
}

public static class Req {
    private String name;
    private int age;

    // ignore getter & setter
}

声明 API 服务

该步骤目的是将定义好的 RPC 服务,通过网关提供的 SPI 包,声明为对外提供服务的 API。需要如下 5 个参数:

  • registryUrl: 注册中心的地址。共享式金融科技平台的注册中心地址为 mpcpub.mpaas.cn-hangzhou.aliyuncs.com

  • appName:业务方的应用名。

  • workspaceId:应用所处环境的工作空间标识(workspaceId)。

  • projectName:应用所属租户的项目名称。

  • privateKeyPathRSA 私钥的 ClassPath,与 mpaaschannel 建立连接时用于校验合法性。

    重要
    • 此处的私钥应和在控制台配置的 应用公钥 相对应。如您还未生成密钥或未在控制台配置 应用公钥,请查看后面的步骤 配置应用公钥

    • 私钥放置在 /META-INF/config/rsa-mpc-pri-key-{env}.der,其中 {env} 为不同的环境,如 devsitprod 等。

您可以通过 SpringSpring Boot 方式声明 API 服务。

Spring 声明方式

  1. 在对应 bundle 的 Spring 配置文件中,声明上述服务的 Spring Bean。示例如下:

    <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>
  2. 在对应 bundle 的 Spring 配置文件中,声明 com.alipay.gateway.spi.mpc.MpcServiceStarter 类型的 Spring Bean。MpcServiceStarter 会将所有带有 @OperationType 的 bean 通过 mpaaschannel 协议注册到指定的注册中心。示例如下:

     <bean id="mpcServiceStarter" class="com.alipay.gateway.spi.mpc.MpcServiceStarter">
         <property name="registryUrl" value="${registry_url}"/>
         <property name="appName" value="${app_name}"/>
         <property name="workspaceId" value="${workspace_id}"/>
         <property name="projectName" value="${project_name}"/>
         <property name="privateKeyPath" value="${privatekey_path}"/>
     </bean>

Spring Boot 声明方式

  1. 以注解的方式声明上述服务的 Spring Bean。示例如下:

    @Service
    public class MockRpcImpl implements MockRpc{
    }
  2. 以注解的方式声明 com.alipay.gateway.spi.mpc.MpcServiceStarter 类型的 Spring Bean。MpcServiceStarter 会将所有带有 @OperationType 的 bean 通过 mpaaschannel 协议注册到指定的注册中心。示例如下:

     @Configuration
     public class MpaaschannelDemo {
         @Bean(name="mpcServiceStarter")
         public MpcServiceStarter mpcServiceStarter(){
             MpcServiceStarter mpcServiceStarter = new MpcServiceStarter();
             mpcServiceStarter.setWorkspaceId("${workspace_id}");
             mpcServiceStarter.setAppName("${app_name}");
             mpcServiceStarter.setRegistryUrl("${registry_url}");
             mpcServiceStarter.setProjectName("${project_name}");
             mpcServiceStarter.setPrivateKeyPath("${privatekey_path}");
             return mpcServiceStarter;
         }
     }

配置 MPC 日志

为了便于排查问题,可酌情配置 MPC 相关日志,下面以 log4j 配置为例。

<!-- [MPC Logger] tenant link,记录建联,settings 信息 -->
<appender name="MPC-TENANT-LINK-APPENDER" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="file" value="${log_root}/mpaaschannel/tenant-link.log"/>
    <param name="append" value="true"/>
    <param name="encoding" value="${file.encoding}"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d [%X{remoteAddr}][%X{uniqueId}] %-5p %c{2} - %m%n"/>
    </layout>
</appender>

<!-- [MPC Logger] 记录一个流相关的数据(包括一对tenant stream <-> component stream) -->
<appender name="MPC-STREAM-DATA-APPENDER" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="file" value="${log_root}/mpaaschannel/stream-data.log"/>
    <param name="append" value="true"/>
    <param name="encoding" value="${file.encoding}"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d [%X{remoteAddr}][%X{uniqueId}] %-5p %c{2} - %m%n"/>
    </layout>
</appender>

<!-- [MPC Logger] tenant 日志 -->
<logger name="TENANT-LINK-DIGEST" additivity="false">
    <level value="INFO" />
    <appender-ref ref="MPC-TENANT-LINK-APPENDER" />
    <appender-ref ref="ERROR-APPENDER" />
</logger>

<!-- [MPC Logger] component 日志 -->
<logger name="STREAM-DATA-DIGEST" additivity="false">
    <level value="INFO" />
    <appender-ref ref="MPC-STREAM-DATA-APPENDER" />
    <appender-ref ref="ERROR-APPENDER" />
</logger>

配置应用公钥

  1. 进入控制台 接口密钥 配置页面。

    1. 登录控制台,在 产品与服务 中选择 移动开发平台 mPaaS 进入移动开发平台主页。

    2. 切换至正确的工作空间后,点击需要接入 API 服务的 App 名称。

    3. 在左侧导航栏选择 接口密钥,进入接口密钥配置页面。

  2. 点击页面 配置 按钮,输入公钥内容(去掉最后的空格或空行)后提交。使用的 RSA 密钥必须是 2048 位的,并且经过 Base64 编码。

    说明

    使用的 RSA 密钥必须是 2048 位的,并且经过 Base64 编码。

    生成 RSA 密钥的方法:

    1. 安装好 OpenSSL 工具。

    2. 执行以下命令,生成私钥文件 private_key_base64.der,公钥文件 public_key_base64.der

       * ### 1. Generate a 2048-bit RSA private key
       * $ openssl genrsa -out private_key.pem 2048
       *
       * ### 2. Convert private Key to PKCS#8 format (so Java can read it)
       * $ openssl pkcs8 -topk8 -inform PEM -outform DER -in private_key.pem -out private_key.der -nocrypt
       *
       * ### 3. Output public key portion in DER format (so Java can read it)
       * $ openssl rsa -in private_key.pem -pubout -outform DER -out public_key.der
       *
       * ### 4. change to base64:
       * ## 生成的私钥,后端应用中配置
       * $ openssl base64 -in private_key.der -out private_key_base64.der
       * ## 生成的公钥
       * $ openssl base64 -in public_key.der -out public_key_base64.der
       *
       * ### remember to clear the whitespace chars and line breaks before submit!!!

注册 API 分组

  1. 在控制台左侧导航栏选择 移动网关,进入移动网关管理页面。

  2. 选择 API 分组 选项卡进入 API 分组列表页,点击 创建 API 分组 按钮。

  3. 在弹出的对话框中填写表单信息。

    • 分组类型:此处选择 MPC

    • API 分组:必填,提供服务的业务系统的英文名称。API 分组名称要与注册的 API 服务应用名保持一致。

    • Project Name:必填,默认取当前所处环境的 Project Name。

    • 超时时间:选填,发送请求至业务系统时的超时时间,单位毫秒;默认值:3000 ms

  4. 点击 确定 按钮提交。如需进一步完善 API 分组相关配置,请阅读 配置分组

创建 API

  1. 选择 API 管理 选项卡进入 API 列表页,点击 创建 API 按钮。

  2. 在弹出的对话框中,API 类型 选择 MPC,选择 API 分组,在拉取到的 operationType 列表中勾选需要的服务,点击 确认 按钮。

配置 API 服务

  1. 点击 API 列表操作列中的 配置,进入 API 配置页面。

  2. 在 API 配置区域,点击 修改 按钮进行相应参数的编辑;修改完成后,点击 保存 按钮。

    说明
    • 为了快速入门,您可以先将 高级配置 中的 签名校验 关闭。关于签名校验的详细信息,请参考 签名校验说明

    • 关于 API 配置的详细信息,请参考 API 配置

  3. 检查右上方开关,保证 API 服务处于 开通 状态。只有处于开通状态的 API 服务才能被调用。

测试 API 服务

相关信息请参考 API 测试

生成客户端 SDK

相关信息请参考 代码生成

结果

完成上述几步操作,API 服务即可供客户端调用。有关客户端开发的更多信息,参见下列 客户端开发指南

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