liubao68 closed pull request #22: Update local develop
URL: https://github.com/apache/incubator-servicecomb-docs/pull/22
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/.gitignore b/.gitignore
new file mode 100644
index 0000000..a09c56d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/.idea
diff --git a/java-chassis-reference/zh_CN/build-provider/define-contract.md
b/java-chassis-reference/zh_CN/build-provider/define-contract.md
index 31efa97..e653c7e 100644
--- a/java-chassis-reference/zh_CN/build-provider/define-contract.md
+++ b/java-chassis-reference/zh_CN/build-provider/define-contract.md
@@ -1,8 +1,17 @@
# 定义服务契约
-
+``
## 概念阐述
-服务契约，指基于OpenAPI规范的微服务接口契约，是服务端与消费端对于接口的定义。java
chassis提供了两种方式定义契约：显示和隐式。显示契约用于开发者使用RPC方式开发代码，然后期望内部程序客户端使用RPC方式访问，同时期望浏览器、手机终端等通过HTTP访问后台接口场景，显示契约需要开发者在yaml文件中描述接口的访问方式。隐式契约中的契约完全由框架根据默认规则（对于RPC方式）或者Annotation（Spring
MVC和JAX RS方式）来生成运行时的契约，不需要准备单独的yaml文件。
+服务契约，指基于OpenAPI规范的微服务接口契约，是服务端与消费端对于接口的定义。java chassis提供了两种方式定义契约：code
first和contract first。
+* code first
+
+producer使用Jax-RS或SpringMVC的RESTful
annotation声明接口的输入、输出参数，或者再配合OpenAPI的annotation，增加人类可读的信息，比如样例代码、文本描述等等；ServiceComb引擎启动时，根据这些annotation生成契约描述，并自动上传到服务中心。producer也可以使用透明RPC方式开发，但是因为没有任何RESTful的annotation指导如何生成契约，所以此时自动生成的契约非常的不RESTful化，不建议使用。
+consumer使用透明RPC或RestTemplate进行调用。
+code first的开发模式下，开发人员，不必手写契约。
+
+* contract first
+
+此场景下，不使用框架自动生成的契约，而是直接使用开发人员提供的契约文件，这需要由开发人员保证契约与代码的一致性。
## 场景描述
@@ -95,7 +104,10 @@ definitions:
> **注意**：
>
-> * 根据swagger标准，basePath配置的路径需要包括web server的webroot。
+> * ServiceComb中的契约，建议basePath不要包含web container的web root，以及servlet的url pattern。
+
+因为ServiceComb支持部署解耦，既可以脱离servlet container独立部署，也可使用war的方式部署到servlet
container中，还可以使用embedded servlet container的方式运行。
+只要base path不包含web root以及url pattern，则部署方式修改导致的实际url变更，ServiceComb
consumer业务代码并不需要感知，框架会自动适配。
> * info.x-java-interface需要标明具体的接口路径，根据项目实际情况而定。
> *
> SchemaId中可以包含"."字符，但不推荐这样命名。这是由于ServiceComb使用的配置文件是yaml格式的，"."符号用于分割配置项名称，如果SchemaId中也包含了"."可能会导致一些支持契约级别的配置无法正确被识别。
> * OperationId的命名中不可包含"."字符。
diff --git
a/java-chassis-reference/zh_CN/general-development/local-develop-test.md
b/java-chassis-reference/zh_CN/general-development/local-develop-test.md
index 5f368cf..e38f946 100644
--- a/java-chassis-reference/zh_CN/general-development/local-develop-test.md
+++ b/java-chassis-reference/zh_CN/general-development/local-develop-test.md
@@ -40,13 +40,11 @@
```
注意：前端（frontend）在Linux环境下默认会绑定ipv6地址，导致浏览器报错，修复办法为：先修改conf/app.conf中的httpaddr为外部可达网卡ip，之后修改app/appList/apiList.js中`ip
: 'http://127.0.0.1'`为对应ip，最后重启ServiceCenter即可。
- {: .notice--warning}
</div>
</div>
注意：Window和Linux版本均只支持64位系统。
- {: .notice--warning}
2. 以Docker的方式运行
@@ -59,11 +57,11 @@ docker run -d -p 30100:30100
servicecomb/service-center:latest
```yaml
servicecomb:
- service:
- registry:
- address:
-http://127.0.0.1:30100
- #服务中心地址及端口
+ service:
+ registry:
+ address:
+ # 服务中心地址及端口
+ http://127.0.0.1:30100
```
* **步骤 3 **开发服务提供/消费者，启动微服务进行本地测试。
@@ -71,35 +69,44 @@ http://127.0.0.1:30100
**----结束**
## Mock机制启动服务中心
+在本进程内存中模拟一个只能本进程使用的服务中心，一般是在测试场景中使用。
+* ### 进程内调用
+只需要在启动ServiceComb引擎之前声明一下即可启用：
+```java
+System.setProperty("local.registry.file", "notExistJustForceLocal");
+```
+* ### 跨进程调用
+如果部署比较简单，并且部署信息是静态的，即使有跨进程调用也可以使用本Mock机制
+producer端仍然像“进程内调用”一样声明即可
+但是，因为Mock并不能跨进程生效，所以consumer端的Mock，需要提供一个本地的配置文件，在里面描述调用目标的详细信息，包括名字、版本、地址、schema
id等等信息
+同样，因为Mock不能跨进程，consumer也无法动态取得producer的契约信息，所以，需要在本地提供契约文件
+（这个场景，使用Mock服务中心，比使用standalone的服务中心，成本高得多得多，不建议使用）
-* **步骤 1**新建本地服务中心定义文件registry.yaml，内容如下：
+* **步骤 1**新建本地服务中心定义文件，假设名字为registry.yaml，内容示例如下：
```yaml
-springmvctest:
- - id: "001"
- version: "1.0"
- appid: myapp #调试的服务id
- instances:
- - endpoints:
- - rest://127.0.0.1:8080
+localserv:
+ - id: "100"
+ version: "0.0.1"
+ appid: localservreg
+ schemaIds:
+ - hello
+ instances:
+ - endpoints:
+ - rest://localhost:8080
+ - highway://localhost:7070
```
+* **步骤 2**consumer本地部署契约文件
-#### 注意：mock机制需要自己准备契约，并且当前只支持在本地进行服务消费端\(consumer\)侧的调试，不支持服务提供者\(provider\)
-
-* **步骤 2**在服务消费者Main函数首末添加如下代码：
+参考：[定义服务契约](https://huaweicse.github.io/servicecomb-java-chassis-doc/zh_CN/build-provider/define-contract.html)
+* **步骤 3**在consumer main函数，启动ServiceComb引擎之前声明：
```java
-public class xxxClient {
-public static void main(String[] args) {
System.setProperty("local.registry.file", "/path/registry.yaml");
- // your code
- System.clearProperty("local.registry.file");
-}
```
setProperty第二个参数填写registry.yaml在磁盘中的系统绝对路径，注意区分在不同系统下使用对应的路径分隔符。
-* **步骤 3**开发服务消费者，启动微服务进行本地测试。
## 通过设置环境信息方便本地调试
java
chassis在设计时，严格依赖于契约，所以正常来说契约变了就必须要修改微服务的版本。但是如果当前还是开发模式，那么修改接口是很正常的情况，每次都需要改版本的话，对用户来说非常的不友好，所以增加了一个环境设置。如果微服务配置成开发环境，接口修改了（schema发生了变化），重启就可以注册到服务中心，而不用修改版本号。但是如果有consumer已经调用了重启之前的服务，那么consumer端需要重启才能获取最新的schema。比如A
->
B，B接口进行了修改并且重启，那么A这个时候还是使用B老的schema，调用可能会出错，以免出现未知异常，A也需要重启。有三种方式可以设置，推荐使用方法1
----------------------------------------------------------------
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:
[email protected]
With regards,
Apache Git Services
