liubao68 closed pull request #6: 增加POJO定义注意事项的说明
URL: https://github.com/apache/incubator-servicecomb-docs/pull/6
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/java-chassis-reference/zh_CN/SUMMARY.md
b/java-chassis-reference/zh_CN/SUMMARY.md
index e95a145..d914e87 100644
--- a/java-chassis-reference/zh_CN/SUMMARY.md
+++ b/java-chassis-reference/zh_CN/SUMMARY.md
@@ -14,8 +14,8 @@
* [用SpringMVC开发微服务](build-provider/springmvc.md)
* [用JAX-RS开发微服务](build-provider/jaxrs.md)
* [用透明RPC开发微服务](build-provider/transparent-rpc.md)
+ * [接口定义和数据类型](build-provider/interface-constraints.md)
* [服务监听地址和发布地址](build-provider/listen-address-and-publish-address.md)
- * [支持的数据类型](build-provider/interface-constraints.md)
* [服务配置](build-provider/service-configuration.md)
* [负载均衡策略](build-provider/configuration/lb-strategy.md)
* [限流策略](build-provider/configuration/ratelimite-strategy.md)
diff --git
a/java-chassis-reference/zh_CN/build-provider/interface-constraints.md
b/java-chassis-reference/zh_CN/build-provider/interface-constraints.md
index f260af3..a6b4a43 100644
--- a/java-chassis-reference/zh_CN/build-provider/interface-constraints.md
+++ b/java-chassis-reference/zh_CN/build-provider/interface-constraints.md
@@ -1,6 +1,8 @@
-## 接口约束说明
+# 接口定义和数据类型
-ServiceComb-Java-Chassis对于接口的使用约束建立在一个简单的原则上：接口定义即接口使用说明，不用通过查看代码实现，就能识别如何调用这个接口。可以看出，我们是站在使用者这边的，以更容易被使用作为参考。这个原则，不同的开发者的理解也是有差异的。
+## 接口定义的要求
+
+ServiceComb-Java-Chassis对于接口定义的要求建立在一个简单的原则上：接口定义即接口使用说明，不用通过查看代码实现，就能识别如何调用这个接口。可以看出，我们是站在使用者这边的，以更容易被使用作为参考。
举个例子：
@@ -31,7 +33,7 @@ ResponseType methodName(RequestType...)
不能定义异常、不能包含在接口原型未声明的错误码和输出（如果没声明错误码，缺省的错误码除外，比如HTTP 的200）。
-通常，系统约束越多，那么就更加容易对系统进行统一的管控和治理；开发方式越自由，实现业务功能则更加快速。需要在这两方面取得一些平衡。ServiceComb-Java-Chassis是比gRPC要灵活的多的框架，同时也去掉了Spring
MVC的一些不常用的扩展。开发者可以在ServiceComb-Java-Chassis讨论区反馈开发过程中期望支持的场景，更好的维护这个平衡。期望这个讨论是围绕某个具体的应用场景来进行的，比如上传文件如何更好的进行，而不是具体的开发方式进行的，比如使用Object来传递参数。
+通常，系统约束越多，那么就更加容易对系统进行统一的管控和治理；开发方式越自由，实现业务功能则更加快速，需要在这两方面取得一些平衡。ServiceComb-Java-Chassis是比gRPC要灵活很多的框架，同时也去掉了Spring
MVC的一些不常用的扩展。开发者可以在ServiceComb-Java-Chassis讨论区反馈开发过程中期望支持的场景，更好的维护这个平衡。期望这个讨论是围绕某个具体的应用场景来进行的，比如上传文件如何更好的进行，而不是具体的开发方式进行的，比如使用Object来传递参数。
## 详细的约束列表
@@ -58,6 +60,45 @@ ResponseType methodName(RequestType...)
总之，数据结构需要能够使用简单的数据类型进行描述，一目了然就是最好的。这个在不同的语言，不同的协议里面都支持的很好，长期来看，可以大大减少开发者联调沟通和后期重构的成本。
+### 关于数据结构和接口变更
+接口名称、参数类型、参数顺序、返回值类型变更都属于接口变更。ServiceComb启动的时候，会根据版本号检测接口变化，接口变化要求修改版本号。ServiceComb识别接口是否变化是通过代码生成的契约内容，有些不规范的接口定义可能导致在代码没有变化的情况下，生成的契约不同。比如：
+
+```
+public void get(Person p)
+class Person {
+ private String value;
+ private boolean isOk;
+ public String getName() {return value}
+ public boolean isOk() {return isOK}
+}
+```
+
+这个接口通过access
method定义了"name"和"ok"两个属性，和实际的字段"value"和"isOk"不同。这种情况可能导致每次启动生成的契约不一样。需要将代码调整为符合JAVA
Bean规范的定义。
+```
+public void get(Person p)
+class Person {
+ private String name;
+ private boolean ok;
+ public String getName() {return name}
+ public boolean isOk() {return ok}
+}
+```
+
+或者通过JSON标注，显示的指明字段顺序。比如：
+
+```
+public void get(Person p)
+@JsonPropertyOrder({"name", "ok"})
+class Person {
+ private String value;
+ private boolean isOk;
+ public String getName() {return value}
+ public boolean isOk() {return isOK}
+}
+```
+
+考虑到接口变更的影响，建议在进行对外接口定义的时候，尽可能不要使用第三方软件提供的类作为接口参数，而是使用自定义的POJO类。一方面升级三方件的时候，可能感知不到接口变化；另外一方面，如果出现问题，无法通过修改第三方代码进行规避。比如：java.lang.Timestamp,
org.joda.time.JodaTime等。
+
## 协议上的差异
尽管ServiceComb-Java-Chassis实现了不同协议之间开发方式的透明，受限于底层协议的限制，不同的协议存在少量差异。
----------------------------------------------------------------
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
