nginx中文文档-ngx_http_perl_module

lyz810

9 年前

该模块默认不会构建，需要通过–with-http_perl_module参数配置。
该模块需要Perl版本5.6.1或更高。C编译器需要匹配构建Perl。

已知问题
该模块是实验性的。
重新编译Perl时，需要使用-Dusemultiplicity=yes或-Dusethreads=yes参数。同时，为了是Perl运行时占用更少的内存，应该使用-Dusemymalloc=no参数。为检测当前构建的Perl的参数，运行：

$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';

注意，通过-Dusemultiplicity=yes或-Dusethreads=yes参数重新构建Perl后，所有二进制Perl模块必须一同重新构建。
在每次重新配置后，主进程和工作进程的大小可能会增长。如果主进程增长到不可接受的大小，live upgrade程序可以不改变可执行文件。
当Perl模块执行长时间的任务，例如解析一个域名、连接其他服务器或查询数据库，分配给当前工作进程的其他请求不会被处理。因此建议只有确定耗时短的操作被执行，例如访问本地文件系统。

示例配置

http {

    perl_modules perl/lib;
    perl_require hello.pm;

    perl_set $msie6 '

        sub {
            my $r = shift;
            my $ua = $r->header_in("User-Agent");

            return "" if $ua =~ /Opera/;
            return "1" if $ua =~ / MSIE [6-9]\.\d+/;
            return "";
        }

    ';

    server {
        location / {
            perl hello::handler;
        }
    }

perl/lib/hello.pm模块：

package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->send_http_header("text/html");
    return OK if $r->header_only;

    $r->print("hello!\n
");

    if (-f $r->filename or -d _) {
        $r->print($r->uri, " exists!\n");
    }

    return OK;
}

1;
__END__

perl

语法：perl module::function|’sub { … }’
默认：—
上下文：location, limit_except

设置给定location的Perl处理器。

perl_modules

语法：perl_modules path
默认：—
上下文：http

为Perl模块添加额外的路径。

perl_require

语法：perl_require module
默认：—
上下文：http

定义模块名，在每次重配置时加载。可以有多个perl_require指令。

perl_set

语法：perl_set $variable module::function|’sub { … }’
默认：—
上下文：http

为指定的变量安装Perl处理器。

从SSI调用Perl
SSI命令调用Perl有下面的格式：

$r请求对象方法

$r->args
返回请求参数

$r->filename
返回请求URI对应的文件名

$r->has_request_body(handler)
如果请求体内容为空，返回0。如果有请求体，指定的handler将设置请求，并返回1。在读取请求体后，nginx将调用指定的handler。注意handler函数应通过引用传递，例如：

package hello;

use nginx;

sub handler {
    my $r = shift;

    if ($r->request_method ne "POST") {
        return DECLINED;
    }

    if ($r->has_request_body(\&post)) {
        return OK;
    }

    return HTTP_BAD_REQUEST;
}

sub post {
    my $r = shift;

    $r->send_http_header;

    $r->print("request_body: \"", $r->request_body, "\"
");
    $r->print("request_body_file: \"", $r->request_body_file, "\"
\n");

    return OK;
}

1;

__END__

$r->allow_ranges
发送响应时启用byte range功能

$r->discard_request_body
让nginx丢弃请求体

$r->header_in(field)
返回请求头中指定的值

$r->header_only
决定发送客户端完整响应还是只发送头

$r->header_out(field, value)
设置指定的响应头域

$r->internal_redirect(uri)
向指定的uri做内部重定向。重定向发送在Perl处理器执行完毕。
重定向到名称location目前不支持。

$r->log_error(errno, message)
写指定的信息到error_log。如果errno非零，错误码和描述信息将被追加到信息中。

$r->print(text, …)
发送数据到客户端。

$r->request_body
如果请求体没有写入临时文件，则返回请求体。确保客户端请求体在内存中，大小需要被client_max_body_size指令限制，并且需要通过client_body_buffer_size指令设置足够大的缓冲区。

$r->request_body_file
返回客户端请求体文件的名称。在处理后，文件会被移除。需要使用client_body_in_file_only指令确保请求体总会写到文件中。

$r->request_method
返回客户端请求的HTTP方法

$r->remote_addr
返回客户端IP地址

$r->flush
立即发送数据到客户端

$r->sendfile(name[, offset[, length]])
发送指定的文件内容到客户端。可选参数定义了初始的偏移和要传输数据的长度。实际的传输发生在Perl处理器完成时。

$r->send_http_header([type])
发送响应头到客户端。可选参数type这只了响应头域“Content-Type”。如果值是一个空字符串，“Content-Type”不会被设置。

$r->status(code)
设置响应码

$r->sleep(milliseconds, handler)
设置滴定的处理器，并暂停处理请求指定的时间。与此同时，nginx处理其他的请求，在指定时间过后，nginx将会调用安装的处理器。注意处理器函数需要通过引用传递。为在处理器之间传递数据，需要使用$r->variable()，例如：

package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->discard_request_body;
    $r->variable("var", "OK");
    $r->sleep(1000, \&next);

    return OK;
}

sub next {
    my $r = shift;

    $r->send_http_header;
    $r->print($r->variable("var"));

    return OK;
}

1;

__END__

$r->unescape(text)
解码一个“%XX”格式的文本

$r->uri
返回请求URI

$r->variable(name[, value])
返回或设置指定变量的值。变量对每一个请求都是本地的。