diff options
author | Francisco Souza <franciscossouza@gmail.com> | 2012-03-27 13:35:40 +1100 |
---|---|---|
committer | Andrew Gerrand <adg@golang.org> | 2012-03-27 13:35:40 +1100 |
commit | a786fe8e13d4cb9192ee98864ea4df91321a8665 (patch) | |
tree | 49d1cc9d186b6052784fa5041648cd5741254c09 | |
parent | 308cc100e63c7e5fc3c887aee37cb158ac829255 (diff) | |
download | go-a786fe8e13d4cb9192ee98864ea4df91321a8665.tar.gz go-a786fe8e13d4cb9192ee98864ea4df91321a8665.zip |
doc: add JSON-RPC: a tale of interfaces article
Originally published on The Go Programming Language Blog, Abril 27, 2010.
http://blog.golang.org/2010/04/json-rpc-tale-of-interfaces.html
R=adg, r
CC=golang-dev
https://golang.org/cl/5920044
-rw-r--r-- | doc/Makefile | 1 | ||||
-rw-r--r-- | doc/articles/json_rpc_tale_of_interfaces.html | 78 | ||||
-rw-r--r-- | doc/docs.html | 10 |
3 files changed, 84 insertions, 5 deletions
diff --git a/doc/Makefile b/doc/Makefile index da29e600b3..37deecab3e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,6 +12,7 @@ RAWHTML=\ articles/godoc_documenting_go_code.rawhtml\ articles/gobs_of_data.rawhtml\ articles/json_and_go.rawhtml\ + articles/json_rpc_tale_of_interfaces.rawhtml\ articles/image_draw.rawhtml\ effective_go.rawhtml\ go1.rawhtml\ diff --git a/doc/articles/json_rpc_tale_of_interfaces.html b/doc/articles/json_rpc_tale_of_interfaces.html new file mode 100644 index 0000000000..a545f55f61 --- /dev/null +++ b/doc/articles/json_rpc_tale_of_interfaces.html @@ -0,0 +1,78 @@ +<!--{ +"Title": "JSON-RPC: a tale of interfaces" +}--> + +<p> +Here we present an example where Go's +<a href="/doc/effective_go.html#interfaces_and_types">interfaces</a> made it +easy to refactor some existing code to make it more flexible and extensible. +Originally, the standard library's <a href="/pkg/net/rpc/">RPC package</a> used +a custom wire format called <a href="/pkg/encoding/gob/">gob</a>. For a +particular application, we wanted to use <a href="/pkg/encoding/json/">JSON</a> +as an alternate wire format. +</p> + +<p> +We first defined a pair of interfaces to describe the functionality of the +existing wire format, one for the client, and one for the server (depicted +below). +</p> + +<pre> +type ServerCodec interface { + ReadRequestHeader(*Request) error + ReadRequestBody(interface{}) error + WriteResponse(*Response, interface{}) error + Close() error +} +</pre> + +<p> +On the server side, we then changed two internal function signatures to accept +the <code>ServerCodec</code> interface instead of our existing +<code>gob.Encoder</code>. Here's one of them: +</p> + +<pre> +func sendResponse(sending *sync.Mutex, req *Request, + reply interface{}, enc *gob.Encoder, errmsg string) +</pre> + +<p> +became +</p> + +<pre> +func sendResponse(sending *sync.Mutex, req *Request, + reply interface{}, enc ServerCodec, errmsg string) +</pre> + +<p> +We then wrote a trivial <code>gobServerCodec</code> wrapper to reproduce the +original functionality. From there it is simple to build a +<code>jsonServerCodec</code>. +</p> + +<p> +After some similar changes to the client side, this was the full extent of the +work we needed to do on the RPC package. This whole exercise took about 20 +minutes! After tidying up and testing the new code, the +<a href="http://code.google.com/p/go/source/diff?spec=svn9daf796ebf1cae97b2fcf760a4ab682f1f063f29&r=9daf796ebf1cae97b2fcf760a4ab682f1f063f29&format=side&path=/src/pkg/rpc/server.go">final changeset</a> +was submitted. +</p> + +<p> +In an inheritance-oriented language like Java or C++, the obvious path would be +to generalize the RPC class, and create JsonRPC and GobRPC subclasses. However, +this approach becomes tricky if you want to make a further generalization +orthogonal to that hierarchy. (For example, if you were to implement an +alternate RPC standard). In our Go package, we took a route that is both +conceptually simpler and requires less code be written or changed. +</p> + +<p> +A vital quality for any codebase is maintainability. As needs change, it is +essential to adapt your code easily and cleanly, lest it become unwieldy to work +with. We believe Go's lightweight, composition-oriented type system provides a +means of structuring code that scales. +</p> diff --git a/doc/docs.html b/doc/docs.html index d94962845b..577166e15c 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -91,7 +91,7 @@ the Go team and guests.</p> <h4>Codewalks</h4> <p> -Guided tours of Go programs. +Guided tours of Go programs. </p> <ul> <li><a href="/doc/codewalk/functions">First-Class Functions in Go</a></li> @@ -102,7 +102,7 @@ Guided tours of Go programs. <h4>Language</h4> <ul> -<li><a href="http://blog.golang.org/2010/04/json-rpc-tale-of-interfaces.html">JSON-RPC: a tale of interfaces</a></li> +<li><a href="/doc/articles/json_rpc_tale_of_interfaces.html">JSON-RPC: a tale of interfaces</a></li> <li><a href="/doc/articles/gos_declaration_syntax.html">Go's Declaration Syntax</a></li> <li><a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a></li> <li><a href="/doc/articles/concurrency_patterns.html">Go Concurrency Patterns: Timing out, moving on</a></li> @@ -167,7 +167,7 @@ App Engine and renders images that it stores on Google Cloud Storage. A presentation delivered by Rob Pike and Russ Cox at Google I/O 2010. It illustrates how programming in Go differs from other languages through a set of examples demonstrating features particular to Go. These include concurrency, -embedded types, methods on any type, and program construction using interfaces. +embedded types, methods on any type, and program construction using interfaces. </p> <h3 id="practical_go_programming"><a href="http://www.youtube.com/watch?v=2-pPAvqyluI">Practical Go Programming</a><font color="red">*</font></h3> @@ -188,7 +188,7 @@ more Go talks. <h2 id="nonenglish">Non-English Documentation</h2> <p> -See the <a href="http://code.google.com/p/go-wiki/wiki/NonEnglish">NonEnglish</a> page +See the <a href="http://code.google.com/p/go-wiki/wiki/NonEnglish">NonEnglish</a> page at the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for localized documentation. </p> @@ -198,7 +198,7 @@ documentation. <img class="gopher" src="/doc/gopher/project.png"/> <h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3> -<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a> +<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a> mailing list is for general Go discussion.</p> <h3 id="projects"><a href="http://godashboard.appspot.com/project">Go Project Dashboard</a></h3> |