You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2020/03/23 00:54:17 UTC
[servicecomb-docs] branch master updated: add Helloworld sample
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 35558e1 add Helloworld sample
35558e1 is described below
commit 35558e1f47e5f046517a026bda6918f4e4125f12
Author: yhs0092 <yh...@163.com>
AuthorDate: Mon Feb 24 15:02:27 2020 +0800
add Helloworld sample
---
.../docs/start/first-sample-registered-in-sc.png | Bin 0 -> 24284 bytes
.../en_US/docs/start/first-sample.md | 139 +++++++++++++++++++-
.../docs/start/first-sample-registered-in-sc.png | Bin 0 -> 24284 bytes
.../zh_CN/docs/start/first-sample.md | 140 ++++++++++++++++++++-
4 files changed, 273 insertions(+), 6 deletions(-)
diff --git a/java-chassis-reference/en_US/docs/start/first-sample-registered-in-sc.png b/java-chassis-reference/en_US/docs/start/first-sample-registered-in-sc.png
new file mode 100644
index 0000000..c7cb97c
Binary files /dev/null and b/java-chassis-reference/en_US/docs/start/first-sample-registered-in-sc.png differ
diff --git a/java-chassis-reference/en_US/docs/start/first-sample.md b/java-chassis-reference/en_US/docs/start/first-sample.md
index 8e67809..cf24dcb 100644
--- a/java-chassis-reference/en_US/docs/start/first-sample.md
+++ b/java-chassis-reference/en_US/docs/start/first-sample.md
@@ -1,6 +1,141 @@
# Develop the first microservice
-Before you start, developers need to choose a familiar development method. There are currently 3 ways to choose:
+## Preparement
+
+Before developing the first Java-Chassis microservice, please make sure that your local development environment is prepared. See more details about this in [Prepare the local development environment](./development-environment.md).
+
+The Apache Service Center is needed in this show case. About using service center, please refer to [Install of ServiceCenter](http://servicecomb.apache.org/docs/products/service-center/install/).
+
+## Develop a HelloWorld microservice
+
+### pom configurations
+
+First, please to create an empty maven project. It is suggested that the dependencies should be managed by `dependencyManagement` item, so that only the `solution-basic` is needed to be imported as dependency:
+```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>
+```
+`solution-basic` has contains almost all of the dependencies you need in the common cases.
+
+For the version 2.0.0 Java-Chassis, `maven-compiler-plugin` compilation plugin is also needed, which can make the method argument names preserved during the source project is build into a jar file.
+```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>
+```
+
+### add microservice configurations
+
+By default, Java-Chassis read configurations from the file named `microservice.yaml` placed in `resources` directory.
+
+The content of the file is like below.
+```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
+```
+
+### Main class
+
+Add a main class in the project:
+```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();
+ }
+}
+```
+
+Invoking the `org.apache.servicecomb.foundation.common.utils.BeanUtils#init()` method will trigger the boot up procedure including configuration loading, Spring application context loading, microservice registration.
+
+### Write a REST service interface
+
+Add a REST service interface class to declare the request you want to handle.
+```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!";
+ }
+}
+```
+
+### Add log configuration
+
+The `solution-basic` module introduces the `log4j2` module. To enable it, a configuration file is needed. This file should be placed in `resources\log4j2.xml` and the content is like below:
+```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>
+```
+
+### Start the microservice
+
+After completing the work above, the microservice can be started by running the `AppMain` class. Please visit the web page of local service center `http://127.0.0.1:30103/`. If the helloworld microservice instance is found like below, the microservice is started successfully.
+
+
+If you visit the address `http://127.0.0.1:8080/hello`, you can see the response `"Hello world!"` from helloworld service. Now, your first Java-Chassis microservice is completed!.
+
+## Additional
+
+The introduction demo is developed in Spring MVC style.
+And there are currently 3 ways to choose:
* Spring MVC
* JaxRS
@@ -21,5 +156,3 @@ Developers can quickly build a project in following ways:
* Generate projects using ServiceComb Spring Initializer
ServiceComb Spring Initializer is an graphic user interface to generate projects. See [LINK](http://start.servicecomb.io/)
-
-
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/start/first-sample-registered-in-sc.png b/java-chassis-reference/zh_CN/docs/start/first-sample-registered-in-sc.png
new file mode 100644
index 0000000..c7cb97c
Binary files /dev/null and b/java-chassis-reference/zh_CN/docs/start/first-sample-registered-in-sc.png differ
diff --git a/java-chassis-reference/zh_CN/docs/start/first-sample.md b/java-chassis-reference/zh_CN/docs/start/first-sample.md
index a348091..befb801 100644
--- a/java-chassis-reference/zh_CN/docs/start/first-sample.md
+++ b/java-chassis-reference/zh_CN/docs/start/first-sample.md
@@ -1,6 +1,140 @@
# 开发第一个微服务
-开始之前，开发者需要选择熟悉的开发方式，目前有3种方式可供选择：
+## 准备工作
+
+在开发第一个Java-Chassis微服务之前，请先确保你的本地开发环境已经准备就绪，参考[安装本地开发环境](./development-environment.md)。
+
+本文示例需要用到服务中心，请参考[ServiceCenter 安装说明](http://servicecomb.apache.org/cn/docs/products/service-center/install/)。
+
+## 开发一个HelloWorld服务
+
+### 配置pom文件
+
+创建一个空的maven工程。建议先配置`dependencyManagement`来管理依赖项，依赖项只需要引入`solution-basic`即可：
+```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>
+```
+`solution-basic`中已经包含了常见场景下开发Java-Chassis微服务所需的全部依赖项。
+
+Java-Chassis 2.0版本还需要引入`maven-compiler-plugin`插件，使项目打包时保留方法参数名：
+```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>
+```
+
+### 添加配置文件
+
+Java-Chassis默认读取的配置文件名为`microservice.yaml`，存放在`resources`目录中。
+
+文件内容如下，这份文件表示当前开发的是`sample`应用下的名为`helloworld`的微服务，版本为0.0.1。该微服务连接的服务中心地址为`http://127.0.0.1:30100`，监听`8080`端口。
+```yaml
+APPLICATION_ID: sample
+service_description:
+ name: helloworld
+ version: 1.0.0
+servicecomb:
+ service:
+ registry:
+ address: http://127.0.0.1:30100
+ rest:
+ address: 0.0.0.0:8080
+```
+
+### 编写Main类
+
+在工程中添加一个Main类，用于启动微服务实例：
+```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();
+ }
+}
+```
+
+调用`org.apache.servicecomb.foundation.common.utils.BeanUtils#init()`方法会完成配置加载、Spring应用上下文加载、微服务注册等一系列启动流程。
+
+### 编写REST接口类
+
+最后在工程中添加一个REST接口类用于接收请求：
+```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!";
+ }
+}
+```
+
+### 添加日志配置文件
+
+`solution-basic`引入了log4j2组件。如果想要看到运行日志，还需要手动添加一份日志配置文件，文件存放位置为`resources\log4j2.xml`，内容如下：
+```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>
+```
+
+### 启动服务
+
+以上工作完成后，运行`AppMain`类即可启动微服务。在浏览器中打开本地服务中心的页面`http://127.0.0.1:30103/`，如果能看到helloworld服务的实例记录，则表示启动成功。如下图所示：
+
+
+访问`http://127.0.0.1:8080/hello`，可以得到helloworld服务的响应`"Hello world!"`。至此，第一个Java-Chassis微服务开发完成。
+
+## 补充说明
+
+上文以Spring MVC开发风格来编写helloworld服务的REST接口类，目前Java-Chassis提供了三种REST接口类开发风格：
* Spring MVC
* JaxRS
@@ -8,7 +142,7 @@
Spring MVC和JaxRS适合REST接口开发。 POJO是通常说的RPC，适合于进行内部接口开发。java-chassis允许在一个微服务里面混合使用上述开发方式，并且可以使用完全一致的方式，比如RestTemplate或者POJO的方式访问不同类型的服务，所以开始之前，可以根据熟悉程度，选择任意一种开发方式即可。java-chassis的开发方式和通信方式是完全解耦的，因此不同的开发方式并没有性能上的差异。
-开发者可以通过如下方式快速构建一个项目：
+开发者也可以通过如下方式快速构建一个项目：
* 下载samples项目。java-chassis提供了大量的示例代码，这些示例代码可以通过[servicecomb-samples](https://github.com/apache/servicecomb-samples)获取。
@@ -22,4 +156,4 @@ Spring MVC和JaxRS适合REST接口开发。 POJO是通常说的RPC，适合于
* 使用脚手架生成项目
- 脚手架提供了一个图形化向导，通过向导可以快速构建项目，参考[链接](http://start.servicecomb.io/)。
\ No newline at end of file
+ 脚手架提供了一个图形化向导，通过向导可以快速构建项目，参考[链接](http://start.servicecomb.io/)。