Mercurial > hg > nginx-site

comparison xml/ru/docs/njs/index.xml @ 2245:87a0e2c73a25

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Refactored njs documentation.
author Yaroslav Zhuravlev <yar@nginx.com>
date Mon, 24 Sep 2018 19:10:29 +0300
parents 467aef18bf12
children 32ba43abf9cd
comparison
equal deleted inserted replaced
2244:467aef18bf12 2245:87a0e2c73a25
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Сценарный язык njs" 9 <article name="Сценарный язык njs"
10 link="/ru/docs/njs/index.html" 10 link="/ru/docs/njs/index.html"
11 lang="ru" 11 lang="ru"
12 rev="23"> 12 rev="24"
13 toc="no">
13 14
14 <section id="summary"> 15 <section id="links">
15
16 <para>
17 njs - это подмножество языка JavaScript, который позволяет
18 задавать обработчики location и переменных в
19 <link doc="../http/ngx_http_js_module.xml">http</link> и
20 <link doc="../stream/ngx_stream_js_module.xml">stream</link>.
21 njs совместим с
22 <link url="http://www.ecma-international.org/ecma-262/5.1/">ECMAScript 5.1</link>
23 (строгий режим) c некоторыми расширениями
24 <link url="http://www.ecma-international.org/ecma-262/6.0/">ECMAScript 6</link>.
25 Совместимость находится в стадии развития.
26 </para>
27
28 </section>
29
30
31 <section id="supported" name="Готовая функциональность">
32 16
33 <para> 17 <para>
34 <list type="bullet"> 18 <list type="bullet">
35 19
36 <listitem> 20 <listitem>
37 Логические значения, числа, строки, объекты, массивы, 21 <link doc="install.xml"/>
38 функции и регулярные выражения
39 </listitem> 22 </listitem>
40 23
41 <listitem> 24 <listitem>
42 ES5.1 операторы, ES7 операторы возведения в степень 25 <link doc="njs_changes.xml">Изменения в njs</link>
43 </listitem> 26 </listitem>
44 27
45 <listitem> 28 <listitem>
46 ES5.1 инструкции: <literal>var</literal>, <literal>if</literal>, 29 <link doc="njs_api.xml"/>
47 <literal>else</literal>, <literal>switch</literal>, <literal>for</literal>,
48 <literal>for in</literal>, <literal>while</literal>,
49 <literal>do while</literal>, <literal>break</literal>,
50 <literal>continue</literal>, <literal>return</literal>, <literal>try</literal>,
51 <literal>catch</literal>, <literal>throw</literal>, <literal>finally</literal>
52 </listitem> 30 </listitem>
53 31
54 <listitem> 32 <listitem>
55 ES6 методы и свойства <literal>Number</literal> и 33 <link doc="examples.xml"/>
56 <literal>Math</literal>
57 </listitem> 34 </listitem>
58 35
59 <listitem> 36 <listitem>
60 Методы <literal>String</literal>: 37 <link doc="compatibility.xml"/>
38 </listitem>
39
40 <listitem>
41 <link doc="cli.xml"/>
42 </listitem>
43
44 </list>
45 </para>
46
47 <para>
61 <list type="bullet"> 48 <list type="bullet">
62 49
63 <listitem> 50 <listitem>
64 ES5.1: 51 <link doc="../http/ngx_http_js_module.xml">
65 <literal>fromCharCode</literal>, <literal>concat</literal>, 52 ngx_http_js_module</link>
66 <literal>slice</literal>, <literal>substring</literal>,
67 <literal>substr</literal>, <literal>charAt</literal>,
68 <literal>charCodeAt</literal>, <literal>indexOf</literal>,
69 <literal>lastIndexOf</literal>, <literal>toLowerCase</literal>,
70 <literal>toUpperCase</literal>, <literal>trim</literal>,
71 <literal>search</literal>, <literal>match</literal>, <literal>split</literal>,
72 <literal>replace</literal>
73 </listitem> 53 </listitem>
74 54
75 <listitem> 55 <listitem>
76 ES6: 56 <link doc="../stream/ngx_stream_js_module.xml">
77 <literal>fromCodePoint</literal>, <literal>codePointAt</literal>, 57 ngx_stream_js_module</link>
78 <literal>includes</literal>, <literal>startsWith</literal>,
79 <literal>endsWith</literal>, <literal>repeat</literal>
80 </listitem>
81
82 <listitem>
83 нестандартные:
84 <literal>bytesFrom</literal> (0.2.3),
85 <literal>fromUTF8</literal>, <literal>toUTF8</literal>,
86 <literal>fromBytes</literal>, <literal>toBytes</literal>
87 </listitem>
88 </list>
89
90 </listitem>
91
92 <listitem>
93 Методы <literal>Object</literal>:
94 <list type="bullet">
95 <listitem>
96 ES5.1:
97 <literal>create</literal> (поддержка без списка свойств),
98 <literal>keys</literal>,
99 <literal>defineProperty</literal>,
100 <literal>defineProperties</literal>,
101 <literal>getOwnPropertyDescriptor</literal>,
102 <literal>getPrototypeOf</literal>,
103 <literal>hasOwnProperty</literal>,
104 <literal>isPrototypeOf</literal>,
105 <literal>preventExtensions</literal>,
106 <literal>isExtensible</literal>,
107 <literal>freeze</literal>,
108 <literal>isFrozen</literal>,
109 <literal>seal</literal>,
110 <literal>isSealed</literal>
111 </listitem>
112 </list>
113
114 </listitem>
115
116 <listitem>
117 Методы <literal>Array</literal>:
118 <list type="bullet">
119 <listitem>
120 ES5.1:
121 <literal>isArray</literal>, <literal>slice</literal>, <literal>splice</literal>,
122 <literal>push</literal>, <literal>pop</literal>, <literal>unshift</literal>,
123 <literal>shift</literal>, <literal>reverse</literal>, <literal>sort</literal>,
124 <literal>join</literal>, <literal>concat</literal>, <literal>indexOf</literal>,
125 <literal>lastIndexOf</literal>, <literal>forEach</literal>,
126 <literal>some</literal>, <literal>every</literal>, <literal>filter</literal>,
127 <literal>map</literal>, <literal>reduce</literal>,
128 <literal>reduceRight</literal>
129 </listitem>
130
131 <listitem>
132 ES6:
133 <literal>of</literal>, <literal>fill</literal>, <literal>find</literal>,
134 <literal>findIndex</literal>
135 </listitem>
136
137 <listitem>
138 ES7: <literal>includes</literal>
139 </listitem>
140 </list>
141
142 </listitem>
143
144 <listitem>
145 ES5.1 методы <literal>Function</literal>:
146 <literal>call</literal>, <literal>apply</literal>, <literal>bind</literal>
147 </listitem>
148
149 <listitem>
150 ES5.1 методы <literal>RegExp</literal>:
151 <literal>test</literal>, <literal>exec</literal>
152 </listitem>
153
154 <listitem>
155 ES5.1 методы <literal>Date</literal>
156 </listitem>
157
158 <listitem>
159 ES5.1 объект <literal>JSON</literal>
160 </listitem>
161
162 <listitem>
163 ES5.1 глобальные функции:
164 <literal>isFinite</literal>, <literal>isNaN</literal>,
165 <literal>parseFloat</literal>, <literal>parseInt</literal>,
166 <literal>decodeURI</literal>, <literal>decodeURIComponent</literal>,
167 <literal>encodeURI</literal>, <literal>encodeURIComponent</literal>
168 </listitem>
169
170 <listitem>
171 Объекты <literal>Error</literal>:
172 <literal>Error</literal>, <literal>EvalError</literal>,
173 <literal>InternalError</literal>, <literal>RangeError</literal>,
174 <literal>ReferenceError</literal>, <literal>SyntaxError</literal>,
175 <literal>TypeError</literal>, <literal>URIError</literal>
176 </listitem>
177
178 <listitem>
179 Функции <literal>setTimeout()</literal> и <literal>clearTimeout()</literal>
180 (0.2.0)
181 </listitem>
182
183 <listitem>
184 Методы <literal>File system</literal>
185 <link url="https://nodejs.org/api/fs.html#fs_file_system">стиль Node.js</link>:
186 <literal>fs.readFile</literal>, <literal>fs.readFileSync</literal>,
187 <literal>fs.appendFile</literal>, <literal>fs.appendFileSync</literal>,
188 <literal>fs.writeFile</literal>, <literal>fs.writeFileSync</literal>
189 </listitem>
190
191 <listitem>
192 Методы <literal>Crypto</literal>
193 <link url="https://nodejs.org/api/crypto.html#crypto_class_hash">стиль Node.js</link>
194 (0.2.0):
195 <literal>crypto.createHash</literal>,
196 <literal>crypto.createHmac</literal>
197 </listitem> 58 </listitem>
198 59
199 </list> 60 </list>
200 </para> 61 </para>
201 62
202 </section> 63 </section>
203 64
204 65
205 <section id="not_supported" name="Функциональность в разработке"> 66 <section id="summary">
67
68 <para>
69 njs - это подмножество языка JavaScript, позволяющее
70 расширить функциональность nginx.
71 njs совместим с
72 <link url="http://www.ecma-international.org/ecma-262/5.1/">ECMAScript 5.1</link>
73 (строгий режим) c некоторыми расширениями
74 <link url="http://www.ecma-international.org/ecma-262/6.0/">ECMAScript 6</link>
75 и позже.
76 Совместимость находится в стадии
77 <link doc="compatibility.xml">развития</link>.
78 </para>
79
80 </section>
81
82
83 <section id="usecases" name="Сценарии использования">
206 84
207 <para> 85 <para>
208 <list type="bullet"> 86 <list type="bullet">
209 87
210 <listitem> 88 <listitem>
211 ES6 объявления <literal>let</literal> и <literal>const</literal> 89 Комплексное управление доступом и проверка защиты при помощи njs
90 до получения запроса сервером группы
212 </listitem> 91 </listitem>
213 92
214 <listitem> 93 <listitem>
215 labels 94 Управление заголовками ответа
216 </listitem> 95 </listitem>
217 96
218 <listitem> 97 <listitem>
219 массив <literal>arguments</literal> 98 Создание гибких асинхронных обработчиков содержимого и фильтров
220 </listitem>
221
222 <listitem>
223 функция <literal>eval</literal>
224 </listitem>
225
226 <listitem>
227 конструктор <literal>new Function()</literal>
228 </listitem>
229
230 <listitem>
231 функции <literal>setInterval</literal>,
232 <literal>setImmediate</literal>
233 </listitem>
234
235 <listitem>
236 дроби без целой части (<literal>.235</literal>)
237 </listitem> 99 </listitem>
238 100
239 </list> 101 </list>
102 Подробнее о сценариях использования
103 см. в <link doc="examples.xml">примерах</link>
104 и <link url="https://www.nginx.com/blog/tag/nginscript/">блогпостах</link>.
240 </para> 105 </para>
241 106
242 </section> 107 </section>
243 108
244 109
245 <section id="changelog" name="История изменений"> 110 <section id="example" name="Базовый пример HTTP">
246 111
247 <para> 112 <para>
248 Полная история изменений njs доступна 113 Чтобы использовать njs в nginx, необходимо:
249 <link doc="njs_changes.xml">здесь</link>.
250 </para>
251 </section>
252
253 <section id="njs_api" name="Справочник njs API">
254
255 <para>
256 Справочник njs API доступен
257 <link doc="njs_api.xml">здесь</link>.
258 </para>
259 </section>
260
261
262 <section id="install" name="Загрузка и установка">
263
264 <para>
265 njs доступен в двух модулях:
266 <list type="bullet"> 114 <list type="bullet">
267 115
268 <listitem> 116 <listitem>
269 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> 117 <para>
118 <link doc="install.xml">установить</link> njs
119 </para>
120 </listitem>
121
122 <listitem id="hello_world">
123 <para>
124 создать файл сценария njs, например <path>hello_world.js</path>.
125 Описание свойств и методов языка njs
126 см. в <link doc="njs_api.xml">справочнике</link>.
127 <example>
128 function hello(r) {
129 r.return(200, “Hello world!”);
130 }
131 </example>
132 </para>
270 </listitem> 133 </listitem>
271 134
272 <listitem> 135 <listitem>
273 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> 136
137 <para>
138 в файле <path>nginx.conf</path> включить
139 модуль <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>
140 и указать директиву
141 <link doc="../http/ngx_http_js_module.xml" id="js_include">js_include</link>
142 с файлом сценария <path>hello_world.js</path>:
143 <example>
144 load_module modules/ngx_http_js_module.so;
145
146 events {}
147
148 http {
149 js_include hello_world.js;
150
151 server {
152 listen 8000;
153
154 location / {
155 js_content hello;
156 }
157 }
158 }
159
160 </example>
161 </para>
274 </listitem> 162 </listitem>
275 163
276 </list> 164 </list>
277 По умолчанию модули не собираются 165 Также доступна отдельная утилита <link doc="cli.xml">командной строки</link>,
278 их необходимо собрать из исходного кода 166 которая может использоваться независимо от nginx для разработки и отладки njs.
279 или установить из отдельного пакета Linux.
280 Кроме того, в пакете Linux предоставляется
281 <link id="cli">утилита</link> командной строки njs.
282 </para>
283
284
285 <section id="install_package" name="Установка пакета Linux">
286 <para>
287 Для установки модулей njs на Linux могут быть использованы
288 <link doc="../../linux_packages.xml" id="dynmodules">пакеты</link>:
289 <list type="bullet">
290
291 <listitem>
292 <literal>nginx-module-njs</literal> —
293 <link doc="../ngx_core_module.xml" id="load_module">динамические</link> модули
294 njs
295 </listitem>
296
297 <listitem>
298 <literal>nginx-module-njs-dbg</literal> — debug-символы для
299 пакета <literal>nginx-module-njs</literal>
300 </listitem>
301
302 </list>
303 </para> 167 </para>
304 168
305 </section> 169 </section>
306 170
307
308 <section id="install_sources" name="Установка из исходных файлов">
309
310 <para>
311 <link url="http://hg.nginx.org/njs">Репозиторий</link>
312 с исходным кодом njs можно клонировать следующей командой:
313 (необходим клиент <link url="https://www.mercurial-scm.org">Mercurial</link>):
314 <example>
315 hg clone http://hg.nginx.org/njs
316 </example>
317 Затем модули необходимо собрать с помощью
318 конфигурационного параметра <literal>--add-module</literal>:
319 <example>
320 ./configure --add-module=<value>path-to-njs</value>/nginx
321 </example>
322 Модули также можно собрать как
323 <link doc="../ngx_core_module.xml" id="load_module">динамические</link>:
324 <example>
325 ./configure --add-dynamic-module=<value>path-to-njs</value>/nginx
326 </example>
327 </para>
328
329 <para>
330 Чтобы собрать только <link id="cli">утилиту</link> командной строки njs
331 необходимо запустить
332 команды <literal>./configure</literal> и <literal>make njs</literal>
333 из корневого каталога.
334 Утилита доступна как <literal>./build/njs</literal>.
335 </para>
336
337 </section>
338
339
340 <section id="cli" name="Интерфейс командной строки">
341
342 <para>
343 Создание и отладка njs-скриптов может осуществляться
344 в командной строке.
345 Утилита командной строки доступна после установки
346 <link id="install_package">пакета</link> Linux
347 или после сборки из <link id="install_sources">исходных файлов</link>.
348 В отличие от njs, запущенном внутри nginx,
349 в утилите недоступны объекты nginx
350 (<link doc="njs_api.xml" id="http">HTTP</link> и
351 <link doc="njs_api.xml" id="stream">Stream</link>).
352 <example>
353 $ echo "2**3" | njs -
354 8
355
356 $ njs
357 >> var o = {a:[]}
358 undefined
359
360 >> JSON.stringify(o, undefined,1)
361 {
362 "a": [
363
364 ]
365 }
366 >>
367 </example>
368 </para>
369
370 </section>
371
372 </section>
373
374 </article> 171 </article>