dongxuwang commented on a change in pull request #14: DubboX New Features URL: https://github.com/apache/incubator-dubbo-docs/pull/14#discussion_r180660576
########## File path: dubbo-user-book/rest.md ########## @@ -0,0 +1,1209 @@ +# 在Dubbo中开发REST风格的远程调用（RESTful Remoting） + +**作者：沈理** + +**文档版权：[Apache 2.0许可证 署名-禁止演绎](http://www.apache.org/licenses/LICENSE-2.0)** + +完善中…… + +> 本文篇幅较长，因为REST本身涉及面较多。另外，本文参照Spring等的文档风格，不仅仅局限于框架用法的阐述，同时也努力呈现框架的设计理念和优良应用的架构思想。 + +> 对于想粗略了解dubbo和REST的人，只需浏览 `概述` 至 `标准Java REST API：JAX-RS简介` 几节即可。 + +TODO 生成可点击的目录 + +## 目录 + +* 概述 +* REST的优点 +* 应用场景 +* 快速入门 +* 标准Java REST API：JAX-RS简介 +* REST服务提供端详解 + * HTTP POST/GET的实现 + * Annotation放在接口类还是实现类 + * JSON、XML等多数据格式的支持 + * 中文字符支持 + * XML数据格式的额外要求 + * 定制序列化 + * 配置REST Server的实现 + * 获取上下文（Context）信息 + * 配置端口号和Context Path + * 配置线程数和IO线程数 + * 配置长连接 + * 配置最大的HTTP连接数 + * 配置每个消费端的超时时间和HTTP连接数 + * GZIP数据压缩 + * 用Annotation取代部分Spring XML配置 + * 添加自定义的Filter、Interceptor等 + * 添加自定义的Exception处理 + * 配置HTTP日志输出 + * 输入参数的校验 + * 是否应该透明发布REST服务 +* REST服务消费端详解 + * 场景1：非dubbo的消费端调用dubbo的REST服务 + * 场景2：dubbo消费端调用dubbo的REST服务 + * 场景3：dubbo的消费端调用非dubbo的REST服务 +* Dubbo中JAX-RS的限制 +* REST常见问题解答（REST FAQ） + * Dubbo REST的服务能和Dubbo注册中心、监控中心集成吗？ + * Dubbo REST中如何实现负载均衡和容错（failover）？ + * JAX-RS中重载的方法能够映射到同一URL地址吗？ + * JAX-RS中作POST的方法能够接收多个参数吗？ +* Dubbo当前体系可能的不足之处（与REST相关的） + * RpcContext的侵入性 + * Protocol配置的局限性 + * XML命名不符合spring规范 +* REST最佳实践 +* 性能基准测试 + * 测试环境 + * 测试脚本 + * 测试结果 +* 扩展讨论 + * REST与Thrift、Protobuf等的对比 + * REST与传统WebServices的对比 + * JAX-RS与Spring MVC的对比 +* 未来 + +## 概述 + +dubbo支持多种远程调用方式，例如dubbo RPC（二进制序列化 + tcp协议）、http invoker（二进制序列化 + http协议，至少在开源版本没发现对文本序列化的支持）、hessian（二进制序列化 + http协议）、WebServices （文本序列化 + http协议）等等，但缺乏对当今特别流行的REST风格远程调用（文本序列化 + http协议）的支持。 + +有鉴于此，我们基于标准的Java REST API——JAX-RS 2.0（Java API for RESTful Web Services的简写），为dubbo提供了接近透明的REST调用支持。由于完全兼容Java标准API，所以为dubbo开发的所有REST服务，未来脱离dubbo或者任何特定的REST底层实现一般也可以正常运行。 + +特别值得指出的是，我们并不需要完全严格遵守REST的原始定义和架构风格。即使著名的Twitter REST API也会根据情况做适度调整，而不是机械的遵守原始的REST风格。 + +> 附注：我们将这个功能称之为REST风格的远程调用，即RESTful Remoting（抽象的远程处理或者调用），而不是叫RESTful RPC（具体的远程“过程”调用），是因为REST和RPC本身可以被认为是两种不同的风格。在dubbo的REST实现中，可以说有两个面向，其一是提供或消费正常的REST服务，其二是将REST作为dubbo RPC体系中一种协议实现，而RESTful Remoting同时涵盖了这个面向。 Review comment: ``` -而RESTful Remoting同时涵盖了这个面向 +而RESTful Remoting同时涵盖了这两个面向 ``` ---------------------------------------------------------------- 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
