This document is only applicable to systems that are integrated with gateway SPI, such as business systems that expose mpaaschannel or Dubbo API services. For business systems that use HTTP APIs, you do not need to view this document.
Introducing the Gateway Second-Party Package
Introduce the following two-party package into the main pom.xml
file of the project (if the original project already has dependencies, please ignore it).
You must reference all the basic dependencies. You can use the type of the API that you want to integrate.
Basic Dependency
<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
<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>
Define and implement the service API
According to business requirements, define the service API: com.alipay.xxxx.MockRpc
, and provide the implementation com.alipay.xxxx.MockRpcImpl
of the API.
The input parameters in the method definition are defined as VO as much as possible. If you add parameters later, you can add parameters in VO without changing the declaration format of the method.
For more information about service API definition specifications, see Service API definition specifications.
Define operationType
Add a @OperationType
annotation to the method of the service API to define the API name of the published service. @OperationType
have three parameter members:
value
: The unique identifier of the RPC service. The definition rule isthe organization. Product domain. Products. Sub-products. Operation
.name
: the Chinese name of the API.desc
: the description of the API.
value
the gateway is globally unique, try to define it in detail, otherwise it may be the same as the value of other business parties, resulting in failure to register the service.For ease of maintenance, be sure to fill in the three fields of the full
@OperationType
.
Example:
public API 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
}
Then, the defined API service is registered to the specified registry by using the SPI package provided by the gateway.
Register the MPC API service
The following parameters are required to register the MPC API service:
registryUrl
: The value is the address of the registry. The address of the shared Fintech registry is thempcpub.mpaas.cn-hangzhou.aliyuncs.com
.appName
: The value is the application name of the business party and is the same as the API group name.workspaceId
: The workspace ID of the application environment.projectName
: The projectName of the tenant to which the application belongs, which is the same as the project name in the API group.privateKeyPath
: The ClassPath that stores the RSA private key, which is used to verify validity when a connection is established with the mpaaschannel. We recommend that you place it in a/META-INF/config/rsa-mpc-pri-key-{env}.der
,{env}
different environments, such as dev, sit, and prod.
Configure a public key
Log on to the Apsara Uni-manager Management Console. In the left-side navigation pane, choose Code Management > Interface Keys > Configuration. On the page that appears, configure the RSA public key.
The method for generating an RSA public-private key is as follows, where the public key is configured on the console and the private key file is configured in the ${privateKeyPath}
of the backend application:
* 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:
*
* ## The generated private key, which is configured in the backend application
* $ openssl base64 -in private_key.der -out private_key_base64.der
*
* ## The generated public key, which is configured in the console port key
* $ openssl base64 -in public_key.der -out public_key_base64.der
*
* ### remember to clear the whitespace chars and line breaks before submit!!!
Spring mode
In the spring configuration file of the corresponding bundle, declare the spring bean of the defined service.
<bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>
In the spring configuration file for the corresponding bundle, declare the starter bean that exposes the service.
The API
MpcServiceStarter
registers all beans withOperationType
to the specified registry through the mpaaschannel protocol.<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 mode
Spring-boot is essentially the same as spring, except that the registration method is changed to annotation instead of configuring xml files.
Register the defined service as a bean by way of annotations:
@Service public class MockRpcImpl implements MockRpc{ }
Define the starter of the exposed service as an annotation:
@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; } }
Configure MPC logs
To facilitate troubleshooting, you can configure MPC-related logs as appropriate. The following example uses log4j
configuration:
!" -- [MPC Logger] tenant link: records the link information and settings information. -->
<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] Records data related to a stream (including a pair of tenant streams <-> component streams) -->
<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 logs -->
<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 log -->
<logger name="STREAM-DATA-DIGEST" additivity="false">
<level value="INFO" />
<appender-ref ref="MPC-STREAM-DATA-APPENDER" />
<appender-ref ref="ERROR-APPENDER" />
</logger>
The returned results.
After completing the preceding steps, you can perform a series of operations on the gateway to expose the defined API service to the client. For more information, see Register an API operation.