API - ctx - 《ThinkKoa 2.x 文档》 - 书栈网

ctx

Koa处理请求的过程：当请求到来的时候，会通过req和res来创建一个context (ctx)，然后执行中间件。Koa并没有改变req和res，而是通过req和res封装了一个ctx (context)对象，进行后面的逻辑处理。ThinkKoa在koa的基础上，给ctx对象扩展了一些实用的特性。

ctx.startTime

ThinkKoa扩展 think_trace中间件

request处理开始时间，用于输出和记录处理时长

ctx.version

ThinkKoa扩展 think_trace中间件

http协议版本

ctx.originalPath

ThinkKoa扩展 think_trace中间件

因为ctx.path在中间件处理的时候可能发生变化，originalPath属性保存原始请求path。

ThinkKoa扩展 think_cookie中间件

获取或者设置cookie值。options包括项

signed sign cookie 值
domain: '', // cookie所在的域名
path: '/', // cookie所在的路径
maxAge: 86400, // cookie有效时长
httpOnly: true, // 是否只用于http请求中获取
overwrite: false, // 是否允许重写
expires: new Date('2017-02-15') // cookie失效时间

如果options未传递，默认遵循http中间件的配置。可在项目中间件配置文件中进行定义：


/**
 * Middleware config
 * @return
 */
module.exports = {
    list: [], //加载的中间件列表
    config: { //中间件配置 
        http: {
            cookie: {
                domain: '',
                path: '/',
                ...
            }
        }
    }
};

ctx.querys([name, value])

ThinkKoa扩展 think_payload中间件

获取或构造querystring的值。

//获取所有querystring值
ctx.querys();
//获取某个querystring值
ctx.querys('username');
//构造querystring 值
ctx.querys('username', 'lin');
ctx.querys({
    username: 'lin',
    age: 22
})

ctx.post([name, value])

ThinkKoa扩展 think_payload中间件

获取或构造post传递的值。

//获取所有post传递的值
ctx.post();
//获取某个post传递的值
ctx.post('username');
//构造post传递的值
ctx.post('username', 'lin');
ctx.post({
    username: 'lin',
    age: 22
})

ctx.param([name])

ThinkKoa扩展 think_payload中间件

获取querystring或者post传递的值，其中同名的键post会覆盖querystring中的值。

//获取所有querystring和post传递的值
ctx.param();
//获取某个post传递的值,如果post中不存在,则查找querystring
ctx.param('username');

ctx.file([name])

ThinkKoa扩展 think_payload中间件

获取或构造form-data传递的文件。

//获取所有传递的文件
ctx.file();
//获取某个传递的文件
ctx.file('filename');
//构造传递的文件
ctx.file('filename', fileObject);

ctx.group

ThinkKoa扩展 think_router中间件

根据路由规则解析生成的模块名(单模块模式下为'')。

ctx.controller

ThinkKoa扩展 think_router中间件

根据路由规则解析生成的控制器名。

ctx.action

ThinkKoa扩展 think_router中间件

根据路由规则解析生成的方法名。

ctx.routers

ThinkKoa扩展 think_router中间件

项目路由规则集合。

ctx.session(name[, value, timeout])

ThinkKoa扩展 think_session中间件

获取或设置session。

//获取session
ctx.session('user');
//写入session
ctx.session('user', {'username': 'test'});
//写入session，30s过期
ctx.session('user', {'username': 'test'}, 30);

ctx.compile(templateFile, data)

ThinkKoa扩展 think_view中间件

调用模板解析引擎解析模板，返回解析后的内容。

templateFile 模板物理路径
data 模板变量Object

ctx.compile(process.env.APP_PATH + '/view/default/test.html', {data: 'hello world'});

ctx.render(templateFile, data[, charset, contentType])

ThinkKoa扩展 think_view中间件

调用模板解析引擎解析模板，将解析后的内容response输出(赋值给ctx.body)。

templateFile 模板物理路径
data 模板变量Object
charset 输出模板字符集
contentType 输出模板文档类型

ctx.render(process.env.APP_PATH + '/view/default/test.html', {data: 'hello world'});

ctx.req

koa原生

Node 的 request 对象.

ctx.res

koa原生

Node 的 response 对象.

绕开 Koa 的 response 处理是不支持的. 避免使用如下 node 属性:

res.statusCode
res.writeHead()
res.write()
res.end()

ctx.get(name)

koa原生

获取名为 name 的 header值:

ctx.get('user-agent');

ctx.set(name, value)

koa原生

设置 header值:

ctx.set('Cache-Control', `max-age=3000`);

ctx.type

koa原生

获取或设置response header中的content-type值:

console.log(ctx.type);
ctx.type = 'text/plain';

ctx.query

koa原生

获取querystring值:

console.log(ctx.query);

ctx.body

koa原生

设置返回的response：

ctx.body = 'hello world';

ctx.path

koa原生

request的pathname(ThinkKoa中的路由中间件会根据路由规则解析覆盖path值)。

ctx.cookies.get(name, [options])

koa原生

获取名为 name 带有 options 的 cookie:

signed 请求的 cookie 应该是被 signedkoa 使用 cookies 模块, options 被直接传递过去.

ctx.cookies.set(name, value, [options])

koa原生

设置 cookie name 为 value 带有 options:

signed sign cookie 值
domain: '', // cookie所在的域名
path: '/', // cookie所在的路径
maxAge: 86400, // cookie有效时长
httpOnly: true, // 是否只用于http请求中获取
overwrite: false, // 是否允许重写
expires: new Date('2017-02-15') // cookie失效时间

koa 使用 cookies 模块, options 被直接传递过去.

ctx.throw([msg], [status], [properties])

koa原生

Helper 方法, 抛出包含 .status 属性的错误, 默认为 500. 该方法让 Koa 能够合适的响应. 并且支持如下组合:

this.throw(403);
this.throw('name required', 400);
this.throw(400, 'name required');
this.throw('something exploded');

例如 this.throw('name required', 400) 等价于:

var err = new Error('name required');
err.status = 400;
throw err;

注意这些是 user-level 的错误, 被标记为 err.expose, 即这些消息可以用于 client 响应, 而不是 error message 的情况, 因为你不想泄露失败细节.

你可以传递一个 properties 对象, 该对象会被合并到 error 中, 这在修改传递给上游中间件的机器友好错误时非常有用

this.throw(401, 'access_denied', { user: user });
this.throw('access_denied', { user: user });

koa 使用 http-errors 创建错误对象.

ctx.assert(value, [msg], [status], [properties])

koa原生

抛出错误的 Helper 方法, 跟 .throw() 相似当 !value. 跟 node 的 assert() 方法相似.

this.assert(this.user, 401, 'User not found. Please login!');

koa 使用 http-assert 实现断言.

Request 别名

koa原生

如下访问器和别名同 Request 等价:

ctx.header
ctx.headers
ctx.method
ctx.url
ctx.originalUrl
ctx.path
ctx.query
ctx.querystring
ctx.host
ctx.hostname
ctx.fresh
ctx.stale
ctx.socket
ctx.protocol
ctx.secure
ctx.ip
ctx.ips
ctx.subdomains
ctx.is()
ctx.accepts()
ctx.acceptsEncodings()
ctx.acceptsCharsets()
ctx.acceptsLanguages()
ctx.get()

Response 别名

koa原生

如下访问器和别名同 Response 等价:

ctx.body
ctx.status
ctx.message
ctx.length
ctx.type
ctx.etag
ctx.lastModified
ctx.headerSent
ctx.redirect()
ctx.attachment()
ctx.set()
ctx.remove()

ctx

ctx

ctx.startTime

ctx.version

ctx.originalPath

ctx.cookie(name[, value, options = {}])

ctx.querys([name, value])

ctx.post([name, value])

ctx.param([name])

ctx.file([name])

ctx.group

ctx.controller

ctx.action

ctx.routers

ctx.session(name[, value, timeout])

ctx.compile(templateFile, data)

ctx.render(templateFile, data[, charset, contentType])

ctx.req

ctx.res

ctx.get(name)

ctx.set(name, value)

ctx.type

ctx.query

ctx.body

ctx.path

ctx.cookies.get(name, [options])

ctx.cookies.set(name, value, [options])

ctx.throw([msg], [status], [properties])

ctx.assert(value, [msg], [status], [properties])

Request 别名

Response 别名