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

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/example/examplefile.txt?k=v', 'enhance_break')
}
说明:回源和缓存的uri+参数,修改为/a/example/examplefile.txt?k=v

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

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

if and($arg_mode, eq($arg_mode, 'rewrite:redirect')) {
    rewrite('/a/example/examplefile.txt', 'redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:redirect_301')) {
    rewrite('/a/example/examplefile.txt', 'redirect', 301)
}
说明:302或301跳转至/a/example/examplefile.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)
    }

get_rsp_header

函数详细信息,请参见下表:
项目 描述
语法 get_rsp_header(str)
说明 获取响应头。
参数 str:string类型。
返回值 返回string、number、字典和boolean类型。
  • 头存在:返回对应的值,可以为字典和字符串类型。
  • 头不存在:返回false。
示例
ct = get_rsp_header('content-type')
if ct {
    add_rsp_header('origin-content-type', 'is')
} else {
      add_rsp_header('origin-content-type', 'no')
}

add_rsp_cookie

函数详细信息,请参见下表:
项目 描述
语法 add_rsp_cookie(k, v [,properties])
说明 设置响应cookie,每次调用均会生成一个新的Set-Cookie响应头。
参数
  • k:cookie名称。
  • v:cookie值。
  • properties(可选参数):cookie属性。详细信息,请参见Set-Cookie
返回值 成功返回true,失败返回false。
示例
add_rsp_cookie('user', 'edgescript')

add_rsp_cookie('login_time', tostring(now()), [
    'path' = '/'
])

expires = cookie_time(time())
add_rsp_cookie('psid', 'SDF93745HFSDF2934JKHG', [
    'path' = '/play',
    'domain' = 'foo.com',
    'secure' = true,
    'httponly' = true,
    'expires' = expires,
    'max_age' = 100,
    'samesite' = 'Strict',
    'extension' = 'xxt3s'
])
响应:
Set-Cookie: user=edgescript
Set-Cookie: login_time=1582538968.912; Path=/
Set-Cookie: psid=SDF93745HFSDF2934JKHG; Expires=Mon, 24-Feb-20 10:09:28 GMT; Max-Age=100; Domain=foo.com; Path=/play; Secure; HttpOnly; SameSite=Strict; xxt3s