[SCB-2076] add documents for service definition (#199)

diff --git a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
index 16ea73b..532b411 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
@@ -1,6 +1,5 @@
 # 开发服务提供者
 
-* [微服务定义](definition/service-definition.md)
 * [理解服务契约](define-contract.md)
 * [用JAX-RS开发微服务](jaxrs.md)
 * [用SpringMVC开发微服务](springmvc.md)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md b/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md
index ebd90e5..6ac5114 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md
@@ -12,46 +12,73 @@
 
   servicecomb 的实例信息在类 `MicroserviceInstance` 中定义。 它主要包含网络地址(endpoints) 信息。
 
+微服务的定义会用于微服务管理、微服务的发现、治理等多种场景。专题文章[微服务实例间多环境隔离](../../general-development/multienvironment.md)介绍
+了微服务定义的一些常见应用场景。
+
 # 场景描述
 
 开发一个微服务,需要在 `microservice.yaml` 文件中配置微服务的基本信息。 如果使用 spring boot,也可以在
-`application.yml` 文件中配置微服务的基本信息。 
+`application.yml` 文件中配置微服务的基本信息。 `microservice.yaml` 文件在项目中的存放路径为 `src\main\resources\microservice.yaml`。
+微服务信息和实例信息属于基础元数据信息, 只能够在配置文件指定,无法通过配置中心指定。
 
-`microservice.yaml` 文件在项目中的存放路径为 `src\main\resources\microservice.yaml`。
+***表1-1 微服务信息配置项说明***
 
-表1-1配置项说明
-
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| APPLICATION\_ID | - | - | 是 | 应用名 | - |
-| service\_description.name | - | - | 是 | 微服务名 | 应确保app内部唯一。微服务名支持数字、大小写字母和"-"、"\_"、"."三个特殊字符,但是不能以特殊字符作为首尾字符,命名规范为:^\[a-zA-Z0-9\]+$|^\[a-zA-Z0-9\]\[a-zA-Z0-9\_-.\]\*\[a-zA-Z0-9\]$。 |
-| service\_description.version | - | - | 是 | 微服务版本号 | - |
-| service\_description.description | - | - | 否 | 微服务描述 |  |
-| service\_description.properties | - | - | 否 | 微服务元数据配置(通过microservice.yaml文件进行配置) | - |
-| service\_description.propertyExtendedClass | - | - | 否 | 微服务元数据配置(通过实现接口PropertyExtended进行配置) | 接口返回的配置会覆盖配置文件中key相同的配置。 |
-| instance\_description.properties | - | - | 否 | 服务实例元数据配置(通过microservice.yaml文件进行配置) |  |
-| instance\_description.propertyExtendedClass | - | - | 否 | 微服务元数据配置(通过实现接口PropertyExtended进行配置) | 同service\_description.propertyExtendedClass |
+| 配置项 | 版本 | 默认值 | 是否必选 | 含义 |
+| :--- | :--- | :--- | :--- | :--- |
+| servicecomb.service.application | 2.1.2 | default | 是 | 应用名 |
+| servicecomb.service.name | 2.1.2 | defaultMicroservice | 是 | 微服务名, 应确保应用内部唯一。微服务名支持数字、大小写字母和"-"、"\_"、"."三个特殊字符,但是不能以特殊字符作为首尾字符,命名规范为:^\[a-zA-Z0-9\]+$|^\[a-zA-Z0-9\]\[a-zA-Z0-9\_-.\]\*\[a-zA-Z0-9\]$。 |
+| servicecomb.service.version | 2.1.2 | 1.0.0.0 | 是 | 微服务版本号 |
+| servicecomb.service.role | 2.1.2 | FRONT | 否 | 服务类型 |
+| servicecomb.service.description | 2.1.2+| - | 否 | 微服务描述 |
+| ervicecomb.service.environment | 2.1.2 | - | 否 | 运行环境,比如 development, production 等 |
+| servicecomb.service.propertyExtendedClass | 2.1.2 | - | 否 | 微服务元数据配置扩展信息, 接口返回的配置会覆盖配置文件中key相同的配置。|
+| servicecomb.service.properties | 2.1.2 | - | 否 | 服务实例元数据配置(通过microservice.yaml文件进行配置)|
+| servicecomb.service.paths | 2.1.2 | - | 否 | URL 前缀列表 |
+| APPLICATION_ID | 2.1.2之前 | default | 是 | 应用名 |
+| service_description.name | 2.1.2之前 | defaultMicroservice | 是 | 微服务名, 应确保应用内部唯一。微服务名支持数字、大小写字母和"-"、"\_"、"."三个特殊字符,但是不能以特殊字符作为首尾字符,命名规范为:^\[a-zA-Z0-9\]+$|^\[a-zA-Z0-9\]\[a-zA-Z0-9\_-.\]\*\[a-zA-Z0-9\]$。 |
+| service_description.version | 2.1.2之前 | 1.0.0.0 | 是 | 微服务版本号 |
+| service_description.role | 2.1.2之前 | FRONT | 否 | 服务类型 |
+| service_description.description | 2.1.2之前 | - | 否 | 微服务描述 |
+| service_description.environment | 2.1.2之前 | - | 否 | 运行环境,比如 development, production 等 |
+| service_description.propertyExtendedClass | 2.1.2之前 | - | 否 | 微服务元数据配置扩展信息, 接口返回的配置会覆盖配置文件中key相同的配置。|
+| service_description.properties | 2.1.2之前 | - | 否 | 服务元数据配置|
+| service_description.paths | 2.1.2之前 | - | 否 | URL 前缀列表 |
 
 > 说明:
 >
 > * 服务的元数据会随服务一同注册到服务中心,如需修改,则要连同服务version一起变更。若想保持服务version不变,则需要通过服务管理中心统一变更元数据。
-> * 虽然微服务名、契约名中可以使用"."字符,但是不推荐在命名中使用"."。这是由于ServiceComb使用的配置文件是yaml格式的,"."符号用于分割配置项名称,如果微服务名、契约名中也包含了"."可能会导致一些支持微服务、契约级别的配置无法正确被识别。
+> * 虽然微服务名、契约名中可以使用"."字符,但是不推荐在命名中使用"."。这是由于ServiceComb使用的配置文件是yaml格式的,"."符号用于分割配置项名称,
+     如果微服务名、契约名中也包含了"."可能会导致一些支持微服务、契约级别的配置无法正确被识别。
 
-下面是一个微服务信息的配置示例:
+***表1-2 微服务实例信息配置项说明***
+
+| 配置项 | 版本 | 默认值 | 是否必选 | 含义 |
+| :--- | :--- | :--- | :--- | :--- |
+| servicecomb.instance.properties | 2.1.2 | - | 否 | 服务实例云数据配置 |
+| servicecomb.instance.propertyExtendedClass | 2.1.2 | - | 否 | 微服务实例元数据配置扩展信息, 接口返回的配置会覆盖配置文件中key相同的配置。| |
+| servicecomb.instance.initialStatus | 2.1.2 | UP | 否 | 实例初始状态 |
+| servicecomb.instance.properties.tags | 2.1.2 | - | 否 | 标签 |
+| instance_description.properties | 2.1.2之前 | - | 否 | 服务实例云数据配置 |
+| instance_description.propertyExtendedClass | 2.1.2之前 | - | 否 | 微服务实例元数据配置扩展信息, 接口返回的配置会覆盖配置文件中key相同的配置。| |
+| instance_description.initialStatus | 2.1.2之前 | UP | 否 | 实例初始状态 |
+| instance_description.properties.tags | 2.1.2之前 | - | 否 | 标签 |
+
+下面是一个配置示例:
 
 ```yaml
-APPLICATION_ID: helloTest # 应用名
-service_description: # 服务描述
-  name: helloServer # 微服务名称
-  version: 0.0.1 # 服务版本号
-  properties: # 元数据
-    key1: value1
-    key2: value2
-  description: This is a description about the microservice # 微服务描述
-  propertyExtentedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
-instance_description: #实例描述
-  properties: #元数据
-    key3: value3
-  propertyExtentedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
+servicecomb:
+  service:
+    application: helloTest # 应用名
+    name: helloServer # 微服务名称
+    version: 0.0.1 # 服务版本号
+    properties: # 元数据
+      key1: value1
+      key2: value2
+    description: This is a description about the microservice # 微服务描述
+  instance:
+    properties: #元数据
+      key3: value3
+    propertyExtentedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
 ```
 
+
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
index 1745527..46e347a 100644
--- a/java-chassis-reference/zh_CN/docs/toc.md
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -15,8 +15,8 @@
     * [Java Chassis 微服务应用架构](start/design.md#h3)
     * [Java Chassis 微服务技术选型](start/design.md#h4)
     * [Java Chassis 与 Spring Cloud](start/design.md#h5)
+* [微服务定义](build-provider/definition/service-definition.md)
 * [开发服务提供者](build-provider/catalog.md)
-    * [微服务定义](build-provider/definition/service-definition.md)
     * [理解服务契约](build-provider/define-contract.md)
     * [用JAX-RS开发微服务](build-provider/jaxrs.md)
     * [用SpringMVC开发微服务](build-provider/springmvc.md)
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index 77d0b87..10c7cba 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -6,6 +6,7 @@
 - 概述 : index.md
 - 快速入门: start/catalog.md
 - 设计选型参考: start/design.md
+- 微服务定义: build-provider/definition/service-definition.md
 - 开发服务提供者: build-provider/catalog.md
 - 开发服务消费者: build-consumer/catalog.md
 - 通用功能开发: general-development/catalog.md