koa源码阅读之request.js与response.js

这个源码阅读我是想将旁支末梢先捋顺了。再进入主程的application
Response与Request主要是对原生createServer的req可读流 res可写流做二次封装

Response.js

/**
 * Prototype.
 */

module.exports = {

  /**
   * Return the request socket.
   *
   * @return {Connection}
   * @api public
   */
    //定义一个getter 获得req.socket
  get socket() {
    return this.ctx.req.socket;
  },

  /**
   * Return response header.
   *
   * @return {Object}
   * @api public
   */
    //返回一个response header
    //这里做了个版本的兼容 用getHeaders 来判断版本兼容方法
  get header() {
    const { res } = this;
    return typeof res.getHeaders === 'function'
      ? res.getHeaders()
      : res._headers || {};  // Node < 7.7
  },

  /**
   * Return response header, alias as response.header
   *
   * @return {Object}
   * @api public
   */
    
  //定义一个getter 也就是headers 其实是header的别名
  get headers() {
    return this.header;
  },

  /**
   * Get response status code.
   *
   * @return {Number}
   * @api public
   */
  //定义一个seeter 用来返回res的statusCode
  get status() {
    return this.res.statusCode;
  },

  /**
   * Set response status code.
   *
   * @param {Number} code
   * @api public
   */
  //设置status
  set status(code) {
    assert('number' == typeof code, 'status code must be a number');
    //检测是否为数字
    assert(statuses

, `invalid status code: ${code}`);
//判断是否存在这个状态码
assert(!this.res.headersSent, 'headers have already been sent');
//判断响应是否已发送
this._explicitStatus = true;
//这里有一个私有变量
//作为一个标记如果这个为false后面会自动设置状态码
this.res.statusCode = code;
//设置res.statusCode
this.res.statusMessage = statuses

;
//设置status message statuses是一些状态码与常见回应的字符串例如404 :not found这种
if (this.body && statuses.empty

) this.body = null;
//如果状态码不在http状态码内 body=null不应答
},

/**
* Get response status message
*
* @return {String}
* @api public
*/
//获得statusMessage不存在就根据状态码从statuses取
get message() {
return this.res.statusMessage || statuses[this.status];
},

/**
* Set response status message
*
* @param {String} msg
* @api public
*/
//设置statusMessage 用的还是res
set message(msg) {
this.res.statusMessage = msg;
},

/**
* Get response body.
*
* @return {Mixed}
* @api public
*/
//getter 返回响应的body

get body() {
return this._body;
},

/**
* Set response body.
*
* @param {String|Buffer|Object|Stream} val
* @api public
*/
//设置响应的body
set body(val) {
const original = this._body;
this._body = val;
//使用一个私有变量来记录这个值

if (this.res.headersSent) return;
//判断响应体是否发送了

// no content
//如果body为空
if (null == val) {
if (!statuses.empty[this.status]) this.status = 204;
this.remove('Content-Type');
this.remove('Content-Length');
this.remove('Transfer-Encoding');
return;
}
//设置状态码(_explicitStatus上面有这个标记)
// set the status
if (!this._explicitStatus) this.status = 200;

// set the content-type only if not yet set
const setType = !this.header['content-type'];

//根据传入的value 进行不同的处理
// string
if ('string' == typeof val) {
if (setType) this.type = /^\s*</.test(val) ? 'html' : 'text';
this.length = Buffer.byteLength(val);
return;
}

// buffer
if (Buffer.isBuffer(val)) {
if (setType) this.type = 'bin';
this.length = val.length;
return;
}

// stream
if ('function' == typeof val.pipe) {
onFinish(this.res, destroy.bind(null, val));
ensureErrorHandler(val, err => this.ctx.onerror(err));

// overwriting
if (null != original && original != val) this.remove('Content-Length');

if (setType) this.type = 'bin';
return;
}

// json
//remove方法是移除header某个字段
this.remove('Content-Length');
this.type = 'json';
},

/**
* Set Content-Length field to `n`.
*
* @param {Number} n
* @api public
*/
//设置content-length根据传入一个值
set length(n) {
this.set('Content-Length', n);
},

/**
* Return parsed response Content-Length when present.
*
* @return {Number}
* @api public
*/
// getter 获得content-length
get length() {
const len = this.header['content-length'];
const body = this.body;
//如果content-length为空
//则根据我们自己的方法来获得这个body响应体的length
if (null == len) {
if (!body) return;
if ('string' == typeof body) return Buffer.byteLength(body);
if (Buffer.isBuffer(body)) return body.length;
if (isJSON(body)) return Buffer.byteLength(JSON.stringify(body));
return;
}
//这位运算返回一个number
return ~~len;
},

/**
* Check if a header has been written to the socket.
*
* @return {Boolean}
* @api public
*/
//返回res.headersSent
get headerSent() {
return this.res.headersSent;
},

/**
* Vary on `field`.
*
* @param {String} field
* @api public
*/
/* 给vary添加field 用于代理服务器的缓存控制
* 服务器为 Vary 设置一组 header,告诉代理服务器该如何使用缓存。
* 在后续的请求中,代理服务器只对请求中包含相同的 header 返回缓存。
*/
vary(field) {
vary(this.res, field);
},

/**
* Perform a 302 redirect to `url`.
*
* The string "back" is special-cased
* to provide Referrer support, when Referrer
* is not present `alt` or "/" is used.
*
* Examples:
*
* this.redirect('back');
* this.redirect('back', '/index.html');
* this.redirect('/login');
* this.redirect('http://google.com');
*
* @param {String} url
* @param {String} [alt]
* @api public
*/
//提供302重定向
//两个参数 一个url 一个alt
//如果url为'back'的时候我们获取它的Referrer来源
//在进行跳转到这个location
redirect(url, alt) {
// location
if ('back' == url) url = this.ctx.get('Referrer') || alt || '/';
this.set('Location', url);

// status
//如果不在跳转状态码内就设定302
if (!statuses.redirect[this.status]) this.status = 302;

// html
//accept type如果为html
if (this.ctx.accepts('html')) {
url = escape(url);
this.type = 'text/html; charset=utf-8';
//设置一个跳转
this.body = `Redirecting to <a href="${url}">${url}</a>.`;
return;
}

// text
//不然的话就文本描述跳转
this.type = 'text/plain; charset=utf-8';
this.body = `Redirecting to ${url}.`;
},

/**
* Set Content-Disposition header to "attachment" with optional `filename`.
*
* @param {String} filename
* @api public
*/
//将Content-Disposition标题设置为可选的`filename`为“attachment”。
//也就是说将filename包裹成我们熟悉的acttachment;filename = xxx
//用作消息主体的时候
//https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Content-Disposition

attachment(filename) {
if (filename) this.type = extname(filename);
this.set('Content-Disposition', contentDisposition(filename));
},

/**
* Set Content-Type response header with `type` through `mime.lookup()`
* when it does not contain a charset.
*
* Examples:
*
* this.type = '.html';
* this.type = 'html';
* this.type = 'json';
* this.type = 'application/json';
* this.type = 'png';
*
* @param {String} type
* @api public
*/
//设置content-type
//被允许的时候为添加,不被允许为删除
set type(type) {
type = getType(type);
if (type) {
this.set('Content-Type', type);
} else {
this.remove('Content-Type');
}
},
//lastModified 用于web缓存的
/**
* Set the Last-Modified date using a string or a Date.
*
* this.response.lastModified = new Date();
* this.response.lastModified = '2013-09-13';
*
* @param {String|Date} type
* @api public
*/

set lastModified(val) {
if ('string' == typeof val) val = new Date(val);
this.set('Last-Modified', val.toUTCString());
},
//get last-modified
/**
* Get the Last-Modified date in Date form, if it exists.
*
* @return {Date}
* @api public
*/

get lastModified() {
const date = this.get('last-modified');
if (date) return new Date(date);
},

/**
* Set the ETag of a response.
* This will normalize the quotes if necessary.
*
* this.response.etag = 'md5hashsum';
* this.response.etag = '"md5hashsum"';
* this.response.etag = 'W/"123456789"';
*
* @param {String} etag
* @api public
*/
//设置etag
set etag(val) {
if (!/^(W\/)?"/.test(val)) val = `"${val}"`;
this.set('ETag', val);
},

/**
* Get the ETag of a response.
*
* @return {String}
* @api public
*/
//获得etag值
get etag() {
return this.get('ETag');
},

/**
* Return the response mime type void of
* parameters such as "charset".
*
* @return {String}
* @api public
*/
//获得content ;分割的前面部分
//类似这种Content-Type: multipart/form-data;boundary=something
get type() {
const type = this.get('Content-Type');
if (!type) return '';
return type.split(';')[0];
},

/**
* Check whether the response is one of the listed types.
* Pretty much the same as `this.request.is()`.
*
* @param {String|Array} types...
* @return {String|false}
* @api public
*/

is(types) {
const type = this.type;
if (!types) return type || false;
if (!Array.isArray(types)) types = [].slice.call(arguments);
//检查是否被允许 允许就返回对应的值
return typeis(type, types);
},

/**
* Return response header.
*
* Examples:
*
* this.get('Content-Type');
* // => "text/plain"
*
* this.get('content-type');
* // => "text/plain"
*
* @param {String} field
* @return {String}
* @api public
*/
//返回响应头
//这边得到某个头部信息都转化成小写
get(field) {
return this.header[field.toLowerCase()] || '';
},

/**
* Set header `field` to `val`, or pass
* an object of header fields.
*
* Examples:
*
* this.set('Foo', ['bar', 'baz']);
* this.set('Accept', 'application/json');
* this.set({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
*
* @param {String|Object|Array} field
* @param {String} val
* @api public
*/
//设置header字段或者值 or 传递头部字段的对象。
set(field, val) {
if (2 == arguments.length) {
if (Array.isArray(val)) val = val.map(String);
else val = String(val);
this.res.setHeader(field, val);
} else {
for (const key in field) {
this.set(key, field[key]);
}
}
},

/**
* Append additional header `field` with value `val`.
*
* Examples:
*
* ```
* this.append('Link', ['<http://localhost/>', '<http://localhost:3000/>']);
* this.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly');
* this.append('Warning', '199 Miscellaneous warning');
* ```
*
* @param {String} field
* @param {String|Array} val
* @api public
*/
//附加额外的头部字段值
append(field, val) {
const prev = this.get(field);

if (prev) {
val = Array.isArray(prev)
? prev.concat(val)
: [prev].concat(val);
}

return this.set(field, val);
},
//删除头部字段
/**
* Remove header `field`.
*
* @param {String} name
* @api public
*/

remove(field) {
this.res.removeHeader(field);
},

/**
* Checks if the request is writable.
* Tests for the existence of the socket
* as node sometimes does not set it.
*
* @return {Boolean}
* @api private
*/
//检查请求是否可写
get writable() {
// can't write any more after response finished
//判断流是否结束
if (this.res.finished) return false;

const socket = this.res.socket;
// There are already pending outgoing res, but still writable
// https://github.com/nodejs/node/blob/v4.4.7/lib/_http_server.js#L486
if (!socket) return true;
return socket.writable;
},

/**
* Inspect implementation.
*
* @return {Object}
* @api public
*/
//Inspect
//当我们在内部console.log(this)时候默认调用这个方法
//
inspect() {
if (!this.res) return;
const o = this.toJSON();
o.body = this.body;
return o;
},

/**
* Return JSON representation.
*
* @return {Object}
* @api public
*/
//返回json表示
toJSON() {
return only(this, [
'status',
'message',
'header'
]);
},

/**
* Flush any set headers, and begin the body
*/
flushHeaders() {
this.res.flushHeaders();
}
};

Request.js

/**
 * Prototype.
 */

module.exports = {
  //以下三个跟response相似只是对象不同了
  get header() {
    return this.req.headers;
  },

  set header(val) {
    this.req.headers = val;
  },

  get headers() {
    return this.req.headers;
  },

  set headers(val) {
    this.req.headers = val;
  },
  //返回请求的url字符串
  get url() {
    return this.req.url;
  },

  // 设置url地址 用于进行 url 重写
  set url(val) {
    this.req.url = val;
  },
  // getter获得origin
  // 请求首部字段 Origin 指示了请求来自于哪个站点
  get origin() {
    return `${this.protocol}://${this.host}`;
  },

  /**
   * Get full request URL.
   *
   * @return {String}
   * @api public
   */
  // 获得request完全地址
  get href() {
    // support: `GET http://example.com/foo`
    if (/^https?:\/\//i.test(this.originalUrl)) return this.originalUrl;
    return this.origin + this.originalUrl;
  },

  //获得请求方法
  get method() {
    return this.req.method;
  },

  //设置请求方法
  set method(val) {
    this.req.method = val;
  },

  // 返回请求 pathname
  get path() {
    return parse(this.req).pathname;
  },

  //设置pathname  如果原url有查询字符串queryString的话会得到保留
  set path(path) {
    const url = parse(this.req);
    if (url.pathname === path) return;

    url.pathname = path;
    url.path = null;

    this.url = stringify(url);
  },

  // 获得解析过后的查询字符串 ?xxx=123&abc=878这些
  get query() {
    const str = this.querystring;
    const c = this._querycache = this._querycache || {};
    return c[str] || (c[str] = qs.parse(str));
  },

  // 设置一个对象做查询字符串
  set query(obj) {
    this.querystring = qs.stringify(obj);
  },


  //返回 url 中的查询字符串,去除了头部的 '?'
  get querystring() {
    if (!this.req) return '';
    return parse(this.req).query || '';
  },

    //设置查询字符串
  set querystring(str) {
    const url = parse(this.req);
    if (url.search === `?${str}`) return;

    url.search = str;
    url.path = null;

    this.url = stringify(url);
  },
    //返回url中的查询字符串包括?
  get search() {
    if (!this.querystring) return '';
    return `?${this.querystring}`;
  },
  //设置查询字符串包含?
  set search(str) {
    this.querystring = str;
  },
  // 获得请求主机名 不包含端口 
  // 如果app.proxy为true 支持X-Forwarded-Host
  get host() {
    const proxy = this.app.proxy;
    let host = proxy && this.get('X-Forwarded-Host');
    host = host || this.get('Host');
    if (!host) return '';
    return host.split(/\s*,\s*/)[0];
  },

  //加了个ipv6支持
  get hostname() {
    const host = this.host;
    if (!host) return '';
    if ('[' == host[0]) return this.URL.hostname || ''; // IPv6
    return host.split(':')[0];
  },

  /**
   * Get WHATWG parsed URL.
   * Lazily memoized.
   *
   * @return {URL|Object}
   * @api public
   */
  //这是一个新加的
  //因为以前的一些[::]:80解析出错
  //就使用这个做解析
  //https://github.com/koajs/koa/commit/327b65cb6b86e31285cbe5c423505da15ca589f6
  get URL() {
    if (!this.memoizedURL) {
      const protocol = this.protocol;
      const host = this.host;
      const originalUrl = this.originalUrl || ''; // avoid undefined in template string
      try {
        this.memoizedURL = new URL(`${protocol}://${host}${originalUrl}`);
      } catch (err) {
        this.memoizedURL = Object.create(null);
      }
    }
    return this.memoizedURL;
  },

  //检查请求是否足够新 也就是检查Last-Modified(和/或)ETag仍然匹配
  //当缓存为最新时,可编写业务逻辑直接返回 304
  get fresh() {
    const method = this.method;
    const s = this.ctx.status;

    // GET or HEAD for weak freshness validation only
    if ('GET' != method && 'HEAD' != method) return false;

    // 2xx or 304 as per rfc2616 14.26
    if ((s >= 200 && s < 300) || 304 == s) {
      return fresh(this.header, this.ctx.response.header);
    }

    return false;
  },
  //检查如果请求过时了,又称为"Last-Modified" and / or the "ETag"资源被改变
  get stale() {
    return !this.fresh;
  },

  //检查请求是否是幂等的。
//一个幂等操作的特点是其任意多次执行所产生的影响均与一次执行的影响相同
  get idempotent() {
    const methods = ['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS', 'TRACE'];
    return !!~methods.indexOf(this.method);
  },
  //返回request资源链接socket
  get socket() {
    return this.req.socket;
  },
  //当存在或未定义时获取charset。
  //content-type:text/html; charset=utf-8
  get charset() {
    let type = this.get('Content-Type');
    if (!type) return '';

    try {
      type = contentType.parse(type);
    } catch (e) {
      return '';
    }

    return type.parameters.charset || '';
  },

  /**
   * Return parsed Content-Length when present.
   *
   * @return {Number}
   * @api public
   */
//返回content-length
//返回一个number
  get length() {
    const len = this.get('Content-Length');
    if (len == '') return;
    return ~~len;
  },

  /**
   * Return the protocol string "http" or "https"
   * when requested with TLS. When the proxy setting
   * is enabled the "X-Forwarded-Proto" header
   * field will be trusted. If you're running behind
   * a reverse proxy that supplies https for you this
   * may be enabled.
   *
   * @return {String}
   * @api public
   */
/*
   * 如果socket被加密了直接返回https
   * 返回协议字符串http或者https当请求是使用TLS(传输层安全协议),当proxy代理设置被支持X-Forwarded-Proto头部
   * 字段,如果你运行了一个反向代理为你提供https 这也许可以被支持
*/
  get protocol() {
    const proxy = this.app.proxy;
    if (this.socket.encrypted) return 'https';
    if (!proxy) return 'http';
    const proto = this.get('X-Forwarded-Proto') || 'http';
    return proto.split(/\s*,\s*/)[0];
  },

  /**
   * Short-hand for:
   *
   *    this.protocol == 'https'
   *
   * @return {Boolean}
   * @api public
   */
  //'https' == this.protocol;
  get secure() {
    return 'https' == this.protocol;
  },

  /**
   * When `app.proxy` is `true`, parse
   * the "X-Forwarded-For" ip address list.
   *
   * For example if the value were "client, proxy1, proxy2"
   * you would receive the array `["client", "proxy1", "proxy2"]`
   * where "proxy2" is the furthest down-stream.
   *
   * @return {Array}
   * @api public
   */
   /* 当app.proxy为true的时候 解析X-Forwarded-For ip地址列表
   * 例如如果那个值为 client, proxy1, proxy2
   * 你会得到一个数组 其中”proxy2“是最远的下游。
   */
  get ips() {
    const proxy = this.app.proxy;
    const val = this.get('X-Forwarded-For');
    return proxy && val
      ? val.split(/\s*,\s*/)
      : [];
  },

/*
   * 返回请求对象中的子域名数组。子域名数组会自动由请求域名字符串中的 . 分割开,
   * 在没有设置自定义的 app.subdomainOffset 参数时,默认返回根域名之前的所有子域名数组。
   * 获得子域
*/
  get subdomains() {
    const offset = this.app.subdomainOffset;
    const hostname = this.hostname;
    if (net.isIP(hostname)) return [];
    return hostname
      .split('.')
      .reverse()
      .slice(offset);
  },

  /**
   * Check if the given `type(s)` is acceptable, returning
   * the best match when true, otherwise `false`, in which
   * case you should respond with 406 "Not Acceptable".
   *
   * The `type` value may be a single mime type string
   * such as "application/json", the extension name
   * such as "json" or an array `["json", "html", "text/plain"]`. When a list
   * or array is given the _best_ match, if any is returned.
   *
   * Examples:
   *
   *     // Accept: text/html
   *     this.accepts('html');
   *     // => "html"
   *
   *     // Accept: text/*, application/json
   *     this.accepts('html');
   *     // => "html"
   *     this.accepts('text/html');
   *     // => "text/html"
   *     this.accepts('json', 'text');
   *     // => "json"
   *     this.accepts('application/json');
   *     // => "application/json"
   *
   *     // Accept: text/*, application/json
   *     this.accepts('image/png');
   *     this.accepts('png');
   *     // => false
   *
   *     // Accept: text/*;q=.5, application/json
   *     this.accepts(['html', 'json']);
   *     this.accepts('html', 'json');
   *     // => "json"
   *
   * @param {String|Array} type(s)...
   * @return {String|Array|false}
   * @api public
   */
  /*
   * 检测type是否合法
   * 匹配返回你想要的值默认返回全部
   * 当请求头中不包含 Accept 属性时,给定的第一个 type 将会被返回。
   */
  accepts(...args) {
    return this.accept.types(...args);
  },
/**
   *    返回一个可接受的编码。优先级如下
   * 也可以指定返回没有就返回false
   *     ['gzip', 'deflate']
*/
  acceptsEncodings(...args) {
    return this.accept.encodings(...args);
  },
/*
   *返回被接收的charset或最适合基于charsets的 
   * Return accepted charsets or best fit based on `charsets`.
   * 判断客户端是否接受给定的编码方式的快捷方法,当有传入参数时,返回最应当返回的一种编码方式。
   * Given `Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5`
   * an array sorted by quality is returned:
   * 优先级是这个 也可以指定
   *     ['utf-8', 'utf-7', 'iso-8859-1']
   * 返回就是返回一个 没有就返回false
   * 当没有传入参数时,返回客户端的请求数组:
*/
  //接受的字符集
  acceptsCharsets(...args) {
    return this.accept.charsets(...args);
  },

  /**返回被接受的语言
   * Return accepted languages or best fit based on `langs`.
   *
   * Given `Accept-Language: en;q=0.8, es, pt`
   * an array sorted by quality is returned:
   *    优先级为下面这个
   *     ['es', 'pt', 'en']
   *    返回就是返回一个 没有就返回false
   */

  acceptsLanguages(...args) {
    return this.accept.languages(...args);
  },

  /**检查是否包含Content-Type头域  并且包含任何给予mime type的任何内容
   * 如果没有请求体就返回空  如果没有内容类型就返回false 不然就返回匹配的第一个type
   * 判断请求对象中 Content-Type 是否为给定 type 的快捷方法,如果不存在 request.body,将返回 undefined,
   * 如果没有符合的类型,返回 false,除此之外,返回匹配的类型字符串。
*/
  //检查响应是不是被允许的 与this.request.is()相同
  is(types) {
    if (!types) return typeis(this.req);
    if (!Array.isArray(types)) types = [].slice.call(arguments);
    //检查是否被允许 允许就返回对应的值
    return typeis(this.req, types);
    //判断是否存在type存在的话返回那个type不存在的话返回Boolean
  },

  /**
   * Return the request mime type void of
   * parameters such as "charset".
   *
   * @return {String}
   * @api public
   */
  //获取头部Content-type值(内容的格式)
  get type() {
    const type = this.get('Content-Type');
    if (!type) return '';
    return type.split(';')[0];
  },

  /**
   * Return request header.
   *
   * The `Referrer` header field is special-cased,
   * both `Referrer` and `Referer` are interchangeable.
   *
   * Examples:
   *
   *     this.get('Content-Type');
   *     // => "text/plain"
   *
   *     this.get('content-type');
   *     // => "text/plain"
   *
   *     this.get('Something');
   *     // => undefined
   *
   * @param {String} field
   * @return {String}
   * @api public
   */
    //获取某个头部字段
  get(field) {
    const req = this.req;
    switch (field = field.toLowerCase()) {
      case 'referer':
      case 'referrer':
        return req.headers.referrer || req.headers.referer || '';
      default:
        return req.headers[field] || '';
    }
  },
    //这个方法的作用是这样的
    //class test(){
    //    inspect(){
    //        return 'xixi'
    //    }
    //}
    //console.log(new test())
    //也就是返回这个对象的JSON格式啦
    //类似util.inspect
  inspect() {
    if (!this.req) return;
    return this.toJSON();
  },

  /**
   * Return JSON representation.
   *
   * @return {Object}
   * @api public
   */

  toJSON() {
    return only(this, [
      'method',
      'url',
      'header'
    ]);
  }
};
    原文作者:ZWkang
    原文地址: https://segmentfault.com/a/1190000010740869
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞