WillemJiang closed pull request #581: [SCB-378] add readme document for samples URL: https://github.com/apache/incubator-servicecomb-java-chassis/pull/581
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/samples/auth-sample/README.md b/samples/auth-sample/README.md new file mode 100644 index 000000000..fbf78217e --- /dev/null +++ b/samples/auth-sample/README.md @@ -0,0 +1,91 @@ +## Auth-Sample + +To make sure the security between the interfaces of services, users can enable `RSA Authorizaiton` by simple configuration as below. + +## Consumer Service + +* Add dependence in pom.xml file: + + ```xml + <dependency> + <groupId>org.apache.servicecomb</groupId> + <artifactId>handler-publickey-auth</artifactId> + </dependency> + ``` + +* Add handler chain in microservice.yaml: + + ```yaml + cse: + # other configurations omitted + handler: + chain: + Consumer: + default: auth-consumer + ``` + +## Provider Service + +* Add dependence in pom.xml file: + + ```xml + <dependency> + <groupId>org.apache.servicecomb</groupId> + <artifactId>handler-publickey-auth</artifactId> + </dependency> + ``` + +* Add handler chain in microservice.yaml: + + ```yaml + cse: + # other configurations omitted + handler: + chain: + Consumer: + default: auth-provider + ``` + +## Sample Quick Start + +Auth sample use `RestTemplate` to present RSA communication between provider and consumer. + +1. Start the ServiceComb/Service Center + + - [how to start the service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + - make sure service center address is configured correctly in `microservice.yaml` file + + ```yaml + cse: + service: + registry: + address: http://127.0.0.1:30100 #service center address + ``` + +2. Start the auth-provider service + + - Start provider service by maven + + Compile the source code at root directory of ServiceComb Java Chassis, which is `incubator-servicecomb-java-chassis/`, and use `mvn exec` to execute the main class `AuthProviderMain`. + + ```bash + cd incubator-servicecomb-java-chassis/ + mvn clean install -Psamples -DskipTests #only need to install at first time. + cd samples/auth-sample/auth-provider/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.springmvc.provider.AuthProviderMain" + ``` + + - Start provider service by IDE + + Import the project by InteliJ IDEA or Eclipse, add sample module to pom.xml file in root module `incubator-servicecomb-java-chassis/pom.xml`, and add `<module>samples</module>` to `<modules></modules>` block, Then find `main` function `AuthProviderMain` of provider service and `RUN` it like any other Java program. + +3. Start the auth-consumer service + + Just like how to start auth-provider service. But the main class of auth-consumer service is `AuthConsumerMain`. + + ```bash + cd samples/auth-sample/auth-consumer/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.springmvc.consumer.AuthConsumerMain" + ``` + + ? \ No newline at end of file diff --git a/samples/bmi/README.md b/samples/bmi/README.md index 481e084b2..e7a9c9e59 100644 --- a/samples/bmi/README.md +++ b/samples/bmi/README.md @@ -10,15 +10,13 @@ There are two microservices in this demo. ## Quick Start(Linux) 1. Run the service center -```bash -wget https://github.com/ServiceComb/service-center/releases/download/0.1.1/service-center-0.1.1-linux-amd64.tar.gz -tar xvf service-center-0.1.1-linux-amd64.tar.gz -(cd service-center-0.1.1-linux-amd64; bash start.sh) -``` + + [how to start service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + 2. Get the bmi demo's code ```bash -git clone https://github.com/ServiceComb/ServiceComb-Java-Chassis -cd ServiceComb-Java-Chassis/samples +git clone https://github.com/apache/incubator-servicecomb-java-chassis.git +cd incubator-servicecomb-java-chassis/samples ``` 3. Run microservices * Run the **BMI calculator service** @@ -29,4 +27,4 @@ cd ServiceComb-Java-Chassis/samples ```bash (cd bmi/webapp; mvn spring-boot:run) ``` -4. Visit the services via **<a>http://127.0.0.1:8889</a>**. \ No newline at end of file +4. Visit the services via **<a>http://127.0.0.1:8889</a>**. diff --git a/samples/codefirst-sample/README.md b/samples/codefirst-sample/README.md new file mode 100644 index 000000000..b756ae984 --- /dev/null +++ b/samples/codefirst-sample/README.md @@ -0,0 +1,51 @@ +## Code First Sample + +ServiceComb Java Chassis supports generating provider-service API implicitly. When the service is started, an API is automatically generated and registered to the service center. + +When you develop a microservice in transparent RPC mode, the code does not show how you want to define an API, and all generated APIs are POST methods, The input parameters of all the methods will be packaged as a class and transferred as body parameters. Therefore, if you develop providers using implicit APIs, you are advised to choose Spring MVC or JAX-RS mode to obtain complete RESTful statements. + +For detail information please refer to [Doc](http://servicecomb.incubator.apache.org/users/service-contract/) + + + +## Sample Quick Start + +1. Start the ServiceComb/Service Center + + - [how to start the service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + - make sure service center address is configured correctly in `microservice.yaml` file + + ```yaml + cse: + service: + registry: + address: http://127.0.0.1:30100 #service center address + ``` + +2. Start the codefirst-provider service + + - Start provider service by maven + + Compile the source code at root directory of ServiceComb Java Chassis, which is `incubator-servicecomb-java-chassis/`, and use `mvn exec` to execute the main class `CodeFirstProviderMain`. + + ```bash + cd incubator-servicecomb-java-chassis/ + mvn clean install -Psamples -DskipTests #only need to install at first time. + cd samples/codefirst-sample/codefirst-provider/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.codefirst.provider.CodeFirstProviderMain" + ``` + + - Start provider service by IDE + + Import the project by InteliJ IDEA or Eclipse, add sample module to pom.xml file in root module `incubator-servicecomb-java-chassis/pom.xml`, and add `<module>samples</module>` to `<modules></modules>` block, Then find `main` function `CodeFirstProviderMain` of provider service and `RUN` it like any other Java program. + +3. Start the codefirst-consumer service + + Just like how to start codefirst-provider service. But the main class of codefirst-consumer service is `CodeFirstConsumerMain`. + + ```bash + cd samples/codefirst-sample/codefirst-consumer/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.codefirst.consumer.CodeFirstConsumerMain" + ``` + + ? \ No newline at end of file diff --git a/samples/custom-handler-sample/README.md b/samples/custom-handler-sample/README.md new file mode 100644 index 000000000..72223e767 --- /dev/null +++ b/samples/custom-handler-sample/README.md @@ -0,0 +1,82 @@ +## Customized Handler Sample + +ServiceComb support users to define a customized handler and and invoke the handler in handler chain. + +* Customize a handler by implement Handler interface, for example: + + ```java + public class MyHandler implements Handler { + private static final Logger LOGGER = LoggerFactory.getLogger(MyHandler.class); + @Override + public void handle(Invocation invocation, AsyncResponse asyncResponse) throws Exception { + //code before + LOGGER.info("It's my handler! \r\n"); + invocation.next(response -> { + // code after + asyncResponse.handle(response); + }); + } + } + ``` + +* Define handler `id` and `class` in `cse.handler.xml` `config` item under `resources/config` directory + + ```xml + <config> + <handler id="myhandler" class="org.apache.servicecomb.samples.customerhandler.handlers.MyHandler" /> + </config> + + ``` + +* Configure customized `MyHandler` in `microservice.yaml` file along with other handler together + + ```yaml + cse: + # other configurations omitted + handler: + chain: + Consumer: + default: bizkeeper-consumer,loadbalance, myhandler + ``` + +## Sample Quick Start + +1. Start the ServiceComb/Service Center + + - [how to start the service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + - make sure service center address is configured correctly in `microservice.yaml` file + + ```yaml + cse: + service: + registry: + address: http://127.0.0.1:30100 #service center address + ``` + +2. Start the custom-handler-provider service + + - Start provider service by maven + + Compile the source code at root directory of ServiceComb Java Chassis, which is `incubator-servicecomb-java-chassis/`, and use `mvn exec` to execute the main class `CustomHandlerProviderMain`. + + ```bash + cd incubator-servicecomb-java-chassis/ #need to complie code at root directory + mvn clean install -Psamples -DskipTests #only need to install at first time. + cd samples/custom-handler-sample/custom-handler-provider/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.customerhandler.provider.CustomHandlerProviderMain" + ``` + + - Start provider service by IDE + + Import the project by InteliJ IDEA or Eclipse, add sample module to pom.xml file in root module `incubator-servicecomb-java-chassis/pom.xml`, and add `<module>samples</module>` to `<modules></modules>` block, Then find `main` function `CustomHandlerProviderMain` of provider service and `RUN` it like any other Java program. + +3. Start the custom-handler-consumer service + + Just like how to start custom-handler-provider service. But the main class of custom-handler-consumer service is `CustomHandlerCustomerMain`. + + ```bash + cd samples/custom-handler-sample/custom-handler-consumer + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.customerhandler.consumer.CustomHandlerCustomerMain" + ``` + + ? \ No newline at end of file diff --git a/samples/jaxrs-sample/README.md b/samples/jaxrs-sample/README.md new file mode 100644 index 000000000..0f3f5a6fa --- /dev/null +++ b/samples/jaxrs-sample/README.md @@ -0,0 +1,58 @@ +## JAX-RS Sample + +ServiceComb supports developers in developing services in JAX-RS mode by using JAX-RS. + +### Provider Service + +* Define a service API. Compile the Java API definition based on the API definition defined before development +* Implement the service. JAX-RS is used to describe the development of service code. +* Release the service. Add `@RestSchema` as the annotation of the service implementation class and specify schemaID, which indicates that the implementation is released as a schema of the current microservice. +* Create the jaxrsHello.bean.xml file in the resources/META-INF/spring directory and configure base-package that performs scanning + + [Detail information please refer to Doc](http://servicecomb.incubator.apache.org/users/develop-with-jax-rs/) + +### Consumer Service + +To consume a provider-service, only need to decalare a member of a service API type and add the `RpcReference` annotation for the member, the microservice that depends on the declaration and the `schemaID` just like pojo consumer sample. + +### Sample Quick Start + +1. Start the ServiceComb/Service Center + + - [how to start the service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + - make sure service center address is configured correctly in `microservice.yaml` file + + ```yaml + cse: + service: + registry: + address: http://127.0.0.1:30100 #service center address + ``` + +2. Start the jaxrs-provider service + + - Start provider service by maven + + Compile the source code at root directory of ServiceComb Java Chassis, which is `incubator-servicecomb-java-chassis/`, and use `mvn exec` to execute the main class `JaxrsProviderMain`. + + ```bash + cd incubator-servicecomb-java-chassis/ + mvn clean install -Psamples -DskipTests #only need to install at first time. + cd samples/jaxrs-sample/jaxrs-provider/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.jaxrs.provider.JaxrsProviderMain" + ``` + + - Start provider service by IDE + + Import the project by InteliJ IDEA or Eclipse, add sample module to pom.xml file in root module `incubator-servicecomb-java-chassis/pom.xml`, and add `<module>samples</module>` to `<modules></modules>` block, Then find `main` function `JaxrsProviderMain` of provider service and `RUN` it like any other Java Program. + +3. Start the jaxrs-consumer service + + Just like how to start jaxrs-provider service. But the main class of jaxrs-consumer service is `JaxrsConsumerMain`. + + ```bash + cd samples/jaxrs-sample/jaxrs-consumer/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.jaxrs.consumer.JaxrsConsumerMain" + ``` + + ? \ No newline at end of file diff --git a/samples/pojo-sample/README.md b/samples/pojo-sample/README.md new file mode 100644 index 000000000..15f0e0e0e --- /dev/null +++ b/samples/pojo-sample/README.md @@ -0,0 +1,81 @@ +## POJO Sample + +POJO is also called as Transparent Remote Procedure Call (RPC), POJO development mode based on API and API implementation. The service developer does not need to use the description of Spring MVC and JAX-RS. + +### Provider Service + +The transparent RPC development mode supports two service release mode: Spring XML configuration and annotation configuration. + +The Spring XML Configuration Mode: + +* Define a service API. Compile the Java API definition based on the API definition defined before development. +* Implement the service. +* Release the service. Create the `pojoHello.bean.xml` file in the `resources/META-INF/spring` directory and declare the schema in the file. + +The Develop Method by Configure Remarks: + +* Define a service API, which is the same as the Spring XML mode +* Implement the service in the same way as using Spring XML. +* Release the service. `@RpcSchema` is used to define schema during the API Hello implementation. + +[Detail information please refer to Doc](http://servicecomb.incubator.apache.org/users/develop-with-transparent-rpc/) + +### Consumer Service + +To call a microservice, you only need to declare a member of a service API type and add the `@RpcReference` annotation for the member, the microservice that depends on the declaration, and the `schemaID`. The sample code is as follows. + +```java +@Component +public class CodeFirstConsumerMain { + @RpcReference(microserviceName = "codefirst", schemaId = "codeFirstHello") + private static Hello hello; + public static void main(String[] args) throws Exception { + //init first + System.out.println(hello.sayHi("World!")); + } +} +``` + +[Detail information please refer to Doc](http://servicecomb.incubator.apache.org/users/develop-with-rpc/) + +### Sample Quick Start + +1. Start the ServiceComb/Service Center + + - [how to start the service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + - make sure service center address is configured correctly in `microservice.yaml` file + + ```yaml + cse: + service: + registry: + address: http://127.0.0.1:30100 #service center address + ``` + +2. Start the pojo-provider service + + - Start provider service by maven + + Compile the source code at root directory of ServiceComb Java Chassis, which is `incubator-servicecomb-java-chassis/`, and use `mvn exec` to execute the main class `PojoProviderMain`. + + ```bash + cd incubator-servicecomb-java-chassis/ + mvn clean install -Psamples -DskipTests #only need to install at first time. + cd samples/pojo-sample/pojo-provider/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.pojo.provider.PojoProviderMain" + ``` + + - Start provider service by IDE + + Import the project by InteliJ IDEA or Eclipse, add sample module to pom.xml file in root module `incubator-servicecomb-java-chassis/pom.xml`, and add `<module>samples</module>` to `<modules></modules>` block, Then find `main` function `PojoProviderMain` of provider service and `RUN` it like any other Java program. + +3. Start the pojo-consumer service + + Just like how to start pojo-provider service. But the main class of pojo-consumer service is `PojoConsumerMain`. + + ```bash + cd samples/pojo-sample/pojo-consumer/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.pojo.consumer.PojoConsumerMain" + ``` + + ? \ No newline at end of file diff --git a/samples/springmvc-sample/README.md b/samples/springmvc-sample/README.md new file mode 100644 index 000000000..fdb156dd1 --- /dev/null +++ b/samples/springmvc-sample/README.md @@ -0,0 +1,52 @@ +# Spring MVC Sample + +`RestTemplate` is a RESTful API provide by the Spring framework. ServiceComb provides the API for service calling. Users can call microservices using customized URL and `RestTemplate` instance provided by ServiceComb regardless of the specific address of the service. + +* The URL must be in format of ServiceComb: `cse://microserviceName/path?querystring`. +* During use of this URL format, the ServiceComb framework will perform internal microservice descovery, fallbreak, and fault tolerance and send the requests to the microservice providers. + +## Sample Quick Start + +1. Start the ServiceComb/Service Center + + * [how to start the service center](http://servicecomb.incubator.apache.org/users/setup-environment/#) + * make sure service center address is configured correctly in `microservice.yaml` file + + ```yaml + cse: + service: + registry: + address: http://127.0.0.1:30100 #service center address + ``` + +2. Start the springmvc-provider service + + * Start provider service by maven + + Compile the source code at root directory of ServiceComb Java Chassis, which is `incubator-servicecomb-java-chassis/`, and use `mvn exec` to execute the main class `SpringmvcProviderMain`. + + ```bash + cd incubator-servicecomb-java-chassis/ + mvn clean install -Psamples -DskipTests #Only need to install at first time + cd samples/springmvc-sample/springmvc-provider/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.springmvc.provider.SpringmvcProviderMain" + ``` + + * Start provider service by IDE + + Import the project by InteliJ IDEA or Eclipse, add sample module to pom.xml file in root module `incubator-servicecomb-java-chassis/pom.xml`, and add `<module>samples</module>` to `<modules></modules>` block, Then find `main` function of provider service and `RUN` it like any other Java Program. + +3. Start the springmvc-consumer service + + Just like how to start springmvc-provider service. But the main class of springmvc-consumer service is `SpringmvcConsumerMain`. + + ```bash + cd samples/springmvc-sample/springmvc-consumer/ + mvn exec:java -Dexec.mainClass="org.apache.servicecomb.samples.springmvc.consumer.SpringmvcConsumerMain" + ``` + + ? + +## More + +[Develop with RestTemplate](http://servicecomb.incubator.apache.org/users/develop-with-rest-template/) \ No newline at end of file ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
