JSOC
-
### Getting start
-
first , star this repositorie
-
install dependencies
npm install jsoc -g -
Is that OK?
jsoc -v
-
-
### jsoc entity
jsoc entity 是描述一个字段属性的一种方式。
在这里，字段被一系列属性来描述，比如：
_type,_length,_required等等，我们将在附录里完整地罗列出这些属性。 要很好地使用jsoc，需要充分熟悉每个属性的作用。为此，你可能要花10分钟来浏览一下 附录b 。
你并不需要立刻就熟记这些内容，现阶段，我们只要看一个例子就够了
username : { _type: 'string', _required: true, _from: 'username', _default: 'Tom' }上面的例子表示，username 这个字段，是一个
string类型，并且是必须的, 它的值可以从暂存区加载（什么是暂存区?）, 当暂存区无法提供时，默认值为Tom。 -
### jsoc comment
jsoc comment 是我们代码里注释的一种写法，用来描述一个接口
我们看一下这段注释：
/** * @jsoc.host http://127.0.0.1:3001 */ /** * @jsoc * name:api1 * desc:a demo doc * group:test * request * method:get * uri:/demo/{id} * params * id * _type:number * _required:true * query * page * _from:pageNum * _type:number * _default:1 * response * body * code * _type:number * _assert:200 * data * _type:object * message * _type:string * _required:false */第一段注释，直观地表名这套接口的
host地址。重点在第二段，这是描述一个接口的模板，通过缩进2空格来表达层级关系，
我们逐行解构一下：
-
@jsoc
开始标记，表明这是一段 jsoc comment -
name:api1
这是接口名字 ， api1 -
desc: a demo doc
描述，简要描述接口的作用 -
group:test
接口分组，后续会支持这个功能，暂时没啥用 -
request
注意 ！ request后面什么都没有，并且从下一行开始多了一级缩进， 这里表示request是个对象。 -
method:get
这个接口使用的http方法 -
uri:/demo/{id}
表达了接口的 uri ，这里可以支持占位符({id})， -
params ...
params id _type:number _required:true 这里又是利用缩进来表达层次关系， 表示params这个对象，包含一个 id 属性， id 是必填参数，类型为 number 我们可以通过一个json对象来理解这一段注释： params:{ id:{ _type:'number', _required:true } } P.S. params和uri的关系？就是params描述了uri里的占位符 。 -
query , headers , body
基本和params一个模式，分别表示http请求中的几个关键，但并不是都必须的。 一个足够简单的接口，甚至只有 method 、 uri 就够了 -
response
和request对应的，这个是用来描述返回信息的。 headers并不是必须，但是body是需要的。 从上面这个例子里，我们这个接口可能会返回一下数据 { code:200, data:{}, message:'success' } -
jsoc entity 的深层嵌套
jsoc entity是支持嵌套的， 比如上面的data字段，你可以只表明它是一个 object. 又或者你可以更进一步描述这个object内部结构： code _type:number _assert:200 data name _type:string age _type:number address _type:string message: _type:string _required:false 像这样，我们就能够描述data里面的结构，理论上是支持无限等次的。
-
-
### jsoc document(markdown)
当我们写好
jsoc comment,我们可以通过简单的命令生成一份markdown格式的接口文档。Step 1 ： 生成接口json描述文件
jsoc -g {path_of_comment} -o {output_file} path_of_comment 是你编写jsoc comment的文件，也可以是一个目录。 output_file 生成的文件名 例子： jsoc -g route_demo/demo.js -o demo.js 将会在 {jsoc_home}/plans/ 下生成一个 demo.js文件， 生成的是一个标准 node module 。Step 2 ： 生成md文档文件
jsoc -m demo 这里的 demo 指的是plans目录下的文件名（不含 .js ） 以上命令自动在 plans 目录生成一份 demo.md 文件。 （暂不支持指定目录） -
### jsoc mock
json描述文件是
jsoc很重要的部分，通过jsoc --gen生成以后， 就能使用其他jsoc功能，比如 mock 。假设你已经顺利生成
plans/demo.js，否则请看前面章节。执行命令：
jsoc --mock demo如果
mock成功，将会看到看到Mock in demo listen on port:3001,ip:null . . <------ nobody care about this point!!此时打开浏览器，尝试访问
http://127.0.0.1:3001/demo/1(前面章节定义的接口)深入学习
jsoc entity描述，可以定制出更加丰富的返回格式， 在mock中就能模拟出更加复杂的数据。 -
### jsoc test
jsoc有一个激动人心的功能，可以测试在线接口，这是jsoc最精髓部分。前面我们定义
demo的时候，有一个jsoc.host， 如果我们正确地输入一个正在运行的线上地址，比如http://mydomain.com。那么我们可以使用一套
jsoc命令来自动构建请求，测试接口的正确性。基本用法
jsoc {planName} [option]以
demo为例：列出 demo 的全部接口
jsoc demo -l查看某个接口的描述
jsoc demo -a api1 -i构造
http请求测试某个接口jsoc demo -a api1 [-b] 执行结果： 测试接口：［api1] { code : true data : true } 表示返回结果的code和data都符合预期。 如果你想看到这个请求的详细信息，可以加上 -b 参数，将会打印请求体和返回体。 -
### 附录
A . jsoc test进阶用法
这一节我们详细说说 jsoc test的各种参数。
基本格式： jsoc demo [options]
-
-l / --list
返回一个数组，列出demo所有的接口。 -
-a / --api
指定测试的接口名， -
-b / --body
打印请求、返回的详细信息。 -
-d / --data
注入数据的方式，举个例子，比如前面 demo 里的query query page _from:pageNum _type:number _default:1 你可以用 jsoc demo -a api1 -d.pageNum 2 来注入page的值， 如果你不这么做，page就是默认值 1 。 -d 支持另一种格式,要求是标准的json字符串，书写比较麻烦 jsoc demo -a api1 -d '{"pageNum":2}' 如果需要注入多个参数，除了使用json字符串，第一种方式也是可以的 jsoc demo -a api1 -d.pageNum 2 -d.other 3 -d.more 4 -
一次性测试多个接口
如果忽略 -a 参数，会默认按照你书写的顺序全部接口测试一遍。 jsoc demo 测试接口：［api1] 测试接口：［api2] 测试接口：［api3] ... 有时我们并不希望这样，我们希望自行决定测试哪些接口，自行决定调用顺序。 万幸，-a 是支持多个接口的，下面是例子 jsoc ucenterApi -a create,auth,getProfile 将会按照create,auth,getProfile的顺序进行测试 
B . jsoc entity 深入
下面详解一下jsoc entity每个描述带来
（未完）