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 dc3424f [SCB-2076] add documents for service definition (#199)
dc3424f is described below
commit dc3424f0e002a640fa5031be58ac95d889fa2d69
Author: bao liu <[email protected]>
AuthorDate: Tue Oct 27 17:40:11 2020 +0800
[SCB-2076] add documents for service definition (#199)
---
.../zh_CN/docs/build-provider/catalog.md | 1 -
.../definition/service-definition.md | 85 ++++++++++++++--------
java-chassis-reference/zh_CN/docs/toc.md | 2 +-
java-chassis-reference/zh_CN/mkdocs.yml | 1 +
4 files changed, 58 insertions(+), 31 deletions(-)
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 微服务定义包括两个基础模型 `Microservice` 和 `Microser
servicecomb 的实例信息在类 `MicroserviceInstance` 中定义。 它主要包含网络地址(endpoints) 信息。
+微服务的定义会用于微服务管理、微服务的发现、治理等多种场景。专题文章[微服务实例间多环境隔离](../../general-development/multienvironment.md)介绍
+了微服务定义的一些常见应用场景。
+
# 场景描述
开发一个微服务，需要在 `microservice.yaml` 文件中配置微服务的基本信息。 如果使用 spring boot，也可以在
-`application.yml` 文件中配置微服务的基本信息。
-
-`microservice.yaml` 文件在项目中的存放路径为 `src\main\resources\microservice.yaml`。
+`application.yml` 文件中配置微服务的基本信息。 `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 @@ nav:
- 概述 : 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
