All Products
Search
Document Center

Develop RESTful applications (not recommended)

Last Updated: Dec 13, 2018

Implement service discovery

This section describes how to enable the service discovery function of EDAS for your RESTful applications.

Download the Demo source code sc-vip-server and sc-vip-client.

Create a service provider

The service provider in this example provides a simple echo service and registers itself with the service discovery center.

  1. Create a Spring Cloud project named sc-vip-server.

  2. Introduce necessary dependencies in pom.xml:

    1. <parent>
    2. <groupId>org.springframework.boot</groupId>
    3. <artifactId>spring-boot-starter-parent</artifactId>
    4. <version>1.5.8.RELEASE</version>
    5. <relativePath/>
    6. </parent>
    7. <dependencies>
    8. <dependency>
    9. <groupId>org.springframework.cloud</groupId>
    10. <artifactId>spring-cloud-starter-vipclient</artifactId>
    11. <version>1.3</version>
    12. </dependency>
    13. <dependency>
    14. <groupId>org.springframework.cloud</groupId>
    15. <artifactId>spring-cloud-starter-pandora</artifactId>
    16. <version>1.3</version>
    17. </dependency>
    18. </dependencies>
    19. <dependencyManagement>
    20. <dependencies>
    21. <dependency>
    22. <groupId>org.springframework.cloud</groupId>
    23. <artifactId>spring-cloud-dependencies</artifactId>
    24. <version>Dalston.SR4</version>
    25. <type>pom</type>
    26. <scope>import</scope>
    27. </dependency>
    28. </dependencies>
    29. </dependencyManagement>

    If you do not want to configure the parent of the project as spring-boot-starter-parent, you can add dependencyManagement and set scope=import as follows to manage dependencies.

    1. <dependencyManagement>
    2. <dependencies>
    3. <dependency>
    4. <groupId>org.springframework.boot</groupId>
    5. <artifactId>spring-boot-dependencies</artifactId>
    6. <version>1.5.8.RELEASE</version>
    7. <type>pom</type>
    8. <scope>import</scope>
    9. </dependency>
    10. </dependencies>
    11. </dependencyManagement>
  3. Add the code of the service provider, in which the annotation of @EnableDiscoveryClient indicates that the service registration and discovery features must be enabled for the service.

    1. @SpringBootApplication
    2. @EnableDiscoveryClient
    3. public class ServerApplication {
    4. public static void main(String[] args) {
    5. PandoraBootstrap.run(args);
    6. SpringApplication.run(ServerApplication.class, args);
    7. PandoraBootstrap.markStartupAndWait();
    8. }
    9. }
  4. Create an EchoController to provide simple echo service.

    1. @RestController
    2. public class EchoController {
    3. @RequestMapping(value = "/echo/{string}", method = RequestMethod.GET)
    4. public String echo(@PathVariable String string) {
    5. return string;
    6. }
    7. }
  5. Configure the service name and the listener port number in the application.properties file in resources.

    1. spring.application.name=service-provider
    2. server.port=18081

Create a service consumer

A service consumer is created in this example. The service consumer calls the service provider through RestTemplate, AsyncRestTemplate, and FeignClient.

  1. Create a Spring Cloud project named sc-vip-client.

  2. Introduce necessary dependencies in pom.xml:

    1. <parent>
    2. <groupId>org.springframework.boot</groupId>
    3. <artifactId>spring-boot-starter-parent</artifactId>
    4. <version>1.5.8.RELEASE</version>
    5. <relativePath/>
    6. </parent>
    7. <dependencies>
    8. <dependency>
    9. <groupId>org.springframework.cloud</groupId>
    10. <artifactId>spring-cloud-starter-vipclient</artifactId>
    11. <version>1.3</version>
    12. </dependency>
    13. <dependency>
    14. <groupId>org.springframework.cloud</groupId>
    15. <artifactId>spring-cloud-starter-pandora</artifactId>
    16. <version>1.3</version>
    17. </dependency>
    18. <dependency>
    19. <groupId>org.springframework.cloud</groupId>
    20. <artifactId>spring-cloud-starter-feign</artifactId>
    21. </dependency>
    22. </dependencies>
    23. <dependencyManagement>
    24. <dependencies>
    25. <dependency>
    26. <groupId>org.springframework.cloud</groupId>
    27. <artifactId>spring-cloud-dependencies</artifactId>
    28. <version>Dalston.SR4</version>
    29. <type>pom</type>
    30. <scope>import</scope>
    31. </dependency>
    32. </dependencies>
    33. </dependencyManagement>

    To demonstrate the use of FeignClient, an additional dependency of spring-cloud-starter-feign is added to the pom.xml file compared to that of the service provider.

  3. Different from the server, the clients support other functions in addition to service enabling and registration. In addition to service enabling and registration, two more configurations must be added to use the three clients of RestTemplate, AsyncRestTemplate, and FeignClient:

    • Add the annotation of @LoadBalanced to combine RestTemplate, AsyncRestTemplate, and service discovery.
    • Activate FeignClients by using the annotation of @EnableFeignClients.

      1. @SpringBootApplication
      2. @EnableDiscoveryClient
      3. @EnableFeignClients
      4. public class ConsumerApplication {
      5. @LoadBalanced
      6. @Bean
      7. public RestTemplate restTemplate() {
      8. return new RestTemplate();
      9. }
      10. @LoadBalanced
      11. @Bean
      12. public AsyncRestTemplate asyncRestTemplate(){
      13. return new AsyncRestTemplate();
      14. }
      15. public static void main(String[] args) {
      16. PandoraBootstrap.run(args);
      17. SpringApplication.run(ConsumerApplication.class, args);
      18. PandoraBootstrap.markStartupAndWait();
      19. }
      20. }
  4. Complete the configuration of FeignClient of EchoService before using it. Configure the service name and the HTTP request corresponding to the method. The service name is service-provider configured in the sc-vip-server project. The code is as follows:

    1. @FeignClient(name = "service-provider")
    2. public interface EchoService {
    3. @RequestMapping(value = "/echo/{str}", method = RequestMethod.GET)
    4. String echo(@PathVariable("str") String str);
    5. }
  5. Create a Controller for call test.

    /echo-rest/ verifies the call of the service provider through RestTemplate.

    /echo-async-rest/ verifies the call of the service provider through AsyncRestTemplate.

    /echo-feign/ verifies the call of the service provider through FeignClient.

    1. @RestController
    2. public class Controller {
    3. @Autowired
    4. private RestTemplate restTemplate;
    5. @Autowired
    6. private AsyncRestTemplate asyncRestTemplate;
    7. @Autowired
    8. private EchoService echoService;
    9. @RequestMapping(value = "/echo-rest/{str}", method = RequestMethod.GET)
    10. public String rest(@PathVariable String str) {
    11. return restTemplate.getForObject("http://service-provider/echo/" + str, String.class);
    12. }
    13. @RequestMapping(value = "/echo-async-rest/{str}", method = RequestMethod.GET)
    14. public String asyncRest(@PathVariable String str) throws Exception{
    15. ListenableFuture<ResponseEntity<String>> future = asyncRestTemplate.
    16. getForEntity("http://service-provider/echo/"+str, String.class);
    17. return future.get().getBody();
    18. }
    19. @RequestMapping(value = "/echo-feign/{str}", method = RequestMethod.GET)
    20. public String feign(@PathVariable String str) {
    21. return echoService.echo(str);
    22. }
    23. }
  6. Configure the application name and the listener port number.

    1. spring.application.name=service-consumer
    2. server.port=18082

Test the RESTful services

Start the Lightweight Configuration Center

The Lightweight Configuration Center must be started for local development and commissioning, which includes a lightweight version of the server of EDAS service registration and discovery. See Lightweight Configuration Center for details.

Start the services

The services can be locally started in two ways.

  • Start in IDE

    To start the service in IDE, configure the startup parameter -Dvipserver.server.port=8080 in VM options and start the service directly using the main method.

    If your Lightweight Configuration Center and the service are deployed on different computers, hosts binding is required. See Lightweight Configuration Center for details.

  • Start by using FatJar

    1. Add FatJar packaging plugins.

      To package pandora-boot project into FatJar by using Maven, the following plugins should be added in pom.xml.To avoid conflicts with other packaging plugins, do not add other FatJar plugins in build plugin.

      1. <build>
      2. <plugin>
      3. <groupId>com.taobao.pandora</groupId>
      4. <artifactId>pandora-boot-maven-plugin</artifactId>
      5. <version>2.1.9.1</version>
      6. <executions>
      7. <execution>
      8. <phase>package</phase>
      9. <goals>
      10. <goal>repackage</goal>
      11. </goals>
      12. </execution>
      13. </executions>
      14. </plugin>
      15. </build>
    2. After adding the plugins, run the maven command mvn clean package under the home directory of the project to create a package. The created FatJar file is located under the target directory.

    3. Start the service using Java command.

      1. java -Dvipserver.server.port=8080 -Dpandora.location=/Users/{$username}/.m2/repository/com/taobao/pandora/taobao-hsf.sar/dev-SNAPSHOT/taobao-hsf.sar-dev-SNAPSHOT.jar -jar sc-vip-server-0.0.1-SNAPSHOT.jar

      NOTE: The path specified by -Dpandora.location must be a full path placed before sc-vip-server-0.0.1-SNAPSHOT.jar.

Demonstration

Start the service and call the service provider through the clients. Each call is successful.

Calling result

FAQ

  1. Failed to enable service discovery for AsyncRestTemplate.

    AsyncRestTemplate is not enabled with service discovery until recently and versions after Dalston are required. See the pull request for details.

  2. FatJar packaging plugin conflict

    To avoid conflicts with other packaging plugins, do not add other FatJar plugins in build plugin.

  3. Can taobao-hsf.sar be included during packaging?

    Yes, but this is not recommended.

    Modify the pandora-boot-maven-plugin plugin and set excludeSar as false to automatically include taobao-hsf.sar during packaging.

    1. <plugin>
    2. <groupId>com.taobao.pandora</groupId>
    3. <artifactId>pandora-boot-maven-plugin</artifactId>
    4. <version>2.1.9.1</version>
    5. <configuration>
    6. <excludeSar>false</excludeSar>
    7. </configuration>
    8. <executions>
    9. <execution>
    10. <phase>package</phase>
    11. <goals>
    12. <goal>repackage</goal>
    13. </goals>
    14. </execution>
    15. </executions>
    16. </plugin>

    In this way, the package can be started without a configured Pandora address.

    1. java -jar -Dvipserver.server.port=8080 sc-vip-server-0.0.1-SNAPSHOT.jar

    Restore the configuration to excluding the SAR package before deploying an application in EDAS.

Implement distributed tracing

To reduce development cost and increase development efficiency, EDAS provides EagleEye, a component for service call tracing.Once EagleEye tracking is configured in the code, you can directly use the tracing function of EDAS without considering other processes including log collection, analysis, or storage.

This document introduces how to enable the distributed tracing function for your services.

Download the Demo source code service1 and service2.

How to use EagleEye

Configure the EDAS private server address in Maven

Currently, packages of Pandora Boot Starter are only published on the private servers of EDAS. You need to add the private server address in the Maven configuration file. See Configure the EDAS private server address in Maven in Prepare development tools for details.

NOTE: Maven 3.x or later is required. Add the EDAS private server address in the Maven configuration file settings.xml. Click to download the sample file.

Modify the code

You can connect Spring Cloud to EDAS EagleEye according to the following three steps.

  1. Add the following public configurations to pom.xml.

    1. <dependency>
    2. <groupId>org.springframework.cloud</groupId>
    3. <artifactId>spring-cloud-starter-eagleeye</artifactId>
    4. <version>1.3</version>
    5. </dependency>
    6. <dependency>
    7. <groupId>org.springframework.cloud</groupId>
    8. <artifactId>spring-cloud-starter-pandora</artifactId>
    9. <version>1.3</version>
    10. </dependency>
  2. Add two lines in the main function. The original content of the main function is as follows:

    1. public static void main(String[] args) {
    2. SpringApplication.run(ServerApplication.class, args);
    3. }

    The modified content of the main function is as follows:

    1. public static void main(String[] args) {
    2. PandoraBootstrap.run(args);
    3. SpringApplication.run(ServerApplication.class, args);
    4. PandoraBootstrap.markStartupAndWait();
    5. }
  3. Add FatJar packaging plugins.

    To package the pandora-boot project into FatJar by using Maven, you need to add the following plugins in pom.xml.

    To avoid conflicts with other packaging plugins, do not add other FatJar plugins in build plugin.

    1. <build>
    2. <plugins>
    3. <plugin>
    4. <groupId>com.taobao.pandora</groupId>
    5. <artifactId>pandora-boot-maven-plugin</artifactId>
    6. <version>2.1.9.1</version>
    7. <executions>
    8. <execution>
    9. <phase>package</phase>
    10. <goals>
    11. <goal>repackage</goal>
    12. </goals>
    13. </execution>
    14. </executions>
    15. </plugin>
    16. </plugins>
    17. </build>

After completing the preceding steps, you can directly use the distributed tracing function of EDAS without setting up any collection or analysis system.

Distributed tracing example

Source code

To demonstrate how to use the distributed tracing function, two code demos service1 and service2 are used in this example.

service1 provides the entrances for three demonstrating scenes.

  • /rest/ok for normal calls

    /rest/ok

  • /rest/delay for calls with large delay

    /rest/delay

  • /rest/error for calls with exceptions or errors

    /rest/error

Deploy the services

The collection and analysis functions of EagleEye are both set up in EDAS. To demonstrate the trace view function, we must deploy the two applications service1 and service2 in EDAS.

  1. When creating an application, choose the latest version of the container.

  2. Add FatJar packaging plugins, and run the mvn clean package command under the directory of the project to create a FatJar package.

  3. Deploy applications on EDAS by uploading the FatJar services in the target directory without configuration.

To view the trace information after the deployment, calling methods corresponding to the entrances of three demonstrating scenes of service1 are required.

You can run the curl http://{$ip:$port}/rest/ok command.Or you can use tools such as postman, or directly call the methods in browsers.

To observe the response, it is recommended that you call the methods in script mode for multiple times.

View the call trace

  1. Log on to the EDAS console and enter the deployed services.

  2. In the left-side navigation pane on the application details page, choose Application Monitoring > Service Monitoring.

  3. On the service monitoring page, click RPC Service Provided, and then View Trace.

See Service Monitoring for details.

Demonstration of other clients

At the same time, the automatic tracking of EagleEye for RestTemplate, AsyncRestTemplate, and FeignClient is demonstrated separately in the three URIs /echo-rest/str, /echo-async-rest/str, and /ech-feign/str of service1.

FAQ

Tracking support

Now, EagleEye of EDAS supports the automatic tracking for requests called by RestTemplate, AsyncRestTemplate, and FeignClient. We will provide the automatic tracking for more components in the future.

AsyncRestTemplate

As AsyncRestTemplate requires to perform the modification of tracking support during class instantiation, injection of object eagleEyeAsyncRestTemplate, which supports service discovery by default, is required to enable tracing.

  1. @Autowired
  2. private AsyncRestTemplate eagleEyeAsyncRestTemplate;

FatJar packaging plugin

To package the pandora-boot project into FatJar by using Maven, you need to add the pandora-boot-maven-plugin in pom.xml.To avoid conflicts with other packaging plugins, do not add other FatJar plugins in build plugin.

More information

See Enable the EDAS distributed tracing function for Spring Cloud for more information about the distributed tracing function and EagleEye.