全部产品
云市场
云游戏

服务定义与开发

更新时间:2020-09-24 11:41:53

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

网关管控平台

引入网关二方包

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

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

说明:引入依赖前,请确认您完成了 Maven 的配置,参见 配置 Maven

基础依赖

  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-adapter</artifactId>
  4. <version>1.0.5.20180503</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.alipay.gateway</groupId>
  8. <artifactId>mobilegw-unify-log</artifactId>
  9. <version>1.0.5.20180503</version>
  10. </dependency>
  11. <dependency>
  12. <groupId>com.alipay.hybirdpb</groupId>
  13. <artifactId>classparser</artifactId>
  14. <version>1.2.1</version>
  15. </dependency>
  16. <dependency>
  17. <groupId>org.apache.commons</groupId>
  18. <artifactId>commons-lang3</artifactId>
  19. <version>3.5</version>
  20. </dependency>
  21. <dependency>
  22. <groupId>com.alibaba</groupId>
  23. <artifactId>fastjson</artifactId>
  24. <version>1.2.48</version>
  25. </dependency>

MPC 依赖

  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-mpc</artifactId>
  4. <version>1.0.5.20180503</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.alipay.mpaaschannel</groupId>
  8. <artifactId>common</artifactId>
  9. <version>2.3.20180501001</version>
  10. </dependency>
  11. <dependency>
  12. <groupId>com.alipay.mpaaschannel</groupId>
  13. <artifactId>tenant-client</artifactId>
  14. <version>2.3.20180501001</version>
  15. </dependency>

Dubbo 依赖

  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-dubbo</artifactId>
  4. <version>1.0.5.20180503</version>
  5. </dependency>
说明:dubbo 请使用原生版本,不要使用 dubbox(不兼容)。

HRPC 依赖

  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-hrpc</artifactId>
  4. <version>1.0.5.20180810</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.alipay.gateway</groupId>
  8. <artifactId>mobilegw-unify-registry</artifactId>
  9. <version>1.0.5.20180810</version>
  10. </dependency>
  11. <dependency>
  12. <groupId>hessian</groupId>
  13. <artifactId>hessian</artifactId>
  14. <version>3.1.3</version>
  15. </dependency>

TR 依赖

  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-sofa</artifactId>
  4. <version>1.0.5.20180810</version>
  5. </dependency>

定义服务接口并实现

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

说明
  • 方法定义中的入参尽量定义为 VO,后期添加参数,就可以在 VO 中添加参数,而不改变方法的声明格式。
  • 服务接口定义的相关规范,请参见 业务接口定义规范

定义 operationType

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

  • value:RPC 服务的唯一标识,定义规则为 组织.产品域.产品.子产品.操作
  • name:接口中文名称。
  • desc:接口描述。
说明
  • value 在网关为全局唯一,尽量定义详细,否则可能会和其他业务方的 value 值一样,导致无法注册服务。
  • 为便于维护,请务必填写完整 @OperationType 的三个字段。

样例:

  1. public interface MockRpc {
  2. @OperationType("com.alipay.mock")
  3. Resp mock(Req s);
  4. @OperationType("com.alipay.mock2")
  5. String mock2(String s);
  6. }
  7. public static class Resp {
  8. private String msg;
  9. private int code;
  10. // ignore getter & setter
  11. }
  12. public static class Req {
  13. private String name;
  14. private int age;
  15. // ignore getter & setter
  16. }

注册 API 服务

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

注册 MPC API 服务

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

  • registryUrl: 该值为注册中心的地址,共享式金融科技注册中心地址为 116.62.81.246
  • 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} 中配置:

  1. * the way to generate key pair :
  2. * ### Generate a 2048-bit RSA private key
  3. *
  4. * $ openssl genrsa -out private_key.pem 2048
  5. *
  6. * ### Convert private Key to PKCS#8 format (so Java can read it)
  7. *
  8. * $ openssl pkcs8 -topk8 -inform PEM -outform DER -in private_key.pem -out private_key.der -nocrypt
  9. *
  10. * ### Output public key portion in DER format (so Java can read it)
  11. *
  12. * $ openssl rsa -in private_key.pem -pubout -outform DER -out public_key.der
  13. *
  14. * ### change to base64:
  15. *
  16. * ## 生成的私钥,后端应用中配置
  17. * $ openssl base64 -in private_key.der -out private_key_base64.der
  18. *
  19. * ## 生成的公钥,在控制台 接口密钥 中配置
  20. * $ openssl base64 -in public_key.der -out public_key_base64.der
  21. *
  22. * ### remember to clear the whitespace chars and line breaks before submit!!!

spring 方式

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

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

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

    1. <bean id="mpcServiceStarter" class="com.alipay.gateway.spi.mpc.MpcServiceStarter">
    2. <property name="registryUrl" value="${registy_url}"/>
    3. <property name="appName" value="${app_name}"/>
    4. <property name="workspaceId" value="${workspace_id}"/>
    5. <property name="projectName" value="${project_name}"/>
    6. <property name="privateKeyPath" value="${privatekey_path}"/>
    7. </bean>

spring-boot 方式

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

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

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

    1. @Configuration
    2. public class MpaaschannelDemo {
    3. @Bean(name="mpcServiceStarter")
    4. public MpcServiceStarter mpcServiceStarter(){
    5. MpcServiceStarter mpcServiceStarter = new MpcServiceStarter();
    6. mpcServiceStarter.setWorkspaceId("${workspace_id}");
    7. mpcServiceStarter.setAppName("${app_name}");
    8. mpcServiceStarter.setRegistryUrl("${registy_url}");
    9. mpcServiceStarter.setProjectName("${project_name}");
    10. mpcServiceStarter.setPrivateKeyPath("${privatekey_path}");
    11. return mpcServiceStarter;
    12. }
    13. }

配置 MPC 日志

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

  1. <!-- [MPC Logger] tenant link,记录建联,settings 信息 -->
  2. <appender name="MPC-TENANT-LINK-APPENDER" class="org.apache.log4j.DailyRollingFileAppender">
  3. <param name="file" value="${log_root}/mpaaschannel/tenant-link.log"/>
  4. <param name="append" value="true"/>
  5. <param name="encoding" value="${file.encoding}"/>
  6. <layout class="org.apache.log4j.PatternLayout">
  7. <param name="ConversionPattern" value="%d [%X{remoteAddr}][%X{uniqueId}] %-5p %c{2} - %m%n"/>
  8. </layout>
  9. </appender>
  10. <!-- [MPC Logger] 记录一个流相关的数据 (包括一对tenant stream <-> component stream) -->
  11. <appender name="MPC-STREAM-DATA-APPENDER" class="org.apache.log4j.DailyRollingFileAppender">
  12. <param name="file" value="${log_root}/mpaaschannel/stream-data.log"/>
  13. <param name="append" value="true"/>
  14. <param name="encoding" value="${file.encoding}"/>
  15. <layout class="org.apache.log4j.PatternLayout">
  16. <param name="ConversionPattern" value="%d [%X{remoteAddr}][%X{uniqueId}] %-5p %c{2} - %m%n"/>
  17. </layout>
  18. </appender>
  19. <!-- [MPC Logger] tenant 日志 -->
  20. <logger name="TENANT-LINK-DIGEST" additivity="false">
  21. <level value="INFO" />
  22. <appender-ref ref="MPC-TENANT-LINK-APPENDER" />
  23. <appender-ref ref="ERROR-APPENDER" />
  24. </logger>
  25. <!-- [MPC Logger] component 日志 -->
  26. <logger name="STREAM-DATA-DIGEST" additivity="false">
  27. <level value="INFO" />
  28. <appender-ref ref="MPC-STREAM-DATA-APPENDER" />
  29. <appender-ref ref="ERROR-APPENDER" />
  30. </logger>

注册 Dubbo API 服务

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

  • registryUrl:该值为注册中心的地址。
  • appName:该值为业务方的应用名,与 API 分组名相同。

spring 方式

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

    1. <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>
  2. 在对应 bundle 的 spring 配置文件中,声明暴露服务的 starter bean —DubboServiceStarter,该接口会将所有带有 OperationType 的 bean 通过 Dubbo 协议注册到指定的注册中心。

    1. <bean id="dubboServiceStarter" class="com.alipay.gateway.spi.dubbo.DubboServiceStarter">
    2. <property name="registryUrl" value="${registy_url}"/>
    3. <property name="appName" value="${app_name}"/>
    4. </bean>

spring-boot 方式

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

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

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

    1. @Configuration
    2. public class DubboDemo {
    3. @Bean(name="dubboServiceStarter")
    4. public DubboServiceStarter dubboServiceStarter(){
    5. DubboServiceStarter dubboServiceStarter = new DubboServiceStarter();
    6. dubboServiceStarter.setAppName("${app_name}");
    7. dubboServiceStarter.setRegistryUrl("${registy_url}");
    8. return dubboServiceStarter;
    9. }
    10. }

注册 HRPC API 服务

注册 HRPC API 服务需要如下几个参数:

  • registryUrl:该值为注册中心的地址,必填。
  • appName:该值为业务方的应用名,必填。
  • serverPort:该值为 HRPC 服务监听端口,选填,默认 7079。

spring 方式

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

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

    HRpcServiceStarter:该接口会将所有带有 @OperationType 的 bean 通过 HRPC 协议注册到指定的注册中心。

    1. <bean id="hrpcServiceStarter" class="com.alipay.gateway.spi.hrpc.HRpcServiceStarter">
    2. <property name="registryUrl" value="${registy_url}"/>
    3. <property name="appName" value="${app_name}"/>
    4. <property name="serverPort" value="${serverPort可选}"/>
    5. </bean>

spring-boot 方式

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

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

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

    1. @Configuration
    2. public class HRpcDemo {
    3. @Bean(name="hrpcServiceStarter")
    4. public HRpcServiceStarter hrpcServiceStarter(){
    5. HRpcServiceStarter hRpcServiceStarter = new HRpcServiceStarter();
    6. hRpcServiceStarter.setAppName("${app_name}");
    7. hRpcServiceStarter.setRegistryUrl("${registy_url}");
    8. hRpcServiceStarter.setServerPort("${serverPort可选}");
    9. return hRpcServiceStarter;
    10. }
    11. }
    说明:HRPC 使用的注册中心为 ZK,地址可以填一个或者多个,用逗号分割。如 “11.163.193.240:2181” 或 “11.163.193.240:2181,11.163.193.230:2181”。

注册 TR API 服务

注册 TR API 服务需要如下 1 个参数:

  • appName:该值为业务方的应用名,必填。

spring 方式

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

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

    SofaServiceStarter:该接口会将所有带有 @OperationType 的 bean 通过 TR 协议暴露给网关调用。

    1. <bean id="SofaServiceStarter" class="com.alipay.gateway.spi.sofa.SofaServiceStarter">
    2. <property name="appName" value="${app_name}"/>
    3. </bean>

spring-boot 方式

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

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

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

    1. @Configuration
    2. public class TRDemo {
    3. @Bean(name="sofaServiceStarter")
    4. public SofaServiceStarter sofaServiceStarter(){
    5. SofaServiceStarter sofaServiceStarter = new SofaServiceStarter();
    6. sofaServiceStarter.setAppName("${app_name}");
    7. return sofaServiceStarter;
    8. }
    9. }

结果

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