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

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

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')
}

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

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' = 'example.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=example.com; Path=/play; Secure; HttpOnly; SameSite=Strict; xxt3s

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)
}

set_status

函数详细信息，请参见下表：
项目 描述
语法 set_status(code)。
说明
  • 设置当前请求的响应状态码。
  • 当响应发出后，此方法无任何作用。
参数 code：响应状态码。
返回值 永远返回true。
示例 
set_status(200)

get_status

函数详细信息，请参见下表：
项目 描述
语法 get_status()。
说明 获取当前请求的响应状态码。
参数 无。
返回值 返回响应状态码。
示例 
code = get_status()

get_body_data

函数详细信息，请参见下表：
项目 描述
语法 get_body_data()。
说明 返回请求BODY（例如：POST请求）。
说明 请求须携带Content-Length且请求体小于128KB，否则将返回false。
参数 无。
返回值 回请求BODY，若无则返回false。
示例 
if eq($request_method, 'POST') {
    req_body = get_body_data()
    if not(req_body) {
        add_rsp_header('X-DY-DEBUG', 'missing request body')
        exit(400)
    }

    # req_args is dict
    req_args = []

    # when content-type is urlencoded, decode by decode_args()
    if match_re($http_content_type, 'application/x-www-form-urlencoded') {
        req_args = decode_args(req_body)
        add_rsp_header('X-DY-DEBUG-CONTENT-TYPE', 'urlencoded')
    }

    # when content-type is json, decode by json_decode()
    if match_re($http_content_type, 'application/json') {
        req_args = json_dec(req_body)
        add_rsp_header('X-DY-DEBUG-CONTENT-TYPE', 'json')
    }
}