---
title: "OpenResty 中常见 API 的介绍 - API7.ai"
description: "この記事では、OpenRestyの一般的なAPIを使用して、時間操作、正規表現、およびその他の一般的な問題に対処する方法を紹介します。"
url: "https://api7.ai/ja/learning-center/openresty/introduction-openresty-common-apis"
---

# OpenResty 中常见 API 的介绍

API7.ai

November 4, 2022

[OpenResty (NGINX + Lua)](https://api7.ai/learning-center/openresty)

以前の記事では、OpenRestyの多くの重要なLua APIに慣れ親しんできました。今日は、正規表現、時間、プロセスなどに関連する他の一般的なAPIについて学びます。

## 正規表現関連のAPI

まず、最も一般的で重要な正規表現から見ていきましょう。OpenRestyでは、Luaのパターンマッチングではなく、`ngx.re.*`が提供するAPIセットを使用して正規表現に関連するロジックを処理するべきです。これはパフォーマンス上の理由だけでなく、Luaの正規表現が自己完結型であり、`PCRE`仕様ではないため、多くの開発者にとって煩わしいからです。

以前の記事ですでにいくつかの`ngx.re.*` APIに出会っていますが、そのドキュメントは非常に詳細です。したがって、ここではそれらを再度リストアップしません。代わりに、以下の2つのAPIを個別に紹介します。

### `ngx.re.split`

最初に紹介するのは`ngx.re.split`です。文字列の分割は非常に一般的な機能であり、OpenRestyも対応するAPIを提供していますが、多くの開発者はそのような関数を見つけられず、自分で実装することを選択しています。

なぜでしょうか？`ngx.re.split` APIは`lua-nginx-module`にはなく、`lua-resty-core`にあります。さらに、`lua-resty-core`のホームページのドキュメントには記載されておらず、`lua-resty-core/lib/ngx/re.md`というサードレベルのディレクトリのドキュメントに記載されています。そのため、多くの開発者はこのAPIの存在を完全に知りません。

同様に、発見しにくいAPIには、以前に紹介した`ngx_resp.add_header`、`enable_privileged_agent`などがあります。では、この問題を迅速に解決するにはどうすればよいでしょうか？`lua-resty-core`のホームページのドキュメントを読むだけでなく、`lua-resty-core/lib/ngx/`ディレクトリ内の`*.md`ドキュメントも読む必要があります。

### `lua_regex_match_limit`

次に、`lua_regex_match_limit`を紹介します。以前、OpenRestyが提供するNGINXコマンドについてはほとんど触れませんでした。なぜなら、ほとんどの場合、デフォルト値で十分であり、実行時に変更する必要がないからです。例外は、正規表現に関連する`lua_regex_match_limit`コマンドです。

バックトラッキングNFAに基づいて実装された正規エンジンを使用する場合、カタストロフィックバックトラッキング（Catastrophic Backtracking）のリスクがあります。これは、正規表現がマッチング時に過剰にバックトラッキングし、CPUが100%になり、サービスがブロックされる現象です。

カタストロフィックバックトラッキングが発生した場合、`gdb`を使用してダンプを分析するか、`systemtap`を使用してオンライン環境を分析して特定する必要があります。残念ながら、事前に検出することは容易ではありません。なぜなら、特別なリクエストのみがこれを引き起こすからです。これにより、攻撃者がこれを悪用する可能性があり、`ReDoS`（RegEx Denial of Service）はこの種の攻撃を指します。

ここでは、OpenRestyで以下のコードを使用して、上記の問題を簡単かつ効果的に回避する方法を紹介します。

`lua_regex_match_limit`は、`PCRE`正規エンジンによるバックトラッキングの回数を制限するために使用されます。これにより、カタストロフィックバックトラッキングが発生しても、その影響がCPUを飽和させない範囲に限定されます。

```
lua_regex_match_limit 100000;
```

## 時間関連のAPI

最も一般的に使用される時間APIは`ngx.now`で、現在のタイムスタンプを出力します。例えば、以下のコードです。

```
resty -e 'ngx.say(ngx.now())'
```

出力結果からわかるように、`ngx.now`は小数部分を含むため、より正確です。関連する`ngx.time` APIは、値の整数部分のみを返します。その他、`ngx.localtime`、`ngx.utctime`、`ngx.cookie_time`、`ngx.http_time`は、主に異なる形式で時間を返したり処理したりするために使用されます。これらを使用したい場合は、ドキュメントを確認してください。理解するのは難しくないので、ここでは詳しく説明しません。

ただし、**これらの現在の時間を返すAPIは、非ブロッキングネットワークIO操作によってトリガーされない場合、常にキャッシュされた値を返し、私たちが望む現在のリアルタイムの時間を返しません**。以下のサンプルコードを見てください。

```
$ resty -e 'ngx.say(ngx.now())
os.execute("sleep 1")
ngx.say(ngx.now())'
```

`ngx.now`の2回の呼び出しの間に、Luaのブロッキング関数を使用して`1`秒間スリープしていますが、出力結果からわかるように、両方のタイムスタンプは同じです。

では、非ブロッキングのスリープ関数に置き換えた場合はどうなるでしょうか？例えば、以下の新しいコードです。

```
$ resty -e 'ngx.say(ngx.now())
ngx.sleep(1)
ngx.say(ngx.now())'
```

これにより、異なるタイムスタンプが出力されます。これにより、`ngx.sleep`という非ブロッキングのスリープ関数にたどり着きます。この関数は、指定された時間スリープするだけでなく、もう1つの特別な目的があります。

例えば、集中的な計算を行っているコードがあり、それが多くの時間を要する場合、このコードに対応するリクエストはその間ずっとワーカーとCPUリソースを占有し、他のリクエストがキューに入り、タイムリーに応答されなくなります。この場合、`ngx.sleep(0)`を挿入して、このコードが制御を放棄し、他のリクエストも処理されるようにすることができます。

## ワーカーとプロセスAPI

OpenRestyは、ワーカーとプロセスに関する情報を取得するために`ngx.worker.*`と`ngx.process.*` APIを提供しています。前者はNginxワーカープロセスに関連し、後者は一般的にすべてのNginxプロセスを指します。ワーカープロセスだけでなく、マスタープロセス、特権プロセスなども含まれます。

## `true`と`null`値の問題

最後に、`true`と`null`値の問題を見てみましょう。OpenRestyでは、`true`値と`null`値の判定は非常に面倒で混乱しやすいポイントです。

まず、Luaでの`true`値の定義を見てみましょう。`nil`と`false`を除いて、すべて`true`値です。

したがって、`true`値には`0`、空の`string`、空の`table`なども含まれます。

次に、Luaの`nil`を見てみましょう。これは「未定義」を意味します。例えば、変数を宣言したが初期化していない場合、その値は`nil`です。

```
$ resty -e 'local a
ngx.say(type(a))'
```

また、`nil`はLuaのデータ型でもあります。これら2つの定義を理解した上で、これらの定義から派生する他の問題を見ていきましょう。

### `ngx.null`

最初の問題は`ngx.null`です。Luaの`nil`は`table`の値として使用できないため、OpenRestyは`ngx.null`を`table`内の`null`値として導入しました。

```
$ resty -e  'print(ngx.null)'
null
```

```
$ resty -e 'print(type(ngx.null))'
userdata
```

上記の2つのコードからわかるように、`ngx.null`は`null`として出力され、その型は`userdata`です。では、これを`false`値として扱えるでしょうか？もちろんできません。`ngx.null`のブール値は`true`です。

```
$ resty -e 'if ngx.null then
ngx.say("true")
end'
```

したがって、`nil`と`false`のみが`false`値であることを覚えておいてください。この点を見落とすと、例えば`lua-resty-redis`を使用して以下の判定を行う場合に、簡単に落とし穴に陥ります。

```
local res, err = red:get("dog")
if not res then
    res = res + "test"
end
```

戻り値`res`が`nil`の場合、関数呼び出しは失敗しています。`res`が`ngx.null`の場合、redisにキー`dog`が存在しないため、キー`dog`が存在しない場合にコードがクラッシュします。

### `cdata:NULL`

2番目の問題は`cdata:NULL`です。LuaJIT FFIインターフェースを介してC関数を呼び出し、その関数が`NULL`ポインタを返す場合、別の種類の`null`値である`cdata:NULL`に遭遇します。

```
$ resty -e 'local ffi = require "ffi"
local cdata_null = ffi.new("void*", nil)
if cdata_null then
    ngx.say("true")
end'
```

`ngx.null`と同様に、`cdata:NULL`も`true`です。しかし、さらに困惑するのは、以下のコードが`true`を出力するということで、`cdata:NULL`が`nil`と等価であることを意味します。

```
$ resty -e 'local ffi = require "ffi"
local cdata_null = ffi.new("void*", nil)
ngx.say(cdata_null == nil)'
```

では、`ngx.null`と`cdata:NULL`をどのように処理すべきでしょうか？アプリケーション層にこれらの面倒を気にさせるのは良い解決策ではありません。セカンドレベルのラッパーを作成し、呼び出し側にこれらの詳細を知らせない方が良いです。

### `cjson.null`

最後に、`cjson`に現れる`null`値を見てみましょう。`cjson`ライブラリは、json内の`NULL`をLuaの`lightuserdata`にデコードし、`cjson.null`として表現します。

```
$ resty -e 'local cjson = require "cjson"
local data = cjson.encode(nil)
local decode_null = cjson.decode(data)
ngx.say(decode_null == cjson.null)'
```

Luaの`nil`は、JSONによってエンコードおよびデコードされると、`cjson.null`になります。想像できるように、これは`ngx.null`と同じ理由で導入されました。なぜなら、`nil`は`table`の値として使用できないからです。

これまで、OpenRestyの多くの種類の`null`値に混乱しましたか？心配しないでください。この部分を何度か読み、自分で整理すれば、混乱することはありません。もちろん、今後`if not foo then`のようなものを書くときに、それが機能するかどうかを考える必要があります。

## まとめ

今日の記事では、OpenRestyで一般的に使用されるLua APIを紹介しました。

最後に、1つの質問を残します。`ngx.now`の例で、`yield`操作がない場合、なぜ`ngx.now`の値が変更されないのでしょうか？コメントで意見を共有し、この記事を共有して、一緒に交流し、改善していきましょう。

Share article link

Share

Related Posts

[![OpenResty FAQ | OpenRestyの実践的な使い方](https://static.api7.ai/uploads/2023/02/12/jbv9M0zi_Hello%20World%20in%20OpenResty%20%283%29.png)](https://api7.ai/learning-center/openresty/faq-5)

## [OpenResty FAQ | OpenRestyの実践的な使い方](https://api7.ai/learning-center/openresty/faq-5)

[![第3部：OpenRestyを使用してマイクロサービスAPIゲートウェイを構築する方法](https://static.api7.ai/uploads/2023/02/07/3XJXY9Jy_45.png)](https://api7.ai/learning-center/openresty/how-to-build-a-microservices-api-gateway-part-3)

## [第3部：OpenRestyを使用してマイクロサービスAPIゲートウェイを構築する方法](https://api7.ai/learning-center/openresty/how-to-build-a-microservices-api-gateway-part-3)

Table of Contents

- [正規表現関連のAPI](#%E6%AD%A3%E8%A6%8F%E8%A1%A8%E7%8F%BE%E9%96%A2%E9%80%A3%E3%81%AEapi)

  - [`ngx.re.split`](#ngxresplit)
  - [`lua_regex_match_limit`](#lua_regex_match_limit)

- [時間関連のAPI](#%E6%99%82%E9%96%93%E9%96%A2%E9%80%A3%E3%81%AEapi)

- [ワーカーとプロセスAPI](#%E3%83%AF%E3%83%BC%E3%82%AB%E3%83%BC%E3%81%A8%E3%83%97%E3%83%AD%E3%82%BB%E3%82%B9api)

- [`true`と`null`値の問題](#true%E3%81%A8null%E5%80%A4%E3%81%AE%E5%95%8F%E9%A1%8C)

  - [`ngx.null`](#ngxnull)
  - [`cdata:NULL`](#cdatanull)
  - [`cjson.null`](#cjsonnull)

- [まとめ](#%E3%81%BE%E3%81%A8%E3%82%81)
