content/references/java-chassis/en_US/start/first-sample/index.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <link rel="shortcut icon" href="../../img/favicon.ico" /> <title>Develop the first microservice - ServiceComb Java Chassis Developers Guide</title> <link rel="stylesheet" href="../../css/theme.css" /> <link rel="stylesheet" href="../../css/theme_extra.css" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" /> <script> // Current page data var mkdocs_page_name = "Develop the first microservice"; var mkdocs_page_input_path = "start/first-sample.md"; var mkdocs_page_url = null; </script> <script src="../../js/jquery-3.6.0.min.js" defer></script>  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script> <script>hljs.initHighlightingOnLoad();</script> </head> <body class="wy-body-for-nav" role="document"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="../.." class="icon icon-home"> ServiceComb Java Chassis Developers Guide </a><div role="search"> <form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" title="Type search term here" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <ul> <li class="toctree-l1"><a class="reference internal" href="../..">Introduction</a> </li> </ul> <p class="caption"><span class="caption-text">Getting Started</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../terminology/">Glossary</a> </li> <li class="toctree-l1"><a class="reference internal" href="../architecture/">Architecture</a> </li> <li class="toctree-l1"><a class="reference internal" href="../development-environment/">Development environment</a> </li> <li class="toctree-l1 current"><a class="reference internal current" href="./">Develop the first microservice</a> <ul class="current"> <li class="toctree-l2"><a class="reference internal" href="#preparement">Preparement</a> </li> <li class="toctree-l2"><a class="reference internal" href="#develop-a-helloworld-microservice">Develop a HelloWorld microservice</a> <ul> <li class="toctree-l3"><a class="reference internal" href="#pom-configurations">pom configurations</a> </li> <li class="toctree-l3"><a class="reference internal" href="#add-microservice-configurations">add microservice configurations</a> </li> <li class="toctree-l3"><a class="reference internal" href="#main-class">Main class</a> </li> <li class="toctree-l3"><a class="reference internal" href="#write-a-rest-service-interface">Write a REST service interface</a> </li> <li class="toctree-l3"><a class="reference internal" href="#add-log-configuration">Add log configuration</a> </li> <li class="toctree-l3"><a class="reference internal" href="#start-the-microservice">Start the microservice</a> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#additional">Additional</a> </li> </ul> </li> </ul> <p class="caption"><span class="caption-text">Development Service Provider</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/definition/service-definition/">Service definition</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/define-contract/">Service contract definition</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/code-first/">Implicit API definition</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/swagger-annotation/">Use Swagger annotations</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/springmvc/">Develop with SpringMVC</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/jaxrs/">Develop with JAX-RS</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/transparent-rpc/">Develop with Transparent RPC</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/interface-constraints/">Interface definition and data type</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/listen-address-and-publish-address/">Service listening address and publishing address</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/thread-pool/">Thread pool</a> </li> <li class="toctree-l1"><a class="reference internal" href="#">Service Configuration</a> <ul> <li class="toctree-l2"><a class="reference internal" href="../../build-provider/configuration/ratelimite-strategy/">Rate Limiting Policy</a> </li> <li class="toctree-l2"><a class="reference internal" href="../../build-provider/configuration/downgrade-strategy/">Fallback Policy</a> </li> <li class="toctree-l2"><a class="reference internal" href="../../build-provider/configuration/parameter-validator/">Parameter Validator</a> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/bootup/">Boot-up Process</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-provider/access-log-configuration/">Access Log Configuration</a> </li> </ul> <p class="caption"><span class="caption-text">Writing Service Consumer</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../build-consumer/common-configuration/">Consumer common configuration</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-consumer/using-resttemplate/">Using Rest Template</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-consumer/using-AsyncRestTemplate/">Using AsyncRestTemplate</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-consumer/develop-consumer-using-rpc/">Using with RPC</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-consumer/with-contract/">Contract</a> </li> <li class="toctree-l1"><a class="reference internal" href="#">Invoke control</a> <ul> <li class="toctree-l2"><a class="reference internal" href="../../build-consumer/circuit-breaker/">Circuit Breaker</a> </li> <li class="toctree-l2"><a class="reference internal" href="../../build-consumer/flow-control/">Flow Control</a> </li> <li class="toctree-l2"><a class="reference internal" href="../../build-consumer/fault-injection/">Fault Injection</a> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../build-consumer/3rd-party-service-invoke/">Invoke 3rd-party REST services</a> </li> </ul> <p class="caption"><span class="caption-text">Transports</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../transports/rest-over-servlet/">REST over Servlet</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../transports/rest-over-vertx/">REST over Vertx</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../transports/highway-rpc/">Highway</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../transports/http2/">HTTP2</a> </li> </ul> <p class="caption"><span class="caption-text">General Development</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../general-development/visit-sc/">Access Service Center</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/metrics/">Metrics</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/microservice-invocation-chain/">Microservice invocation chain</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/customized-tracing/">Customized-Tracing</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/local-develop-test/">Local development and testing</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/http-filter/">Http Filter</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/file-upload/">File Uploading</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/file-download/">File Downloading</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/reactive/">Reactive Programing</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/dnsconfig/">DNS Custom Configuration</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/dai-li-she-zhi/">Proxy Settings</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/report-framework-version/">Report framework version</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/cross-app-invocation/">Cross-application invocation</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/secret-field/">Customized serialization and deserialization</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/context/">Using Context to pass control messages</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/produceprocess/">Return value serialization extension</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/CORS/">CORS mechanism</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/AlarmEvent/">Get fuse and instance isolation alarm event information</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/shutdown/">Shutdown gracefully</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/error-handling/">Handling exceptions</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/multienvironment/">Multi-environment isolation between microservice instances</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../general-development/thread-model/">Thread Model</a> </li> </ul> <p class="caption"><span class="caption-text">Configuration</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../config/general-config/">General config</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../config/inject-config/">Configuration injection</a> </li> </ul> <p class="caption"><span class="caption-text">Service Capability Open</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../edge/open-service/">Intruductions</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../edge/by-servicecomb-sdk/">Using Edge Service</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../edge/nginx/">Using confd and Nginx as edge services</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../edge/zuul/">Use zuul as edge services</a> </li> </ul> <p class="caption"><span class="caption-text">Service Packing and Running</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../packaging/standalone/">Standalone mode</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../packaging/web-container/">WEB container mode</a> </li> </ul> <p class="caption"><span class="caption-text">Micro Service Security</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../security/tls/">Using TLS</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../security/rsa/">Using RSA certification</a> </li> </ul> <p class="caption"><span class="caption-text">Using java chassis in Spring Boot</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot/">Intruductions</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/components-for-spring-boot/">spring boot starter for java-chassis</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/java-application/">JAVA application development</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/web-application/">Web development method development</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/diff-between-java-web/">The difference between JAVA application method and Web development method</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/diff-spring-mvc/">The difference in Spring MVC mode</a> </li> </ul> <p class="caption"><span class="caption-text">Handlers reference</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../references-handlers/intruduction/">Intruductions</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../references-handlers/loadbalance/">Load Balancing</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../references-handlers/publickey/">Public key authentication</a> </li> </ul> <p class="caption"><span class="caption-text">FAQ</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../../question-and-answer/question_answer/">Q & A</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../question-and-answer/faq/">FAQ</a> </li> <li class="toctree-l1"><a class="reference internal" href="../../question-and-answer/interface-compatibility/">Micro Service Interface Compatibility FAQ</a> </li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="../..">ServiceComb Java Chassis Developers Guide</a> </nav> <div class="wy-nav-content"> <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="../.." class="icon icon-home" alt="Docs"></a> »</li> <li>Getting Started »</li> <li>Develop the first microservice</li> <li class="wy-breadcrumbs-aside"> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div class="section" itemprop="articleBody"> <h1 id="develop-the-first-microservice">Develop the first microservice</h1> <h2 id="preparement">Preparement</h2> <p>Before developing the first Java-Chassis microservice, please make sure that your local development environment is prepared. See more details about this in <a href="../development-environment/">Prepare the local development environment</a>.</p> <p>The Apache Service Center is needed in this show case. About using service center, please refer to <a href="http://servicecomb.apache.org/docs/products/service-center/install/">Install of ServiceCenter</a>.</p> <h2 id="develop-a-helloworld-microservice">Develop a HelloWorld microservice</h2> <h3 id="pom-configurations">pom configurations</h3> <p>First, please to create an empty maven project. It is suggested that the dependencies should be managed by <code>dependencyManagement</code> item, so that only the <code>solution-basic</code> is needed to be imported as dependency:</p> <pre><code class="language-xml"><dependencyManagement> <dependencies> <dependency> <groupId>org.apache.servicecomb</groupId> <artifactId>java-chassis-dependencies</artifactId> <version>${java-chassis-dependencies.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.apache.servicecomb</groupId> <artifactId>solution-basic</artifactId> </dependency> </dependencies> </code></pre> <p><code>solution-basic</code> has contains almost all of the dependencies you need in the common cases.</p> <p>For the version 2.0.0 Java-Chassis, <code>maven-compiler-plugin</code> compilation plugin is also needed, which can make the method argument names preserved during the source project is build into a jar file.</p> <pre><code class="language-xml"><build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.1</version> <configuration> <compilerArgument>-parameters</compilerArgument> <encoding>UTF-8</encoding> <source>1.8</source> <target>1.8</target> </configuration> </plugin> </plugins> </build> </code></pre> <h3 id="add-microservice-configurations">add microservice configurations</h3> <p>By default, Java-Chassis read configurations from the file named <code>microservice.yaml</code> placed in <code>resources</code> directory.</p> <p>The content of the file is like below.</p> <pre><code class="language-yaml">APPLICATION_ID: sample # this microservice belongs to the sample application service_description: name: helloworld # this microservice is named "helloworld" version: 1.0.0 servicecomb: service: registry: address: http://127.0.0.1:30100 # this address of the service center rest: address: 0.0.0.0:8080 </code></pre> <h3 id="main-class">Main class</h3> <p>Add a main class in the project:</p> <pre><code class="language-java">package org.apache.servicecomb.samples; import org.apache.servicecomb.foundation.common.utils.BeanUtils; public class AppMain { public static void main(String[] args) { BeanUtils.init(); } } </code></pre> <p>Invoking the <code>org.apache.servicecomb.foundation.common.utils.BeanUtils#init()</code> method will trigger the boot up procedure including configuration loading, Spring application context loading, microservice registration.</p> <h3 id="write-a-rest-service-interface">Write a REST service interface</h3> <p>Add a REST service interface class to declare the request you want to handle.</p> <pre><code class="language-java">package org.apache.servicecomb.samples.service; import org.apache.servicecomb.provider.rest.common.RestSchema; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @RestSchema(schemaId = "hello") @RequestMapping("/") public class HelloWorldService { @GetMapping("/hello") public String hello() { return "Hello world!"; } } </code></pre> <h3 id="add-log-configuration">Add log configuration</h3> <p>The <code>solution-basic</code> module introduces the <code>log4j2</code> module. To enable it, a configuration file is needed. This file should be placed in <code>resources\log4j2.xml</code> and the content is like below:</p> <pre><code class="language-xml"><?xml version="1.0" encoding="UTF-8"?> <Configuration status="WARN"> <Appenders> <Console name="Console" target="SYSTEM_OUT"> <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36}[%L] - %msg%n"/> </Console> </Appenders> <Loggers> <Root level="info"> <AppenderRef ref="Console"/> </Root> </Loggers> </Configuration> </code></pre> <h3 id="start-the-microservice">Start the microservice</h3> <p>After completing the work above, the microservice can be started by running the <code>AppMain</code> class. Please visit the web page of local service center <code>http://127.0.0.1:30103/</code>. If the helloworld microservice instance is found like below, the microservice is started successfully. <img alt="" src="../first-sample-registered-in-sc.png" /></p> <p>If you visit the address <code>http://127.0.0.1:8080/hello</code>, you can see the response <code>"Hello world!"</code> from helloworld service. Now, your first Java-Chassis microservice is completed!.</p> <h2 id="additional">Additional</h2> <p>The introduction demo is developed in Spring MVC style. And there are currently 3 ways to choose:</p> <ul> <li>Spring MVC</li> <li>JaxRS</li> <li>RPC</li> </ul> <p>Developers can quickly build a project in following ways:</p> <ul> <li> <p>Download the samples project. <a href="https://github.com/apache/servicecomb-samples">servicecomb-samples</a> provides many samples in hand.</p> </li> <li> <p><a href="https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/springmvc-sample">Spring MVC Sample</a></p> </li> <li><a href="https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/jaxrs-sample">JaxRS Sample</a></li> <li> <p><a href="https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/pojo-sample">POJO Sample</a></p> </li> <li> <p>Generate projects using archetypes</p> </li> </ul> <p>Maven provide archetypes to generate projects. Java-chassis implements many types of archetypes, see <a href="https://github.com/apache/servicecomb-java-chassis/tree/master/archetypes">LINK</a> for details.</p> <ul> <li>Generate projects using ServiceComb Spring Initializer</li> </ul> <p>ServiceComb Spring Initializer is an graphic user interface to generate projects. See <a href="http://start.servicecomb.io/">LINK</a></p> </div> </div><footer> <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation"> <a href="../development-environment/" class="btn btn-neutral float-left" title="Development environment"><span class="icon icon-circle-arrow-left"></span> Previous</a> <a href="../../build-provider/definition/service-definition/" class="btn btn-neutral float-right" title="Service definition">Next <span class="icon icon-circle-arrow-right"></span></a> </div> <hr/> <div role="contentinfo">  </div> Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <div class="rst-versions" role="note" aria-label="Versions"> <span class="rst-current-version" data-toggle="rst-current-version"> <span><a href="../development-environment/" style="color: #fcfcfc">« Previous</a></span> <span><a href="../../build-provider/definition/service-definition/" style="color: #fcfcfc">Next »</a></span> </span> </div> <script>var base_url = '../..';</script> <script src="../../js/theme_extra.js" defer></script> <script src="../../js/theme.js" defer></script> <script src="../../search/main.js" defer></script> <script defer> window.onload = function () { SphinxRtdTheme.Navigation.enable(true); }; </script> </body> </html>

content/references/java-chassis/en_US/start/first-sample/index.html (441 lines of code) (raw):