├── .gitignore ├── _config.yml ├── images ├── netty.jpg ├── components.png ├── netty_logo.jpg ├── discard-server-001.png ├── discard-server-002.png ├── stream-based-transport-001.png ├── stream-based-transport-002.png └── stream-based-transport-003.png ├── Architectural-Overview ├── Architectural-Overview.md ├── Summary.md ├── Universal-Asynchronous-IO-API.md ├── Event-Model-based-on-the-Interceptor-Chain-Pattern.md ├── Rich-Buffer-Data-Structure.md └── Advanced-Components-for-More-Rapid-Development.md ├── Getting-Started ├── Getting-Started.md ├── Shutting-Down-Your-Application.md ├── Before-Getting-Started.md ├── Summary.md ├── Writing-an-Echo-Server.md ├── Looking-into-the-Received-Data.md ├── Writing-a-Time-Server.md ├── Writing-a-Time-Client.md ├── Speaking-in-POJO-instead-of-ByteBuf.md ├── Dealing-with-a-Stream-based-Transport.md └── Writing-a-Discard-Server.md ├── Preface ├── The-Problem.md └── The-Solution.md ├── README.md └── SUMMARY.md /.gitignore: -------------------------------------------------------------------------------- 1 | _book 2 | *.project -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-cayman -------------------------------------------------------------------------------- /images/netty.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/netty.jpg -------------------------------------------------------------------------------- /images/components.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/components.png -------------------------------------------------------------------------------- /images/netty_logo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/netty_logo.jpg -------------------------------------------------------------------------------- /images/discard-server-001.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/discard-server-001.png -------------------------------------------------------------------------------- /images/discard-server-002.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/discard-server-002.png -------------------------------------------------------------------------------- /images/stream-based-transport-001.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/stream-based-transport-001.png -------------------------------------------------------------------------------- /images/stream-based-transport-002.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/stream-based-transport-002.png -------------------------------------------------------------------------------- /images/stream-based-transport-003.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/waylau/netty-4-user-guide/HEAD/images/stream-based-transport-003.png -------------------------------------------------------------------------------- /Architectural-Overview/Architectural-Overview.md: -------------------------------------------------------------------------------- 1 | # Architectural Overview 架构总览 2 | 3 | ![](../images/components.png) 4 | 5 | 在本章中，我们将研究 Netty 提供的核心功能以及他们是如何构成一个完整的网络应用开发堆栈顶部的核心。你阅读本章时，请把这个图记住。 6 | -------------------------------------------------------------------------------- /Getting-Started/Getting-Started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 开始 2 | 3 | 本章围绕 Netty 的核心架构，通过简单的示例带你快速入门。当你读完本章节，你马上就可以用 Netty 写出一个客户端和服务器。 4 | 5 | 如果你在学习的时候喜欢“top-down（自顶向下）”，那你可能需要要从第二章“[Architectural Overview （架构总览）](../Architectural-Overview/Architectural-Overview.md)”开始，然后再回到这里。 6 | -------------------------------------------------------------------------------- /Architectural-Overview/Summary.md: -------------------------------------------------------------------------------- 1 | # Summary 总结 2 | 3 | 在这一章节，我们从功能特性的角度回顾了 Netty 的整体架构。Netty 有一个简单却不失强大的架构。这个架构由三部分组成——缓冲（buffer），通道（channel），事件模型（event model）——所有的高级特性都构建在这三个核心组件之上。一旦你理解了它们之间的工作原理，你便不难理解在本章简要提及的更多高级特性。 4 | 5 | 你可能对 Netty 的整体架构以及每一部分的工作原理仍旧存有疑问。如果是这样，最好的方式是[告诉我们](http://netty.io/community.html) 应该如何改进这份指南。 6 | 7 | _译者注：对本翻译有任何疑问，在提问_ 8 | -------------------------------------------------------------------------------- /Preface/The-Problem.md: -------------------------------------------------------------------------------- 1 | # The Problem 问题 2 | 3 | 今天，我们使用通用的应用程序或者类库来实现互相通讯，比如，我们经常使用一个 HTTP 客户端库来从 web 服务器上获取信息，或者通过 web 服务来执行一个远程的调用。 4 | 5 | 然而，有时候一个通用的协议或他的实现并没有很好的满足需求。比如我们无法使用一个通用的 HTTP 服务器来处理大文件、电子邮件以及近实时消息，比如金融信息和多人游戏数据。我们需要一个高度优化的协议来处理一些特殊的场景。例如你可能想实现一个优化了的 Ajax 的聊天应用、媒体流传输或者是大文件传输器，你甚至可以自己设计和实现一个全新的协议来准确地实现你的需求。 6 | 7 | 另一个不可避免的情况是当你不得不处理遗留的专有协议来确保与旧系统的互操作性。在这种情况下，重要的是我们如何才能快速实现协议而不牺牲应用的稳定性和性能。 8 | -------------------------------------------------------------------------------- /Getting-Started/Shutting-Down-Your-Application.md: -------------------------------------------------------------------------------- 1 | # Shutting Down Your Application 关闭你的应用 2 | 3 | 关闭一个 Netty 应用往往只需要简单地通过 shutdownGracefully() 方法来关闭你构建的所有的 [EventLoopGroup](http://netty.io/4.0/api/io/netty/channel/EventLoopGroup.html)。当 EventLoopGroup 被完全地终止,并且对应的所有 [channel](http://netty.io/4.0/api/io/netty/channel/Channel.html) 都已经被关闭时，Netty 会返回一个[Future](http://netty.io/4.0/api/io/netty/util/concurrent/Future.html)对象来通知你。 4 | -------------------------------------------------------------------------------- /Getting-Started/Before-Getting-Started.md: -------------------------------------------------------------------------------- 1 | # Before Getting Started 开始之前 2 | 3 | 在运行本章示例之前，需要准备：最新版的 Netty 以及 JDK 1.6 或以上版本。最新版的 Netty 在这[下载](http://netty.io/downloads.html)。自行下载 JDK。 4 | 5 | 阅读本章节过程中，你可能会对相关类有疑惑，关于这些类的详细的信息请请参考 API 说明文档。为了方便，所有文档中涉及到的类名字都会被关联到一个在线的 API 说明。当然，如果有任何错误信息、语法错误或者你有任何好的建议来改进文档说明，那么请[联系 Netty 社区](http://netty.io/community.html)。 6 | 7 | _译者注：对本翻译有任何疑问，在提问_ 8 | -------------------------------------------------------------------------------- /Getting-Started/Summary.md: -------------------------------------------------------------------------------- 1 | # Summary 总结 2 | 3 | 在这一章节中，我们快速地回顾下如果在熟练掌握 Netty 的情况下编写出一个健壮能运行的网络应用程序。在 Netty 接下去的章节中还会有更多更相信的信息。我们也鼓励你去重新复习下在 [io.netty.example](https://github.com/netty/netty/tree/4.0/example/src/main/java/io/netty/example) 包下的例子。请注意[社区](http://netty.io/community.html)一直在等待你的问题和想法以帮助 Netty 的持续改进，Netty 的文档也是基于你们的快速反馈上。 4 | 5 | _译者注：翻译版本的项目源码见 。如对本翻译有任何建议，可以在留言_ 6 | -------------------------------------------------------------------------------- /Preface/The-Solution.md: -------------------------------------------------------------------------------- 1 | # The Solution 解决 2 | 3 | [Netty](http://netty.io/) 是一个提供 asynchronous event-driven （异步事件驱动）的网络应用框架，是一个用以快速开发高性能、可扩展协议的服务器和客户端。 4 | 5 | 换句话说，Netty 是一个 NIO 客户端服务器框架，使用它可以快速简单地开发网络应用程序，比如服务器和客户端的协议。Netty 大大简化了网络程序的开发过程比如 TCP 和 UDP 的 socket 服务的开发。 6 | 7 | “快速和简单”并不意味着应用程序会有难维护和性能低的问题，Netty 是一个精心设计的框架，它从许多协议的实现中吸收了很多的经验比如 FTP、SMTP、HTTP、许多二进制和基于文本的传统协议.因此，Netty 已经成功地找到一个方式,在不失灵活性的前提下来实现开发的简易性，高性能，稳定性。 8 | 9 | 有一些用户可能已经发现其他的一些网络框架也声称自己有同样的优势，所以你可能会问是 Netty 和它们的不同之处。答案就是 Netty 的哲学设计理念。Netty 从开始就为用户提供了用户体验最好的 API 以及实现设计。正是因为 Netty 的哲学设计理念，才让您得以轻松地阅读本指南并使用 Netty。 10 | -------------------------------------------------------------------------------- /Getting-Started/Writing-an-Echo-Server.md: -------------------------------------------------------------------------------- 1 | # Writing an Echo Server 写个应答服务器 2 | 3 | 到目前为止，我们虽然接收到了数据，但没有做任何的响应。然而一个服务端通常会对一个请求作出响应。让我们学习怎样在 [ECHO](http://tools.ietf.org/html/rfc862) 协议的实现下编写一个响应消息给客户端，这个协议针对任何接收的数据都会返回一个响应。 4 | 5 | 和 discard server 唯一不同的是把在此之前我们实现的 channelRead() 方法，返回所有的数据替代打印接收数据到控制台上的逻辑。因此，需要把 channelRead() 方法修改如下： 6 | 7 | ```java 8 | @Override 9 | public void channelRead(ChannelHandlerContext ctx, Object msg) { 10 | ctx.write(msg); // (1) 11 | ctx.flush(); // (2) 12 | } 13 | ``` 14 | 15 | 1. [ChannelHandlerContext](http://netty.io/4.0/api/io/netty/channel/ChannelHandlerContext.html) 对象提供了许多操作，使你能够触发各种各样的 I/O 事件和操作。这里我们调用了 write(Object) 方法来逐字地把接受到的消息写入。请注意不同于 DISCARD 的例子我们并没有释放接受到的消息，这是因为当写入的时候 Netty 已经帮我们释放了。 16 | 2. ctx.write(Object) 方法不会使消息写入到通道上，他被缓冲在了内部，你需要调用 ctx.flush() 方法来把缓冲区中数据强行输出。或者你可以用更简洁的 cxt.writeAndFlush(msg) 以达到同样的目的。 17 | 18 | 如果你再一次运行 telnet 命令，你会看到服务端会发回一个你已经发送的消息。 19 | 20 | 完整的 echo 服务的代码放在了 [io.netty.example.echo](http://netty.io/4.0/xref/io/netty/example/echo/package-summary.html)包下面。 21 | 22 | 译者注：翻译版本的项目源码见 中的`com.waylau.netty.demo.echo` 包下 23 | -------------------------------------------------------------------------------- /Architectural-Overview/Universal-Asynchronous-IO-API.md: -------------------------------------------------------------------------------- 1 | # Universal Asynchronous I/O API 统一的异步 I/O API 2 | 3 | 传统的 Java I/O API 在应对不同的传输协议时需要使用不同的类型和方法。例如：java.net.Socket 和 java.net.DatagramSocket 它们并不具有相同的超类型，因此，这就需要使用不同的调用方式执行 socket 操作。 4 | 5 | 这种模式上的不匹配使得在更换一个网络应用的传输协议时变得繁杂和困难。由于（Java I/O API）缺乏协议间的移植性，当你试图在不修改网络传输层的前提下增加多种协议的支持，这时便会产生问题。并且理论上讲，多种应用层协议可运行在多种传输层协议之上例如 TCP/IP,UDP/IP,SCTP 和串口通信。 6 | 7 | 让这种情况变得更糟的是，Java 新的 I/O（NIO）API 与原有的阻塞式的 I/O（OIO）API 并不兼容，NIO.2(AIO)也是如此。由于所有的 API 无论是在其设计上还是性能上的特性都与彼此不同，在进入开发阶段，你常常会被迫的选择一种你需要的 API。 8 | 9 | 例如，在用户数较小的时候你可能会选择使用传统的 OIO(Old I/O) API，毕竟与 NIO 相比使用 OIO 将更加容易一些。然而，当你的业务呈指数增长并且服务器需要同时处理成千上万的客户连接时你便会遇到问题。这种情况下你可能会尝试使用 NIO，但是复杂的 NIO Selector 编程接口又会耗费你大量时间并最终会阻碍你的快速开发。 10 | 11 | Netty 有一个叫做 [Channel](http://netty.io/4.0/api/io/netty/channel/package-summary.html#package_description) 的统一的异步 I/O 编程接口，这个编程接口抽象了所有点对点的通信操作。也就是说，如果你的应用是基于 Netty 的某一种传输实现，那么同样的，你的应用也可以运行在 Netty 的另一种传输实现上。Netty 提供了几种拥有相同编程接口的基本传输实现： 12 | 13 | - 基于 NIO 的 TCP/IP 传输 (见 io.netty.channel.nio), 14 | - 基于 OIO 的 TCP/IP 传输 (见 io.netty.channel.oio), 15 | - 基于 OIO 的 UDP/IP 传输, 和 16 | - 本地传输 (见 io.netty.channel.local). 17 | 18 | 切换不同的传输实现通常只需对代码进行几行的修改调整，例如选择一个不同的 [ChannelFactory](http://netty.io/4.0/api/io/netty/bootstrap/ChannelFactory.html) 实现。 19 | 20 | 此外，你甚至可以利用新的传输实现没有写入的优势，只需替换一些构造器的调用方法即可，例如串口通信。而且由于核心 API 具有高度的可扩展性，你还可以完成自己的传输实现。 21 | -------------------------------------------------------------------------------- /Getting-Started/Looking-into-the-Received-Data.md: -------------------------------------------------------------------------------- 1 | Looking into the Received Data 查看收到的数据 2 | ======================== 3 | 4 | 5 | 现在我们已经编写出我们第一个服务端，我们需要测试一下他是否真的可以运行。最简单的测试方法是用 telnet 命令。例如，你可以在命令行上输入`telnet localhost 8080`或者其他类型参数。 6 | 7 | ![](../images/discard-server-001.png) 8 | 9 | ![](../images/discard-server-002.png) 10 | 11 | 然而我们能说这个服务端是正常运行了吗？事实上我们也不知道，因为他是一个 discard 服务，你根本不可能得到任何的响应。为了证明他仍然是在正常工作的，让我们修改服务端的程序来打印出他到底接收到了什么。 12 | 13 | 我们已经知道 channelRead() 方法是在数据被接收的时候调用。让我们放一些代码到 DiscardServerHandler 类的 channelRead() 方法。 14 | 15 | ```java 16 | @Override 17 | public void channelRead(ChannelHandlerContext ctx, Object msg) { 18 | ByteBuf in = (ByteBuf) msg; 19 | try { 20 | while (in.isReadable()) { // (1) 21 | System.out.print((char) in.readByte()); 22 | System.out.flush(); 23 | } 24 | } finally { 25 | ReferenceCountUtil.release(msg); // (2) 26 | } 27 | } 28 | ``` 29 | 30 | 1.这个低效的循环事实上可以简化为:System.out.println(in.toString(io.netty.util.CharsetUtil.US_ASCII)) 31 | 32 | 2.或者，你可以在这里调用 in.release()。 33 | 34 | 如果你再次运行 telnet 命令，你将会看到服务端打印出了他所接收到的消息。 35 | 36 | ![](http://99btgc01.info/uploads/2015/02/telnet3%281%29.jpg) 37 | 38 | 完整的discard server代码放在了[io.netty.example.discard](http://netty.io/4.0/xref/io/netty/example/discard/package-summary.html)包下面。 39 | 40 | *译者注：翻译版本的项目源码见 中的`com.waylau.netty.demo.discard` 包下* -------------------------------------------------------------------------------- /Architectural-Overview/Event-Model-based-on-the-Interceptor-Chain-Pattern.md: -------------------------------------------------------------------------------- 1 | # Event Model based on the Interceptor Chain Pattern 基于拦截链模式的事件模型 2 | 3 | 一个定义良好并具有扩展能力的事件模型是事件驱动开发的必要条件。Netty 具有定义良好的 I/O 事件模型。由于严格的层次结构区分了不同的事件类型，因此 Netty 也允许你在不破坏现有代码的情况下实现自己的事件类型。这是与其他框架相比另一个不同的地方。很多 NIO 框架没有或者仅有有限的事件模型概念；在你试图添加一个新的事件类型的时候常常需要修改已有的代码，或者根本就不允许你进行这种扩展。 4 | 5 | 在一个 [ChannelPipeline](http://netty.io/4.0/api/io/netty/channel/ChannelPipeline.html) 内部一个 [ChannelEvent]() 被一组[ChannelHandler](http://netty.io/4.0/api/io/netty/channel/ChannelHandler.html) 处理。这个管道是 [Intercepting Filter (拦截过滤器)](http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html)模式的一种高级形式的实现，因此对于一个事件如何被处理以及管道内部处理器间的交互过程，你都将拥有绝对的控制力。例如，你可以定义一个从 socket 读取到数据后的操作： 6 | 7 | ```java 8 | public class MyReadHandler implements SimpleChannelHandler { 9 | public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) { 10 | Object message = evt.getMessage(); 11 | // Do something with the received message. 12 | ... 13 | 14 | // And forward the event to the next handler. 15 | ctx.sendUpstream(evt); 16 | } 17 | } 18 | ``` 19 | 20 | 同时你也可以定义一种操作响应其他处理器的写操作请求： 21 | 22 | ```java 23 | public class MyWriteHandler implements SimpleChannelHandler { 24 | public void writeRequested(ChannelHandlerContext ctx, MessageEvent evt) { 25 | Object message = evt.getMessage(); 26 | // Do something with the message to be written. 27 | ... 28 | 29 | // And forward the event to the next handler. 30 | ctx.sendDownstream(evt); 31 | } 32 | } 33 | ``` 34 | 35 | 有关事件模型的更多信息，请参考 API 文档 ChannelEvent 和 ChannelPipeline 部分。 36 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Netty 4.x User Guide《Netty 4.x 用户指南》/《Netty 原理解析与开发实战》 2 | 3 | ![](images/netty_logo.jpg) 4 | 5 | Chinese translation of [Netty 4.x User Guide](http://netty.io/wiki/user-guide-for-4.x.html) . You can also see the demos of the guide [here](https://github.com/waylau/netty-4-user-guide-demos). There is a GitBook version of the book: or 6 | Let's [READ](SUMMARY.md)! 7 | 8 | 《Netty 4.x 用户指南》中文翻译（包含了官方文档以及其他文章），并在原文的基础上，插入配图，图文并茂方便用户理解。至今为止，Netty 的最新版本为 Netty 4.1.79.Final(2022-7-11)。 9 | 10 | 作为提升，也推荐阅读《[Netty 实战(精髓)](https://github.com/waylau/essential-netty-in-action)》。与之类似的 NIO 框架还有 MINA，可以参阅《[Apache MINA 2 用户指南](https://github.com/waylau/apache-mina-2.x-user-guide)》。 11 | 12 | ### Get Started 如何开始阅读 13 | 14 | 选择下面入口之一： 15 | 16 | - 的 [SUMMARY.md](SUMMARY.md)（源码） 17 | - 点击 Read 按钮（同步更新，国内访问速度一般） 18 | - （国内访问速度快，定期更新。最后更新于 2022-7-31） 19 | 20 | ### Code 源码 21 | 22 | 书中所有示例源码，移步至 23 | 24 | ### 配套书籍 25 | 26 | 如果你喜欢本开源书，也请支持下该书的正式出版物《[Netty 原理解析与开发实战](https://book.douban.com/subject/35317298/)》 27 | 28 | 实体店及各大网店有售。 29 | 30 | - 当当： 31 | - 京东： 32 | 33 | ![](images/netty.jpg) 34 | 35 | ### Issue 意见、建议 36 | 37 | 如有勘误、意见或建议欢迎拍砖 38 | 39 | ### Contact 联系作者: 40 | 41 | - Blog: [waylau.com](https://waylau.com) 42 | - Gmail: [waylau521(at)gmail.com](mailto:waylau521@gmail.com) 43 | - Weibo: [waylau521](http://weibo.com/waylau521) 44 | - Twitter: [waylau521](https://twitter.com/waylau521) 45 | - Github : [waylau](https://github.com/waylau) 46 | 47 | ### Support Me 请老卫喝一杯 48 | 49 | ![开源捐赠](https://waylau.com/images/showmethemoney-sm.jpg) 50 | -------------------------------------------------------------------------------- /Architectural-Overview/Rich-Buffer-Data-Structure.md: -------------------------------------------------------------------------------- 1 | # Rich Buffer Data Structure 丰富的缓冲实现 2 | 3 | Netty 使用自建的 buffer API，而不是使用 NIO 的 [ByteBuffer](http://docs.oracle.com/javase/7/docs/api/java/nio/ByteBuffer.html?is-external=true) 来表示一个连续的字节序列。与 ByteBuffer 相比这种方式拥有明显的优势。Netty 使用新的 buffer 类型 [ByteBuf](http://netty.io/4.0/api/io/netty/buffer/ByteBuf.html)，被设计为一个可从底层解决 ByteBuffer 问题，并可满足日常网络应用开发需要的缓冲类型。这些很酷的特性包括： 4 | 5 | - 如果需要，允许使用自定义的缓冲类型。 6 | - 复合缓冲类型中内置的透明的零拷贝实现。 7 | - 开箱即用的动态缓冲类型，具有像 [StringBuffer](http://docs.oracle.com/javase/7/docs/api/java/lang/StringBuffer.html?is-external=true) 一样的动态缓冲能力。 8 | - 不再需要调用的 flip()方法。 9 | - 正常情况下具有比 ByteBuffer 更快的响应速度。 10 | 11 | 更多信息请参考：[io.netty.buffer 包描述](http://netty.io/4.0/api/io/netty/buffer/package-summary.html#package_description) 12 | 13 | ###Extensibility 可扩展性 14 | 15 | ByteBuf 具有丰富的操作集,可以快速的实现协议的优化。例如，ByteBuf 提供各种操作用于访问无符号值和字符串，以及在缓冲区搜索一定的字节序列。你也可以扩展或包装现有的缓冲类型用来提供方便的访问。自定义缓冲仍然实现自 ByteBuf 接口，而不是引入一个不兼容的类型 16 | 17 | ###Transparent Zero Copy 透明的零拷贝 18 | 19 | 举一个网络应用到极致的表现，你需要减少内存拷贝操作次数。你可能有一组缓冲区可以被组合以形成一个完整的消息。网络提供了一种复合缓冲，允许你从现有的任意数的缓冲区创建一个新的缓冲区而无需内存拷贝。例如，一个信息可以由两部分组成；header 和 body。在一个模块化的应用，当消息发送出去时，这两部分可以由不同的模块生产和装配。 20 | 21 | 
 +--------+----------+
22 |  | header |   body   |
23 |  +--------+----------+
24 |
25 | 26 | 如果你使用的是 ByteBuffer ，你必须要创建一个新的大缓存区用来拷贝这两部分到这个新缓存区中。或者，你可以在 NiO 做一个收集写操作，但限制你将复合缓冲类型作为 ByteBuffer 的数组而不是一个单一的缓冲区，打破了抽象，并且引入了复杂的状态管理。此外，如果你不从 NIO channel 读或写，它是没有用的。 27 | 28 | ```java 29 | // 复合类型与组件类型不兼容。 30 | ByteBuffer[] message = new ByteBuffer[] { header, body }; 31 | ``` 32 | 33 | 通过对比， ByteBuf 不会有警告，因为它是完全可扩展并有一个内置的复合缓冲区。 34 | 35 | ```java 36 | // 复合类型与组件类型是兼容的。 37 | ByteBuf message = Unpooled.wrappedBuffer(header, body); 38 | 39 | // 因此，你甚至可以通过混合复合类型与普通缓冲区来创建一个复合类型。 40 | ByteBuf messageWithFooter = Unpooled.wrappedBuffer(message, footer); 41 | 42 | // 由于复合类型仍是 ByteBuf，访问其内容很容易， 43 | //并且访问方法的行为就像是访问一个单独的缓冲区， 44 | //即使你想访问的区域是跨多个组件。 45 | //这里的无符号整数读取位于 body 和 footer 46 | messageWithFooter.getUnsignedInt( 47 | messageWithFooter.readableBytes() - footer.readableBytes() - 1); 48 | ``` 49 | 50 | ###Automatic Capacity Extension 自动容量扩展 51 | 52 | 许多协议定义可变长度的消息，这意味着没有办法确定消息的长度，直到你构建的消息。或者，在计算长度的精确值时，带来了困难和不便。这就像当你建立一个字符串。你经常估计得到的字符串的长度，让 StringBuffer 扩大了其本身的需求。 53 | 54 | ```java 55 | // 一种新的动态缓冲区被创建。在内部，实际缓冲区是被“懒”创建，从而避免潜在的浪费内存空间。 56 | ByteBuf b = Unpooled.buffer(4); 57 | 58 | // 当第一个执行写尝试，内部指定初始容量 4 的缓冲区被创建 59 | b.writeByte('1'); 60 | 61 | b.writeByte('2'); 62 | b.writeByte('3'); 63 | b.writeByte('4'); 64 | 65 | // 当写入的字节数超过初始容量 4 时， 66 | //内部缓冲区自动分配具有较大的容量 67 | b.writeByte('5'); 68 | ``` 69 | 70 | ###Better Performance 更好的性能 71 | 72 | 最频繁使用的缓冲区 ByteBuf 的实现是一个非常薄的字节数组包装器（比如，一个字节）。与 ByteBuffer 不同，它没有复杂的边界和索引检查补偿，因此对于 JVM 优化缓冲区的访问更加简单。更多复杂的缓冲区实现是用于拆分或者组合缓存，并且比 ByteBuffer 拥有更好的性能。 73 | -------------------------------------------------------------------------------- /Getting-Started/Writing-a-Time-Server.md: -------------------------------------------------------------------------------- 1 | # Writing a Time Server 写个时间服务器 2 | 3 | 在这个部分被实现的协议是 [TIME](http://tools.ietf.org/html/rfc868) 协议。和之前的例子不同的是在不接受任何请求时他会发送一个含 32 位的整数的消息，并且一旦消息发送就会立即关闭连接。在这个例子中，你会学习到如何构建和发送一个消息，然后在完成时关闭连接。 4 | 5 | 因为我们将会忽略任何接收到的数据，而只是在连接被创建发送一个消息，所以这次我们不能使用 channelRead() 方法了，代替他的是，我们需要覆盖 channelActive() 方法，下面的就是实现的内容： 6 | 7 | ```java 8 | public class TimeServerHandler extends ChannelInboundHandlerAdapter { 9 | 10 | @Override 11 | public void channelActive(final ChannelHandlerContext ctx) { // (1) 12 | final ByteBuf time = ctx.alloc().buffer(4); // (2) 13 | time.writeInt((int) (System.currentTimeMillis() / 1000L + 2208988800L)); 14 | 15 | final ChannelFuture f = ctx.writeAndFlush(time); // (3) 16 | f.addListener(new ChannelFutureListener() { 17 | @Override 18 | public void operationComplete(ChannelFuture future) { 19 | assert f == future; 20 | ctx.close(); 21 | } 22 | }); // (4) 23 | } 24 | 25 | @Override 26 | public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) { 27 | cause.printStackTrace(); 28 | ctx.close(); 29 | } 30 | } 31 | ``` 32 | 33 | 1. channelActive() 方法将会在连接被建立并且准备进行通信时被调用。因此让我们在这个方法里完成一个代表当前时间的 32 位整数消息的构建工作。 34 | 35 | 2. 为了发送一个新的消息，我们需要分配一个包含这个消息的新的缓冲。因为我们需要写入一个 32 位的整数，因此我们需要一个至少有 4 个字节的 [ByteBuf](http://netty.io/4.0/api/io/netty/buffer/ByteBuf.html)。通过 ChannelHandlerContext.alloc() 得到一个当前的[ByteBufAllocator](http://netty.io/4.0/api/io/netty/buffer/ByteBufAllocator.html)，然后分配一个新的缓冲。 36 | 37 | 3. 和往常一样我们需要编写一个构建好的消息。但是等一等，flip 在哪？难道我们使用 NIO 发送消息时不是调用 java.nio.ByteBuffer.flip() 吗？ByteBuf 之所以没有这个方法因为有两个指针，一个对应读操作一个对应写操作。当你向 ByteBuf 里写入数据的时候写指针的索引就会增加，同时读指针的索引没有变化。读指针索引和写指针索引分别代表了消息的开始和结束。 38 | 39 | 比较起来，NIO 缓冲并没有提供一种简洁的方式来计算出消息内容的开始和结尾，除非你调用 flip 方法。当你忘记调用 flip 方法而引起没有数据或者错误数据被发送时，你会陷入困境。这样的一个错误不会发生在 Netty 上，因为我们对于不同的操作类型有不同的指针。你会发现这样的使用方法会让你过程变得更加的容易，因为你已经习惯一种没有使用 flip 的方式。 40 | 41 | 另外一个点需要注意的是 ChannelHandlerContext.write() (和 writeAndFlush() )方法会返回一个 [ChannelFuture](http://netty.io/4.0/api/io/netty/channel/ChannelFuture.html) 对象，一个 ChannelFuture 代表了一个还没有发生的 I/O 操作。这意味着任何一个请求操作都不会马上被执行，因为在 Netty 里所有的操作都是异步的。举个例子下面的代码中在消息被发送之前可能会先关闭连接。 42 | 43 | ```java 44 | Channel ch = ...; 45 | ch.writeAndFlush(message); 46 | ch.close(); 47 | ``` 48 | 49 | 因此你需要在 write() 方法返回的 ChannelFuture 完成后调用 close() 方法，然后当他的写操作已经完成他会通知他的监听者。请注意,close() 方法也可能不会立马关闭，他也会返回一个 ChannelFuture。 50 | 51 | 4. 当一个写请求已经完成是如何通知到我们？这个只需要简单地在返回的 ChannelFuture 上增加一个[ChannelFutureListener](http://netty.io/4.0/api/io/netty/channel/ChannelFutureListener.html)。这里我们构建了一个匿名的 ChannelFutureListener 类用来在操作完成时关闭 Channel。 52 | 53 | 或者，你可以使用简单的预定义监听器代码: 54 | 55 | ```java 56 | f.addListener(ChannelFutureListener.CLOSE); 57 | ``` 58 | 59 | 为了测试我们的 time 服务如我们期望的一样工作，你可以使用 UNIX 的 rdate 命令 60 | 61 | ```SHELL 62 | $ rdate -o -p 63 | ``` 64 | 65 | Port 是你在 main()函数中指定的端口，host 使用 localhost 就可以了。 66 | -------------------------------------------------------------------------------- /Architectural-Overview/Advanced-Components-for-More-Rapid-Development.md: -------------------------------------------------------------------------------- 1 | # Advanced Components for More Rapid Development 适用快速开发的高级组件 2 | 3 | 上述所提及的核心组件已经足够实现各种类型的网络应用，除此之外，Netty 也提供了一系列的高级组件来加速你的开发过程。 4 | 5 | ##Codec 框架 6 | 7 | 就像“[使用 POJO 代替 ChannelBuffer](../Getting-Started/Speaking-in-POJO-instead-of-ByteBuf.md)”一节所展示的那样，从业务逻辑代码中分离协议处理部分总是一个很不错的想法。然而如果一切从零开始便会遭遇到实现上的复杂性。你不得不处理分段的消息。一些协议是多层的（例如构建在其他低层协议之上的协议）。一些协议过于复杂以致难以在一台独立状态机上实现。 8 | 9 | 因此，一个好的网络应用框架应该提供一种可扩展，可重用，可单元测试并且是多层的 codec 框架，为用户提供易维护的 codec 代码。 10 | 11 | Netty 提供了一组构建在其核心模块之上的 codec 实现，这些简单的或者高级的 codec 实现帮你解决了大部分在你进行协议处理开发过程会遇到的问题，无论这些协议是简单的还是复杂的，二进制的或是简单文本的。 12 | 13 | ##SSL / TLS 支持 14 | 15 | 不同于传统阻塞式的 I/O 实现，在 NIO 模式下支持 SSL 功能是一个艰难的工作。你不能只是简单的包装一下流数据并进行加密或解密工作，你不得不借助于 javax.net.ssl.SSLEngine，SSLEngine 是一个有状态的实现，其复杂性不亚于 SSL 自身。你必须管理所有可能的状态，例如密码套件，密钥协商（或重新协商），证书交换以及认证等。此外，与通常期望情况相反的是 SSLEngine 甚至不是一个绝对的线程安全实现。 16 | 17 | 在 Netty 内部，[SslHandler](http://netty.io/4.0/api/io/netty/handler/ssl/SslHandler.html) 封装了所有艰难的细节以及使用 SSLEngine 可 能带来的陷阱。你所做的仅是配置并将该 SslHandler 插入到你的 [ChannelPipeline](http://netty.io/4.0/api/io/netty/channel/ChannelPipeline.html) 中。同样 Netty 也允许你实现像 [StartTlS](http://en.wikipedia.org/wiki/Starttls) 那样所拥有的高级特性，这很容易。 18 | 19 | ##HTTP 实现 20 | 21 | HTTP 无 疑是互联网上最受欢迎的协议，并且已经有了一些例如 Servlet 容器这样的 HTTP 实现。因此，为什么 Netty 还要在其核心模块之上构建一套 HTTP 实现？ 22 | 23 | 与现有的 HTTP 实现相比 Netty 的 HTTP 实现是相当与众不同的。在 HTTP 消息的低层交互过程中你将拥有绝对的控制力。这是因为 Netty 的 HTTP 实现只是一些 HTTP codec 和 HTTP 消息类的简单组合，这里不存在任何限制——例如那种被迫选择的线程模型。你可以随心所欲的编写那种可以完全按照你期望的工作方式工作的客户端或服务器端代码。这包括线程模型，连接生命期，快编码，以及所有 HTTP 协议允许你做的，所有的一切，你都将拥有绝对的控制力。 24 | 25 | 由于这种高度可定制化的特性，你可以开发一个非常高效的 HTTP 服务器，例如： 26 | 27 | - 要求持久化链接以及服务器端推送技术的聊天服务（如，[Comet](http://en.wikipedia.org/wiki/Comet_%28programming%29) ) 28 | - 需要保持链接直至整个文件下载完成的媒体流服务（如，2 小时长的电影） 29 | - 需要上传大文件并且没有内存压力的文件服务（如，上传 1GB 文件的请求） 30 | - 支持大规模混合客户端应用用于连接以万计的第三方异步 web 服务。 31 | 32 | ##WebSockets 实现 33 | 34 | [WebSockets](http://en.wikipedia.org/wiki/WebSockets) 允许双向，全双工通信信道，在 TCP socket 中。它被设计为允许一个 Web 浏览器和 Web 服务器之间通过数据流交互。 35 | 36 | WebSocket 协议已经被 IETF 列为 [RFC 6455](http://tools.ietf.org/html/rfc6455)规范。 37 | 38 | Netty 实现了 RFC 6455 和一些老版本的规范。请参阅[io.netty.handler.codec.http.websocketx](http://netty.io/4.0/api/io/netty/handler/codec/http/websocketx/package-frame.html)包和相关的[例子](http://static.netty.io/3.5/xref/org/jboss/netty/example/http/websocketx/server/package-summary.html)。 39 | 40 | ##Google Protocol Buffer 整合 41 | 42 | [Google Protocol Buffers](http://code.google.com/apis/protocolbuffers/docs/overview.html) 是快速实现一个高效的二进制协议的理想方案。通过使用 [ProtobufEncoder](http://netty.io/4.0/api/io/netty/handler/codec/protobuf/ProtobufEncoder.html) 和 [ProtobufDecoder](http://netty.io/4.0/api/io/netty/handler/codec/protobuf/ProtobufDecoder.html)，你可以把 Google Protocol Buffers 编译器 (protoc) 生成的消息类放入到 Netty 的 codec 实现中。请参考“[LocalTime](http://docs.jboss.org/netty/3.2/xref/org/jboss/netty/example/localtime/package-summary.html)”实例，这个例子也同时显示出开发一个由简单协议定义 的客户及服务端是多么的容易。 43 | 44 | _译者注：翻译版本的项目源码见 _ 45 | -------------------------------------------------------------------------------- /Getting-Started/Writing-a-Time-Client.md: -------------------------------------------------------------------------------- 1 | # Writing a Time Client 写个时间客户端 2 | 3 | 不像 DISCARD 和 ECHO 的服务端，对于 TIME 协议我们需要一个客户端,因为人们不能把一个 32 位的二进制数据翻译成一个日期或者日历。在这一部分，我们将会讨论如何确保服务端是正常工作的，并且学习怎样用 Netty 编写一个客户端。 4 | 5 | 在 Netty 中,编写服务端和客户端最大的并且唯一不同的使用了不同的[BootStrap](http://netty.io/4.0/api/io/netty/bootstrap/Bootstrap.html) 和 [Channel](http://netty.io/4.0/api/io/netty/channel/Channel.html)的实现。请看一下下面的代码： 6 | 7 | ```java 8 | public class TimeClient { 9 | 10 | public static void main(String[] args) throws Exception { 11 | 12 | String host = args[0]; 13 | int port = Integer.parseInt(args[1]); 14 | EventLoopGroup workerGroup = new NioEventLoopGroup(); 15 | 16 | try { 17 | Bootstrap b = new Bootstrap(); // (1) 18 | b.group(workerGroup); // (2) 19 | b.channel(NioSocketChannel.class); // (3) 20 | b.option(ChannelOption.SO_KEEPALIVE, true); // (4) 21 | b.handler(new ChannelInitializer() { 22 | @Override 23 | public void initChannel(SocketChannel ch) throws Exception { 24 | ch.pipeline().addLast(new TimeClientHandler()); 25 | } 26 | }); 27 | 28 | // 启动客户端 29 | ChannelFuture f = b.connect(host, port).sync(); // (5) 30 | 31 | // 等待连接关闭 32 | f.channel().closeFuture().sync(); 33 | } finally { 34 | workerGroup.shutdownGracefully(); 35 | } 36 | } 37 | } 38 | ``` 39 | 40 | 1. BootStrap 和 [ServerBootstrap](http://netty.io/4.0/api/io/netty/bootstrap/ServerBootstrap.html) 类似,不过他是对非服务端的 channel 而言，比如客户端或者无连接传输模式的 channel。 41 | 42 | 2. 如果你只指定了一个 [EventLoopGroup](http://netty.io/4.0/api/io/netty/channel/EventLoopGroup.html)，那他就会即作为一个 boss group ，也会作为一个 workder group，尽管客户端不需要使用到 boss worker 。 43 | 44 | 3. 代替[NioServerSocketChannel](http://netty.io/4.0/api/io/netty/channel/socket/nio/NioServerSocketChannel.html)的是[NioSocketChannel](http://netty.io/4.0/api/io/netty/channel/socket/nio/NioSocketChannel.html),这个类在客户端 channel 被创建时使用。 45 | 46 | 4. 不像在使用 ServerBootstrap 时需要用 childOption() 方法，因为客户端的 [SocketChannel](http://netty.io/4.0/api/io/netty/channel/socket/SocketChannel.html) 没有父亲。 47 | 48 | 5. 我们用 connect() 方法代替了 bind() 方法。 49 | 50 | 正如你看到的，他和服务端的代码是不一样的。[ChannelHandler](http://netty.io/4.0/api/io/netty/channel/ChannelHandler.html) 是如何实现的?他应该从服务端接受一个 32 位的整数消息，把他翻译成人们能读懂的格式，并打印翻译好的时间，最后关闭连接: 51 | 52 | ```java 53 | import java.util.Date; 54 | 55 | public class TimeClientHandler extends ChannelInboundHandlerAdapter { 56 | @Override 57 | public void channelRead(ChannelHandlerContext ctx, Object msg) { 58 | ByteBuf m = (ByteBuf) msg; // (1) 59 | try { 60 | long currentTimeMillis = (m.readUnsignedInt() - 2208988800L) * 1000L; 61 | System.out.println(new Date(currentTimeMillis)); 62 | ctx.close(); 63 | } finally { 64 | m.release(); 65 | } 66 | } 67 | 68 | @Override 69 | public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) { 70 | cause.printStackTrace(); 71 | ctx.close(); 72 | } 73 | } 74 | ``` 75 | 76 | 1. 在 TCP/IP 中，Netty 会把读到的数据放到 ByteBuf 的数据结构中。 77 | 78 | 79 | 这样看起来非常简单，并且和服务端的那个例子的代码也相差不多。然而，处理器有时候会因为抛出 IndexOutOfBoundsException 而拒绝工作。在下个部分我们会讨论为什么会发生这种情况。 80 | -------------------------------------------------------------------------------- /Getting-Started/Speaking-in-POJO-instead-of-ByteBuf.md: -------------------------------------------------------------------------------- 1 | # Speaking in POJO instead of ByteBuf 用 POJO 代替 ByteBuf 2 | 3 | 我们回顾了迄今为止的所有例子使用 [ByteBuf](http://netty.io/4.0/api/io/netty/buffer/ByteBuf.html) 作为协议消息的主要数据结构。在本节中,我们将改善的 TIME 协议客户端和服务器例子，使用 POJO 代替 ByteBuf。 4 | 5 | 在 [ChannelHandler](http://netty.io/4.0/api/io/netty/channel/ChannelHandler.html) 使用 POJO 的好处很明显：通过从 ChannelHandler 中提取出 ByteBuf 的代码，将会使 ChannelHandler 的实现变得更加可维护和可重用。在 TIME 客户端和服务器的例子中，我们读取的仅仅是一个 32 位的整形数据，直接使用 ByteBuf 不会是一个主要的问题。然而，你会发现当你需要实现一个真实的协议，分离代码变得非常的必要。 6 | 7 | 首先，让我们定义一个新的类型叫做 UnixTime。 8 | 9 | ```java 10 | public class UnixTime { 11 | 12 | private final long value; 13 | 14 | public UnixTime() { 15 | this(System.currentTimeMillis() / 1000L + 2208988800L); 16 | } 17 | 18 | public UnixTime(long value) { 19 | this.value = value; 20 | } 21 | 22 | public long value() { 23 | return value; 24 | } 25 | 26 | @Override 27 | public String toString() { 28 | return new Date((value() - 2208988800L) * 1000L).toString(); 29 | } 30 | } 31 | ``` 32 | 33 | 现在我们可以修改下 TimeDecoder 类，返回一个 UnixTime，以替代 ByteBuf 34 | 35 | ```java 36 | @Override 37 | protected void decode(ChannelHandlerContext ctx, ByteBuf in, List out) { 38 | if (in.readableBytes() < 4) { 39 | return; 40 | } 41 | 42 | out.add(new UnixTime(in.readUnsignedInt())); 43 | } 44 | ``` 45 | 46 | 下面是修改后的解码器，TimeClientHandler 不再任何的 ByteBuf 代码了。 47 | 48 | ```java 49 | @Override 50 | public void channelRead(ChannelHandlerContext ctx, Object msg) { 51 | UnixTime m = (UnixTime) msg; 52 | System.out.println(m); 53 | ctx.close(); 54 | } 55 | ``` 56 | 57 | 是不是变得更加简单和优雅了？相同的技术可以被运用到服务端。让我们修改一下 TimeServerHandler 的代码。 58 | 59 | ```java 60 | @Override 61 | public void channelActive(ChannelHandlerContext ctx) { 62 | ChannelFuture f = ctx.writeAndFlush(new UnixTime()); 63 | f.addListener(ChannelFutureListener.CLOSE); 64 | } 65 | ``` 66 | 67 | 现在,唯一缺少的功能是一个编码器,是[ChannelOutboundHandler](http://netty.io/4.0/api/io/netty/channel/ChannelOutboundHandler.html)的实现，用来将 UnixTime 对象重新转化为一个 ByteBuf。这是比编写一个解码器简单得多,因为没有需要处理的数据包编码消息时拆分和组装。 68 | 69 | ```java 70 | public class TimeEncoder extends ChannelOutboundHandlerAdapter { 71 | @Override 72 | public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) { 73 | UnixTime m = (UnixTime) msg; 74 | ByteBuf encoded = ctx.alloc().buffer(4); 75 | encoded.writeInt((int)m.value()); 76 | ctx.write(encoded, promise); // (1) 77 | } 78 | } 79 | ``` 80 | 81 | 1.在这几行代码里还有几个重要的事情。第一，通过 [ChannelPromise](http://netty.io/4.0/api/io/netty/channel/ChannelPromise.html)，当编码后的数据被写到了通道上 Netty 可以通过这个对象标记是成功还是失败。第二， 我们不需要调用 cxt.flush()。因为处理器已经单独分离出了一个方法 void flush(ChannelHandlerContext cxt),如果像自己实现 flush() 方法内容可以自行覆盖这个方法。 82 | 83 | 进一步简化操作，你可以使用 [MessageToByteEncode](http://netty.io/4.0/api/io/netty/handler/codec/MessageToByteEncoder.html): 84 | 85 | public class TimeEncoder extends MessageToByteEncoder { 86 | @Override 87 | protected void encode(ChannelHandlerContext ctx, UnixTime msg, ByteBuf out) { 88 | out.writeInt((int)msg.value()); 89 | } 90 | } 91 | 92 | 最后的任务就是在 TimeServerHandler 之前把 TimeEncoder 插入到 ChannelPipeline。 但这是不那么重要的工作。 93 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | This is the summary of my book. 4 | 5 | - Preface 前言 6 | - [The Problem 问题](Preface/The-Problem.md) 7 | - [The Solution 解决](Preface/The-Solution.md) 8 | - [Getting Started 开始](Getting-Started/Getting-Started.md) 9 | - [Before Getting Started 开始之前](Getting-Started/Before-Getting-Started.md) 10 | - [Writing a Discard Server 写个抛弃服务器](Getting-Started/Writing-a-Discard-Server.md) 11 | - [Looking into the Received Data 查看收到的数据](Getting-Started/Looking-into-the-Received-Data.md) 12 | - [Writing an Echo Server 写个应答服务器](Getting-Started/Writing-an-Echo-Server.md) 13 | - [Writing a Time Server 写个时间服务器](Getting-Started/Writing-a-Time-Server.md) 14 | - [Writing a Time Client 写个时间客户端](Getting-Started/Writing-a-Time-Client.md) 15 | - [Dealing with a Stream-based Transport 处理一个基于流的传输](Getting-Started/Dealing-with-a-Stream-based-Transport.md) 16 | - [Speaking in POJO instead of ByteBuf 用 POJO 代替 ByteBuf](Getting-Started/Speaking-in-POJO-instead-of-ByteBuf.md) 17 | - [Shutting Down Your Application 关闭你的应用](Getting-Started/Shutting-Down-Your-Application.md) 18 | - [Summary 总结](Getting-Started/Summary.md) 19 | - [Architectural Overview 架构总览](Architectural-Overview/Architectural-Overview.md) 20 | - [Rich Buffer Data Structure 丰富的缓冲实现](Architectural-Overview/Rich-Buffer-Data-Structure.md) 21 | - [Universal Asynchronous I/O API 统一的异步 I/O API](Architectural-Overview/Universal-Asynchronous-IO-API.md) 22 | - [Event Model based on the Interceptor Chain Pattern 基于拦截链模式的事件模型](Architectural-Overview/Event-Model-based-on-the-Interceptor-Chain-Pattern.md) 23 | - [Advanced Components for More Rapid Development 适用快速开发的高级组件](Architectural-Overview/Advanced-Components-for-More-Rapid-Development.md) 24 | - [Summary 总结](Architectural-Overview/Summary.md) 25 | - Others 其他 26 | - [Netty 实现聊天功能](https://waylau.com/netty-chat/) 27 | - [Netty 实现 WebSocket 聊天功能](https://waylau.com/netty-websocket-chat/) 28 | - [Netty 超时机制及心跳程序实现](https://waylau.com/netty-time-out-and-heartbeat/) 29 | - [Netty——ChannelHandler 之概述](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201121578210430057&fid=23) 30 | - [Netty——ChannelHandler 之 flush 行为控制](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201121588902470048&fid=23) 31 | - [Netty——ChannelHandler 之 IP 地址过滤](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201121602029690061&fid=23) 32 | - [Netty——ChannelHandler 之流量整形](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201124824648340084&fid=23) 33 | - [Netty——ChannelHandler 之流量整形 AbstractTrafficShapingHandler 类](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201125631815620129&fid=23) 34 | - [Netty——ChannelHandler 之安全处理](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201126757703410192&fid=23) 35 | - [Netty——HTTP 之 Netty 对于 HTTP 的支持](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201127654293200021&fid=23) 36 | - [Netty——HTTP 之基于 HTTP 协议的 Web 服务器](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201127656849730021&fid=23) 37 | - [Netty——HTTP 之 HTTP 协议](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201127650592760020&fid=23) 38 | - [Netty——案例分析之 Vert.x ](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201133750897750140&fid=23) 39 | - [Netty——案例分析之 RocketMQ](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201133760691530141&fid=23) 40 | - [Netty——案例分析之 Dubbo](https://developer.huawei.com/consumer/cn/forum/topicview?tid=0201134505783170160&fid=23) 41 | -------------------------------------------------------------------------------- /Getting-Started/Dealing-with-a-Stream-based-Transport.md: -------------------------------------------------------------------------------- 1 | # Dealing with a Stream-based Transport 处理一个基于流的传输 2 | 3 | ##One Small Caveat of Socket Buffer 关于 Socket Buffer 的一个小警告 4 | 5 | 基于流的传输比如 TCP/IP, 接收到数据是存在 socket 接收的 buffer 中。不幸的是，基于流的传输并不是一个数据包队列，而是一个字节队列。意味着，即使你发送了 2 个独立的数据包，操作系统也不会作为 2 个消息处理而仅仅是作为一连串的字节而言。因此这是不能保证你远程写入的数据就会准确地读取。举个例子，让我们假设操作系统的 TCP/TP 协议栈已经接收了 3 个数据包： 6 | 7 | ![](../images/stream-based-transport-001.png) 8 | 9 | 由于基于流传输的协议的这种普通的性质，在你的应用程序里读取数据的时候会有很高的可能性被分成下面的片段 10 | 11 | ![](../images/stream-based-transport-002.png) 12 | 13 | 因此，一个接收方不管他是客户端还是服务端，都应该把接收到的数据整理成一个或者多个更有意思并且能够让程序的业务逻辑更好理解的数据。在上面的例子中，接收到的数据应该被构造成下面的格式： 14 | 15 | ![](../images/stream-based-transport-003.png) 16 | 17 | ##The First Solution 办法一 18 | 19 | 回到 TIME 客户端例子。同样也有类似的问题。一个 32 位整型是非常小的数据，他并不见得会被经常拆分到到不同的数据段内。然而，问题是他确实可能会被拆分到不同的数据段内，并且拆分的可能性会随着通信量的增加而增加。 20 | 21 | 最简单的方案是构造一个内部的可积累的缓冲，直到 4 个字节全部接收到了内部缓冲。下面的代码修改了 TimeClientHandler 的实现类修复了这个问题 22 | 23 | ```java 24 | public class TimeClientHandler extends ChannelInboundHandlerAdapter { 25 | private ByteBuf buf; 26 | 27 | @Override 28 | public void handlerAdded(ChannelHandlerContext ctx) { 29 | buf = ctx.alloc().buffer(4); // (1) 30 | } 31 | 32 | @Override 33 | public void handlerRemoved(ChannelHandlerContext ctx) { 34 | buf.release(); // (1) 35 | buf = null; 36 | } 37 | 38 | @Override 39 | public void channelRead(ChannelHandlerContext ctx, Object msg) { 40 | ByteBuf m = (ByteBuf) msg; 41 | buf.writeBytes(m); // (2) 42 | m.release(); 43 | 44 | if (buf.readableBytes() >= 4) { // (3) 45 | long currentTimeMillis = (buf.readUnsignedInt() - 2208988800L) * 1000L; 46 | System.out.println(new Date(currentTimeMillis)); 47 | ctx.close(); 48 | } 49 | } 50 | 51 | @Override 52 | public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) { 53 | cause.printStackTrace(); 54 | ctx.close(); 55 | } 56 | } 57 | ``` 58 | 59 | 1.[ChannelHandler](http://netty.io/4.0/api/io/netty/channel/ChannelHandler.html) 有 2 个生命周期的监听方法：handlerAdded()和 handlerRemoved()。你可以完成任意初始化任务只要他不会被阻塞很长的时间。 60 | 61 | 2.首先，所有接收的数据都应该被累积在 buf 变量里。 62 | 63 | 3.然后，处理器必须检查 buf 变量是否有足够的数据，在这个例子中是 4 个字节，然后处理实际的业务逻辑。否则，Netty 会重复调用 channelRead() 当有更多数据到达直到 4 个字节的数据被积累。 64 | 65 | ##The Second Solution 方法二 66 | 67 | 尽管第一个解决方案已经解决了 TIME 客户端的问题了，但是修改后的处理器看起来不那么的简洁，想象一下如果由多个字段比如可变长度的字段组成的更为复杂的协议时，你的 [ChannelInboundHandler](http://netty.io/4.0/api/io/netty/channel/ChannelInboundHandler.html) 的实现将很快地变得难以维护。 68 | 69 | 正如你所知的，你可以增加多个 [ChannelHandler](http://netty.io/4.0/api/io/netty/channel/ChannelHandler.html) 到[ChannelPipeline](http://netty.io/4.0/api/io/netty/channel/ChannelPipeline.html) ,因此你可以把一整个 ChannelHandler 拆分成多个模块以减少应用的复杂程度，比如你可以把 TimeClientHandler 拆分成 2 个处理器： 70 | 71 | - TimeDecoder 处理数据拆分的问题 72 | - TimeClientHandler 原始版本的实现 73 | 74 | 幸运地是，Netty 提供了一个可扩展的类，帮你完成 TimeDecoder 的开发。 75 | 76 | ```java 77 | public class TimeDecoder extends ByteToMessageDecoder { // (1) 78 | @Override 79 | protected void decode(ChannelHandlerContext ctx, ByteBuf in, List out) { // (2) 80 | if (in.readableBytes() < 4) { 81 | return; // (3) 82 | } 83 | 84 | out.add(in.readBytes(4)); // (4) 85 | } 86 | } 87 | ``` 88 | 89 | 1.[ByteToMessageDecoder](http://netty.io/4.0/api/io/netty/handler/codec/ByteToMessageDecoder.html) 是 [ChannelInboundHandler](http://netty.io/4.0/api/io/netty/channel/ChannelInboundHandler.html) 的一个实现类，他可以在处理数据拆分的问题上变得很简单。 90 | 91 | 2.每当有新数据接收的时候，ByteToMessageDecoder 都会调用 decode() 方法来处理内部的那个累积缓冲。 92 | 93 | 3.Decode() 方法可以决定当累积缓冲里没有足够数据时可以往 out 对象里放任意数据。当有更多的数据被接收了 ByteToMessageDecoder 会再一次调用 decode() 方法。 94 | 95 | 4.如果在 decode() 方法里增加了一个对象到 out 对象里，这意味着解码器解码消息成功。ByteToMessageDecoder 将会丢弃在累积缓冲里已经被读过的数据。请记得你不需要对多条消息调用 decode()，ByteToMessageDecoder 会持续调用 decode() 直到不放任何数据到 out 里。 96 | 97 | 现在我们有另外一个处理器插入到 [ChannelPipeline](http://netty.io/4.0/api/io/netty/channel/ChannelPipeline.html) 里，我们应该在 TimeClient 里修改 ChannelInitializer 的实现： 98 | 99 | ```java 100 | b.handler(new ChannelInitializer() { 101 | @Override 102 | public void initChannel(SocketChannel ch) throws Exception { 103 | ch.pipeline().addLast(new TimeDecoder(), new TimeClientHandler()); 104 | } 105 | }); 106 | ``` 107 | 108 | 如果你是一个大胆的人，你可能会尝试使用更简单的解码类[ReplayingDecoder](http://netty.io/4.0/api/io/netty/handler/codec/ReplayingDecoder.html)。不过你还是需要参考一下 API 文档来获取更多的信息。 109 | 110 | ```java 111 | public class TimeDecoder extends ReplayingDecoder { 112 | @Override 113 | protected void decode( 114 | ChannelHandlerContext ctx, ByteBuf in, List out) { 115 | out.add(in.readBytes(4)); 116 | } 117 | } 118 | ``` 119 | 120 | 此外，Netty 还提供了更多开箱即用的解码器使你可以更简单地实现更多的协议，帮助你避免开发一个难以维护的处理器实现。请参考下面的包以获取更多更详细的例子： 121 | 122 | - 对于二进制协议请看 [io.netty.example.factorial](http://netty.io/4.0/xref/io/netty/example/factorial/package-summary.html) 123 | - 对于基于文本协议请看 [io.netty.example.telnet](http://netty.io/4.0/xref/io/netty/example/telnet/package-summary.html) 124 | 125 | _译者注：翻译版本的项目源码见 中的`com.waylau.netty.demo.factorial` 和 `com.waylau.netty.demo.telnet` 包下_ 126 | -------------------------------------------------------------------------------- /Getting-Started/Writing-a-Discard-Server.md: -------------------------------------------------------------------------------- 1 | # Writing a Discard Server 写个抛弃服务器 2 | 3 | 世上最简单的协议不是'Hello, World!' 而是 [DISCARD(抛弃服务)](http://tools.ietf.org/html/rfc863)。这个协议将会抛弃任何收到的数据，而不响应。 4 | 5 | 为了实现 DISCARD 协议，你只需忽略所有收到的数据。让我们从 handler （处理器）的实现开始，handler 是由 Netty 生成用来处理 I/O 事件的。 6 | 7 | ```java 8 | import io.netty.buffer.ByteBuf; 9 | 10 | import io.netty.channel.ChannelHandlerContext; 11 | import io.netty.channel.ChannelInboundHandlerAdapter; 12 | 13 | /** 14 | * 处理服务端 channel. 15 | */ 16 | public class DiscardServerHandler extends ChannelInboundHandlerAdapter { // (1) 17 | 18 | @Override 19 | public void channelRead(ChannelHandlerContext ctx, Object msg) { // (2) 20 | // 默默地丢弃收到的数据 21 | ((ByteBuf) msg).release(); // (3) 22 | } 23 | 24 | @Override 25 | public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) { // (4) 26 | // 当出现异常就关闭连接 27 | cause.printStackTrace(); 28 | ctx.close(); 29 | } 30 | } 31 | ``` 32 | 33 | 1.DiscardServerHandler 继承自 [ChannelInboundHandlerAdapter](http://netty.io/4.0/api/io/netty/channel/ChannelInboundHandlerAdapter.html)，这个类实现了 [ChannelInboundHandler](http://netty.io/4.0/api/io/netty/channel/ChannelInboundHandler.html)接口，ChannelInboundHandler 提供了许多事件处理的接口方法，然后你可以覆盖这些方法。现在仅仅只需要继承 ChannelInboundHandlerAdapter 类而不是你自己去实现接口方法。 34 | 35 | 2.这里我们覆盖了 channelRead() 事件处理方法。每当从客户端收到新的数据时，这个方法会在收到消息时被调用，这个例子中，收到的消息的类型是 [ByteBuf](http://netty.io/4.0/api/io/netty/buffer/ByteBuf.html) 36 | 37 | 3.为了实现 DISCARD 协议，处理器不得不忽略所有接受到的消息。ByteBuf 是一个引用计数对象，这个对象必须显示地调用 release() 方法来释放。请记住处理器的职责是释放所有传递到处理器的引用计数对象。通常，channelRead() 方法的实现就像下面的这段代码： 38 | 39 | ```java 40 | @Override 41 | public void channelRead(ChannelHandlerContext ctx, Object msg) { 42 | try { 43 | // Do something with msg 44 | } finally { 45 | ReferenceCountUtil.release(msg); 46 | } 47 | } 48 | ``` 49 | 50 | 4.exceptionCaught() 事件处理方法是当出现 Throwable 对象才会被调用，即当 Netty 由于 IO 错误或者处理器在处理事件时抛出的异常时。在大部分情况下，捕获的异常应该被记录下来并且把关联的 channel 给关闭掉。然而这个方法的处理方式会在遇到不同异常的情况下有不同的实现，比如你可能想在关闭连接之前发送一个错误码的响应消息。 51 | 52 | 目前为止一切都还不错，我们已经实现了 DISCARD 服务器的一半功能，剩下的需要编写一个 main() 方法来启动服务端的 DiscardServerHandler。 53 | 54 | ```java 55 | import io.netty.bootstrap.ServerBootstrap; 56 | import io.netty.channel.ChannelFuture; 57 | import io.netty.channel.ChannelInitializer; 58 | import io.netty.channel.ChannelOption; 59 | import io.netty.channel.EventLoopGroup; 60 | import io.netty.channel.nio.NioEventLoopGroup; 61 | import io.netty.channel.socket.SocketChannel; 62 | import io.netty.channel.socket.nio.NioServerSocketChannel; 63 | /** 64 | * 丢弃任何进入的数据 65 | */ 66 | public class DiscardServer { 67 | private int port; 68 | public DiscardServer(int port) { 69 | this.port = port; 70 | } 71 | public void run() throws Exception { 72 | EventLoopGroup bossGroup = new NioEventLoopGroup(); // (1) 73 | EventLoopGroup workerGroup = new NioEventLoopGroup(); 74 | try { 75 | ServerBootstrap b = new ServerBootstrap(); // (2) 76 | b.group(bossGroup, workerGroup) 77 | .channel(NioServerSocketChannel.class) // (3) 78 | .childHandler(new ChannelInitializer() { // (4) 79 | @Override 80 | public void initChannel(SocketChannel ch) throws Exception { 81 | ch.pipeline().addLast(new DiscardServerHandler()); 82 | } 83 | }) 84 | .option(ChannelOption.SO_BACKLOG, 128) // (5) 85 | .childOption(ChannelOption.SO_KEEPALIVE, true); // (6) 86 | // 绑定端口，开始接收进来的连接 87 | ChannelFuture f = b.bind(port).sync(); // (7) 88 | 89 | // 等待服务器 socket 关闭 。 90 | // 在这个例子中，这不会发生，但你可以优雅地关闭你的服务器。 91 | f.channel().closeFuture().sync(); 92 | } finally { 93 | workerGroup.shutdownGracefully(); 94 | bossGroup.shutdownGracefully(); 95 | } 96 | } 97 | public static void main(String[] args) throws Exception { 98 | int port; 99 | if (args.length > 0) { 100 | port = Integer.parseInt(args[0]); 101 | } else { 102 | port = 8080; 103 | } 104 | new DiscardServer(port).run(); 105 | } 106 | } 107 | ``` 108 | 109 | 1. [NioEventLoopGroup](http://netty.io/4.0/api/io/netty/channel/nio/NioEventLoopGroup.html) 是用来处理 I/O 操作的多线程事件循环器，Netty 提供了许多不同的 [EventLoopGroup](http://netty.io/4.0/api/io/netty/channel/EventLoopGroup.html) 的实现用来处理不同的传输。在这个例子中我们实现了一个服务端的应用，因此会有 2 个 NioEventLoopGroup 会被使用。第一个经常被叫做‘boss’，用来接收进来的连接。第二个经常被叫做‘worker’，用来处理已经被接收的连接，一旦‘boss’接收到连接，就会把连接信息注册到‘worker’上。如何知道多少个线程已经被使用，如何映射到已经创建的 [Channel](http://netty.io/4.0/api/io/netty/channel/Channel.html)上都需要依赖于 EventLoopGroup 的实现，并且可以通过构造函数来配置他们的关系。 110 | 111 | 2. [ServerBootstrap](http://netty.io/4.0/api/io/netty/bootstrap/ServerBootstrap.html) 是一个启动 NIO 服务的辅助启动类。你可以在这个服务中直接使用 Channel，但是这会是一个复杂的处理过程，在很多情况下你并不需要这样做。 112 | 113 | 3. 这里我们指定使用 [NioServerSocketChannel](http://netty.io/4.0/api/io/netty/channel/socket/nio/NioServerSocketChannel.html) 类来举例说明一个新的 Channel 如何接收进来的连接。 114 | 115 | 4. 这里的事件处理类经常会被用来处理一个最近的已经接收的 Channel。[ChannelInitializer](http://netty.io/4.0/api/io/netty/channel/ChannelInitializer.html) 是一个特殊的处理类，他的目的是帮助使用者配置一个新的 Channel。也许你想通过增加一些处理类比如 DiscardServerHandler 来配置一个新的 Channel 或者其对应的[ChannelPipeline](http://netty.io/4.0/api/io/netty/channel/ChannelPipeline.html) 来实现你的网络程序。当你的程序变的复杂时，可能你会增加更多的处理类到 pipline 上，然后提取这些匿名类到最顶层的类上。 116 | 117 | 5. 你可以设置这里指定的 Channel 实现的配置参数。我们正在写一个 TCP/IP 的服务端，因此我们被允许设置 socket 的参数选项比如 tcpNoDelay 和 keepAlive。请参考 [ChannelOption](http://netty.io/4.0/api/io/netty/channel/ChannelOption.html) 和详细的 [ChannelConfig](http://netty.io/4.0/api/io/netty/channel/ChannelConfig.html) 实现的接口文档以此可以对 ChannelOption 的有一个大概的认识。 118 | 119 | 6. 你关注过 option() 和 childOption() 吗？option() 是提供给[NioServerSocketChannel](http://netty.io/4.0/api/io/netty/channel/socket/nio/NioServerSocketChannel.html) 用来接收进来的连接。childOption() 是提供给由父管道 [ServerChannel](http://netty.io/4.0/api/io/netty/channel/ServerChannel.html) 接收到的连接，在这个例子中也是 NioServerSocketChannel。 120 | 121 | 7. 我们继续，剩下的就是绑定端口然后启动服务。这里我们在机器上绑定了机器所有网卡上的 8080 端口。当然现在你可以多次调用 bind() 方法(基于不同绑定地址)。 122 | 123 | 恭喜！你已经熟练地完成了第一个基于 Netty 的服务端程序。 124 | --------------------------------------------------------------------------------