本文为您介绍请求处理相关函数的语法、说明、参数、返回值和示例。

add_req_header

函数详细解释如下：
  • 语法：add_req_header(name, value [, append])。
  • 说明

    添加请求头，即回源请求头。

  • 参数
    • name：待添加的请求头name，字符类型。
    • value：待添加的请求头value，字符类型。
    • append：若请求头已添加，append决定是否追加value，默认覆盖（即默认不追加），布尔类型。
  • 返回值

    默认返回true，无效请求头返回false。

  • 示例 
    add_req_header('USER-DEFINED-REQ-1', '1')
add_req_header('USER-DEFINED-REQ-1', 'x', true)
add_req_header('USER-DEFINED-REQ-2', '2')
del_req_header('USER-DEFINED-REQ-2')

说明：添加2个请求头，分别为
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

USER-DEFINED-REQ-2先添加、后删除，故回源请求头中无USER-DEFINED-REQ-2

del_req_header

函数详细解释如下：
  • 语法：del_req_header(name)。
  • 说明

    删除请求头，即回源请求头。

  • 参数

    name：待删除的请求头name，字符类型。

  • 返回值

    默认返回true，无效请求头返回false。

  • 示例 
    add_req_header('USER-DEFINED-REQ-1', '1')
add_req_header('USER-DEFINED-REQ-1', 'x', true)
add_req_header('USER-DEFINED-REQ-2', '2')
del_req_header('USER-DEFINED-REQ-2')

说明：添加2个请求头，分别为
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

USER-DEFINED-REQ-2先添加、后删除，故回源请求头中无USER-DEFINED-REQ-2

add_rsp_header

函数详细解释如下：
  • 语法：add_rsp_header(name, value [, append])。
  • 说明

    添加响应头。

  • 参数
    • name：待添加的响应头name，字符类型。
    • value：待添加的响应头value，字符类型。
      value可包含如下标记，用于在响应阶段执行动态替换：
      • ${x} ：将替换为ngx.var.x的值。
      • @{y}：将替换为响应头y的值。
    • append：若响应头已添加，append决定是否追加value，默认覆盖，布尔类型。
  • 返回值

    默认返回true，无效响应头返回false。

  • 示例 
    add_rsp_header('USER-DEFINED-RSP-1', '1')
add_rsp_header('USER-DEFINED-RSP-1', 'x', true)
add_rsp_header('USER-DEFINED-RSP-2', '2')
del_rsp_header('USER-DEFINED-RSP-2')

说明：添加2个响应头，分别为
USER-DEFINED-RSP-1：1
USER-DEFINED-RSP-1：x

USER-DEFINED-RSP-2先添加、后删除，故响应头中无USER-DEFINED-RSP-2

del_rsp_header

函数详细解释如下：
  • 语法：del_rsp_header(name)。
  • 说明

    删除响应头。

  • 参数

    name：待删除的响应头name，字符类型。

  • 返回值

    默认返回true，无效响应头返回false。

  • 示例 
    add_rsp_header('USER-DEFINED-RSP-1', '1')
add_rsp_header('USER-DEFINED-RSP-1', 'x', true)
add_rsp_header('USER-DEFINED-RSP-2', '2')
del_rsp_header('USER-DEFINED-RSP-2')

说明：添加2个响应头，分别为
USER-DEFINED-RSP-1：1
USER-DEFINED-RSP-1：x

USER-DEFINED-RSP-2先添加、后删除，故响应头中无USER-DEFINED-RSP-2

encode_args

函数详细解释如下：
  • 语法：encode_args(d)。
  • 说明

    将字典d中的k/v，转换为URI编码的k1=v1&k2=v2格式的字符串。

  • 参数

    d：字典类型。

  • 返回值

    返回URI编码格式的字符串。

  • 示例 
    my_args = []
set(my_args, 'signature', 'da9dc4b7-87ae-4330-aaaf-e5454e2c2af1')
set(my_args, 'algo', 'private sign1')
my_args_str = encode_args(my_args)
add_rsp_header('X-DSL-ENCODE-ARGS', my_args_str)

to_args = decode_args(my_args_str)
if get(to_args, 'algo') {
    add_rsp_header('X-DSL-DECODE-ARGS-ALGO', get(to_args, 'algo'))
}
if get(to_args, 'signature') {
    add_rsp_header('X-DSL-DECODE-ARGS-SIGN', get(to_args, 'signature'))
}

输出：添加3个响应头，分别为
X-DSL-ENCODE-ARGS: signature=da9dc4b7-87ae-4330-aaaf-e5454e2c2af1&algo=private%20sign1
X-DSL-DECODE-ARGS-ALGO: private sign1
X-DSL-DECODE-ARGS-SIGN: da9dc4b7-87ae-4330-aaaf-e5454e2c2af1

decode_args

函数详细解释如下：
  • 语法：decode_args(s)。
  • 说明

    将URI编码的k1=v1&k2=v2格式的字符串，转换为字典类型。

  • 参数

    s：目标字符串。

  • 返回值

    返回转换后的字典对象。

  • 示例 
    my_args = []
set(my_args, 'signature', 'da9dc4b7-87ae-4330-aaaf-e5454e2c2af1')
set(my_args, 'algo', 'private sign1')
my_args_str = encode_args(my_args)
add_rsp_header('X-DSL-ENCODE-ARGS', my_args_str)

to_args = decode_args(my_args_str)
if get(to_args, 'algo') {
    add_rsp_header('X-DSL-DECODE-ARGS-ALGO', get(to_args, 'algo'))
}
if get(to_args, 'signature') {
    add_rsp_header('X-DSL-DECODE-ARGS-SIGN', get(to_args, 'signature'))
}

输出：添加3个响应头，分别为
X-DSL-ENCODE-ARGS: signature=da9dc4b7-87ae-4330-aaaf-e5454e2c2af1&algo=private%20sign1
X-DSL-DECODE-ARGS-ALGO: private sign1
X-DSL-DECODE-ARGS-SIGN: da9dc4b7-87ae-4330-aaaf-e5454e2c2af1

rewrite

函数详细解释如下：
  • 语法：rewrite(url, flag, code)。
  • 说明

    改写操作或重定向操作。

  • 参数
    • url：目标URL，字符类型。
      • 当flag=redirect或flag=break时，仅改写URI，则参数URL表示改写后的目标URI。
      • 当flag=enhance_redirect或flag=enhance_break时，修改整个URI和参数，参数URL表示改写后的目标URI和参数。
    • flag：重写模式，字符类型。
      • redirect ：仅修改URI，不修改参数；默认执行302跳转至URL；如果指定参数code，则响应码可自定义为：301、302（默认）、303、307或308。
      • break ：仅修改URI，不修改参数，将URI修改为URL。
      • enhance_redirect：与redirect类似，但是修改整个URI和参数。
      • enhance_break：与break类似，但是修改整个URI和参数。
    • code：为响应码，数字类型 。

      当flag=redirect或flag=enhance_redirect时，可自定义响应码。

  • 返回值
    • 对于改写操作，默认返回true。
    • 对于重定向操作，默认不返回。
  • 示例 
    if and($arg_mode, eq($arg_mode, 'rewrite:enhance_break')) {
    rewrite('/a/b/c.txt?k=v', 'enhance_break')
}
说明：回源和缓存的uri+参数，修改为/a/b/c.txt?k=v

if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect')) {
    rewrite('/a/b/c.txt?k=v', 'enhance_redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect_301')) {
    rewrite('/a/b/c.txt?k=v', 'enhance_redirect', 301)
}
说明：302或301跳转至/a/b/c.txt?k=v

if and($arg_mode, eq($arg_mode, 'rewrite:break')) {
    rewrite('/a/b/c.txt', 'break')
}
说明：回源和缓存的uri，修改为/a/b/c.txt，保持原参数不变

if and($arg_mode, eq($arg_mode, 'rewrite:redirect')) {
    rewrite('/a/b/c.txt', 'redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:redirect_301')) {
    rewrite('/a/b/c.txt', 'redirect', 301)
}
说明：302或301跳转至/a/b/c.txt，保持原参数不变

say

函数详细解释如下：
  • 语法：say(arg)。
  • 说明

    输出响应体，并在行尾追加换行符。

  • 参数

    arg：任意类型。

  • 返回值

    无。

  • 示例 
    say('hello')
print('byebye')
print('byebye')

输出：
hello
byebyebyebye

print

函数详细解释如下：
  • 语法：print(arg)。
  • 说明

    输出响应体与say()相同，但不会在行尾追加换行符。

  • 参数

    arg：任意类型。

  • 返回值

    无。

  • 示例 
    say('hello')
print('byebye')
print('byebye')

输出：
hello
byebyebyebye

exit

函数详细解释如下：
  • 语法：exit(code [, body])。
  • 说明

    以状态码code结束当前请求。若有body，则为响应体。

  • 参数
    • code：响应状态码。
    • body：响应体。
  • 返回值

    无。

  • 示例
    • 示例1 
      if not($arg_key) {
    exit(403)
}
说明：如果请求未携带参数key时，403拒绝请求。

if not($cookie_user) {
    exit(403, 'not cookie user')
}
说明：当请求未携带cookie user时，403拒绝请求，响应body为'not cookie user'

if not(0) {
    exit(403)
}
说明：not(0)的结果为false

if not(false) {
    exit(403)
}
说明：not(false)的结果为true
    • 示例2 
      pcs = capture_re($request_uri,'^/([^/]+)/([^/]+)([^?]+)\?(.*)')
sec1 = get(pcs, 1)
sec2 = get(pcs, 2)
sec3 = get(pcs, 3)
if or(not(sec1), not(sec2), not(sec3)) {
   add_rsp_header('X-TENGINE-ERROR', 'auth failed - missing necessary uri set')
   exit(403)
}
digest = md5(concat(sec1, sec3))
if ne(digest, sec2) {
    add_rsp_header('X-TENGINE-ERROR', 'auth failed - invalid digest')
    exit(403)
}