jsoc: A JavaScript repository from captainblue2013

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的顺序进行测试
![](http://lanhao.name/img/upload/jsoc_01.png)

B . jsoc entity 深入

下面详解一下jsoc entity每个描述带来（未完）

captainblue2013/jsoc

JSOC

Getting start

jsoc entity

jsoc comment

jsoc document(markdown)

jsoc mock

jsoc test

附录

A . jsoc test进阶用法

B . jsoc entity 深入