You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by ma...@apache.org on 2019/08/08 01:29:49 UTC
[servicecomb-samples] 10/43: 项目升级到1.2.0，并且增加相关的说明
This is an automated email from the ASF dual-hosted git repository.
mabin pushed a commit to branch houserush-sample
in repository https://gitbox.apache.org/repos/asf/servicecomb-samples.git
commit 9c9b18d326223868083b5eae15810703824773e1
Author: liubao <ba...@huawei.com>
AuthorDate: Fri Apr 12 12:01:36 2019 +0800
项目升级到1.2.0，并且增加相关的说明
---
README.md | 14 +++-
dependency_management/README.md | 19 ++++++
dependency_management/spring4/pom.xml | 4 +-
dependency_management/spring5/pom.xml | 4 +-
dependency_management/springboot1/pom.xml | 10 ++-
dependency_management/springboot2/pom.xml | 3 +-
porter_lightweight/README.md | 109 ++++++++++++++++++++++++++++++
porter_lightweight/pom.xml | 2 +-
8 files changed, 155 insertions(+), 10 deletions(-)
diff --git a/README.md b/README.md
index 0c15baf..c1d8c06 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,17 @@
-# servicecomb samples
+# ServiceComb samples
## porter_lightweight
A sample shows an application with basic login, download file, delete file functions.
## dependency_management
-A sample shows how to use dependency management to create spring 4, spring 5, spring boot 1 or spring boot 2 application.
\ No newline at end of file
+A sample shows how to use dependency management to create spring 4, spring 5, spring boot 1 or spring boot 2 application.
+
+
+# 使用ServiceComb开发微服务的示例项目
+
+## porter_lightweight
+该项目演示了一个包括网关、文件下载、认证鉴权等功能的简单应用系统，同时演示了ServiceComb推荐的先写接口声明，再写业务代码的软件工程实践。
+
+## dependency_management
+该项目演示了ServiceComb如何依赖spring4, spring 5, spring boot1 和 spring boot 2。
+
diff --git a/dependency_management/README.md b/dependency_management/README.md
new file mode 100644
index 0000000..6caac86
--- /dev/null
+++ b/dependency_management/README.md
@@ -0,0 +1,19 @@
+## dependency_management
+
+A sample shows how to use dependency management to create spring 4, spring 5, spring boot 1 or spring boot 2 application.
+
+Compile each project and run with IDE or command line. Each servcie provide a simple REST api. This api can be access using
+```
+http://localhost:9090/hello?name=jack
+```
+
+# dependency_management
+
+该项目演示了ServiceComb如何依赖spring4, spring 5, spring boot1 和 spring boot 2。
+
+启动项目后，可以通过：
+```
+http://localhost:9090/hello?name=jack
+```
+
+来访问微服务。
diff --git a/dependency_management/spring4/pom.xml b/dependency_management/spring4/pom.xml
index 9ee8710..cd5e946 100644
--- a/dependency_management/spring4/pom.xml
+++ b/dependency_management/spring4/pom.xml
@@ -29,11 +29,10 @@
<dependencyManagement>
<dependencies>
- <!-- need to compile lastest java-chassis code -->
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-dependencies-spring4</artifactId>
- <version>1.2.0-SNAPSHOT</version>
+ <version>1.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -52,6 +51,7 @@
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
+ <version>1.5.14.RELEASE</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
diff --git a/dependency_management/spring5/pom.xml b/dependency_management/spring5/pom.xml
index 375c070..343b60f 100644
--- a/dependency_management/spring5/pom.xml
+++ b/dependency_management/spring5/pom.xml
@@ -29,11 +29,10 @@
<dependencyManagement>
<dependencies>
- <!-- need to compile lastest java-chassis code -->
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-dependencies-spring5</artifactId>
- <version>1.2.0-SNAPSHOT</version>
+ <version>1.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -52,6 +51,7 @@
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
+ <version>2.1.2.RELEASE</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
diff --git a/dependency_management/springboot1/pom.xml b/dependency_management/springboot1/pom.xml
index da6b1a7..417164c 100644
--- a/dependency_management/springboot1/pom.xml
+++ b/dependency_management/springboot1/pom.xml
@@ -29,14 +29,19 @@
<dependencyManagement>
<dependencies>
- <!-- need to compile lastest java-chassis code -->
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-dependencies-springboot1</artifactId>
- <version>1.2.0-SNAPSHOT</version>
+ <version>1.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
+ <!-- spring boot 1.5.14.RELEASE use a low version of validation-api, must override it -->
+ <dependency>
+ <groupId>javax.validation</groupId>
+ <artifactId>validation-api</artifactId>
+ <version>2.0.0.Final</version>
+ </dependency>
</dependencies>
</dependencyManagement>
@@ -66,6 +71,7 @@
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
+ <version>1.5.14.RELEASE</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
diff --git a/dependency_management/springboot2/pom.xml b/dependency_management/springboot2/pom.xml
index 8cb3bd9..215afd9 100644
--- a/dependency_management/springboot2/pom.xml
+++ b/dependency_management/springboot2/pom.xml
@@ -33,7 +33,7 @@
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-dependencies-springboot2</artifactId>
- <version>1.2.0-SNAPSHOT</version>
+ <version>1.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -62,6 +62,7 @@
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
+ <version>2.1.2.RELEASE</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
diff --git a/porter_lightweight/README.md b/porter_lightweight/README.md
index 9870398..93d7bd5 100644
--- a/porter_lightweight/README.md
+++ b/porter_lightweight/README.md
@@ -79,4 +79,113 @@ java $JAVA_OPT -Dgateway.webroot=webapp -jar porter-gateway-service-0.0.1-SNAPSH
2. 选择一个文件上传，上传成功，上传成功后的文件会保存在file-service的当前目录， 文件名称是一个随机的数字，这个数字就是文件ID。
3. 删除文件：输入上一步的文件ID，点击删除。 如果是admin用户，上传成功；如果是guest用户，上传失败。
+# 接口使用说明
+ServiceComb推荐先定义接口，再定义实现的开发模式。将接口定义为一个独立项目，可以由设计者统一管控，对于接口的修改，需要设计者进行审核。先定义接口还可以让开发者培养良好的开发习惯，避免将对外接口采用内部实现数据结构（比如JsonObject）、运行平台有关的数据结构（比如HttpServletResponse）来定义，使得以后将项目改在为其他技术框架变得复杂。采用这种方式组织的项目，用户很容易在不同的开发框架上进行迁移，比如gRPC、Spring Cloud等。这里的接口定义代码，对于这些运行框架都是通用的，并且具备跨平台特性。
+## 对于接口实现者(provider)
+ * 依赖api对应的jar包
+
+```
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.servicecomb.samples.porter</groupId>
+ <artifactId>user-service-api-endpoint</artifactId>
+ </dependency>
+ </dependencies>
+```
+
+ * 实现Service接口
+```
+@Service
+public class UserServiceImpl implements UserService
+```
+
+## 对于接口使用者(consumer)
+ * 依赖service对应的jar包（只包含model和接口）
+
+```
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.servicecomb.samples.porter</groupId>
+ <artifactId>user-service-api-service</artifactId>
+ </dependency>
+ </dependencies>
+```
+
+ * 采用RCP方式调用
+```
+ @RpcReference(microserviceName = "user-service", schemaId = "user")
+ private static UserService sserService
+```
+
+# REST接口常见争议问题和处理
+
+## 查询接口参数很复杂
+
+比如：
+
+```
+public List<Goods> queryGoodsByTags(String orgId, List<GoodsTag> tags)
+```
+
+当查询参数很复杂的时候，不建议采用query参数或者path参数。主要有如下原因：
+
+* HTTP对于URL的长度有限制
+* 复杂参数可能包含特殊字符，需要客户端在拼接URL的时候，进行URL转码，客户端开发者通常会遗漏。
+* 对象无法和query参数进行合理的映射。
+* query参数或者path参数会被proxy、web server等记录到日志里面，导致日志过大，或者造成敏感信息泄露。
+
+对于复杂的查询操作，建议使用POST方法，相关复杂参数都封装为body。比如：
+
+```
+@PostMapping(path = "queryGoodsByTags")
+public List<Goods> queryGoodsByTags(@RequestParam(name = "orgId") String orgId, @RequestBody List<GoodsTag> tags)
+```
+
+一般的，通过query传递参数的场景，尽可能要保证参数个数少，参数类型为基础类型（字符串、数字等）。参数比较多的场景采用POST来传参。
+
+本项目的处理原则是“尽可能遵循HTTP REST语义，但是不盲目，以系统可靠优先”。
+
+对于DELETE请求，也有类似的情况。在设计GET和DELETE方法时，建议都不使用body参数，尽管HTTP协议并没有强制要求不能使用body，但是由于历史因素，很多WEB服务器支持上会有问题，接口设计应该尽可能避免不必要的麻烦和陷阱。只在POST、PUT、PATCH方法中使用body参数。
+
+## REST接口的Path是否包含操作
+
+比如：下面的接口定义path是否包含deleteGoodsUnitConvertor。
+
+```
+ @DeleteMapping(path = "deleteGoodsUnitConvertor")
+ public ResponseBase deleteGoodsUnitConvertor(String goodsUnitConvertorId)
+```
+
+由于HTTP的方法POST/PUT/PATCH/GET/DELETE已经包含了增、改、查、删语义，path里面包含delete显得多余。不过由于项目的接口通常比较多，过多的思考接口语义反而增加了理解的难度。所以本项目path全部都包含了方法名字。包含名称有个好处，可以从URL中看出operation id，从而很简单的将URL和契约对应起来，方便查找。此外就是上面提到的原因，并不是所有的删除操作都一定对应于DELETE操作，出于系统可靠性、安全等方面考虑，可能使用POST/PATCH等代表查询或者删除操作。
+
+## 多个对象参数
+
+由于HTTP只能有一个body，所有多个对象参数需要包装为一个参数。 比如：
+
+```
+public ResponseBase inboundOrder(InboundOrder inboundOrder, Set<InboundOrderItem> inboundOrderItems)
+```
+
+封装为下面的REST接口定义：
+
+```
+ @PostMapping(path = "inboundOrder")
+ public ResponseBase inboundOrder(@RequestBody InboundOrderRequest inboundOrderRequest) {
+ return stockService.inboundOrder(inboundOrderRequest.getInboundOrder(), inboundOrderRequest.getInboundOrderItems());
+ }
+```
+
+## 敏感信息不能采用query参数
+
+Query参数可能被各种proxy、web server记录，因此对于用户敏感信息，不能使用query参数。 比如：
+
+```
+public ResponseBase rechargePrepaidCard(String cardId, double amount)
+```
+
+涉及到卡号和金额的数据，需要采用POST提交，参数存储在body。 虽然有些接口仅仅只是查询， 但也可能被设计为POST。 调整后的接口：
+
+```
+public ResponseBase rechargePrepaidCard(@RequestBody PrepaidAmountRequest prepaidAmountRequest)
+```
diff --git a/porter_lightweight/pom.xml b/porter_lightweight/pom.xml
index f891518..08a5500 100644
--- a/porter_lightweight/pom.xml
+++ b/porter_lightweight/pom.xml
@@ -50,7 +50,7 @@
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-dependencies</artifactId>
- <version>1.2.0-SNAPSHOT</version>
+ <version>1.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>