You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2021/02/26 03:44:32 UTC
[servicecomb-docs] branch master updated: [SCB-2195]show multi
error code and response type (#226)
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 319adc9 [SCB-2195]show multi error code and response type (#226)
319adc9 is described below
commit 319adc95a71825468a177355c7cfef4baf439149
Author: bao liu <bi...@qq.com>
AuthorDate: Fri Feb 26 11:44:27 2021 +0800
[SCB-2195]show multi error code and response type (#226)
---
.../zh_CN/docs/build-consumer/catalog.md | 2 -
.../zh_CN/docs/build-provider/catalog.md | 1 +
.../zh_CN/docs/build-provider/multi-code.md | 129 +++++++++++++++++++++
.../fault-injection.md | 4 +-
java-chassis-reference/zh_CN/docs/toc.md | 4 +-
java-chassis-reference/zh_CN/mkdocs.yml | 1 +
6 files changed, 135 insertions(+), 6 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md b/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md
index eb043cf..9321518 100644
--- a/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md
+++ b/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md
@@ -6,6 +6,4 @@
* [使用RPC方式开发服务消费者](develop-consumer-using-rpc.md)
* [泛化调用](../featured-topics/features/invoker.md)
* [使用服务契约](with-contract.md)
-* 调用控制
- * [故障注入](fault-injection.md)
* [调用第三方REST服务](3rd-party-service-invoke.md)
\ No newline at end of file
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 3815ee5..b8b7bdc 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
@@ -6,6 +6,7 @@
* [用透明RPC开发微服务](transparent-rpc.md)
* [只发布interface的方法为服务接口](use-interface.md)
* [使用 Context 参数](context-param.md)
+* [多个返回值和错误码](multi-code.md)
* [使用Swagger注解](swagger-annotation.md)
* [接口定义和数据类型](interface-constraints.md)
* [服务监听地址和发布地址](listen-address-and-publish-address.md)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/multi-code.md b/java-chassis-reference/zh_CN/docs/build-provider/multi-code.md
new file mode 100644
index 0000000..0915357
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/build-provider/multi-code.md
@@ -0,0 +1,129 @@
+# 多个返回值和错误码
+
+使用透明RPC开发服务提供者，开发者很容易理解一个接口只有一个返回值类型。使用REST风格（Spring MVC 或者 JAXRS），很多场景会碰到
+多个返回值和错误码的情况。和很多其他开发框架（比如Servlet、Spring MVC等）不一样，Java Chassis要求接口定义的返回值和错误码都
+必须显示的声明，即通过代码生成的swagger，必须包含所有的错误码描述和返回值类型描述。 在Java Chassis，无法使用隐藏参数、未声明
+的错误码。这样设计的直接好处是接口定义更加明确，不需要额外的文档帮助使用者理解接口的使用方法。
+
+在前面的开发指导里面，主要介绍了一个返回值和一个错误码的情况（200）。 下面介绍如何使用多个错误码和返回值，同时会介绍如何返回额外的
+header参数。
+
+Java Chassis将错误码进行了分类：2xx错误码认为是一个正常的响应，一个接口只允许存在一个正常响应错误码；
+其他错误码认为是一个异常的响应，一个接口可以定义多个异常的响应，并且需要采用InvocationException的方式将异常抛出，每个错误码可以指定
+不同的响应类型。
+
+* 采用`ApiResponse`定义多个返回值和错误码
+
+```java
+@Path("/errorCode")
+@POST
+@ApiResponses({
+ @ApiResponse(code = 200, response = MultiResponse200.class, message = ""),
+ @ApiResponse(code = 400, response = MultiResponse400.class, message = ""),
+ @ApiResponse(code = 500, response = MultiResponse500.class, message = "")})
+public MultiResponse200 errorCode(MultiRequest request) {
+ if (request.getCode() == 400) {
+ MultiResponse400 r = new MultiResponse400();
+ r.setCode(400);
+ r.setMessage("bad request");
+ throw new InvocationException(javax.ws.rs.core.Response.Status.BAD_REQUEST, r);
+ } else if (request.getCode() == 500) {
+ MultiResponse500 r = new MultiResponse500();
+ r.setCode(500);
+ r.setMessage("internal error");
+ throw new InvocationException(javax.ws.rs.core.Response.Status.INTERNAL_SERVER_ERROR, r);
+ } else {
+ MultiResponse200 r = new MultiResponse200();
+ r.setCode(200);
+ r.setMessage("success result");
+ return r;
+ }
+}
+```
+
+* 采用 `org.apache.servicecomb.swagger.invocation.Response` 响应类型
+
+采用 `org.apache.servicecomb.swagger.invocation.Response` 响应类型，除了可以定义多个错误码和响应类型，还可以通过
+`ResponseHeader` 定义额外的响应头。
+
+```java
+@Path("/errorCode")
+@POST
+@ApiResponses({
+ @ApiResponse(code = 200, response = MultiResponse200.class, message = ""),
+ @ApiResponse(code = 400, response = MultiResponse400.class, message = ""),
+ @ApiResponse(code = 500, response = MultiResponse500.class, message = "")})
+@ResponseHeaders({@ResponseHeader(name = "x-code", response = String.class)})
+public Response errorCodeWithHeader(MultiRequest request) {
+ Response response = new Response();
+ if (request.getCode() == 400) {
+ MultiResponse400 r = new MultiResponse400();
+ r.setCode(400);
+ r.setMessage("bad request");
+ response.setStatus(Status.BAD_REQUEST);
+ response.setResult(new InvocationException(Status.BAD_REQUEST, r));
+ response.setHeader("x-code", "400");
+ } else if (request.getCode() == 500) {
+ MultiResponse500 r = new MultiResponse500();
+ r.setCode(500);
+ r.setMessage("internal error");
+ response.setStatus(Status.INTERNAL_SERVER_ERROR);
+ response.setResult(new InvocationException(Status.INTERNAL_SERVER_ERROR, r));
+ response.setHeader("x-code", "500");
+ } else {
+ MultiResponse200 r = new MultiResponse200();
+ r.setCode(200);
+ r.setMessage("success result");
+ response.setStatus(Status.OK);
+ response.setResult(r);
+ response.setHeader("x-code", "200");
+ }
+ return response;
+}
+```
+
+* 采用 `javax.ws.rs.core.Response` 响应类型
+
+采用 `javax.ws.rs.core.Response` 响应类型，除了可以定义多个错误码和响应类型，还可以通过
+`ResponseHeader` 定义额外的响应头。
+
+```java
+@Path("/errorCodeWithHeaderJAXRS")
+@POST
+@ApiResponses({
+ @ApiResponse(code = 200, response = MultiResponse200.class, message = ""),
+ @ApiResponse(code = 400, response = MultiResponse400.class, message = ""),
+ @ApiResponse(code = 500, response = MultiResponse500.class, message = "")})
+public javax.ws.rs.core.Response errorCodeWithHeaderJAXRS(MultiRequest request) {
+ javax.ws.rs.core.Response response;
+ if (request.getCode() == 400) {
+ MultiResponse400 r = new MultiResponse400();
+ r.setCode(request.getCode());
+ r.setMessage(request.getMessage());
+ response = javax.ws.rs.core.Response.status(Status.BAD_REQUEST)
+ .entity(new InvocationException(Status.BAD_REQUEST, r))
+ .header("x-code", "400")
+ .build();
+ } else if (request.getCode() == 500) {
+ MultiResponse500 r = new MultiResponse500();
+ r.setCode(request.getCode());
+ r.setMessage(request.getMessage());
+ response = javax.ws.rs.core.Response.status(Status.INTERNAL_SERVER_ERROR)
+ .entity(new InvocationException(Status.INTERNAL_SERVER_ERROR, r))
+ .header("x-code", "500")
+ .build();
+ } else {
+ MultiResponse200 r = new MultiResponse200();
+ r.setCode(request.getCode());
+ r.setMessage(request.getMessage());
+ // If error code is OK family(like 200), we can use the target type.
+ response = javax.ws.rs.core.Response.status(Status.OK)
+ .entity(r)
+ .header("x-code", "200")
+ .build();
+ }
+ return response;
+}
+```
+
+
diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/fault-injection.md b/java-chassis-reference/zh_CN/docs/references-handlers/fault-injection.md
similarity index 98%
rename from java-chassis-reference/zh_CN/docs/build-consumer/fault-injection.md
rename to java-chassis-reference/zh_CN/docs/references-handlers/fault-injection.md
index 7daf407..05fd332 100644
--- a/java-chassis-reference/zh_CN/docs/build-consumer/fault-injection.md
+++ b/java-chassis-reference/zh_CN/docs/references-handlers/fault-injection.md
@@ -1,10 +1,10 @@
-## 场景描述
+# 故障注入
用户在consumer端使用故障注入，可以设置发往指定微服务的请求的时延和错误及其触发概率。
## 注意事项
-延迟注入请求的延迟时间统一为毫秒级别
+延迟注入请求的延迟时间统一为毫秒。
## 配置说明
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
index 84e9188..d538447 100644
--- a/java-chassis-reference/zh_CN/docs/toc.md
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -23,6 +23,7 @@
* [用透明RPC开发微服务](build-provider/transparent-rpc.md)
* [只发布interface的方法为服务接口](build-provider/use-interface.md)
* [使用 Context 参数](build-provider/context-param.md)
+ * [多个返回值和错误码](build-provider/multi-code.md)
* [使用Swagger注解](build-provider/swagger-annotation.md)
* [接口定义和数据类型](build-provider/interface-constraints.md)
* [服务监听地址和发布地址](build-provider/listen-address-and-publish-address.md)
@@ -40,8 +41,6 @@
* [使用RPC方式开发服务消费者](build-consumer/develop-consumer-using-rpc.md)
* [泛化调用](featured-topics/features/invoker.md)
* [使用服务契约](build-consumer/with-contract.md)
- * 调用控制
- * [故障注入](build-consumer/fault-injection.md)
* [调用第三方REST服务](build-consumer/3rd-party-service-invoke.md)
* [通用功能开发](general-development/catalog.md)
* [应用性能监控（metrics）](general-development/metrics.md)
@@ -81,6 +80,7 @@
- [负载均衡](references-handlers/loadbalance.md)
- [限流](references-handlers/ratelimit.md)
- [路由管理](references-handlers/router.md)
+ - [故障注入](references-handlers/fault-injection.md)
- [隔离熔断容错](references-handlers/bizkeeper.md)
- [基于动态配置的流量特征治理](references-handlers/governance.md)
- 网关功能参考:
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index 0ef6c99..914f192 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -27,6 +27,7 @@ nav:
- 负载均衡: references-handlers/loadbalance.md
- 限流: references-handlers/ratelimit.md
- 路由管理: references-handlers/router.md
+ - 故障注入: references-handlers/fault-injection.md
- 隔离熔断容错: references-handlers/bizkeeper.md
- 基于动态配置的流量特征治理: references-handlers/governance.md
- 网关功能参考: