由对ruff板子的一个技术文档和JSON.stringify引开来说的问题

JSON.stringify这个方法有啥用？

写这篇文档的原因其实是很简单的。 因为用ruff教学，我们要做一个试验，试验过程如下：

1. ruff发起请求。
2. 服务器收到ruff的请求。
3. 服务器转发给各个浏览器客户端。

问题来了！！

ruff发起http请求时，我们用的http.get方法 但是，根据ruff的文档，我的学生不知道如何获取服务器返回的数据。 当时情景如下：

学生问：堂主，如何获取返回数据啊。。看不懂了。（不许怪我学生，他是新手）
我说：怎么可能，文档很全的啊。
学生说：我不会，你教我一下。
我：小意思，我来！

我欢快的看了一眼API文档。嗯，跟node.js一毛一样。 迅速定位到http.get，然后，我也蒙逼了。 （文档链接在此：https://ruff.io/zh-cn/api/http.html） 不愿意看ruff文档的，可以看我这里。我帖出来了：

先看一下官方文档的说明

http.get(options[, callback])
Since most requests are GET requests without bodies, ruff provides this
convenience method. The only difference between this method and http.request()
is that it sets the method to GET and calls req.end() automatically.

再睁大狗眼看他傻逼样的样例代码： Example:

http.get("http://www.google.com/index.html", function(res) {
  console.log("Got response: " + res.statusCode);
}).on('error', function(e) {
  console.log("Got error: " + e.message);
});

这种文档看起来很清晰，但是这都需要人去填空思维的。 而且服务器端调试，很多新手没有老师指导，都不知道怎么进行下一步！？

反正，也许是年岁渐长，我越来越不喜欢记事，一般都是照着手册用。 我一看文档不清楚。

我说，

不要紧的，同学，当你看到这样的文档，不要慌，我们有万能的console.log啊，输出res回调的结构，打出来就可以了。

我哼着歌，在回调函数处加了一段console.log(res)，系统乖乖的喷了很长一串的字符出来。 我慢慢的翻着结构，很长一段，有4屏左右，也许是眼花了，没有找到我要的内容。

于是，我又说：

不要紧的，内容很多，很正常，来，我们用JSON.stringify这个大法，来把对象格式化成string,然后拷到外面来慢慢找

我又输入了下面的代码

http.get("http://www.google.com/index.html", function(res) {
  console.log(JSON.stringify(res));
}).on('error', function(e) {
  console.log("Got error: " + e.message);
});

结果，报错了！内容如下：

[Error: TypeError: cyclic input
                     /mnt/ssd/jenkins/jobs/ruff-mips/workspace/lib/duktape/src-separate/duk_bi_json.c:1725
                     stringify  native strict preventsyield
                     anon /ruff/app/src/index.js:19 strict preventsyield
                     apply  native strict preventsyield
                     _g ~embed~events:248 strict preventsyield
                     call  native strict preventsyield
                     emitOne ~embed~events:76 strict
                     emit ~embed~events:161 strict
                     parserOnIncomingClient /ruff/sdk/ruff_modules/http/src/http-client.js:359 strict
                     parserOnHeadersComplete /ruff/sdk/ruff_modules/http/src/http-common.js:90 strict
                     anon /ruff/sdk/ruff_modules/http/src/http-parser.js:295 strict
                     [...]]

各位朋友不要怕，这个文字的大体意思就是：不支持这个方法。

我想，不就是很简单的对象转字符串吗？怎么不行呢？我细细一想，不对，里面好像有null等数据类型。

群里的官方回答就是：

这东西的用法就是这样，我们完全仿node.js的http api文档写的。
（潜台词：我们也没辙，再说了node.js文档也那个屌样啊！）

呐尼？我是在用ruff教学哎。。。我的亲哥哥哎。我如此的喜欢ruff，特意跑到上海朝圣，听到这句我就不开心了。

于是，我怀着愤怒和不满，对着ruff的哥们一阵狂叫，把周爱民周大帅哥也扯了进来一起批评了一番。

那么，不管如何，我得解决这个问题啊。本文马上给出答案。

一共有两个问题要解决。

1，http的回调数据根本没有样例说明的问题。

文档的代码应改为：

http.get("http://www.google.com/index.html", function(res) {

      res.on('data', function(data){
           //这里是http请求后，返回的数据
           //无论是node.js还是ruff的文档，对于http api部分的介绍几乎都没有这一段。而这一段对于不熟悉回调的人来说，很致命！会让一个初学者在这个地方卡死。
        });

}).on('error', function(e) {
  console.log("Got error: " + e.message);
});

2，JSON.stringify的格式化某种对象无法成功，造成循环引用的问题。

解决代码如下：

var data = [];
//这里的调试数据使用回调中的res
JSON.stringify(res, function(key, val){
    if (val != null && typeof val == "Object") {
        if (data.indexOf(val) >= 0) {
            return ;
        }
        data.push(val)
    }
    return val;
});

好了，暂时说到这里。

临结尾，我来说两句我对技术文档的看法。

1，文档不是指定个技术人员去写，或者派个测试人员去写，就能写出好文档。
2，好文档应有自传播能力，让新手很快入门，让新手再带新手入门。
3，如果要运营某种技术社区，应该让文档去自动运营，而不是派人去四处吆喝。如果文档太差，吆喝的越多，自污染的可能性越大！
4，KPI应该有一项这样的指标：文档的回访率，或者，文档的用户粘度。这个指标上升，则文档成功！反之：失败！

最后，我想说一下：

不要因为别人如何如何，我就如何如何，而是我希望如何如何，所以这件事情就应该如何如何！