All Products
Search
Document Center

Service definition and development

Last Updated: Aug 17, 2021

This document is specific for the business systems integrating gateway SPI, such as the business systems which provide mpaaschannel or dubbo API services externally. For the business systems integrating HTTP API, it is unnecessary to refer to this document.

1

Introduce the second-party package of gateway

Introduce the following second-party package (ignore if the original project has dependency already) in the pom.xml file of the project.

All basic dependencies must be introduced. You can select MPC, Dubbo, HRPC, or TR dependency according to the API type that is to be integrated.

Before introducing the dependencies, make sure that you have completed Maven configuration.

Basic dependencies

 
  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-adapter</artifactId>
  4. <version>1.0.5.20201010</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.alipay.gateway</groupId>
  8. <artifactId>mobilegw-unify-log</artifactId>
  9. <version>1.0.5.20201010</version>
  10. </dependency>
  11. <dependency>
  12. <groupId>com.alipay.hybirdpb</groupId>
  13. <artifactId>classparser</artifactId>
  14. <version>1.2.2</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.72_noneautotype</version>
  25. </dependency>

MPC dependencies

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

Dubbo dependencies

 
  1. <dependency>
  2. <groupId>com.alipay.gateway</groupId>
  3. <artifactId>mobilegw-unify-spi-dubbo</artifactId>
  4. <version>1.0.5.20201010</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>org.apache.dubbo</groupId>
  8. <artifactId>dubbo</artifactId>
  9. <version>2.7.8</version>
  10. </dependency>
Note: For Dubbo, use the native version. Don’t use dubbox, because it is incompatible.

HRPC dependencies

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

TR dependencies

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

Define and implement service interface

Define the service interface com.alipay.xxxx.MockRpc based on business requirement, and provide the implementation com.alipay.xxxx.MockRpcImpl for this interface.

Note:
  • Try to define the incoming parameter in the method as VO. In this way, if you want to add any parameter later, you can add the parameters in the VO without changing the method declaration format.
  • For relevant specifications about service interface definition, see Business interface definition specifications.

Define operationType

Add @OperationType annotation on the service interface’s method to define the interface that is to publish services.

@OperationType contains three parameters:

  • value: The unique identifier of RPC service; definition rule is organization.product domain.product.sub-product.operation.
  • name: Interface name.
  • desc: Interface description.
Note:
  • value must be globally unique in the gateway, you would better to define it as detailed as possible. otherwise, it might be the same as the value of other business party, which might lead service registration failure.
  • For convenient maintenance, ensure that the three fields of @OperationType are completely entered.

Sample:

 
  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. }

Register API service

Register the pre-defined API service to registration center through the SPI package provided by the gateway.

Register MPC API service

The following parameters are required for registering MPC API service:

  • registryUrl: It refers to the address of the registration center. For the shared Ant Financial Cloud registration center, the address is mpcpub.mpaas.cn-hangzhou.aliyuncs.com.
  • appName: It refers to the business-side application name.
  • workspaceId: It refers to the workspaceId of the workspace where the application is.
  • projectName: It refers to the projectName of the tenant where the application is.
  • privateKeyPath: The ClassPath used to store RSA key, which is used to verify the legality when the gateway establishes connection with mpaaschannel.
    Recommended: Put the RSA key in /META-INF/config/rsa-mpc-pri-key-{env}.der where {env} indicates the workspace, such as dev, sit, and prod.

Configure public key

Go to the mPaaS console, click API Keys on the navigation pane, and then click Configure on the left to configure the corresponding RSA public key of the private key.

API key

Follow the instructions below to configure the RSA public/private keys. The public key must be configured on mAppCenter while the private key file in ${privateKeyPath} of the backend application:

 
  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. * ## Go to the backend application to configure the generated private key
  17. * $ openssl base64 -in private_key.der -out private_key_base64.der
  18. *
  19. * ## Go to Interface key in mappcenter to configure the generated public key
  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!!!

Register through Spring

  1. In the Spring configuration file of the corresponding bundle, declare the pre-defined service’s Spring bean:

    <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>

  2. Declare the Starter bean that is to expose the service in the Spring configuration file of the corresponding bundle.

    The interface MpcServiceStarter registers all beans with @OperationType to the specified registration center through mpaaschannel protocol.

       
    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>

Register through Spring Boot

Spring Boot is essentially the same as Spring, and the only difference is that the registration method is changed to annotation, without configuring xml file.

  1. Register the defined service as bean through annotation: @Service public class MockRpcImpl implements MockRpc{ }

  2. Define the starter that is to expose service through annotation:

       
    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. }

    Configure MPC log

    For better troubleshooting, you can configure the logs related to MPC on demand. For example, to configure log4j:

 
  1. <!-- [MPC Logger] tenant link, recording the association, 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] records stream-related data (including a pair of 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 log -->
  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 log -->
  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>

Register Dubbo API service

The following parameters are required for registering Dubbo API service:

  • registryUrl: It refers to the address of the registration center.
  • appName: It refers to the business-side application name.

Register through Spring

  1. In the Spring configuration file of the corresponding bundle, declare the pre-defined service’s Spring bean:

    <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>

  2. In the Spring configuration file of the corresponding bundle, declare the starter bean (DubboServiceStarter) that is to expose service. This interface will register all beans containing @OperationType to the specified registration center through Dubbo protocol.

       
    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>

Register through Spring Boot

Spring Boot is essentially the same as Spring, and the only difference is that the registration method is changed to annotation, without configuring xml file.

  1. Register the defined service as bean through annotation:@Service public class MockRpcImpl implements MockRpc{ }

  2. Define the starter that is to expose service through annotation:

       
    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. }

Register HRPC API service

The following parameters are required for registering HRPC API service:

  • registryUrl: It refers to the address of the registration center, required.
  • appName: It refers to the business-side application name, required.
  • serverPort: It refers to the listening port of HRPC service, it defaults to 7079, optional.

Register through Spring

  1. In the Spring configuration file of the corresponding bundle, declare the pre-defined service’s Spring bean:

    <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>

  2. In the Spring configuration file of the corresponding bundle, declare the starter bean (HRpcServiceStarter) that is to expose service. This interface will register all beans containing @OperationType to the specified registration center through HRPC protocol.

       
    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 (optional)}"/>
    5. </bean>

Register through Spring Boot

Spring Boot is essentially the same as Spring, and the only difference is that the registration method is changed to annotation, without configuring xml file.

  1. Register the defined service as bean through annotation:

       
    1. @Service
    2. public class MockRpcImpl implements MockRpc{
    3. }
  2. Define the starter that is to expose service through annotation:

       
    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 (optional)}");
    9. return hRpcServiceStarter;
    10. }
    11. }
    Note: The registry center used by HRPC is ZK, and there can be one or multiple registry URLs (separated with commas), for example: “11.163.193.240:2181” or “11.163.193.240:2181,11.163.193.230:2181”.

Register TR API service

The parameter appName is required for registering TR API service. It refers to the business-side application name.

Register through Spring

  1. In the Spring configuration file of the corresponding bundle, declare the pre-defined service’s Spring bean:

    <bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>

  2. In the Spring configuration file of the corresponding bundle, declare the starter bean (SofaServiceStarter) that is to expose service. This interface will register all beans containing @OperationType to the specified registration center through TR protocol.

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

Register through Spring Boot

Spring Boot is essentially the same as Spring, and the only difference is that the registration method is changed to annotation, without configuring xml file.

  1. Register the defined service as bean through annotation:

       
    1. @Service
    2. public class MockRpcImpl implements MockRpc{
    3. }
  2. Define the starter that is to expose service through annotation:

       
    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. }

Result

When you complete the above steps, you can operate the defined API services in gateway, and expose them to the client. For more information, see Register API.