From a786fe8e13d4cb9192ee98864ea4df91321a8665 Mon Sep 17 00:00:00 2001 From: Francisco Souza Date: Tue, 27 Mar 2012 13:35:40 +1100 Subject: [PATCH] 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 --- doc/Makefile | 1 + doc/articles/json_rpc_tale_of_interfaces.html | 78 +++++++++++++++++++ doc/docs.html | 10 +-- 3 files changed, 84 insertions(+), 5 deletions(-) create mode 100644 doc/articles/json_rpc_tale_of_interfaces.html 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 @@ + + +

+Here we present an example where Go's +interfaces made it +easy to refactor some existing code to make it more flexible and extensible. +Originally, the standard library's RPC package used +a custom wire format called gob. For a +particular application, we wanted to use JSON +as an alternate wire format. +

+ +

+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). +

+ +
+type ServerCodec interface {
+	ReadRequestHeader(*Request) error
+	ReadRequestBody(interface{}) error
+	WriteResponse(*Response, interface{}) error
+	Close() error
+}
+
+ +

+On the server side, we then changed two internal function signatures to accept +the ServerCodec interface instead of our existing +gob.Encoder. Here's one of them: +

+ +
+func sendResponse(sending *sync.Mutex, req *Request,
+	reply interface{}, enc *gob.Encoder, errmsg string)
+
+ +

+became +

+ +
+func sendResponse(sending *sync.Mutex, req *Request,
+		reply interface{}, enc ServerCodec, errmsg string)
+
+ +

+We then wrote a trivial gobServerCodec wrapper to reproduce the +original functionality. From there it is simple to build a +jsonServerCodec. +

+ +

+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 +final changeset +was submitted. +

+ +

+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. +

+ +

+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. +

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.

Codewalks

-Guided tours of Go programs. +Guided tours of Go programs.