Develop Microservice with SpringMVC

Concept Description

ServiceComb supports Spring MVC annotations to define your REST services. The samples project has a lot of working examples.

Development Example

Step1 Define the service interface (optional)

Writing a interface for the REST service make it easy to call the service in client in RPC style.

public interface Hello {
    String sayHi(String name);
    String sayHello(Person person);

Step2 Implement the services

The annotations of Spring MVC are used to describe the development of service code. The implementation of the Hello service is as follow:

```java @RestSchema(schemaId = "springmvcHello") @RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON) public class SpringmvcHelloImpl implements Hello { @Override @RequestMapping(path = "/sayhi", method = RequestMethod.POST) public String sayHi(@RequestParam(name = "name") String name) { return "Hello " + name; }

@RequestMapping(path = "/sayhello", method = RequestMethod.POST)
public String sayHello(@RequestBody Person person) {
    return "Hello person " + person.getName();


### Step3 add a component scan (optional)

create `resources/META-INF/spring` folder and add `springmvcprovider.bean.xml`, add component-scan to specify the bean package. This step is optional. The package where main class located is automatically added.

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns=""
       xsi:schemaLocation=" classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd">

    <context:component-scan base-package="org.apache.servicecomb.samples.springmvc.povider"/>

Step4 Wrtie a main class

This code using log4j as the logger framework. Users can change it to any other favorite logger framework.

public class SpringmvcProviderMain {

  public static void main(String[] args) throws Exception {

Using POJO as query parameters


SpringBoot supports to map a bean parameter to HTTP queries.

public class HelloService {
  @RequestMapping(value = "/sayHello", method = RequestMethod.GET)
  public String sayHello(Person person) {
    System.out.println("sayHello is called, person = [" + person + "]");
    return "Hello, your name is " + person.getName() + ", and age is " + person.getAge();

ServiceComb supports this usage too, but has following constraints. 1. Must not add any mapping annotations, such as @QueryParam 2. Only map to query parameters, headers and forms not supported. 3. Variables name in POJO definition must be the same as query keys. 4. Only primitive and String types supported in POJO, add @JsonIgnore to other types to ignore it. 5. In consumer site(e.g RestTemplate), still need to use query parameters, can not use POJO.



  • service definition
  @RestSchema(schemaId = "helloService")
  public class HelloService {
    @RequestMapping(value = "/sayHello", method = RequestMethod.GET)
    public String sayHello(Person person) {
      System.out.println("sayHello is called, person = [" + person + "]");
      return "Hello, your name is " + person.getName() + ", and age is " + person.getAge();
  • parameters
  public class Person {
    private String name;
    private int age;
    @JsonIgnore  // add @JsonIgnore to unsupported types
    private List<Person> children;
  • Schemas

basePath: "/hello"
      operationId: "sayHello"
        # name and age is query parameter
      - name: "name"
        in: "query"
        required: false
        type: "string"
      - name: "age"
        in: "query"
        required: false
        type: "integer"
        format: "int32"
          description: "response of 200"
            type: "string"


  • Call using RPC
  • add an interface java public interface HelloServiceIntf { String sayHello(String name, int age); }
  • call the interface java String result = helloService.sayHello("Bob", 22); // result is "Hello, your name is Bob, and age is 22"
  • Call using RestTemplate java String result = restTemplate.getForObject( "cse://provider-service/hello/sayHello?name=Bob&age=22", String.class);

ServiceComb suppoted Spring MVC annotations and differences

ServiceComb supports Spring MVC annotatioins(org.springframework.web.bind.annotation) to define REST interfaces, but they are different. ServiceComb do not support @Controller frameworks and only support @RestController frameworks.

  • Differences in supported annotations

Table 1-1 annotations

annotation supported notes
RequestMapping Yes Can only have one path, multiple path is not supported.
GetMapping Yes
PutMapping Yes
PostMapping Yes
DeleteMapping Yes
PatchMapping Yes
RequestParam Yes
CookieValue Yes
PathVariable Yes
RequestHeader Yes
RequestBody Yes supports application/json,plain/text
RequestPart Yes Used in file upload. Using Part、MultipartFile annotations.
ResponseBody No @Controller framework is not supported
ResponseStatus No Using ApiResponse to define status code
RequestAttribute No
SessionAttribute No
MatrixVariable No
ModelAttribute No
ControllerAdvice No
CrossOrigin No
ExceptionHandler No
InitBinder No
  • Define a REST service

Spring MVC using @RestController to define a REST service,ServiceComb using @RestSchema to define a REST service,and path value in @RequestMapping is required.

@RestSchema(schemaId = "hello")
@RequestMapping(path = "/")

@RestController is also supported and equals to @RestSchma(schemaId="class name"). However we suggest using @RestSchema to define a schemaId,it's more convenient when used in configurations.

Cautions: If the classes with @RestController are not expected to be processed by ServiceComb-Java-Chassis and work as REST services, the config item can be specified to disable the feature mentioned above.

  • Supported data types

Spring MVC supports almost all java types in service difinition, e.g.

// abstract class
public void postData(@RequestBody Object data)
// interface
public void postData(@RequestBody IPerson interfaceData)
// generic without types
public void postData(@RequestBody Map rawData)
// servlet types
public void postData(HttpServletRequest rquest)

ServiceComb need to generate Open API schemas based on definition, and support cross language features, so some of there usage is not supported.

HttpServletRequest,Object is supported in latest version, but they are different. We suggest not using there features if possible.

please refer to API Constraints for data type supports.