服务定义与开发

此文档仅针对集成了网关 SPI 的系统,如对外暴露 mpaaschannel 或 Dubbo 类型 API 服务的业务系统。对于使用 HTTP API 的业务系统无需查看此文档。

41

引入网关二方包

在项目的主 pom.xml 文件中引入如下二方包(若原工程已经有依赖,请忽略)。

基础依赖都需要引用,请根据实际需要集成的 API 类型。

说明

引入依赖前,请确认您完成了 Maven 的配置。详情参见 配置 Maven

基础依赖

<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-spi-adapter</artifactId>
    <version>1.0.5.20201010</version>
</dependency>
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-log</artifactId>
    <version>1.0.5.20201010</version>
</dependency>
<dependency>
    <groupId>com.alipay.hybirdpb</groupId>
    <artifactId>classparser</artifactId>
    <version>1.2.2</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.gateway</groupId>
    <artifactId>mobilegw-unify-common</artifactId>
    <version>1.0.5.20201010</version>
</dependency>

MPC 依赖

<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-spi-mpc</artifactId>
    <version>1.0.5.20201010</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>

定义服务接口并实现

按照业务需求,定义服务接口:com.alipay.xxxx.MockRpc; 并提供该接口的实现 com.alipay.xxxx.MockRpcImpl

说明

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

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

定义 operationType

在服务接口的方法上添加 @OperationType 注解,定义发布服务的接口名称。@OperationType 有三个参数成员:

  • value:RPC 服务的唯一标识,定义规则为 组织.产品域.产品.子产品.操作

  • name:接口中文名称。

  • desc:接口描述。

说明

  • value 在网关为全局唯一,尽量定义详细,否则可能会和其他业务方的 value 值一样,导致无法注册服务。

  • 为便于维护,请务必填写完整 @OperationType 的三个字段。

样例:

public interface MockRpc {

    @OperationType("com.alipay.mock")
    Resp mock(Req s);

    @OperationType("com.alipay.mock2")
    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
}

然后,通过网关提供的 SPI 包,将定义好的 API 服务注册到指定的注册中心。

注册 MPC API 服务

注册 MPC API 服务需要如下参数:

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

  • appName:该值为业务方的应用名,与 API 分组名相同。

  • workspaceId:应用所处环境的 workspaceId。

  • projectName:应用所属租户的 projectName,与 API 分组里的 Project Name 相同。

  • privateKeyPath:存放 RSA 私钥的 ClassPath,与 mpaaschannel 建立连接时用于校验合法性。 建议放置在 /META-INF/config/rsa-mpc-pri-key-{env}.der 中,{env} 为不同的环境,如 dev、sit、prod 等。

配置公钥

前往对应环境的控制台,从左侧导航栏点击 代码管理 > 接口密钥 > 配置,配置私钥对应的 RSA 公钥。

1

生成 RSA 公私钥的方法如下,其中公钥在控制台上配置,私钥文件在后端应用的 ${privateKeyPath} 中配置:

* the way to generate key pair: 
* ### Generate a 2048-bit RSA private key 
* 
* $ openssl genrsa -out private_key.pem 2048 
* 
* ### 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 
* 
* ### 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 
* 
* ### 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!!!

spring 方式

  1. 在对应 bundle 的 spring 配置文件中,声明定义好的服务的 spring bean。

     <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>
  2. 在对应 bundle 的 spring 配置文件中,声明暴露服务的 starter bean。

    接口 MpcServiceStarter 会将所有带有 OperationType 的 bean 通过 mpaaschannel 协议注册到指定的注册中心。

    <bean id="mpcServiceStarter" class="com.alipay.gateway.spi.mpc.MpcServiceStarter">
     <property name="registryUrl" value="${registy_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 方式

spring-boot 和 spring 本质上一样,只是注册的方式改为注解的方式,不用配置 xml 文件。

  1. 通过注解的方式,将定义的服务注册成 bean:

    @Service
    public class MockRpcImpl implements MockRpc{
    }
  2. 以注解的方式,定义暴露服务的 starter:

    @Configuration
    public class MpaaschannelDemo {
     @Bean(name="mpcServiceStarter")
     public MpcServiceStarter mpcServiceStarter(){
         MpcServiceStarter mpcServiceStarter = new MpcServiceStarter();
         mpcServiceStarter.setWorkspaceId("${workspace_id}");
         mpcServiceStarter.setAppName("${app_name}");
         mpcServiceStarter.setRegistryUrl("${registy_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>

结果

完成上述步骤后,就可以通过在网关进行一系列的操作,将定义的 API 服务对客户端进行暴露。具体请参见 注册 API

阿里云首页 移动开发平台 mPaaS 相关技术圈