About contract-first (API First) development of Java Chassis 3

The open source China community team made its first live broadcast, telling the story behind the open source China community in the name of sharing."

This article is shared from Huawei Cloud Community " Java Chassis 3 Technology Decryption: Contract First (API First) Development ", author: liubao68.

Contract-first (API First) development refers to making API design the first priority task in the application development process. Contract-first development has continued to receive attention with the development of the Web Services concept. Especially after the emergence of microservice architecture, API design has become a key factor affecting issues such as function opening and performance optimization. Common contract-first development frameworks and patterns include the following:

Web Services technology allows designers to first write WSDL to describe WEB service content, and then combine it with tools to generate code. WSDL can be distributed, and different languages can be combined with WSDL to generate clients.
With gRPC technology, designers can first write IDL to describe RPC service content, and then combine it with tools to generate code. gRPC mainly solves calls between services.
Spring Boot allows developers to use the swagger tool to first write the Open API interface, and then generate RESTFul server code through the tool.

These technologies all require designers to master a language-independent description language (WSDL, IDL, Swagger, etc.) and generate language-specific code through tools. The application scenarios they support are also different. Web Service is suitable for external WEB services, and gRPC is suitable for internal RPC services. Java Chassis contract-first development features the following improvements:

Allows the Java language to be used directly to define service interfaces, without requiring designers to master a new description language.
Define the Web service interface and the internal RPC interface at the same time.

Like Spring Boot, the language-independent description language of Java Chassis is still Open API. Through Open API, it can meet the requirements of cross-language and service distribution.

Contract Priority Development Process

Contract-first development can cover the entire process of software development such as design, development, testing, deployment, operation and maintenance. Through contracts, parallel work in different links can be achieved, thereby improving development efficiency. A simple contract development process is as follows:

The following code briefly demonstrates the process of defining a contract through Java semantics and implementing providers and consumers.

Define service contract

@RequestMapping(path = "/provider")
public interface ProviderService {
  @GetMapping("/sayHello")
  String sayHello(@RequestParam("name") String name);
}

Define provider

@RestSchema(schemaId = "ProviderController", schemaInterface = ProviderService.class)
public class ProviderController implements ProviderService {
  @Override
  public String sayHello(String name) {
    return "Hello " + name;
  }
}

Define consumers

@Configuration
public class ProviderServiceConfiguration {
  @Bean
  public ProviderService providerService() {
    return Invoker.createProxy("provider", "ProviderController", ProviderService.class);
  }
}

Use RPC to access the provider.

@RestSchema(schemaId = "ConsumerController", schemaInterface = ConsumerService.class)
public class ConsumerController implements ConsumerService {
  private ProviderService providerService;

  @Autowired
  public void setProviderService(ProviderService providerService) {
    this.providerService = providerService;
  }

  @Override
  public String sayHello(String name) {
    return providerService.sayHello(name);
  }
}

Service distribution and web service access

The provider's service definition will generate the following Open API information

openfire: 3.0.1
info:
  title: swagger definition for org.apache.servicecomb.samples.api.ProviderService
  version: 1.0.0
servers:
- url: /provider
paths:
  /sayHello:
    get:
      operationId: sayHello
      parameters:
      - name: name
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: response of 200
          content:
            application/json:
              schema:
                type: string
            application/protobuf:
              schema:
                type: string
            text/plain:
              schema:
                type: string
components: {}

This information can be used for WEB service access. For example, the above information can be used

GET /providers/sayHello?name=World

HTTP request to access. For other frameworks or languages, you can also use Open API to generate corresponding code for access.

Service governance

Service governance is designed to be independent of the development process. Combining Open API and service governance rule description language, it is possible to configure service governance for APIs.

servicecomb:
  matchGroup:
    helloOperation: |
      matches:
        - apiPath:
            prefix: "/provider/sayHello"
  rateLimiting:
    ## The current limiter allows 100 requests every 10 milliseconds. If a request is not received for more than 1000 milliseconds,
    ## Permission will be denied
    helloOperation: |
      rate: 100
      limitRefreshPeriod: 10
      timeoutDuration: 1000

The above rules limit the flow of API interfaces.

Other aspects of covenant-first development

In terms of testing, automated test code can be generated through contracts to cover API testing. In terms of deployment and implementation, Open API information can be imported into the gateway to realize API capability exposure, authentication, and accounting. In addition, contracts can also be used in various aspects such as document generation and application monitoring statistics.

Summarize

Java Chassis is based on the interface definition of the JAVA language, which can satisfy the SDK distribution of both Native language and platform-independent description language, and does not require the use of tools to generate additional running code, providing a unified and consistent approach for external service development and internal service development. Development experience. Contract-first development is a very efficient process method for service-oriented/microservice-oriented. Java Chassis provides good tool support to support contract-first development.

Click to follow and learn about Huawei Cloud’s new technologies as soon as possible~