# NJS API 参考 [NJS](https://cn.angie.software//angie/docs/installation/external-modules/njs.md#external-njs) 模块提供了用于扩展 Angie 功能的对象、方法和属性。 本参考仅包含 NJS 特定的、不符合 ECMAScript 标准的属性、方法和模块。符合 ECMAScript 标准的 NJS 属性和方法的定义可以在 [ECMAScript 规范](http://www.ecma-international.org/ecma-262/) 中找到。 ## Angie 对象 ### HTTP 请求 - `r.args{}` - `r.done()` - `r.error()` - `r.finish()` - `r.headersIn{}` - `r.headersOut{}` - `r.httpVersion` - `r.internal` - `r.internalRedirect()` - `r.log()` - `r.method` - `r.parent` - `r.remoteAddress` - `r.requestBody` - `r.requestBuffer` - `r.requestText` - `r.rawHeadersIn[]` - `r.rawHeadersOut[]` - `r.responseBody` - `r.responseBuffer` - `r.responseText` - `r.return()` - `r.send()` - `r.sendBuffer()` - `r.sendHeader()` - `r.setReturnValue()` - `r.status` - `r.subrequest()` - `r.uri` - `r.rawVariables{}` - `r.variables{}` - `r.warn()` HTTP 请求对象仅在 [HTTP JS](https://cn.angie.software//angie/docs/installation/external-modules/http_js.md#http-js) 模块中可用。在 0.8.5 之前，该对象的所有字符串属性都是字节字符串。 `r.args{}` > 请求参数对象，只读。 > 查询字符串以对象形式返回。从 0.7.6 开始，重复的键以数组形式返回，键区分大小写，键和值都会进行百分号解码。 > 例如，查询字符串 > ```text > a=1&b=%32&A=3&b=4&B=two%20words > ``` > 会被转换为 `r.args`： > ```javascript > {a: "1", b: ["2", "4"], A: "3", B: "two words"} > ``` > 更高级的解析场景可以使用 [Query String](#njs-querystring) 模块和 `$args` 变量来实现，例如： > ```javascript > import qs from 'querystring'; > function args(r) { > return qs.parse(r.variables.args); > } > ``` > 参数对象在首次访问 `r.args` 时进行求值。如果只需要单个参数，例如 `foo`，可以使用 Angie 变量： > ```javascript > r.variables.arg_foo > ``` > 这里，Angie 变量对象返回给定键的第一个值，不区分大小写，不进行百分号解码。 > 要将 `r.args` 转换回字符串，可以使用 Query String 的 `stringify` 方法。 `r.done()` : 调用此函数后，后续的数据块将直接传递给客户端，而不调用 `js_body_filter` （0.5.2）。只能从 `js_body_filter` 函数中调用。 `r.error(string)` : 将 `string` 以 `error` 日志级别写入错误日志。
#### NOTE 由于 Angie 有硬编码的最大行长度限制，只有字符串的前 2048 字节可以被记录。 `r.finish()` : 完成向客户端发送响应。 `r.headersIn{}` : 传入的请求头对象，只读。
可以使用以下语法访问 `Foo` 请求头：`headersIn.foo` 或 `headersIn['Foo']`。
`Authorization`、`Content-Length`、`Content-Range`、`Content-Type`、`ETag`、`Expect`、`From`、`Host`、`If-Match`、`If-Modified-Since`、`If-None-Match`、`If-Range`、`If-Unmodified-Since`、`Max-Forwards`、`Proxy-Authorization`、`Referer`、`Transfer-Encoding` 和 `User-Agent` 请求头只能有一个字段值（0.4.1）。`Cookie` 头中的重复字段值用分号（`;`）分隔。所有其他请求头中的重复字段值用逗号分隔。 `r.headersOut{}` : 主请求的传出响应头对象，可写。
如果 `r.headersOut{}` 是子请求的响应对象，它表示响应头。在这种情况下，`Accept-Ranges`、`Connection`、`Content-Disposition`、`Content-Encoding`、`Content-Length`、`Content-Range`、`Date`、`Keep-Alive`、`Server`、`Transfer-Encoding`、`X-Accel-*` 响应头中的字段值可能会被省略。
可以使用以下语法访问 `Foo` 响应头：`headersOut.foo` 或 `headersOut['Foo']`。
传出的响应头应该在响应头发送给客户端之前设置；否则，头的更新将被忽略。这意味着 `r.headersOut{}` 在以下情况下有效可写：
- 在 `js_content` 处理程序中，在调用 `r.sendHeader()` 或 `r.return()` 之前 - 在 `js_header_filter` 处理程序中
多值响应头（0.4.0）的字段值可以使用以下语法设置：
```javascript r.headersOut['Foo'] = ['a', 'b'] ```
输出将是：
```text Foo: a Foo: b ```
`Foo` 响应头的所有先前字段值将被删除。
对于只接受单个字段值的标准响应头（如 `Content-Type`），只有数组的最后一个元素会生效。`Set-Cookie` 响应头的字段值始终以数组形式返回。`Age`、`Content-Encoding`、`Content-Length`、`Content-Type`、`ETag`、`Expires`、`Last-Modified`、`Location`、`Retry-After` 响应头中的重复字段值会被忽略。所有其他响应头中的重复字段值用逗号分隔。 `r.httpVersion` : HTTP 版本，只读。 `r.internal` : 布尔值，对于内部 location 为 `true`。 `r.internalRedirect(uri)` : 执行到指定 `uri` 的内部重定向。如果 URI 以 `@` 前缀开头，则被视为命名 location。在新 location 中，所有请求处理从普通 location 的 `NGX_HTTP_SERVER_REWRITE_PHASE` 开始重复，从命名 location 的 `NGX_HTTP_REWRITE_PHASE` 开始重复。因此，重定向到命名 location 不会检查 `client_max_body_size` 限制。重定向的请求变为内部请求，可以访问内部 location。实际的重定向发生在处理程序执行完成后。
#### NOTE 重定向后，在目标 location 中启动一个新的 NJS VM，原始 location 中的 VM 停止。Angie 变量的值会保留，可用于向目标 location 传递信息。从 0.5.3 开始，可以使用通过 `js_var` 指令为 HTTP 或 Stream 声明的变量。
#### NOTE 从 0.7.4 开始，该方法接受转义的 URI。 `r.log(string)` : 将 `string` 以 `info` 日志级别写入错误日志。
#### NOTE 由于 Angie 有硬编码的最大行长度限制，只有字符串的前 2048 字节可以被记录。 `r.method` : HTTP 方法，只读。 `r.parent` : 引用父请求对象。 `r.remoteAddress` : 客户端地址，只读。 `r.requestBody` : 该属性在 0.5.0 中已过时，在 0.8.0 中被移除。应该使用 `r.requestBuffer` 或 `r.requestText` 属性代替。 `r.requestBuffer` : 客户端请求体（如果尚未写入临时文件）（从 0.5.0 开始）。要确保客户端请求体在内存中，其大小应受 `client_max_body_size` 限制，并且应使用 `client_body_buffer_size` 设置足够的缓冲区大小。该属性仅在 `js_content` 指令中可用。 `r.requestText` : 与 `r.requestBuffer` 相同，但返回一个字符串。注意，它可能会将 UTF-8 编码中无效的字节转换为替换字符。 `r.rawHeadersIn[]` : 返回键值对数组，完全按照从客户端接收的原样（0.4.1）。
例如，对于以下请求头：
```text Host: localhost Foo: bar foo: bar2 ```
`r.rawHeadersIn` 的输出将是：
```javascript [ ['Host', 'localhost'], ['Foo', 'bar'], ['foo', 'bar2'] ] ```
可以使用以下语法收集所有 `foo` 头：
```javascript r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1]) ```
输出将是：
```javascript ['bar', 'bar2'] ```
头字段名称不会转换为小写，重复的字段值不会合并。 `r.rawHeadersOut[]` : 返回响应头的键值对数组（0.4.1）。头字段名称不会转换为小写，重复的字段值不会合并。 `r.responseBody` : 该属性在 0.5.0 中已弃用，在 0.8.0 中被移除。应该使用 `r.responseBuffer` 或 `r.responseText` 属性代替。 `r.responseBuffer` : 包含子请求响应体，只读（从 0.5.0 开始）。`r.responseBuffer` 的大小受 `subrequest_output_buffer_size` 指令限制。 `r.responseText` : 与 `r.responseBuffer` 相同，但返回字符串（从 0.5.0 开始）。注意，它可能会将 UTF-8 编码中无效的字节转换为替换字符。 `r.return(status[, string | Buffer])` : 向客户端发送带有指定 `status` 的完整响应。响应可以是字符串或 Buffer（0.5.0）。
可以将重定向 URL（用于代码 301、302、303、307 和 308）或响应正文文本（用于其他代码）指定为第二个参数。 `r.send(string | Buffer)` : 向客户端发送响应正文的一部分。发送的数据可以是字符串或 Buffer（0.5.0）。 `r.sendBuffer(data[, options])` : 将数据添加到要转发到下一个正文过滤器的数据块链中（0.5.2）。实际转发会在稍后发生，即当前链的所有数据块都处理完毕时。
数据可以是字符串或 Buffer。`options` 是一个对象，用于覆盖从传入数据块缓冲区派生的 Angie 缓冲区标志。可以使用以下标志覆盖这些标志：
`last` : 布尔值，`true` 表示该缓冲区是最后一个缓冲区。
`flush` : 布尔值，`true` 表示该缓冲区应具有 `flush` 标志。
该方法只能从 `js_body_filter` 函数中调用。 `r.sendHeader()` : 向客户端发送 HTTP 头。 `r.setReturnValue(value)` : 设置 `js_set` 处理程序的返回值（0.7.0）。与普通的 return 语句不同，当处理程序是 JS 异步函数时应使用此方法。例如：
```javascript async function js_set(r) { const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host); r.setReturnValue(digest); } ``` `r.status` : 状态，可写。 `r.subrequest(uri[, options[, callback]])` : 使用给定的 `uri` 和 `options` 创建子请求,并安装可选的完成 `callback`。
子请求与客户端请求共享其输入标头。要向代理服务器发送与原始标头不同的标头,可以使用 `proxy_set_header` 指令。要向代理服务器发送全新的标头集,可以使用 `proxy_pass_request_headers` 指令。
如果 `options` 是字符串,则它保存子请求参数字符串。否则,:samp:options 应为具有以下键的对象:
`args` : 参数字符串,默认使用空字符串。
`body` : 请求主体,默认使用父请求对象的请求主体。
`method` : HTTP 方法,默认使用 `GET` 方法。
`detached` : 布尔标志(0.3.9);如果为 `true`,则创建的子请求是分离的子请求。对分离子请求的响应将被忽略。与普通子请求不同,分离的子请求可以在变量处理程序内创建。`detached` 标志和 callback 参数是互斥的。
完成 `callback` 接收一个子请求响应对象,其方法和属性与父请求对象相同。
从 0.3.8 开始,如果未提供 `callback`,则返回解析为子请求响应对象的 `Promise` 对象。
例如,要查看子请求中的所有响应标头:
```javascript async function handler(r) { const reply = await r.subrequest('/path');
for (const h in reply.headersOut) { r.log(`${h}: ${reply.headersOut[h]}`); }
r.return(200); } ``` `r.uri` : 请求中的当前 URI,已规范化,只读。 `r.rawVariables{}` : Angie 变量作为 Buffers,可写(自 0.5.0 起)。 `r.variables{}` : Angie 变量对象,可写(自 0.2.8 起)。
例如,要获取 `$foo` 变量,可以使用以下语法之一:
```javascript r.variables['foo'] r.variables.foo ```
从 0.8.6 开始,可以使用以下语法访问正则表达式捕获:
```javascript r.variables['1'] r.variables[1] ```
Angie 对在 `angie.conf` 中引用的变量和未引用的变量的处理方式不同。当变量被引用时,它可能是可缓存的,但当它未被引用时,它始终是不可缓存的。例如,当 `$request_id` 变量仅从 NJS 访问时,每次求值时它都有一个新值。但是,当 `$request_id` 被引用时,例如:
```nginx proxy_set_header X-Request-Id $request_id; ```
`r.variables.request_id` 每次都返回相同的值。
变量可写的条件是:
- 它是使用 HTTP 或 Stream 的 `js_var` 指令创建的(自 0.5.3 起) - 它在 Angie 配置文件中被引用
即便如此,某些内置变量仍然无法被赋值(例如 `$http_`)。 `r.warn(string)` : 在 `warning` 日志级别将 `string` 写入错误日志。
#### NOTE 由于 Angie 具有硬编码的最大行长度限制,因此只能记录字符串的前 2048 个字节。 ### Stream 会话 - `s.allow()` - `s.decline()` - `s.deny()` - `s.done()` - `s.error()` - `s.log()` - `s.off()` - `s.on()` - `s.remoteAddress` - `s.rawVariables{}` - `s.send()` - `s.sendDownstream()` - `s.sendUpstream()` - `s.status` - `s.setReturnValue()` - `s.variables{}` - `s.warn()` 流会话对象仅在 [Stream JS](https://cn.angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js) 模块中可用。在 0.8.5 之前,该对象的所有字符串属性都是字节字符串。 `s.allow()` : `s.done(0)` 的别名(0.2.4)。 `s.decline()` : `s.done(-5)` 的别名(0.2.4)。 `s.deny()` : `s.done(403)` 的别名(0.2.4)。 `s.done([code])` : 将当前阶段处理程序的退出 `code` 设置为代码值,默认为 `0`。实际的终结发生在 js 处理程序完成并且所有待处理事件(例如来自 `ngx.fetch()` 或 `setTimeout()` 的事件)都被处理之后(0.2.4)。
可能的代码值:
- `0` — 成功终结,将控制权传递给下一个阶段 - `-5` — 未决定,将控制权传递给当前阶段的下一个处理程序(如果有) - `403` — 访问被禁止
只能从阶段处理程序函数调用:`js_access` 或 `js_preread`。 `s.error(string)` : 在 `error` 日志级别将发送的 `string` 写入错误日志。
#### NOTE 由于 Angie 具有硬编码的最大行长度限制,因此只能记录字符串的前 2048 个字节。 `s.log(string)` : 在 `info` 日志级别将发送的 `string` 写入错误日志。
#### NOTE 由于 Angie 具有硬编码的最大行长度限制,因此只能记录字符串的前 2048 个字节。 `s.off(eventName)` : 注销由 `s.on()` 方法设置的回调(0.2.4)。 `s.on(event, callback)` : 为指定的 `event` 注册 `callback` (0.2.4)。
`event` 可以是以下字符串之一:
`upload` : 来自客户端的新数据(字符串)。
`download` : 发送到客户端的新数据(字符串)。
`upstream` : 来自客户端的新数据(Buffer)(自 0.5.0 起)。
`downstream` : 发送到客户端的新数据(Buffer)(自 0.5.0 起)。
完成回调具有以下原型:`callback(data, flags)`,其中 `data` 是字符串或 Buffer(取决于事件类型);:samp:flags 是具有以下属性的对象:
`last` : 布尔值,:samp:true 表示数据是最后一个缓冲区。 `s.remoteAddress` : 客户端地址,只读。 `s.rawVariables` : Angie 变量作为 Buffers,可写(自 0.5.0 起)。 `s.send(data[, options])` : 将数据添加到将在正向方向转发的数据块链中:在下载回调中发送到客户端;在上传中发送到上游服务器(0.2.4)。实际转发会在稍后发生,即当前链的所有数据块都处理完毕时。
数据可以是字符串或 Buffer(0.5.0)。`options` 是一个对象,用于覆盖从传入数据块缓冲区派生的 Angie 缓冲区标志。可以使用以下标志覆盖这些标志:
`last` : 布尔值,:samp:true 表示该缓冲区是最后一个缓冲区。
`flush` : 布尔值,:samp:true 表示该缓冲区应具有 `flush` 标志。
该方法可以在每次回调调用中多次调用。 `s.sendDownstream()` : 与 `s.send()` 相同,但它始终将数据发送到客户端(自 0.7.8 起)。 `s.sendUpstream()` : 与 `s.send()` 相同,但它始终从客户端发送数据(自 0.7.8 起)。 `s.status` : 会话状态代码,:samp:$status 变量的别名,只读(自 0.5.2 起)。 `s.setReturnValue(value)` : 设置 `js_set` 处理程序的返回值(0.7.0)。与普通的 return 语句不同,当处理程序是 JS 异步函数时应使用此方法。例如:
```javascript async function js_set(r) { const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host); r.setReturnValue(digest); } ``` `s.variables{}` : Angie 变量对象,可写(自 0.2.8 起)。变量只有在 Angie 配置文件中被引用时才可写。即便如此,某些内置变量仍然无法被赋值。 `s.warn(string)` : 在 `warning` 日志级别将发送的 `string` 写入错误日志。
#### NOTE 由于 Angie 具有硬编码的最大行长度限制,因此只能记录字符串的前 2048 个字节。 ### 周期会话 - `PeriodicSession.rawVariables{}` - `PeriodicSession.variables{}` `Periodic Session` 对象作为 HTTP 和 Stream 的 `js_periodic` 处理程序的第一个参数提供(自 0.8.1 起)。 `PeriodicSession.rawVariables{}` : Angie 变量作为 Buffers,可写。 `PeriodicSession.variables{}` : Angie 变量对象,可写。 ### Headers - `Headers()` - `Headers.append()` - `Headers.delete()` - `Headers.get()` - `Headers.getAll()` - `Headers.forEach()` - `Headers.has()` - `Headers.set()` Fetch API 的 `Headers` 接口自 0.5.1 起可用。 可以使用 `Headers()` 构造函数创建新的 `Headers` 对象(自 0.7.10 起): `Headers([init])` : `init` : 包含用于预填充 `Headers` 对象的 HTTP 标头的对象,可以是 `string`、名称-值对的 `array`,或现有的 `Headers` 对象。 可以使用以下属性和方法创建新的 `Headers` 对象: `append()` : 向 `Headers` 对象中的现有标头追加新值,如果标头不存在则添加该标头(自 0.7.10 起)。 `delete()` : 从 `Headers` 对象中删除标头(自 0.7.10 起)。 `get()` : 返回包含指定名称的所有标头值的字符串,值之间用逗号和空格分隔。 `getAll(name)` : 返回包含指定名称的所有标头值的数组。 `forEach()` : 对 `Headers` 对象中的每个键/值对执行一次提供的函数(自 0.7.10 起)。 `has()` : 返回布尔值,指示是否存在具有指定名称的标头。 `set()` : 为 `Headers` 对象内的现有标头设置新值,如果标头不存在则添加该标头(自 0.7.10 起)。 ### Request - `Request()` - `Request.arrayBuffer()` - `Request.bodyUsed` - `Request.cache` - `Request.credentials` - `Request.headers` - `Request.json()` - `Request.method` - `Request.mode` - `Request.text()` - `Request.url` Fetch API 的 `Request` 接口自 0.7.10 起可用。 可以使用 `Request()` 构造函数创建新的 `Request` 对象: `Request[resource[, options]])` : 创建一个可以稍后传递给 `ngx.fetch()` 的 `Request` 对象来获取。`resource` 可以是 URL 或现有的 `Request` 对象。`options` 是可选参数,应为具有以下键的对象:
`body` : 请求主体,默认为空。
`headers` : 响应标头对象——包含用于预填充 `Headers` 对象的 HTTP 标头的对象,可以是 `string`、名称-值对的 `array`,或现有的 `Headers` 对象。
`method` : HTTP 方法,默认使用 GET 方法。 可以使用以下属性和方法创建新的 `Request` 对象: `arrayBuffer()` : 返回一个 `Promise`,该 Promise 解析为 `ArrayBuffer`。 `bodyUsed` : 布尔值,如果主体已在请求中使用则为 `true`。 `cache` : 包含请求的缓存模式。 `credentials` : 包含请求的凭据,默认为 `same-origin`。 `headers` : 与 `Request` 关联的只读 `Headers` 对象。 `json()` : 返回一个 `Promise`,该 Promise 解析为将请求主体解析为 JSON 的结果。 `method` : 包含请求方法。 `mode` : 包含请求的模式。 `text()` : 返回一个 `Promise`,该 Promise 解析为请求主体的字符串表示形式。 `url` : 包含请求的 URL。 ### Response - `Response()` - `Response.arrayBuffer()` - `Response.bodyUsed` - `Response.headers` - `Response.json()` - `Response.ok` - `Response.redirected` - `Response.status` - `Response.statusText` - `Response.text()` - `Response.type` - `Response.url` `Response` 接口自 0.5.1 起可用。 可以使用 `Response()` 构造函数创建新的 `Response` 对象(自 0.7.10 起): `Response[body[, options]])` : 创建 `Response` 对象。`body` 是可选参数,可以是 `string` 或 `buffer`,默认为 `null`。`options` 是可选参数,应为具有以下键的对象:
`headers` : 响应标头对象——包含用于预填充 `Headers` 对象的 HTTP 标头的对象,可以是 `string`、名称-值对的 `array`,或现有的 `Headers` 对象。
`status` : 响应的状态码。
`statusText` : 与状态码对应的状态消息。 可以使用以下属性和方法创建新的 `Response()` 对象: `arrayBuffer()` : 获取 `Response` 流并读取至完成。返回一个 `Promise`,该 Promise 解析为 `ArrayBuffer`。 `bodyUsed` : 布尔值,如果主体已被读取则为 `true`。 `headers` : 与 `Response` 关联的只读 `Headers` 对象。 `json()` : 获取 `Response` 流并读取至完成。返回一个 `Promise`,该 Promise 解析为将主体文本解析为 JSON 的结果。 `ok` : 布尔值,如果响应成功(状态码在 200–299 之间)则为 `true`。 `redirected` : 布尔值,如果响应是重定向的结果则为 `true`。 `status` : 响应的状态码。 `statusText` : 与状态码对应的状态消息。 `text()` : 获取 `Response` 流并读取至完成。返回一个 `Promise`,该 Promise 解析为字符串。 `type` : 响应的类型。 `url` : 响应的 URL。 ### ngx - `ngx.build` - `ngx.conf_file_path` - `ngx.conf_prefix` - `ngx.error_log_path` - `ngx.fetch()` - `ngx.log()` - `ngx.prefix` - `ngx.version` - `ngx.version_number` - `ngx.worker_id` `ngx` 全局对象自 0.5.0 起可用。 `ngx.build` : 包含可选 Angie 构建名称的字符串,对应于 configure 脚本的 `--build=name` 参数,默认为 `""` (0.8.0)。 `ngx.conf_file_path` : 包含当前 Angie 配置文件的文件路径的字符串(0.8.0)。 `ngx.conf_prefix` : 包含 Angie 配置前缀的文件路径的字符串——Angie 当前查找配置的目录(0.7.8)。 `ngx.error_log_path` : 包含当前错误日志文件的文件路径的字符串(0.8.0)。 `ngx.fetch(resource, [options])` : 发起请求以获取 `resource` (0.5.1),可以是 URL 或 `Request` 对象(0.7.10)。返回一个 `Promise`,该 Promise 解析为 `Response` 对象。从 0.7.0 开始,支持 `https://` 协议;不处理重定向。
如果 `resource` 中的 URL 指定为域名,则使用解析器进行解析。如果指定了 `https://` 协议,则应配置 `js_fetch_trusted_certificate` 指令以对 `resource` 的 HTTPS 服务器进行身份验证。
`options` 参数应为包含以下键的对象:
`body` : 请求主体,默认为空。
`buffer_size` : 读取响应的缓冲区大小,默认为 `4096`。
`headers` : 请求头对象。
`max_response_body_size` : 响应主体的最大大小(以字节为单位),默认为 `32768`。
`method` : HTTP 方法,默认使用 `GET` 方法。
`verify` : 启用或禁用 HTTPS 服务器证书验证,默认为 `true` (0.7.0)。
示例:
```javascript let reply = await ngx.fetch('http://example.com/'); let body = await reply.text();
r.return(200, body); ``` `ngx.log(level, message)` : 使用指定的日志级别将消息写入错误日志。`level` 参数指定日志级别之一;:samp:message 参数可以是字符串或 Buffer。可以指定以下日志级别:`ngx.INFO`、`ngx.WARN` 和 `ngx.ERR`。
#### NOTE 由于 Angie 具有硬编码的最大行长度限制,因此只能记录字符串的前 2048 个字节。 `ngx.prefix` : 包含 Angie 前缀文件路径的字符串 — 保存服务器文件的目录(0.8.0)。 `ngx.version` : 包含 Angie 版本的字符串,例如:`1.25.0` (0.8.0)。 `ngx.version_number` : 包含 Angie 版本的数字,例如:`1025000` (0.8.0)。 `ngx.worker_id` : 对应于 Angie 内部工作进程 ID 的数字,该值介于 `0` 和 `worker_processes` 指令中指定的值之间(0.8.0)。 ### ngx.shared `ngx.shared` 全局对象从 0.8.0 开始可用。 #### SharedDict - `ngx.shared.SharedDict.add()` - `ngx.shared.SharedDict.capacity` - `ngx.shared.SharedDict.clear()` - `ngx.shared.SharedDict.delete()` - `ngx.shared.SharedDict.freeSpace()` - `ngx.shared.SharedDict.get()` - `ngx.shared.SharedDict.has()` - `ngx.shared.SharedDict.incr()` - `ngx.shared.SharedDict.items()` - `ngx.shared.SharedDict.keys()` - `ngx.shared.SharedDict.name` - `ngx.shared.SharedDict.pop()` - `ngx.shared.SharedDict.replace()` - `ngx.shared.SharedDict.set()` - `ngx.shared.SharedDict.size()` - `ngx.shared.SharedDict.type` 共享字典对象从 0.8.0 开始可用。共享字典的名称、类型和大小通过 HTTP 或 Stream 中的 `js_shared_dict_zone` 指令设置。 `SharedDict()` 对象具有以下属性和方法: `ngx.shared.SharedDict.add(key, value [,timeout])` : 仅当键尚不存在时,才为字典中的指定 `key` 设置 `value`。`key` 参数是表示要添加项的键的字符串;:samp:value 参数是要添加项的值。
可选的 `timeout` 参数以毫秒为单位指定,并覆盖 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `timeout` 参数(从 0.8.5 开始)。当某些键预期具有唯一的超时时间时,这可能很有用。
如果值已成功添加到 `SharedDict` 字典,则返回 `true`;如果键已存在于字典中,则返回 `false`。如果 `SharedDict` 字典中没有足够的可用空间,则抛出 `SharedMemoryError`。如果 `value` 的类型与此字典预期的类型不同,则抛出 `TypeError`。 `ngx.shared.SharedDict.capacity` : 返回 `SharedDict` 字典的容量,对应于 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `size` 参数。 `ngx.shared.SharedDict.clear()` : 从 `SharedDict` 字典中删除所有项。 `ngx.shared.SharedDict.delete(key)` : 从 `SharedDict` 字典中删除与指定键关联的项;如果字典中的项存在并已删除,则返回 `true`,否则返回 `false`。 `ngx.shared.SharedDict.freeSpace()` : 返回可用页面大小(以字节为单位)。如果大小为零,则 `SharedDict` 字典仍将接受新值(如果已占用页面中有空间)。 `ngx.shared.SharedDict.get(key)` : 通过其 `key` 检索项;返回与 `key` 关联的值,如果没有则返回 `undefined`。 `ngx.shared.SharedDict.has(key)` : 通过其 `key` 搜索项;如果存在此类项,则返回 `true`,否则返回 `false`。 `ngx.shared.SharedDict.incr(key,delta[[,init], timeout])` : 将与 `key` 关联的整数值增加 `delta`。`key` 参数是字符串;:samp:delta 参数是要增加或减少值的数字。如果键不存在,则该项将初始化为可选的 `init` 参数,默认为 `0`。
可选的 `timeout` 参数以毫秒为单位指定,并覆盖 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `timeout` 参数(从 0.8.5 开始)。当某些键预期具有唯一的超时时间时,这可能很有用。
返回新值。如果 `SharedDict` 字典中没有足够的可用空间,则抛出 `SharedMemoryError`。如果此字典不期望数字,则抛出 `TypeError`。
#### NOTE 仅当使用 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `type=number` 参数声明字典类型时,才能使用此方法。 `ngx.shared.SharedDict.items([maxCount])` : 返回 `SharedDict` 字典键值项的数组(从 0.8.1 开始)。`maxCount` 参数设置要检索的最大项数,默认为 `1024`。 `ngx.shared.SharedDict.keys([maxCount])` : 返回 `SharedDict` 字典键的数组。`maxCount` 参数设置要检索的最大键数,默认为 `1024`。 `ngx.shared.SharedDict.name` : 返回 `SharedDict` 字典的名称,对应于 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `zone=` 参数。 `ngx.shared.SharedDict.pop(key)` : 从 `SharedDict` 字典中删除与指定 `key` 关联的项;返回与 `key` 关联的值,如果没有则返回 `undefined`。 `ngx.shared.SharedDict.replace(key, value)` : 仅当键已存在时,才替换指定 `key` 的 `value`;如果值已成功替换,则返回 `true`,如果键在 `SharedDict` 字典中不存在,则返回 `false`。如果 `SharedDict` 字典中没有足够的可用空间,则抛出 `SharedMemoryError`。如果 `value` 的类型与此字典预期的类型不同,则抛出 `TypeError`。 `ngx.shared.SharedDict.set(key, value [,timeout])` : 为指定的 `key` 设置 `value`;返回此 `SharedDict` 字典(用于方法链)。
可选的 `timeout` 参数以毫秒为单位指定,并覆盖 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `timeout` 参数(从 0.8.5 开始)。当某些键预期具有唯一的超时时间时,这可能很有用。 `ngx.shared.SharedDict.size()` : 返回 `SharedDict` 字典的项数。 `ngx.shared.SharedDict.type` : 返回 `string` 或 `number`,对应于 HTTP 或 Stream 中 `js_shared_dict_zone` 指令的 `type=` 参数设置的 `SharedDict` 字典类型。 ## 内置对象 ### console - `console.error()` - `console.info()` - `console.log()` - `console.time()` - `console.timeEnd()` - `console.warn()` `console` 对象从 Angie 0.8.2 开始可用,从 CLI 0.2.6 开始可用。 `console.error(msg[, msg2 ...])` : 输出一条或多条错误消息。消息可以是字符串或对象。 `console.info(msg[, msg2 ...])` : 输出一条或多条信息消息。消息可以是字符串或对象。 `console.log(msg[, msg2 ...])` : 输出一条或多条日志消息。消息可以是字符串或对象。 `console.time(label)` : 启动一个计时器,可以跟踪操作所需的时间。`label` 参数允许命名不同的计时器。如果使用相同的名称调用 `console.timeEnd()`,则将输出自计时器启动以来经过的时间(以毫秒为单位)。 `console.timeEnd(label)` : 停止先前由 `console.time()` 启动的计时器。`label` 参数允许命名不同的计时器。 `console.warn(msg[, msg2 ...])` : 输出一条或多条警告消息。消息可以是字符串或对象。 ### crypto - `crypto.getRandomValues()` - `crypto.subtle.encrypt()` - `crypto.subtle.decrypt()` - `crypto.subtle.deriveBits()` - `crypto.subtle.deriveKey()` - `crypto.subtle.digest()` - `crypto.subtle.exportKey()` - `crypto.subtle.generateKey()` - `crypto.subtle.importKey()` - `crypto.subtle.sign()` - `crypto.subtle.verify()` `crypto` 对象是一个全局对象,允许使用加密功能(自 0.7.0 起)。 `crypto.getRandomValues(typedArray)` : 获取加密强度的随机值。返回作为 `typedArray` 传递的同一数组,但其内容被替换为新生成的随机数。可能的值:
`typedArray` : 可以是 `Int8Array`、`Int16Array`、`Uint16Array`、`Int32Array` 或 `Uint32Array`。 `crypto.subtle.encrypt(algorithm, key, data)` : 使用提供的 `algorithm` 和 `key` 加密 `data`。返回一个 `Promise`,该 Promise 将使用包含密文的 `ArrayBuffer` 来兑现。可能的值:
`algorithm` : 一个对象,指定要使用的算法以及所需的任何额外参数:
- 对于 `RSA-OAEP`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `RSA-OAEP`: ```javascript crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data) ``` - 对于 `AES-CTR`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `AES-CTR`。
`counter` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView` — 计数器块的初始值,必须为 16 字节长(AES 块大小)。此块最右边的 length 位用于计数器,其余部分用于随机数。例如,如果 length 设置为 64,则 counter 的前半部分是随机数,后半部分用于计数器。
`length` : 计数器块中用于实际计数器的位数。计数器必须足够大,以免回绕。 - 对于 `AES-CBC`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `AES-CBC`。
`iv` : 初始化向量,是一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,必须为 16 字节,不可预测,最好是加密随机的。但是,它不需要保密,例如,它可以与密文一起未加密传输。 - 对于 `AES-GCM`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `AES-GCM`。
`iv` : 初始化向量,是一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,必须为 16 字节,并且对于使用给定密钥执行的每个加密操作必须是唯一的。
`additionalData` : (可选)是一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,包含不会被加密但将与加密数据一起进行身份验证的附加数据。如果指定了 `additionalData`,则必须在相应的 `decrypt()` 调用中指定相同的数据:如果提供给 `decrypt()` 调用的数据与原始数据不匹配,解密将抛出异常。`additionalData` 的位长度必须小于 `2^64 - 1`。
`tagLength` : (可选,默认为 `128`) - 一个 `number`,确定在加密操作中生成的身份验证标签的位大小,并在相应的解密中用于身份验证。可能的值: `32`、`64`、`96`、`104`、`112`、`120` 或 `128`。AES-GCM 规范建议应为 `96`、`104`、`112`、`120` 或 `128`,尽管在某些应用程序中 `32` 或 `64` 位可能是可接受的。
`key` : 一个 `CryptoKey`,包含用于加密的密钥。
`data` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,包含要加密的数据(也称为明文)。 `crypto.subtle.decrypt(algorithm, key, data)` : 解密加密的数据。返回一个包含解密数据的 `Promise`。可能的值:
`algorithm` : 一个对象,指定要使用的算法以及所需的任何额外参数。为额外参数提供的值必须与传递到相应 `encrypt()` 调用中的值匹配。
- 对于 `RSA-OAEP`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `RSA-OAEP`: ```javascript crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data) ``` - 对于 `AES-CTR`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `AES-CTR`。
`counter` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView` — 计数器块的初始值,必须为 16 字节长(AES 块大小)。此块最右边的 length 位用于计数器,其余部分用于随机数。例如,如果 length 设置为 64,则 counter 的前半部分是随机数,后半部分用于计数器。
`length` : 计数器块中用于实际计数器的位数。计数器必须足够大,以免回绕。 - 对于 `AES-CBC`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `AES-CBC`。
`iv` : 初始化向量,是一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,必须为 16 字节,不可预测,最好是加密随机的。但是,它不需要保密(例如,它可以与密文一起未加密传输)。 - 对于 `AES-GCM`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `AES-GCM`。
`iv` : 初始化向量,是一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,必须为 16 字节,并且对于使用给定密钥执行的每个加密操作必须是唯一的。
`additionalData` : (可选)是一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,包含不会被加密但将与加密数据一起进行身份验证的附加数据。如果指定了 `additionalData`,则必须在相应的 `decrypt()` 调用中指定相同的数据:如果提供给 `decrypt()` 调用的数据与原始数据不匹配,解密将抛出异常。`additionalData` 的位长度必须小于 `2^64 - 1`。
`tagLength` : (可选,默认为 `128`) - 一个 `number`,确定在加密操作中生成的身份验证标签的位大小,并在相应的解密中用于身份验证。可能的值: `32`、`64`、`96`、`104`、`112`、`120` 或 `128`。AES-GCM 规范建议应为 `96`、`104`、`112`、`120` 或 `128`,尽管在某些应用程序中 `32` 或 `64` 位可能是可接受的。
`key` : 一个 `CryptoKey`,包含用于解密的密钥。如果使用 `RSA-OAEP`,这是 `CryptoKeyPair` 对象的 `privateKey` 属性。
`data` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,包含要解密的数据(也称为密文)。 `crypto.subtle.deriveBits(algorithm, baseKey, length)` : 从基础密钥派生位数组。返回一个 `Promise`,该 Promise 将使用包含派生位的 `ArrayBuffer` 来兑现。可能的值:
`algorithm` : 一个对象,定义要使用的派生算法:
- 对于 `HKDF`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `HKDF`。
`hash` : 一个字符串,包含要使用的摘要算法: `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。
`salt` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,表示与 `digest` 函数的输出长度相同的随机或伪随机值。与传递到 `deriveKey()` 中的输入密钥材料不同,salt 不需要保密。
`info` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,表示特定于应用程序的上下文信息,用于将派生密钥绑定到应用程序或上下文,并允许在使用相同输入密钥材料的同时为不同上下文派生不同的密钥。此属性是必需的,但可以是空缓冲区。 - 对于 `PBKDF2`,传递一个具有以下键的对象:
`name` : 一个字符串,应设置为 `PBKDF2`。
`hash` : 一个字符串,包含要使用的摘要算法: `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。
`salt` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,表示至少 `16` 字节的随机或伪随机值。与传递到 `deriveKey()` 中的输入密钥材料不同,salt 不需要保密。
`iterations` : 一个 `number`,表示在 `deriveKey()` 中哈希函数将被执行的次数。 - 对于 `ECDH`,传递具有以下键的对象(自 0.9.1 起):
`name` : 一个字符串,应设置为 `ECDH`。
`public` : 一个 `CryptoKey`,表示另一方的公钥。该密钥必须使用与基础密钥相同的曲线生成。
`baseKey` : 一个 `CryptoKey`,表示派生算法的输入 - 派生函数的初始密钥材料:例如,对于 `PBKDF2`,它可能是一个密码,使用 `crypto.subtle.importKey()` 作为 `CryptoKey` 导入。
`length` : 一个数字,表示要派生的比特数。为了浏览器兼容性,该数字应该是 `8` 的倍数。 `crypto.subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)` : 从主密钥派生一个秘密密钥。可能的值:
`algorithm` : 一个对象,定义要使用的派生算法:
- 对于 `HKDF`,传递具有以下键的对象:
`name` : 一个字符串,应设置为 `HKDF`。
`hash` : 一个字符串,包含要使用的摘要算法: `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。
`salt` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,表示与 `digest` 函数输出长度相同的随机或伪随机值。与传递给 `deriveKey()` 的输入密钥材料不同,盐不需要保密。
`info` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,表示特定于应用程序的上下文信息,用于将派生密钥绑定到应用程序或上下文,并允许在使用相同输入密钥材料的同时为不同上下文派生不同的密钥。此属性是必需的,但可以是空缓冲区。 - 对于 `PBKDF2`,传递具有以下键的对象:
`name` : 一个字符串,应设置为 `PBKDF2`。
`hash` : 一个字符串,包含要使用的摘要算法: `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。
`salt` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,表示至少 `16` 字节的随机或伪随机值。与传递给 `deriveKey()` 的输入密钥材料不同,盐不需要保密。
`iterations` : 一个 `number`,表示在 `deriveKey()` 中哈希函数将被执行的次数。 - 对于 `ECDH`,传递具有以下键的对象(自 0.9.1 起):
`name` : 一个字符串,应设置为 `ECDH`。
`publicKey` : 一个 `CryptoKey`,表示另一方的公钥。该密钥必须使用与基础密钥相同的曲线生成。
`baseKey` : 一个 `CryptoKey`,表示派生算法的输入 - 派生函数的初始密钥材料:例如,对于 `PBKDF2`,它可能是一个密码,使用 `crypto.subtle.importKey()` 作为 `CryptoKey` 导入。
`derivedKeyAlgorithm` : 一个对象,定义派生密钥将用于的算法:
- 对于 `HMAC`,传递具有以下键的对象:
`name` : 一个字符串,应设置为 `HMAC`。
`hash` : 一个字符串,包含要使用的摘要函数的名称: `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。
`length` : (可选)是一个 `number`,表示密钥的比特长度。如果未指定,密钥的长度等于所选哈希函数的块大小。 - 对于 `AES-CTR`、`AES-CBC` 或 `AES-GCM`,传递具有以下键的对象:
`name` : 一个字符串,应根据所使用的算法设置为 `AES-CTR`、`AES-CBC` 或 `AES-GCM`。
`length` : 一个 `number`,表示要生成的密钥的比特长度: `128`、`192` 或 `256`。
`extractable` : 一个布尔值,指示是否可以导出密钥。
`keyUsages` : 一个 `Array`,指示可以对派生密钥执行的操作。密钥用途必须被 `derivedKeyAlgorithm` 中设置的算法所允许。可能的值:
`encrypt` : 用于加密消息的密钥。
`decrypt` : 用于解密消息的密钥。
`sign` : 用于签名消息的密钥。
`verify` : 用于验证签名的密钥。
`deriveKey` : 用于派生新密钥的密钥。
`deriveBits` : 用于派生比特的密钥。
`wrapKey` : 用于包装密钥的密钥。
`unwrapKey` : 用于解包密钥的密钥。 `crypto.subtle.digest(algorithm, data)` : 生成给定数据的摘要。接受要使用的摘要算法的标识符和要摘要的数据作为参数。返回一个 `Promise`,该 Promise 将使用摘要来完成。可能的值:
`algorithm` : 一个字符串,定义要使用的哈希函数: `SHA-1` (不用于加密应用程序)、`SHA-256`、`SHA-384` 或 `SHA-512`。
`data` : 一个 `ArrayBuffer`、`TypedArray` 或 `DataView`,包含要摘要的数据。 `crypto.subtle.exportKey(format, key)` : 导出密钥:将密钥作为 `CryptoKey` 对象,并以外部可移植格式返回密钥(自 0.7.10 起)。如果 `format` 是 `jwk`,则 `Promise` 使用包含密钥的 JSON 对象来完成。否则,promise 使用包含密钥的 `ArrayBuffer` 来完成。可能的值:
`format` : 一个字符串,描述应导出密钥的数据格式,可以是以下值:
`raw` : 原始数据格式。 - 对于 `HMAC`,传递具有以下键的对象: > > > `name` > > > : 字符串,应设置为 `HMAC`。 > > > `hash` > > > : 字符串,包含要使用的摘要函数的名称:可以是 `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。 > > > `length` > > > : (可选)是一个 `number`,表示密钥的比特长度。如果未指定,密钥的长度等于所选哈希函数的块大小。 > > - 对于 `AES-CTR`、`AES-CBC` 或 `AES-GCM`,传递具有以下键的对象: > > `name` > > : 字符串,应根据所使用的算法设置为 `AES-CTR`、`AES-CBC` 或 `AES-GCM`。 > > `length` > > : 一个 `number`,表示要生成的密钥的比特长度:可以是 `128`、`192` 或 `256`。 > `extractable` > : 布尔值,指示是否可以导出密钥。 > `keyUsages` > : 一个 `Array`,指示派生密钥可以执行的操作。密钥用途必须被 `derivedKeyAlgorithm` 中设置的算法所允许。可能的值: >
> `encrypt` > : 用于加密消息的密钥。 >
> `decrypt` > : 用于解密消息的密钥。 >
> `sign` > : 用于签名消息的密钥。 >
> `verify` > : 用于验证签名的密钥。 >
> `deriveKey` > : 用于派生新密钥的密钥。 >
> `deriveBits` > : 用于派生比特的密钥。 >
> `wrapKey` > : 用于包装密钥的密钥。 >
> `unwrapKey` > : 用于解包密钥的密钥。 `crypto.subtle.digest(algorithm, data)` : 生成给定数据的摘要。接受要使用的摘要算法的标识符和要摘要的数据作为参数。返回一个 `Promise`,该 Promise 以摘要来兑现。可能的值:
`algorithm` : 定义要使用的哈希函数的字符串:可以是 `SHA-1` (不用于加密应用)、`SHA-256`、`SHA-384` 或 `SHA-512`。
`data` : 包含要摘要的数据的 `ArrayBuffer`、`TypedArray` 或 `DataView`。 `crypto.subtle.exportKey(format, key)` : 导出密钥:接受一个密钥作为 `CryptoKey` 对象,并以外部可移植格式返回密钥(自 0.7.10 起)。如果 `format` 是 `jwk`,则 `Promise` 以包含密钥的 JSON 对象来兑现。否则,Promise 以包含密钥的 `ArrayBuffer` 来兑现。可能的值:
`format` : 描述密钥应以何种数据格式导出的字符串,可以是以下值:
`raw` : 原始数据格式。
`pkcs8` : [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208) 格式。
`spki` : [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1) 格式。
`jwk` : [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) 格式(自 0.7.10 起)。
`key` : 包含要导出的密钥的 `CryptoKey`。 `crypto.subtle.generateKey(algorithm, extractable, usage)` : 为对称算法生成新密钥或为公钥算法生成密钥对(自 0.7.10 起)。返回一个 `Promise`,该 Promise 以生成的密钥作为 `CryptoKey` 或 `CryptoKeyPair` 对象来兑现。可能的值:
`algorithm` : 一个字典对象,定义要生成的密钥类型并提供额外的特定于算法的参数:
- 对于 `RSASSA-PKCS1-v1_5`、`RSA-PSS` 或 `RSA-OAEP`,传递具有以下键的对象:
`name` : 字符串,应根据所使用的算法设置为 `RSASSA-PKCS1-v1_5`、`RSA-PSS` 或 `RSA-OAEP`。
`hash` : 字符串,表示要使用的 `digest` 函数的名称,可以是 `SHA-256`、`SHA-384` 或 `SHA-512`。 - 对于 `ECDSA`,传递具有以下键的对象:
`name` : 字符串,应设置为 `ECDSA`。
`namedCurve` : 字符串,表示要使用的椭圆曲线的名称,可以是 `P-256`、`P-384` 或 `P-521`。 - 对于 `HMAC`,传递具有以下键的对象:
`name` : 字符串,应设置为 `HMAC`。
`hash` : 字符串,表示要使用的 `digest` 函数的名称,可以是 `SHA-256`、`SHA-384` 或 `SHA-512`。
`length` : (可选)是一个数字,表示密钥的比特长度。如果省略,密钥的长度等于所选摘要函数生成的摘要的长度。 - 对于 `AES-CTR`、`AES-CBC` 或 `AES-GCM`,传递标识算法的字符串或形式为 ` *"name": "ALGORITHM"* ` 的对象,其中 `ALGORITHM` 是算法的名称。 - 对于 `ECDH`,传递具有以下键的对象(自 0.9.1 起):
`name` : 字符串,应设置为 `ECDH`。
`namedCurve` : 字符串,表示要使用的椭圆曲线的名称,可以是 `P-256`、`P-384` 或 `P-521`。
`extractable` : 布尔值,指示是否可以导出密钥。
`usage` : 一个 `array`,指示密钥的可能操作:
`encrypt` : 用于加密消息的密钥。
`decrypt` : 用于解密消息的密钥。
`sign` : 用于签名消息的密钥。
`verify` : 用于验证签名的密钥。
`deriveKey` : 用于派生新密钥的密钥。
`deriveBits` : 用于派生比特的密钥。
`wrapKey` : 用于包装密钥的密钥。
`unwrapKey` : 用于解包密钥的密钥。 `crypto.subtle.importKey(format, keyData, algorithm, extractable, keyUsages)` : 导入密钥:接受外部可移植格式的密钥作为输入,并返回一个 `CryptoKey` 对象。返回一个 `Promise`,该 Promise 以导入的密钥作为 `CryptoKey` 对象来兑现。可能的值:
`format` : 描述要导入的密钥的数据格式的字符串,可以是以下值:
`raw` : 原始数据格式。
`pkcs8` : [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208) 格式。
`spki` : [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1) 格式。
`jwk` : [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) 格式(自 0.7.10 起)。
`keyData` : 包含给定格式密钥的 `ArrayBuffer`、`TypedArray` 或 `DataView` 对象。
`algorithm` : 定义要导入的密钥类型并提供额外的算法特定参数的字典对象:
- 对于 `RSASSA-PKCS1-v1_5`、`RSA-PSS` 或 `RSA-OAEP`,传递具有以下键的对象:
`name` : 字符串,应根据所使用的算法设置为 `RSASSA-PKCS1-v1_5`、`RSA-PSS` 或 `RSA-OAEP`。
`hash` : 字符串,表示要使用的 `digest` 函数的名称,可以是 `SHA-1`、`SHA-256`、`SHA-384` 或 `SHA-512`。 - 对于 `ECDSA`,传递具有以下键的对象:
`name` : 字符串,应设置为 `ECDSA`。
`namedCurve` : 字符串,表示要使用的椭圆曲线的名称,可以是 `P-256`、`P-384` 或 `P-521`。 - 对于 `HMAC`,传递具有以下键的对象:
`name` : 字符串,应设置为 `HMAC`。
`hash` : 字符串,表示要使用的 `digest` 函数的名称,可以是 `SHA-256`、`SHA-384` 或 `SHA-512`。
`length` : (可选)是一个数字,表示密钥的比特长度。如果省略,密钥的长度等于所选摘要函数生成的摘要的长度。 - 对于 `AES-CTR`、`AES-CBC` 或 `AES-GCM`,传递标识算法的字符串或形式为 ` *"name": "ALGORITHM"* ` 的对象,其中 `ALGORITHM` 是算法的名称。 - 对于 `PBKDF2`,传递 `PBKDF2` 字符串。 - 对于 `HKDF`,传递 `HKDF` 字符串。 - 对于 `ECDH`,传递具有以下键的对象(自 0.9.1 起):
`name` : 字符串,应设置为 `ECDH`。
`namedCurve` : 字符串,表示要使用的椭圆曲线的名称,可以是 `P-256`、`P-384` 或 `P-521`。
`extractable` : 布尔值,指示是否可以导出密钥。
`keyUsages` : 一个 `array`,指示密钥的可能操作:
`encrypt` : 用于加密消息的密钥。
`decrypt` : 用于解密消息的密钥。
`sign` : 用于签名消息的密钥。
`verify` : 用于验证签名的密钥。
`deriveKey` : 用于派生新密钥的密钥。
`deriveBits` : 用于派生比特的密钥。
`wrapKey` : 用于包装密钥的密钥。
`unwrapKey` : 用于解包密钥的密钥。 `crypto.subtle.sign(algorithm, key, data)` : 返回 `signature` 作为 `Promise`,该 Promise 以包含签名的 `ArrayBuffer` 来兑现。可能的值:
`algorithm` : 指定要使用的签名算法及其参数的字符串或对象:
- 对于 `RSASSA-PKCS1-v1_5`,传递标识算法的字符串或形式为 ` *"name": "ALGORITHM"* ` 的对象。 - 对于 `RSA-PSS`,传递具有以下键的对象:
`name` : 字符串,应设置为 `RSA-PSS`。
`saltLength` : 长整型 `integer`,表示要使用的随机盐的长度(以字节为单位)。 - 对于 `ECDSA`,传递具有以下键的对象:
`name` : 字符串,应设置为 `ECDSA`。
`hash` : 要使用的摘要算法的标识符,可以是 `SHA-256`、`SHA-384` 或 `SHA-512`。 - 对于 `HMAC`,传递标识算法的字符串或形式为 ` *"name": "ALGORITHM"* ` 的对象。
`key` : 包含用于签名的密钥的 `CryptoKey` 对象。如果算法标识公钥密码系统,则这是私钥。
`data` : 包含要签名的数据的 `ArrayBuffer`、`TypedArray` 或 `DataView` 对象。 `crypto.subtle.verify(algorithm, key, signature, data)` : 验证数字签名;返回一个 `Promise`,该 Promise 以布尔值兑现:如果签名有效则为 `true`,否则为 `false`。可能的值:
`algorithm` : 指定要使用的算法及其参数的字符串或对象:
- 对于 `RSASSA-PKCS1-v1_5`,传递标识算法的字符串或形式为 ` *"name": "ALGORITHM"* ` 的对象。 - 对于 `RSA-PSS`,传递具有以下键的对象:
`name` : 字符串,应设置为 `RSA-PSS`。
`saltLength` : 长整型 `integer`,表示要使用的随机盐的长度(以字节为单位)。 - 对于 `ECDSA`,传递具有以下键的对象:
`name` : 字符串,应设置为 `ECDSA`。
`hash` : 要使用的摘要算法的标识符,可以是 `SHA-256`、`SHA-384` 或 `SHA-512`。 - 对于 `HMAC`,传递标识算法的字符串或形式为 ` *"name": "ALGORITHM"* ` 的对象。
`key` : 包含用于验证的密钥的 `CryptoKey` 对象。对于对称算法,它是密钥;对于公钥系统,它是公钥。
`signature` : 包含要验证的签名的 `ArrayBuffer`、`TypedArray` 或 `DataView`。
`data` : 包含要验证其签名的数据的 `ArrayBuffer`、`TypedArray` 或 `DataView` 对象。 #### CryptoKey - `CryptoKey.algorithm` - `CryptoKey.extractable` - `CryptoKey.type` - `CryptoKey.usages` `CryptoKey` 对象表示从 `SubtleCrypto` 方法之一获得的加密 `key`：`crypto.subtle.generateKey()`、`crypto.subtle.deriveKey()`、`crypto.subtle.importKey()`。 `CryptoKey.algorithm` : 返回一个对象,描述此密钥可用于的算法以及任何相关的额外参数(自 0.8.0 起),只读。 `CryptoKey.extractable` : 布尔值,如果密钥可以导出则为 `true` (自 0.8.0 起),只读。 `CryptoKey.type` : 字符串值,指示对象表示的密钥类型,只读。可能的值:
`secret` : 此密钥是用于对称算法的秘密密钥。
`private` : 此密钥是非对称算法 `CryptoKeyPair` 的私钥部分。
`public` : 此密钥是非对称算法 `CryptoKeyPair` 的公钥部分。 `CryptoKey.usages` : 字符串数组,指示此密钥可用于什么用途(自 0.8.0 起),只读。可能的数组值:
`encrypt` : 用于加密消息的密钥。
`decrypt` : 用于解密消息的密钥。
`sign` : 用于签名消息的密钥。
`verify` : 用于验证签名的密钥。
`deriveKey` : 用于派生新密钥的密钥。
`deriveBits` : 用于派生比特的密钥。 #### CryptoKeyPair - `CryptoKeyPair.privateKey` - `CryptoKeyPair.publicKey` `CryptoKeyPair` 是 WebCrypto API 的字典对象,表示非对称密钥对。 `CryptoKeyPair.privateKey` : 表示私钥的 `CryptoKey` 对象。 `CryptoKeyPair.publicKey` : 表示公钥的 `CryptoKey` 对象。 ### njs - `njs.version` - `njs.version_number` - `njs.dump()` - `njs.memoryStats` - `njs.on()` `njs` 对象是表示当前 VM 实例的全局对象(自 0.2.0 起)。 `njs.version` : 返回包含当前 NJS 版本的字符串(例如,"0.7.4")。 `njs.version_number` : 返回包含当前 NJS 版本的数字。例如,"0.7.4" 返回为 `0x000704` (自 0.7.4 起)。 `njs.dump(value)` : 返回值的美化打印字符串表示。 `njs.memoryStats` : 包含当前 VM 实例内存统计信息的对象(自 0.7.8 起)。
`size` : NJS 内存池从操作系统申请的内存量(以字节为单位)。 `njs.on(event, callback)` : 为指定的 VM 事件注册回调(自 0.5.2 起)。事件可以是以下字符串之一:
`exit` : 在 VM 销毁之前调用。回调不带参数调用。 ### process - `process.argv` - `process.env` - `process.kill()` - `process.pid` - `process.ppid` `process` 对象是提供有关当前进程信息的全局对象(0.3.3)。 `process.argv` : 返回包含启动当前进程时传递的命令行参数的数组。 `process.env` : 返回包含用户环境的对象。
#### NOTE 默认情况下,Angie 会删除从其父进程继承的所有环境变量,但 TZ 变量除外。使用 `env` 指令来保留一些继承的变量。 `process.kill(pid, number | string)` : 向由 `pid` 标识的进程发送信号。信号名称是数字或字符串,例如 `SIGINT` 或 `SIGHUP`。有关更多信息,请参阅 [kill(2)](https://man7.org/linux/man-pages/man2/kill.2.html)。 `process.pid` : 返回当前进程的 PID。 `process.ppid` : 返回当前父进程的 PID。 ### String 默认情况下,NJS 中的所有字符串都是 Unicode 字符串。它们对应于包含 Unicode 字符的 ECMAScript 字符串。在 0.8.0 之前,还支持字节字符串。 #### 字节字符串(已移除) #### NOTE 自 0.8.0 起,已移除对字节字符串和字节字符串方法的支持。在处理字节序列时,应使用 [Buffer](#njs-buffer) 对象和 Buffer 属性,例如 `r.requestBuffer`、`r.rawVariables`。 字节字符串包含字节序列,用于将 Unicode 字符串序列化为外部数据以及从外部源反序列化。例如,:samp:toUTF8() 方法使用 UTF-8 编码将 Unicode 字符串序列化为字节字符串。`toBytes()` 方法将代码点最多为 255 的 Unicode 字符串序列化为字节字符串;否则返回 `null`。 以下方法已过时并在 0.8.0 中移除: - `String.bytesFrom()` (在 0.8.0 中移除,使用 `Buffer.from()`) - `String.prototype.fromBytes()` (在 0.8.0 中移除) - `String.prototype.fromUTF8()` (在 0.8.0 中移除,使用 `TextDecoder`) - `String.prototype.toBytes()` (在 0.8.0 中移除) - `String.prototype.toString()` 带编码(在 0.8.0 中移除) - `String.prototype.toUTF8()` (在 0.8.0 中移除,使用 `TextEncoder`) ## Web API ### TextDecoder - `TextDecoder()` - `TextDecoder.prototype.encoding` - `TextDecoder.prototype.fatal` - `TextDecoder.prototype.ignoreBOM` - `TextDecoder.prototype.decode()` `TextDecoder` 从字节流生成代码点流(0.4.3)。 `TextDecoder([[encoding], options])` : 为指定的 `encoding` 创建新的 `TextDecoder` 对象;目前仅支持 UTF-8。`options` 是具有以下属性的 `TextDecoderOptions` 字典:
`fatal` : 布尔标志,指示当发现编码错误时 `TextDecoder.decode()` 是否必须抛出 `TypeError` 异常,默认为 `false`。 `TextDecoder.prototype.encoding` : 返回包含 `TextDecoder()` 使用的编码名称的字符串,只读。 `TextDecoder.prototype.fatal` : 布尔标志,如果错误模式是致命的则为 `true`,只读。 `TextDecoder.prototype.ignoreBOM` : 布尔标志,如果忽略字节顺序标记则为 `true`,只读。 `TextDecoder.prototype.decode(buffer, [options])` : 返回包含由 `TextDecoder()` 从 `buffer` 解码的文本的字符串。缓冲区可以是 `ArrayBuffer`。`options` 是具有以下属性的 `TextDecodeOptions` 字典:
`stream` : 布尔标志,指示后续调用 `decode()` 时是否会有额外数据:如果分块处理数据则为 `true`,如果是最后一块或数据未分块则为 `false`。默认为 `false`。
示例:
```javascript >> (new TextDecoder()).decode(new Uint8Array([206,177,206,178])) αβ ``` ### TextEncoder - `TextEncoder()` - `TextEncoder.prototype.encode()` - `TextEncoder.prototype.encodeInto()` `TextEncoder` 对象从代码点流生成 UTF-8 编码的字节流(0.4.3)。 `TextEncoder()` : 返回新构造的 `TextEncoder`,它将生成 UTF-8 编码的字节流。 `TextEncoder.prototype.encode(string)` : 将 `string` 编码为包含 UTF-8 编码文本的 `Uint8Array`。 `TextEncoder.prototype.encodeInto(string, uint8Array)` : 将 `string` 编码为 UTF-8,将结果放入目标 `Uint8Array`,并返回显示编码进度的字典对象。字典对象包含两个成员:
`read` : 从源 `string` 转换为 UTF-8 的 UTF-16 代码单元数。
`written` : 目标 `Uint8Array` 中修改的字节数。 ## 定时器 - `clearTimeout()` - `setTimeout()` `clearTimeout(timeout)` : 取消由 `setTimeout()` 创建的 `timeout` 对象。 `setTimeout(function, milliseconds[, argument1, argumentN])` : 在指定的 `milliseconds` 毫秒数后调用 `function`。可以向指定的函数传递一个或多个可选 `arguments`。返回 `timeout` 对象。
示例:
```javascript function handler(v) { // ... }
t = setTimeout(handler, 12);
// ...
clearTimeout(t); ``` ### 全局函数 - `atob()` - `btoa()` `atob(encodedData)` : 解码使用 `Base64` 编码的数据字符串。`encodedData` 参数是包含 Base64 编码数据的二进制字符串。返回包含从 `encodedData` 解码的数据的字符串。
类似的 `btoa()` 方法可用于编码和传输可能导致通信问题的数据,然后传输它并使用 `atob()` 方法再次解码数据。例如,您可以编码、传输和解码控制字符,如 ASCII 值 `0` 到 `31`。
示例:
```javascript const encodedData = btoa("text to encode"); // 编码字符串 const decodedData = atob(encodedData); // 解码字符串 ``` `btoa(stringToEncode)` : 从二进制字符串创建 Base64 编码的 ASCII 字符串。`stringToEncode` 参数是要编码的二进制字符串。返回包含 `stringToEncode` 的 Base64 表示的 ASCII 字符串。
该方法可用于编码可能导致通信问题的数据,传输它,然后使用 `atob()` 方法再次解码数据。例如,您可以编码控制字符,如 ASCII 值 `0` 到 `31`。
示例:
```javascript const encodedData = btoa("text to encode"); // 编码字符串 const decodedData = atob(encodedData); // 解码字符串 ``` ## 内置模块 ### Buffer `Buffer` 对象是处理二进制数据的 Node.js 兼容方式。由于文件内容过于庞大,本节仅限于 Buffer 方法的完整列表。 - `Buffer.alloc()` - `Buffer.allocUnsafe()` - `Buffer.byteLength()` - `Buffer.compare()` - `Buffer.concat()` - `Buffer.from(array)` - `Buffer.from(arrayBuffer)` - `Buffer.from(buffer)` - `Buffer.from(object)` - `Buffer.from(string)` - `Buffer.isBuffer()` - `Buffer.isEncoding()` - `buffer[]` - `buf.buffer` - `buf.byteOffset` - `buf.compare()` - `buf.copy()` - `buf.equals()` - `buf.fill()` - `buf.includes()` - `buf.indexOf()` - `buf.lastIndexOf()` - `buf.length` - `buf.readIntBE()` - `buf.readIntLE()` - `buf.readUIntBE()` - `buf.readUIntLE()` - `buf.readDoubleBE()` - `buf.readDoubleLE()` - `buf.readFloatBE()` - `buf.readFloatLE()` - `buf.subarray()` - `buf.slice()` - `buf.swap16()` - `buf.swap32()` - `buf.swap64()` - `buf.toJSON()` - `buf.toString()` - `buf.write()` - `buf.writeIntBE()` - `buf.writeIntLE()` - `buf.writeUIntBE()` - `buf.writeUIntLE()` - `buf.writeDoubleBE()` - `buf.writeDoubleLE()` - `buf.writeFloatBE()` - `buf.writeFloatLE()` 有关 Buffer 方法的详细文档,请参阅 [Node.js Buffer 文档](https://nodejs.org/api/buffer.html)。 ### Crypto Crypto 模块提供加密功能支持。Crypto 模块对象使用 `import crypto from 'crypto'` 导入。 #### NOTE 自 0.7.0 起,扩展的 crypto API 可作为全局 [crypto](#njs-builtin-crypto) 对象使用。 - `crypto.createHash()` - `crypto.createHmac()` `crypto.createHash(algorithm)` : 创建并返回一个 Hash 对象,可使用给定的 `algorithm` 生成哈希摘要。算法可以是 `md5`、`sha1` 和 `sha256`。 `crypto.createHmac(algorithm, secret key)` : 创建并返回一个 HMAC 对象,使用给定的 `algorithm` 和 `secret key`。算法可以是 `md5`、`sha1` 和 `sha256`。 #### Hash - `hash.update()` - `hash.digest()` `hash.update(data)` : 使用给定的 `data` 更新哈希内容。 `hash.digest([encoding])` : 计算使用 `hash.update()` 传递的所有数据的摘要。编码可以是 `hex`、`base64` 和 `base64url`。如果未提供编码,则返回 Buffer 对象(0.4.4)。
#### NOTE 在 0.4.4 版本之前,返回的是字节字符串而不是 Buffer 对象。 `hash.copy()` : 复制哈希的当前状态(自 0.7.12 起)。 示例: ```javascript import crypto from 'crypto'; crypto.createHash('sha1').update('A').update('B').digest('base64url'); /* BtlFlCqiamG-GMPiK_GbvKjdK10 */ ``` #### HMAC - `hmac.update()` - `hmac.digest()` `hmac.update(data)` : 使用给定的 `data` 更新 HMAC 内容。 `hmac.digest([encoding])` : 计算使用 `hmac.update()` 传递的所有数据的 HMAC 摘要。编码可以是 `hex`、`base64` 和 `base64url`。如果未提供编码,则返回 Buffer 对象(0.4.4)。
#### NOTE 在 0.4.4 版本之前,返回的是字节字符串而不是 Buffer 对象。 ### fs `fs` 模块提供文件系统操作。模块对象使用 `import fs from 'fs'` 导入。 - `fs.accessSync()` - `fs.appendFileSync()` - `fs.mkdirSync()` - `fs.readdirSync()` - `fs.readFileSync()` - `fs.realpathSync()` - `fs.renameSync()` - `fs.rmdirSync()` - `fs.symlinkSync()` - `fs.unlinkSync()` - `fs.writeFileSync()` - `fs.promises.readFile()` - `fs.promises.appendFile()` - `fs.promises.writeFile()` - `fs.promises.readdir()` - `fs.promises.mkdir()` - `fs.promises.rmdir()` - `fs.promises.rename()` - `fs.promises.unlink()` - `fs.promises.symlink()` - `fs.promises.access()` - `fs.promises.realpath()` 有关 fs 方法的详细文档,请参阅 [Node.js fs 文档](https://nodejs.org/api/fs.html)。 ### Query String Query String 模块提供解析和格式化 URL 查询字符串的方法。模块对象使用 `import qs from 'querystring'` 导入。 - `querystring.decode()` - `querystring.encode()` - `querystring.escape()` - `querystring.parse()` - `querystring.stringify()` - `querystring.unescape()` `querystring.decode()` : `querystring.parse()` 的别名。 `querystring.encode()` : `querystring.stringify()` 的别名。 `querystring.escape(string)` : 以针对 URL 查询字符串要求优化的方式对 `string` 执行 URL 百分号编码。该方法由 `querystring.stringify()` 使用,不应直接使用。 `querystring.parse(string[, separator[, equal[, options]]])` : 将 `string` 解析为 URL 查询字符串并返回一个对象。可选的 `separator` 参数(默认值: `&`)指定用于分隔键值对的子字符串。可选的 `equal` 参数(默认值: `=`)指定用于分隔键和值的子字符串。可选的 `options` 参数是一个对象,可能包含以下属性:
`decodeURIComponent` : 解码查询字符串中百分号编码字符时使用的函数,默认值: `querystring.unescape()`。
`maxKeys` : 要解析的最大键数,默认值: `1000`。值 `0` 会移除对键计数的限制。
示例:
```javascript >> qs.parse('foo=bar&abc=xyz&abc=123') { foo: 'bar', abc: ['xyz', '123'] } ``` `querystring.stringify(object[, separator[, equal[, options]]])` : 通过迭代 `object` 的自有属性从中生成 URL 查询字符串。可选的 `separator` 参数(默认值: `&`)指定用于分隔键值对的子字符串。可选的 `equal` 参数(默认值: `=`)指定用于分隔键和值的子字符串。可选的 `options` 参数是一个对象,可能包含以下属性:
`encodeURIComponent` : 将查询字符串中的 URL 不安全字符转换为百分号编码时使用的函数,默认值: `querystring.escape()`。
示例:
```javascript >> qs.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' }) 'foo=bar&baz=qux&baz=quux&corge=' ``` `querystring.unescape(string)` : 对 `string` 中的 URL 百分号编码字符执行解码。该方法由 `querystring.parse()` 使用,不应直接使用。 ### XML - `xml.parse()` - `xml.c14n()` - `xml.exclusiveC14n()` - `xml.serialize()` - `xml.serializeToString()` - `XMLDoc` - `XMLNode` - `XMLAttr` XML 模块允许处理 XML 文档(自 0.7.10 起)。XML 模块对象使用 `import xml from 'xml'` 导入。 示例: ```javascript import xml from 'xml'; let data = `ToveJani`; let doc = xml.parse(data); console.log(doc.note.to.$text) /* 'Tove' */ console.log(doc.note.to.$attr$b) /* 'bar' */ console.log(doc.note.$tags[1].$text) /* 'Jani' */ let dec = new TextDecoder(); let c14n = dec.decode(xml.exclusiveC14n(doc.note)); console.log(c14n) /* 'ToveJani' */ c14n = dec.decode(xml.exclusiveC14n(doc.note.to)); console.log(c14n) /* 'Tove' */ c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */)); console.log(c14n) /* 'Jani' */ ``` `parse(string | Buffer)` : 解析字符串或 Buffer 中的 XML 文档;返回一个表示已解析 XML 文档的 `XMLDoc` 包装对象。 `c14n(root_node[, excluding_node])` : 根据 [规范 XML 版本 1.1](https://www.w3.org/TR/xml-c14n) 规范化 `root_node` 及其子节点。`root_node` 可以是围绕 XML 结构的 `XMLNode` 或 `XMLDoc` 包装对象。返回包含规范化输出的 Buffer 对象。
`excluding_node` : 允许从输出中省略文档的一部分。 `exclusiveC14n(root_node[, excluding_node[, withComments[,prefix_list]]])` : 根据 [独占 XML 规范化版本 1.0](https://www.w3.org/TR/xml-exc-c14n/) 规范化 `root_node` 及其子节点。
`root_node` : 围绕 XML 结构的 `XMLNode` 或 `XMLDoc` 包装对象。
`excluding_node` : 允许从输出中省略与该节点及其子节点对应的文档部分。
`withComments` : 布尔值,默认为 `false`。如果为 `true`,规范化对应于 [带注释的独占 XML 规范化版本 1.0](http://www.w3.org/2001/10/xml-exc-c14n#WithComments)。返回包含规范化输出的 Buffer 对象。
`prefix_list` : 可选字符串,包含以空格分隔的命名空间前缀,这些命名空间也应包含在输出中。 `serialize()` : 与 `xml.c14n()` 相同(自 0.7.11 起)。 `serializeToString()` : 与 `xml.c14n()` 相同,但以 `string` 形式返回结果(自 0.7.11 起)。 `XMLDoc` : 围绕 XML 结构的 XMLDoc 包装对象,文档的根节点。
> `doc.$root` > : 按名称获取文档的根节点,如果不存在则为 undefined。
> `doc.abc` > : 名为 `abc` 的第一个根标签,作为 `XMLNode` 包装对象。 `XMLNode` : 围绕 XML 标签节点的 XMLNode 包装对象。
> `node.abc` > : 与 `node.$tag$abc` 相同。
> `node.$attr$abc` > : 节点的 `abc` 属性值,自 0.7.11 起可写。
> `node.$attr$abc=xyz` > : 与 `node.setAttribute('abc', xyz)` 相同(自 0.7.11 起)。
> `node.$attrs` > : 节点所有属性的 `XMLAttr` 包装对象。
> `node.$name` > : 节点的名称。
> `node.$ns` > : 节点的命名空间。
> `node.$parent` > : 当前节点的父节点。
> `node.$tag$abc` > : 节点名为 `abc` 的第一个子标签,自 0.7.11 起可写。
> `node.$tags` > : 所有子标签的数组。
> `node.$tags = [node1, node2, ...]` > : 与 `node.removeChildren()`; `node.addChild(node1)`; `node.addChild(node2)` 相同(自 0.7.11 起)。
> `node.$tags$abc` > : 节点所有名为 `abc` 的子标签,自 0.7.11 起可写。
> `node.$text` > : 节点的内容,自 0.7.11 起可写。
> `node.$text = 'abc'` > : 与 `node.setText('abc')` 相同(自 0.7.11 起)。
> `node.addChild(nd)` > : 将 XMLNode 作为子节点添加到该节点(自 0.7.11 起)。`nd` 在添加到节点之前会被递归复制。
> `node.removeAllAttributes()` > : 删除节点的所有属性(自 0.7.11 起)。
> `node.removeAttribute(attr_name)` > : 删除名为 `attr_name` 的属性(自 0.7.11 起)。
> `node.removeChildren(tag_name)` > : 删除所有名为 `tag_name` 的子标签(自 0.7.11 起)。如果 `tag_name` 不存在,则删除所有子标签。
> `node.removeText()` > : 删除节点的文本值(0.7.11)。
> `node.setAttribute(attr_name, value)` > : 为 `attr_name` 设置值(自 0.7.11 起)。当值为 `null` 时,删除名为 `attr_name` 的属性。
> `node.setText(value)` > : 为节点设置文本值(自 0.7.11 起)。当值为 `null` 时,删除节点的文本。 `XMLAttr` : 围绕 XML 节点属性的 XMLAttrs 包装对象。
> `attr.abc` > : `abc` 的属性值。 ### zlib `zlib` 模块(0.5.2)使用 zlib 提供压缩和解压缩功能。模块对象使用 `import zlib from 'zlib'` 导入。 - `zlib.constants` - `zlib.deflateRawSync()` - `zlib.deflateSync()` - `zlib.inflateRawSync()` - `zlib.inflateSync()` `zlib.constants` : 返回 zlib 常量字典。 `zlib.deflateRawSync(data[, options])` : 使用 Deflate 算法压缩 `data`,不包含 zlib 头。 `zlib.deflateSync(data[, options])` : 使用 Deflate 算法压缩 `data`。 `zlib.inflateRawSync(data[, options])` : 使用 Deflate 算法解压缩 `data`,不包含 zlib 头。 `zlib.inflateSync(data[, options])` : 使用 Deflate 算法解压缩 `data`。 `options` 参数是一个对象,可能包含以下属性: `level` : 压缩级别(默认值: `zlib.constants.Z_DEFAULT_COMPRESSION`)。 `memLevel` : 指定应为压缩状态分配多少内存(默认值: `zlib.constants.Z_DEFAULT_MEMLEVEL`)。 `strategy` : 调整压缩算法(默认值: `zlib.constants.Z_DEFAULT_STRATEGY`)。 `windowBits` : 设置窗口大小(默认值: `zlib.constants.Z_DEFAULT_WINDOWBITS`)。 `dictionary` : 包含预定义压缩字典的 Buffer。 `info` : 布尔值,如果为 `true`,返回包含 buffer 和 engine 的对象。 `chunkSize` : 压缩的块大小(默认值: `zlib.constants.Z_DEFAULT_CHUNK`)。 示例: ```javascript import zlib from 'zlib'; const deflated = zlib.deflateSync('Hello World!'); const inflated = zlib.inflateSync(deflated); console.log(inflated.toString()); // 'Hello World!' ```