| <!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>Service contract definition - 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 = "Service contract definition"; |
| var mkdocs_page_input_path = "build-provider/define-contract.md"; |
| var mkdocs_page_url = null; |
| </script> |
| |
| <script src="../../js/jquery-3.6.0.min.js" defer></script> |
| <!--[if lt IE 9]> |
| <script src="../../js/html5shiv.min.js"></script> |
| <![endif]--> |
| <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> |
| <li class="toctree-l1"><a class="reference internal" href="../../start/terminology/">Glossary</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../../start/architecture/">Architecture</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../../start/development-environment/">Development environment</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../../start/first-sample/">Develop the first microservice</a> |
| </li> |
| </ul> |
| <p class="caption"><span class="caption-text">Development Service Provider</span></p> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../definition/service-definition/">Service definition</a> |
| </li> |
| <li class="toctree-l1 current"><a class="reference internal current" href="./">Service contract definition</a> |
| <ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="#concept-description">Concept Description</a> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#scenario">Scenario</a> |
| <ul> |
| <li class="toctree-l3"><a class="reference internal" href="#configuration">Configuration</a> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="#sample-code">Sample Code</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../code-first/">Implicit API definition</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../swagger-annotation/">Use Swagger annotations</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../springmvc/">Develop with SpringMVC</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../jaxrs/">Develop with JAX-RS</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../transparent-rpc/">Develop with Transparent RPC</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../interface-constraints/">Interface definition and data type</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../listen-address-and-publish-address/">Service listening address and publishing address</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../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="../configuration/ratelimite-strategy/">Rate Limiting Policy</a> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../configuration/downgrade-strategy/">Fallback Policy</a> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../configuration/parameter-validator/">Parameter Validator</a> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../bootup/">Boot-up Process</a> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../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>Development Service Provider »</li> |
| <li>Service contract definition</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="service-contract-definition">Service Contract Definition</h1> |
| <h2 id="concept-description">Concept Description</h2> |
| <p>The Service Contract refers to the micro-service interface contract based on the OpenAPI specification. The interface definition between the server and the consumer. The java chassis provides two ways to define the contract: 'code first' and 'contract first'.</p> |
| <ul> |
| <li> |
| <p>Code first<br /> |
| The Producer use of Jax-RS or SpringMVC's RESTful annotation declares the input and output parameters of the interface, or with the OpenAPI annotations, to add human-readable information, such as sample code, text descriptions, etc.; when the ServiceComb engine starts, according to these annotations generate a contract description and automatically upload it to the service center. <br /> |
| The producer can also be developed using the transparent RPC model, but since there is no RESTful annotation to guide how to generate the contract, at this time, the automatically generated contract very non-standard and not recommended. The consumer is called with a transparent RPC or RestTemplate. <br /> |
| Under the code first development model, developers do not have to handwritten contracts. </p> |
| </li> |
| <li> |
| <p>Contract first<br /> |
| In this scenario, instead of using the contract automatically generated by the framework, the contract file provided by the developer is directly used, which requires the developer to ensure the consistency of the contract and the code.</p> |
| </li> |
| </ul> |
| <h2 id="scenario">Scenario</h2> |
| <p>The service contract is used for decoupling between the server and the consumer. The server implements the service around the contract. The consumer invokes the service according to the contract, which can support the server and the consumer to implement in different programming languages.</p> |
| <blockquote> |
| <p><em><strong> Description: </strong></em> |
| The service provider registers the interface contract with the service center at startup, which can be downloaded and used by the service consumer. The interface contract is micro-service-version level information. When multiple micro-service instances are started, if an instance registers the contract with the service center, the service center will not overwrite the existing contract with the contract information registered by the latecomer. Therefore, only modifying the service provider's interface information will not change the contract stored by the service center. For the service consumer, the acquired interface information is still old. To update the interface contract in the service center, you can choose to upgrade the microservice version number or delete existing microservice information (the latter is not recommended for use in a production environment).</p> |
| </blockquote> |
| <h3 id="configuration">Configuration</h3> |
| <p>ServiceComb defines API in a .yaml file. It's recommended to use <a href="http://editor.swagger.io/#/">Swagger Editor</a> to define the APIs. This tool can check syntax and automaticlly generate an API document. For details about the API definition file format, see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md"> Official OpenAPI documentation</a>。</p> |
| <p>The API definition file is located in "resources/microservices" or "resources/applications" directory. The directory structure is as follows:</p> |
| <pre><code class="language-yaml">resources |
| - microservices |
| - serviceName #Microservice name |
| - schemaId.yaml #schema ID |
| - applications |
| - appId #Application ID |
| - serviceName #Service name |
| - schemaId.yaml #Schema ID |
| </code></pre> |
| <blockquote> |
| <p><strong>Note</strong>:</p> |
| <ul> |
| <li>ServiceComb's Swagger contract file should be saved using the UTF-8 character set. If the user saves the contract file with a different character set and the file contains Chinese characters, it may cause an unknown error.</li> |
| </ul> |
| </blockquote> |
| <h3 id="sample-code">Sample Code</h3> |
| <p>The contents of the schemaId.yaml file in the <code>resources/microservices</code> directory and the <code>resources/application</code> directory are as follows. The interface definitions in the file need to match the actual interface of the service.</p> |
| <pre><code class="language-yaml">swagger: '2.0' |
| info: |
| title: hello |
| version: 1.0.0 |
| x-java-interface: org.apache.servicecomb.samples.common.schema.Hello |
| basePath: /springmvchello |
| produces: |
| - application/json |
| |
| paths: |
| /sayhi: |
| post: |
| operationId: sayHi |
| parameters: |
| - name: name |
| in: query |
| required: true |
| type: string |
| responses: |
| 200: |
| description: return value |
| schema: |
| type: string |
| default: |
| description: return a default result |
| schema: |
| type: string |
| /sayhello: |
| post: |
| operationId: sayHello |
| parameters: |
| - name: person |
| in: body |
| required: true |
| schema: |
| $ref: "#/definitions/Person" |
| responses: |
| 200: |
| description: return value |
| schema: |
| type: string |
| default: |
| description: return a default result |
| schema: |
| type: string |
| definitions: |
| Person: |
| type: "object" |
| properties: |
| name: |
| type: "string" |
| description: "person name" |
| xml: |
| name: "Person" |
| </code></pre> |
| <blockquote> |
| <p><strong>NOTE</strong>：<br /> |
| * Contract in ServiceComb, it is recommended that basePath not include the web root of the web container, and the url pattern of the servlet.</p> |
| </blockquote> |
| <p>Because ServiceComb supports deployment decoupling, it can be deployed independently from the servlet container, or deployed to the servlet container using the war, or it can be run using the embedded servlet container. |
| As long as the base path does not contain the web root and the url pattern, the actual url changes caused by the deployment mode modification, the ServiceComb consumer business code does not need to be perceived, and the framework will automatically adapt.</p> |
| <blockquote> |
| <ul> |
| <li>info.x-java-interface needs to indicate the specific interface path, depending on the actual situation of the project.</li> |
| <li>SchemaId can contain "." characters, but it is not recommended. This is because the configuration file used by ServiceComb is in yaml format. The "." symbol is used to split the configuration item name. If the SchemaId also contains ".", some configurations that support the contract level may not be recognized correctly.</li> |
| <li>The "." character cannot be included in the naming of the OperationId.</li> |
| </ul> |
| </blockquote> |
| |
| </div> |
| </div><footer> |
| <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation"> |
| <a href="../definition/service-definition/" class="btn btn-neutral float-left" title="Service definition"><span class="icon icon-circle-arrow-left"></span> Previous</a> |
| <a href="../code-first/" class="btn btn-neutral float-right" title="Implicit API definition">Next <span class="icon icon-circle-arrow-right"></span></a> |
| </div> |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <!-- Copyright etc --> |
| </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="../definition/service-definition/" style="color: #fcfcfc">« Previous</a></span> |
| |
| |
| <span><a href="../code-first/" 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> |
