nodejs入门API之http模块

HTTP上的一些API及应用
HTTP模块上的服务（server）与响应(response)
HTTP模块上的消息（message）
HTTP模块上的代理（agent）与请求（request）
HTTP模块的简单实践

一、HTTP上的一些API及应用

http.Agent：http请求代理，用来管理客户端连接的持久性和重用。
http.ClientRequest：由http.request()产生，用来管理已被放入请求队列中的请求，比如可以通过setHeader(name, value)向请求头添加请求头。
http.Server：该类继承net.server，用来管理来自客户端的http请求。
http.ServerResponse：此类型的对象由 HTTP 服务器在内部创建，而不是由用户创建，用来管理服务端接收到http请求后响应客户端的相关内容。它作为第二个参数传给 'request' 事件。
http.IncomingMessage：此类型的对象由 http.Server 或 http.ClientRequest 创建，并分别作为第一个参数传给 'request' 和 'response' 事件，用来表示接收到的http请求的模型。它可用于访问响应状态、消息头、以及数据。
http.METHODS：该属性用来获取当前node环境下支持的http请求方法，比如：[GET, POST,...]
http.STATUS_CODES：该属性用来获取http的响应码及说明，比如：{'100': 'Continue','200': 'OK','404': 'Not Found','500': 'Internal Server Error',...}
http.createServer([options][,requestListener])：用来实例化一个http.server对象。参数：options可选，有两个属性IncomingMessage、ServerResponse，分别用来指定要使用的 IncomingMessage 类和 ServerResponse 类，用来扩该类的初始属性，默认使用原始的类型；requestListener可选，该参数是一个方法，会被自动添加到‘request’事件作为回调函数。
http.get(options[,callback])：用来发送GTE方法的HTTP请求
http.get(url[, options][, callback])：同上。
http.globalAgent：Agent 的全局实例，作为所有 HTTP 客户端请求的默认值。
http.maxHeaderSize：只读属性，指定 HTTP 消息头的最大允许大小（以字节为单位）。默认为 8KB。可使用 --max-http-header-size 命令行选项进行配置。
http.request(options[,callback])：用来发起http请求。
http.request(url[,options][,callback])：同上。

二、HTTP模块上的服务（server）与响应(response)

http.Server类

http.server事件

checkContinue 事件：每次收到 HTTP Expect: 100-continue 的请求时都会触发。处理此事件时，如果客户端继续发送请求主体就会默认调用response.writeContinue()，即向客户端响应HTTP/1.1 100 Continue 消息，表示应发送请求主体。
checkExpectation 事件：每次收到带有 HTTP Expect 请求头的请求时触发，其中值不是 100-continue。如果未监听此事件，则服务器将根据需要自动响应 417 Expectation Failed。（及客户端期望某个操作，但不是100-continue向服务发送报文主体，这时候就需要该事件进行处理，如果没有设置该事件的处理方法，则自动响应客户端417表示服务端无法满足该期望）
clientError 事件：如果客户端连接触发error事件，服务端连接则会在此处转发，此事件监听器负责关闭或销毁底层套字节，比如直接在监听事件中调用socket.end("HTTP/1.1 400 Bad Request\r\n\r\n")；实现优雅的关闭连接，而不是突然切断连接（切断连接后tcp协议还会有一系列的底层动作，采用这种方式关闭可以避免不必要的消耗）。并且可以在此监听事件中实现对客户端错误进行日志记录，有利于错误筛查与修复。
close 事件：当服务关闭时触发。
connect 事件：客户端请求连接时触发该监听事件，如果没有监听该事件，则请求connect方法的客户端将自动关闭。
connection 事件：建立新的TCP流时会触发该事件。
request 事件：每次有请求时都会触发。每个连接可能有多个请求（在 HTTP Keep-Alive 连接的情况下）。
upgrade 事件：每次客户端请求 HTTP 升级时发出。监听此事件是可选的，客户端无法坚持更改协议。

http.server方法

server.cose([callback])：停止服务器接受新连接。请参见 net.Server.close()。
server.listen()：启动 HTTP 服务器监听连接。此方法与 net.Server 中的 server.listen() 相同。
server.setTimeout([msecs][,callback])：设置连接超时事件和回调函数。msecs默认为120000，也就是连接超时默认为2分钟。

http.server属性

server.headersTimeout：限制解析器等待接收完整 HTTP 请求头的时间，默认值为40000。
server.listening：<boolean> 表明服务器是否正在监听连接。
server.maxHeadersCount：限制最大传入请求头数。如果设置为 0，则不会应用任何限制，默认值为2000。
server.timeout：设置连接超时事件。
server.keepAliveTimeout：设置服务端响应完最后一个响应后，在销毁套字节之前的非活动毫秒数，默认值为5000，即5秒。

http.ServerResponse 类

用于处理服务端响应客户端的http通讯模型。

http.ServerResponse事件

close 事件：底层连接被终止后触发。
finish 事件：响应发送后触发。

http.ServerResponse方法

response.addTrailers(headers)：用于添加http响应报文尾部响应头，在response.write()后面、response.end()前面使用。
response.end([data[,encoding]][,callback])：该方法用于告诉服务，响应头和主体已经发送完毕。如果传入data(数据)和encoding(字符编码集)，相当于response.write(data[,encoding])。callback回调函数在响应流完成以后调用。
response.flushHeaders()
response.getHeader(name)：读取以排队但未发送出去的响应头的值，name为响应头名称。读取对应setHeader()添加的响应头。
response.getHeaderNames()：读取响应报文的所有响应头的名称列表。注意读取出来的字母都是小写。
response.getHeaders()：以键值对的方式读取所有响应头名称和值。
response.hasHeader(name)：<boolean>如果当前在传出的响应头中设置了由 name 标识的响应头，则返回 true。响应头名称匹配不区分大小写。
response.removeHeader(name)：移除排队等待中的隐式发送的响应头。
response.setHeader(name,value)：用于添加响应头。
response.setTimeout(msecs[,callback])：<response>将套接字的超时值设置为 msecs。如果提供了回调，则会将其作为监听器添加到响应对象上的 'timeout' 事件中。
response.write(chunk[,encoding][,callback])：使用该方法给响应报文添加响应数据，通常被称为发送数据。
response.writeContinue()：向客户端发送 HTTP/1.1 100 Continue 消息，表示应发送请求主体。
response.writeHead(statusCode[,statusMess][, headers])：配置响应报文的相应状态码。向请求发送响应头。状态码是一个 3 位的 HTTP 状态码，如 404。最后一个参数 headers 是响应头。可以可选地将用户可读的 statusMessage 作为第二个参数。
response.writeProcessing()：向客户端发送 HTTP/1.1 102 处理消息，表明可以发送请求主体。

http.ServerResponse属性

response.connection：用于获取http连接的底层net.socket对象，与response.socket属性指向同一个对象。
response.finished：<boolean>调用了response.end()方法后，该属性值被修改成true。
response.headersSent： <boolean>如果已发送响应头，则为 true，否则为 false。
response.sendDate：<boolean>默认值为true，表示在响应头中默认添加date响应头。
response.socket：用于获取http连接的底层net.socket对象。
response.statusCode：设置默认响应状态码。如果没有使用writeHead()设置相应码会将该默认响应码添加到相应报文中。比如可以设置为：404。
response.statusMessage：当响应头使用默认相应码状态码时，即上面一个statusCode的默认值被添加到相应头时，会将该属性值作为相应状态说明。（例如状态码200对应的是OK）。
response.writableEnded：<boolean>调用了response.end()方法后，该属性值设置为true。但该属性为true时并不代表相应被发送出去了，如果需要判断请求是否发送出去请使用response.writableFinished。
response.writableFinished：如果在触发 'finish' 事件之前，所有数据都已刷新到底层的系统，则为 true。也就是相应报文发送出去后被置为true。

三、HTTP模块上的消息（message）

http.IncomingMessage 类

服务端与客户端收到的http请求或响应的解析对象，通常它们也被称为“消息”。

http.IncomingMessage事件

aborted 事件：当请求中止后触发该事件。
close 事件：当底层连接关闭后触发该事件。

http.IncomingMessage方法

message.destroy([error])：销毁当前请求，销毁后的请求，服务上response不会做任何响应，该方法可以传入一个Error(异常)对象，调用该方法后如果传入了Error(异常)对象会通过Error事件触发该异常。
message.setTimeout(msecs[,callback])：

http.IncomingMessage属性

message.aborted：<boolean>属性值为true时，表示请求已中止。
message.complete：<boolean>属性值为true时，表示已收到并成功解析完整的http消息。
message.headers：请求头或响应头对象，收到http请求或者响应以后会将请求头作为key/value（键/值）解析为一个对象赋给该属性。
message.httpVersion：<string>获取客户端请求的http版本号,例如：‘1.1’；还可以通过message.httpVersionMajor 是第一个整数， message.httpVersionMinor 是第二个整数。
message.method：获取请求方法的类型，仅在http.server获取的请求中有效。
message.rawHeaders：原始请求头/响应头的列表，与接收到的完全一致。键和值位于同一列表中。它不是元组列表。因此，偶数偏移是键值，奇数偏移是关联的值。例如：['Host', '127.0.0.1:12306','Connection','keep-alive'...]。
message.rawTrailers：
message.socket：获取http请求与响应相关链的net.socket对象，可以通过message.socket访问net.socket的任何方法和属性。比如：message.socket.address()获取当前消息的地址信息。
messave.statusCode：用于客户端获取服务响应报文的状态码。
messave.statusMessage：用于客户端获取服务响应说明，比如响应码200时的说明是“OK”。
message.trailes：由尾部消息头解析出来的对象，也就是由end()响应发出的http报文头。
message.url：<string>获取http请求头中的url，例如：GET /status?name=ryan HTTP/1.1\r\n 中的“/status?name=ryan”。这个rul包含了请求携带的数据，如果需要纯粹的rul还需要使用rul模块解析message.url。例如：url.parse(request.url).pathname;就可以获取到“/status”。

四、HTTP模块上的代理（agent）与请求（request）

http.Agent类

Agent方法

new Agent([options])：如果需要配置代理的设置，需要自定义一个，因为http.request()使用默认的http.globalAgent 具有所有这些值且被设置为各自的默认值。通过new Agent([options])创建一个自定义的代理，options为自定义配置，可配置的选项有：

keepAlive：<boolean>当属性值为true时（默认false）即使没有未完成的请求，也要保持套字节，被用于将来的请求而无需重新建立 TCP 连接。注意不要与http请求头connection的keep-alive值混洗，connection为keep-alive是配置http前请求为长连接的。Connection: keep-alive 请求头始终在使用代理时发送，除非明确指定 Connection 请求头、或者 keepAlive 和 maxSockets 选项分别设置为 false 和 Infinity，在这种情况下将会使用 Connection: close。默认值: false。

keepAliveMsecs：<number>当使用keepAlive选项时，指定保持套字节的延迟时间，默认为1000。若keepAlive选项配置为false或undefined时，则忽略keepAliveMsecs选项。

maxSockets：<number>每个主机允许套字节的最大数量。默认值为Infinity，即无穷不限制。

maxFreeSockets：<number>在空闲状态下保持打开的套字节的最大数量。该配置也需要是在keepAlive选项配置为true时生效。默认值为256。

timeout：<number>配置套字节的超时时间，在套字节被连接之后设置该超时时间。
```
1 //自定义http.Agent实例
2 const http = require('http');
3 const keepAliveAgent = new http.Agent({ keepAlive: true });
4 options.agent = keepAliveAgent;
5 http.request(options, onResponseCallback);
```
agent.createConnection(options[,callback])：用于生成HTTP请求的套字节或流。详细见官方文档
agent.keepSocketAlive(socket)：这个方法封装了net.socket对象上的setKeepAlive()，当该方法返回一个假值时，销毁当前套字节，当前套字节不再保留给下一个请求。
agent.reuseSocket(socket,request)：这个方法封装了net.socket对象上的ref()，可以用来取消销毁套字节操作，继续保留连接。
agent.destroy()：用于销毁代理当前使用的所有套字节。
agent.getName(options)：获取一组请求选项的唯一名称，以判定一个连接是否可以被重用。

Agent属性

agent.freeSockets：一个对象，其中包含当启用 keepAlive 时代理正在等待使用的套接字数组。不要修改。
agent.maxFreeSockets：默认设置为 256。对于启用了 keepAlive 的代理，这将设置在空闲状态下保持打开的最大套接字数。
agent.maxSockets：默认情况下设置为 Infinity。决定代理可以为每个来源打开多少并发套接字。来源是 agent.getName() 的返回值。
agent.requests：一个对象，包含尚未分配给套接字的请求队列。不要修改。
agent.sockets：一个对象，包含当前代理正在使用的套接字数组。不要修改。

http.ClientRequest类

request事件

abort 事件：当客户端中止请求时触发，该事件仅在第一次调用abort()时触发。
connect 事件：每次服务器使用connect()方法响应请求时都会触发。如果没有监听此事件，则收到connect()方法的客户端将关闭其连接。
continue 事件：当服务发送100 Continue HTTP响应时触发，通常是因为请求包含Expect: 100-continue。这时客户端应发送请求主体的指令。
information 事件：服务器发送 1xx 中间响应（不包括 101 Upgrade）时触发。此事件的监听器将会接收一个对象，该对象包含HTTP版本，状态码，状态消息，键值对请求头对象、以及具有原始请求头名称和值的数组。
response 事件：当收到此请求的响应时触发。此事件仅触发一次。
socket 事件：将套接字分配给此请求后触发。
timeout 事件：当底层套字节因不活动而超时时触发。这只会通知套接字已空闲。必须手动中止请求。
upgrade 事件：每次服务器响应升级请求时发出。如果没有监听此事件且响应状态码为101 Switching Protocols，则接收到升级响应头的客户端将关闭其连接。

request方法

request.abort()：将请求标记为中止。调用此方法将导致响应中剩余的数据被丢弃并且套接字被销毁。
request.end([data[,encoding]][,callback])：完成发送请求。如果部分请求主体还未发送，则将它们刷新到流中。如果请求被分块，则发送终止符“0\r\n\r\n。【意思是将data作为请求主体添加到流中，如果没有data则表示结束请求发送终止符，待请求主体发送完以后调用回调函数】
request.flushHeaders()：
request.getHeader(name)：读取请求中的一个请求头，name为请求头的名称，然后返回该请求头的值。
request.removeHeader(name)：删除已经定义到请求头对象中的请求头。
request.setHeader(name,value)：为请求头对象设置的那个请求头的值。
request.setNoDelay([noDelay])：将套接字分配给此请求，如果该套接字处于连接状态，就会调用socket.setNoDelay()。意思是不会对发送数据进行缓冲，立即发送请求。
request.setSocketKeepAlive([enable][,initialDelay])：将套接字分配给此请求，如果套接字处于连接状态，就会调用socket.setKeepAlive()。意思是使用一个指定的套接字发送请求，并且可以配置套接字是否启用长连接。
request.setTimeout(timeout[,callback])：将套接字分配给此请求，如果套接字处于连接状态，就会调用socket.setTimeout()。意思是使用一个超时监听事件监听该请求，如果该请求超时会调用socket上的timeout事件。
request.write(chunk[,encoding][,callback])：发送请求主体数据块。

request属性

request.aborted：如果请求已中止，则该属性值被附为true。
request.connection：
request.finished：如果调用end()，属性值被附为true。如果通过http.get()发起的则自动调用end()方法。
request.maxHeadersCount：限制最大响应头数。如果设置为0，则不会应用任何限制。
request.path：请求路径。
request.socket：指向net上的socket套接字对象。
request.writableEnded：end()方法被调用之后，该属性被附为true。这仅仅请求已完成，并不代表接收到了数据。
request.writableFinished：如果服务确定相应发送完成之前，客户端的数据已经更新完毕，则该属性被附为true。这表明客户端收到了完整的相应数据。