Express API 总结

最近学习了 express，在这里小小地总结一下，分别从app 相关 API、request 相关 API、 response 相关 API、router 相关 API 进行阐述。

express 属于一种 node 框架，所以在使用之前就必须要下载好 node，然后还要下载 express 框架.

命令： npm install express --save

express() 创建应用

express()是 express 模块导出的入口函数，用于创建一个 express 应用。

var express = require('express');

var app = express();

app 相关 API

如上所示，app 是创建的一个 express 应用，它具有很多 api，下面分别陈述。

1. app.set(name,value)

用于将设置项 name 的值设为 value。

示例：

app.set("age",18)

2. app.get(name)

用于获取设置项 name 的值。

示例：

app.get("age")
// => 18

3. app.enable(name)

用于将设置项 name 的值设为 true。

示例：

app.enable("isopen")
app.get("isopen")
// => true

4. app.disable(name)

用于将设置项 name 的值设为 false。

示例：

app.disable("isopen")
app.get("isopen")
// => false

5. app.enabled(name)

用于检查设置项 name 的值是否为 true。

示例：

app.enabled("isopen")

6. app.disabled(name)

用于检查设置项 name 的值是否为 false。

示例：

app.disabled("isopen")

7.app.listen()

在给定的主机和端口监听请求，可以同时处理 http 和 https 版本的服务。

示例：

app.listen(3000)

8.app.use()

用于使用 express 相关中间件，示例如下，其中挂载的路径不会在req里出现，对中间件 function 不可见，这就意味着在回调参数req里找不到path，这样设计的目的是让中间件不需要更改代码在任意前缀路径下执行。

示例：

app.use(function(req,res,next){
    console.log("req.method ->",req.method)
    next()
})

request 相关 API

下面陈列一些request常用的 API。

1.req.params

这是一个数组对象，命名过的参数会以键值对的形式存放。如有一个路由 /user/:id，那么 "id" 属性会存放在 req.param.id 中，而这个对象默认为 {}。对应的还有一个 api 是 req.param(name)，则会返回对应 name 参数的值。

2.req.query

这是一个解析过的请求参数对象，默认为{}，如有一个路由 /detail/id=123，那么 req.query.id 的值就为 123.

3.req.body

这是解析过的请求体，该对象默认为 {}。

4.req.route

这个对象里是当前匹配的 Route 里包含的属性，包括原始路径字符串、产生的正则、method、查询参数等。示例：

app.get("/user/:id?",function(req,res){
   console.log(req.route)
})
// 输出的结果是：
{ path: '/user/:id?',
  method: 'get',
  callbacks: [ [Function] ],
  keys: [ { name: 'id', optional: true } ],
  regexp: /^/user(?:/([^/]+?))?/?$/i,
  params: [ id: '12' ] }

4.req.cookies

使用 cookieParaser() 中间件后该对象默认为 {}，也包含用户代理传过来的 cookies。

5.req.get(field)

获取请求头里的 field 的值，注意是大小写不敏感的，其中 referrer 和 referer 字段是可以互换的。例如 req.get("Content-Type")。

6.req.accepts(types)

检查给定的 types 是不是可以接受类型，当可以接受时返回最匹配的，否则返回 undefined ，这个时候应该响应一个 406 "Not Acceptable"。示例：

// Accept:text/html
req.accepts("html")  // "html"
// Accept:text/*,application/json
req.accepts("html")  // "html"
req.accepts("text/html")  // "text/html"
req.accepts("json,text")  // "json"
req.accepts("image/png")  // undefined
req.accepts("png")  // undefined

7.req.is(type)

检查请求的文件头是不是包含 "Content-Type" 字段，它匹配给定的 type。

// Content-Type：text/html
req.is("html")  //true
req.is("text")  //true
req.is("text/html")  //true
req.is("json")  //false
req.is("application/json")  //false

其他的api，类如 req.is 返回远程地址，req.path 返回请求的 URL 的路径名， req.host 返回从"Host"请求头里取的主机名，不包含端口号，req.protocol 返回表示请求协议的字符串，一般是 "http"，当用tls 请求的时候返回的是"https"。

response 相关 API

下面陈列一些 response 相关 API。

1.res.status(code)

用于设置响应的 HTTP 状态，是 node 的 response.statusCode的链式调用。示例：

res.status(403).end()
res.status(400).send(Bad Request)
res.status(404).sendFile("/images/404.png")

2.res.set(field,[value])

设置响应头字段 field 值为 value，也可以一次传入一个对象设置多个值。示例：

res.set("Content-Type","text/plain")
res.set({
    "Content-Type":"text/plain",
    "Content-Length":"123",
    "ETag":"12345"
})

3.res.get(field)

返回一个大小写不敏感的响应头里的 field 的值。示例：

res.get("Content-Type")  // "text/plain"

4.res.cookie(name,value,[options])

设置 cookie name 值为 value，接受字符串参数或者JSON对象。path属性默认为 "/"。示例：

res.cookie("name","mary",{domain:".baidu.com",path:"/index",secure:true})
res.cookie("cart",{items:[1,2,3]})

5.res.clearCookie(name,[options])

把 name 的 cookie 清除，path 参数默认为"/"。如 res.clearCookie("name",{path:"/index"})

6.res.redirect([status],url)

使用可选的状态码跳转到 url，状态码 status 默认为 302 "Found"。express 支持几种跳转，第一种：使用一个完整的 URL 跳转到一个完全不同的网站，例 res.redirect("baidu.com ")；第二种是根据相对根域路径跳转，如当前在 "example.com "，则 res.redirect("/detail") 则是跳转到 "example.com/detail "。第三种是路径名跳转，res.redirect("..")是跳转到上一级网页，如当前在 "example.com/products/de… "，那么则会跳转至 "example.com/products "，res.redirect("back") 则是跳转到 referer 的地址，当 Referer 丢失的时候默认为 /。

7.res.send([body|status],[body])

发送一个响应，这个方法在输出响应的时候会自动完成大量有用的任务，比如定义前面没有定义的 Content-Length，加一些自动的 HEAD等。当参数为一个 Buffer 时 Content-Type 会被设置为 "application/octet-stream"，当参数为 String 时 Content-Type 默认设置为 "text/html"，当参数为 Array 或 Object 时 Express 会返回一个 JSON，当参数为 Number 时，express 会自动设置一个响应体，比如 200 会返回字符"OK"，404会返回 "Not Found" 等等。

8.res.json([status|body],[body])

返回一个 JSON 响应。当 res.send() 的参数是一个对象或者数组的时候会调用这个方法，它在复杂的空值(null,undefined,etc)JSON转换的时候有用。比如 res.json(null)， res.json({user:"mary"})，res.json(500,{error:"message"})

9.res.format(object)

设置特定请求头的响应，这个方法使用 req.accepted，执行第一个匹配的回调，当没有匹配时服务器会返回一个 406 "Not Acceptable" 或者执行 default 回调。示例：

res.format({
    "text/plain":function(){
        res.send("hi")
    },
    "text/html":function(){
        res.send("hey")
    },
    "application/json":function(){
        res.send({message:"boy"})
    }
})

上述代码在请求头为 "application/json" 或 "*/json" 的时候则会返回 "{message:'boy'}"

其他的api，类如 res.locals 指的是在某一次请求范围下的响应体的本地变量，只对此次请求期间的 views 可见，和 app.locals 是一样的。res.render(view,[locals],callback)渲染 view，同时向 callback 传入渲染后的字符串。

router 相关 API

一个 router 对象是一个单独的实例，可以认为是一个 "mini-application"，具有操作中间件和路由方法的能力，每一个express 程序有一个内建的app路由，路由自身表现为一个中间件，所以可以使用它作为app.use()方法的一个参数或者作为另一个路由的use()的参数。创建路由：

var router = express.Router([options])

可以在一个特别的根URL上挂在一个路由，这样就能把各个路由放在不同的文件中。示例：

app.use("/index",router)

1.router.all(path,[callback,...]callback)

会匹配所有的HTTP动作，对想映射全局的逻辑处理到特殊的路径前缀或者任意匹配是十分有用的，例如想要对从某个点开始的所有路由进行验证操作和自动加载用户信息，示例如下：

router.all("*",requireAuthentication,loadUser)

仅仅作用于以api开头的路径：

router.all("/api/*",requireAuthentication)

2.router.method(path,[callback,...]callback)

指的是router.get()，router.put()，router.post()等等，使用方式和router.all() 一样，若对匹配的path有特殊的限制，也可以使用正则表达式。示例：

router.get("/",function(req,res){
    res.send("hello world")
})

3.router.param(name,callback)

给路由参数添加回调触发器，name 指的是参数名，function 是回调方法，回调方法的参数依次是请求对象、响应对象、下个中间件、参数值和参数名，对于param的回调定义的路由来说，他们是局部的，不会被挂载的app或者路由继承，所以定义在router上的param回调只有是在router上的路由具有这个路由参数时才起作用。在定义param的路由上，param回调都是第一个被调用的，他们在一个请求-响应循环中都会被调用一次并且只有一次，即使多个路由都匹配。示例：

router.param("id",function(req,res,next,id){
    console.log("called only once")
})
router.get("/user/:id",function(req,res,next){
    console.log("although this matches")
    next()
})
router.get("/user/:id",function(req,res){
    console.log("and this matches too")
    res.end()
})

当 GET /user/43,得到下面的结果：

called only once
although this matches
and this matches too

4.router.route(path)

返回一个单例模式的路由的实例，之后可以在其上施加各种HTTP动作的中间件。示例：

router.param('user_id', function(req, res, next, id) {
    req.user = {
        id:id,
        name:"TJ"
    };
    next();
});
router.route('/users/:user_id')
    .all(function(req, res, next) {
        next();
    })
    .get(function(req, res, next) {
        res.json(req.user);
    })
    .put(function(req, res, next) {
        req.user.name = req.params.name;
        res.json(req.user);
    })
    .post(function(req, res, next) {
        next(new Error('not implemented'));
    })
    .delete(function(req, res, next) {
        next(new Error('not implemented'));
    })

5.router.use([path],[function,...]function)

给可选的 path 参数指定的路径挂载给定的中间件方法，未指定 path 参数时默认为 /，类似于app.use()方法。

本文参考：

express中文文档

菜鸟教程