# fastcgi.client 库模块帮助文档 [HTTP 服务端开发指南](https://www.aardio.com/zh-cn/doc/guide/quickstart/web-server.md) ## fastcgi 成员列表 # FastCGI 支持库 ### fastcgi.client # FastCGI 客户端 ### fastcgi.client() # 创建 FastCGI 客户端。 [返回对象:fastcgiclientObject](#fastcgiclientObject) ## 全局对象 成员列表 # ### session["字符串参数"] # 获取或设置 session 。 值不允许指定函数、类等包含可执行代码的对象。 ## fastcgiclientObject 成员列表 # ### fastcgiclientObject.customErrors # ```aardio fastcgiclientObject.customErrors = { [404] = function(response){ response.status = "404 Not Found"; response.write("404 Not Found"); /*自定义错误页*/ } } ``` ### fastcgiclientObject.getStream # function(){ if(!owner.stream){ __/*参考fastcgi.stream*/ } return owner.stream; } ### fastcgiclientObject.run( httpProc ) # ```aardio fastcgiclientObject.run( function(response,request,session){ response.loadcode( request.path /*可省略,可增加多个模板参数, 在被调用文件的函数外部可使用owner参数获取首个模板参数, 也可以使用...获取多个模板参数*/ ); } ); ``` ## request 成员列表 # HTTP 请求对象。 request 对象必须由服务端框架自动维护， 用户发起不同的请求时 request 对象都是不同的， 并且由服务端框架自动设置为全局变量。 注意在单线程异步 HTTP 服务端内，应优先通过函数参数传递此对象, request 的接口规范由标准库中 fastcgi.client 定义， 目前 aardio 提供的所有 HTTP 服务端框架都兼容此接口。 ### request.auth(callback,realm,method) # ```aardio request.auth( function(username){ if(username == "admin") return "123456"/* 参数 @callback 指定验证函数，验证函数返回匹配密码则登录成功。 可选参数 @realm 指定保护领域。 可选参数 method 指定认证方法，默认为 "digest"，可选"basic"（不安全）。 登录成功后 session.authorized 值为 true。 IIS 等 FastCGI 服务端不需要调用此函数。*/; }, "realm") ``` ### request.contentLength # HTTP 请求消息正文的长度，这是一个数值 ### request.contentType # HTTP 请求头指定的的 MIME 类型 ### request.cookies[] # 包含所有 Cookies 的表对象。 字段名已全部转为小写。 成功返回指定名称的值，失败返回 null 值。 ### request.createSessionId() # 应用程序可调用此函数重新创建新的会话 ID ### request.documentBase # 嵌入 HTTP 服务器网站根目录, 此路径不同于 aardio 应用程序根目录。 在 FastCGI 环境下总是为 "/" request.path 等于 request.documentBase ++ request.pathInfo ### request.documentRoot # 网站应用程序根目录， 也是当前 aardio 应用程序根目录。 ### request.eachPost() # ```aardio for buffer,readSize in request.eachPost(){ /*循环读取上传数据。 注意每次读取都会写入相同的 buffer ，readSize 为读入的实际长度。*/ } ``` ### request.environ # CGI 环境变量，这是由多个键值对组成的表。 环境变量中所有值都是字符串类型，即使是端口号也是字符串。 环境变量的所有键名必须大写 ### request.get["字符串参数"] # 包含所有 URL 请求参数名值对的表对象。 字段名一律转为小写。 成功返回指定名称的值，失败返回 null 值。 ### request.headers["字符串参数"] # 包含所有 HTTP 请求头的表对象, 所有请求头的键名已全部转为小写，请求头的值值都是字符串类型 http服务端可选同时以数组形式保存原始http头 数组的第个元素都是包含键、值两个元素的子数组 但服务端可选不使用数组存放任何HTTP头 ### request.host # 请求的网站域名 ### request.keepAlive # 客户端是否请求保持连接 ### request.method # HTTP 请求方法，例如"GET"、"POST"。 ### request.path # 请求 URL 中的路径部分（已经过 URL 解码），前面包含 documentBase 目录。 注意 HTTP 请求路径开始于"/config/","/lib/"时会拒绝请求。 request.path 等于 request.documentBase ++ request.pathInfo ### request.pathInfo # 请求 URL 中的路径部分（已经过 URL 解码），忽略 documentBase 目录。 注意 HTTP 请求路径开始于"/config/","/lib/"时会拒绝请求。 request.path 等于 request.documentBase ++ request.pathInfo ### request.postData() # 获取原始上传数据。 `multipart/form-data` 表单上传的文件数据应使用postFileData函数读取 ### request.postFileData() # 可以使用此函数判断当前请求是否上传文件 获取 `multipart/form-data` 表单上传的文件数据。 如果无上传数据返回空值, 解析出错返回空值并发送 400 错误后关闭页面输出。 此函数的返回值是一个 fsys.multipartFormData 对象 关于数据的格式请参考标准库中该对象的文档, [返回对象:fsysMultipartFormDataObject](https://www.aardio.com/zh-cn/doc/library-reference/fsys/multipartFormData.html#fsysMultipartFormDataObject) ### request.postJson() # 如果请求格式为 `application/json` 或 `text/json` , 获取 JSON 格式的请求数据并解析为 aardio 对象并返回。 解析失败返回 null ### request.post["字符串参数"] # 包含 form 表单提交参数名值对组成的表对象。 字段名一律转为小写。 成功返回指定名称的值，失败返回 null 值。 ### request.protocol # HTTP 协议版本。 ### request.query("字符串参数") # 返回指定的 URL 参数或表单参数的值。 参数指定的名称必须小写。 成功返回指定名称的值，失败返回 null 值。 ### request.remoteAddr # 客户端 IP 地址 ### request.scheme # 请求 URL 中协议部分，值为"http"或"https"。 注意仅 FastCGI 模块支持 HTTPS 请求。 URL协议部分 ### request.serverPort # 请求的服务器端口，数值 ### request.sessionId # 会话 ID。 应用程序需要自行管理会话过期时间。 请参考 sessionHandler.default 实现源码。 ### request.uri # 请求路径，带 URL 参数部分 ### request.url # 请求 URL，不带 URL 参数部分 ## response 成员列表 # Web服务端响应对象, response 对象必须由服务端框架自动维护， 用户发起不同的请求时response对象都是不同的， 并且由服务端框架自动设置为全局变量。 注意在单线程异步 HTTP 服务端内，应优先通过函数参数传递此对象, response 的接口规范由标准库中 fastcgi.client定义， 目前 aardio 提供的所有 HTTP 服务端框架都兼容此接口。 ### response._headersWritten # 是否已向客户端发送 HTTP 头。 如果已发送 HTTP 头，则后续修改 HTTP 状态码或响应头将被忽略。 调用代码不应修改此属性。 ### response.charset # 输出字符集。 可以为空,默认值为 aardio 的默认文本编码 UTF-8 。 不建议更改此值。 ### response.close() # 关闭输出 此函数终止执行页面后续代码 ### response.close(true) # 关闭页面输出 但继续执行页面后续代码 ### response.closed # HTTP 应答对象是否已关闭。 用于判断本次HTTP应答是否已被 response.close 函数关闭 因为 `response.close()` 会抛出空异常自动退出当前代码, 所以一般不需要判断这个值 此属性的值应由HTTP服务器自动维护,用户不可修改 ### response.contentType # ```aardio response.contentType = "application/json";/*指定响应数据的 MIME 类型,默认为"text/html"*/ ``` ### response.cookieDomain # 默认 cookie 域名 ### response.cookieHttpOnly # 设为 true 所有 cookie 默认加上 HttpOnly 属性 ### response.cookiePath # 默认 cookie 目录 ### response.cookieSecure # 设为 true 所有 cookie 默认加上 secure 属性 ### response.cookies[] # ```aardio response.cookies["/*键名*/"] = { value = "值"; expires = time().addDays(7); maxAge = 3600; } ``` ### response.customErrors[404] # ```aardio response.customErrors[404] = function(response,request,session){ response.status = "404 Not Found"; response.write("404 Not Found"); /*自定义错误处理函数, 每次请求仅第一个自定义错误处理函数会被调用*/ } ``` ### response.defalutDocument # 指定 `loadcode` 函数加载 aardio 代码时的默认文件名 默认为"main.aardio",不建议修改 ### response.error() # 输出一个或多个 500 错误信息， 必须在页面尚未输出响应头时调用, 参数将自动转换为字符串对象 table转换为格式化的对象输出 此函数终止执行页面后续代码 ### response.errorStatus(statusCode,message,continueRunning) # 此函数默认输出 HTTP 错误响应代码， 如果自定义了对应的 HTTP 错误代码处理函数则执行该函数。 此函数必须在页面尚未输出 HTTP 响应头时调用才会有效。 参数 @statusCode 指定 HTTP 错误代码（数值）， 可选用参数 @message 自定义页面输出的文本信息（字符串）。 可选指定参数 @continueRunning 为 true 以继续运行页面后续代码，默认为 false 。 ### response.eventStream # 按 `text/event-stream` 协议格式输出表对象。 wsock.tcp.simpleHttpServer,wsock.tcp.asyncHttpServer 已自动支持。 IIS 需要在处理程序映射配置中添加 `responseBufferLimit="0"`（注意备份原配置）， [参考文档](https://www.aardio.com/zh-cn/doc/guide/quickstart/web-server.html#responseBufferLimit) ### response.eventStream(message) # 将参数 @message 指定的表对象按 `text/event-stream` 格式输出。 该表对象中值类型为表的对象自动转换为 JSON 输出。 response.contentType 自动指定为 `text/event-stream` ### response.flush() # 发送并清空缓冲区。 IIS 仍然会继续在缓冲区缓存输出。 IIS 内如果要实时输出请修改 FastCGI 缓冲区大小为 0 [参考文档](https://www.aardio.com/zh-cn/doc/guide/quickstart/web-server.html#responseBufferLimit) ### response.headers[] # 指定响应 HTTP 头, 值可以是字符串、或者多个字符串值组成的数组, 值是数组时则自动输出多个名值对到客户端, 键名中每个单词的首字母必须大写、其他字母必须小写 注意：这与请求头统一小写是不同的 ### response.jsonPrettyPrint # ```aardio response.jsonPrettyPrint = true;/*指定 respose.write 函数将对象转换为 JSON 输出时否缩进格式化*/ ``` ### response.keepAlive # 服务端是否保持连接。 此属性为标准库为 HTTP 服务器所保留。 HTTP 服务器可以忽略该值， 或者由 HTTP 服务器自动维护该值， 用户不应修改此属性 ### response.loadcode # 运行服务端 aardio 代码或下载其他文件。 参数 @1 如果指定 `*.aardio` 文件则执行并解析 aardio 模板代码。 如果指定其他类型的文件则直接下载文件。 注意下载是比较复杂的功能，直接调用这个函数是更可靠的选择。 自己去实现这一套代码工作量可能很大，一般没有必要。 可以参考『扫码传文件』范例。 上传下载都支持，其中下载就是调用这里的 response.loadcode 函数。 ### response.loadcode("文件路径",...) # 省略参数则默认以 request.path 为参数。 参数 @1 如果指定 *.aardio 文件则执行并解析 aardio 模板代码。 后面的其他参数作为模板参数传给被调用的 aardio 文件。 在被调用文件的函数外部可使用 `owner` 参数获取首个模板参数， 也可以使用 `...` 获取多个模板参数。 关于模板语法请查看[帮助文档](https://www.aardio.com/zh-cn/doc/language-reference/templating/syntax.html)。 如果指定其他文件路径，则下载文件。 注意下载是比较复杂的功能，直接调用这个函数是更可靠的选择。 ### response.preheaders # 指定在 headers 发送到客户端以前发送的 HTTP 头 此值将使用 web.joinHeaders 函数格式化然后再发送 可以指定字符串,数组,或键值对,键值对的值可以是多个值组成的数组 如果参数是键值对,自动对值中的宽字符按UTF-8编码进行 UrlEncode 编码 ### response.redirect("字符串参数") # 302 重定向, 必须在页面尚未输出响应头时调用。 参数 @1 可以是相对路径或任意网址, 此函数终止执行页面后续代码。 ### response.redirect("字符串参数",301) # 301重定向, 必须在页面尚未输出响应头时调用, 参数@1可以是相对路径或任意网址, 此函数终止执行页面后续代码。 ### response.status # 响应状态码,值可以为数值或文本, 默认为"200 OK" ### response.transferChunked # 是否使用分块传输协议。 此属性为标准库为 HTTP 服务器所保留。 HTTP服务器可以忽略该值， 或者由 HTTP 服务器自动维护该值， 用户不应修改此属性 ### response.write() # 输出一个或多个值。 可直接输出字符串、buffer、结构体，table 对象自动转换为 JSON 输出， 其他类型对象则转换为字符串输出。 ### response.writeBuffer(buffer,长度) # 输出 buffer 对象中的数据，不指定长度则获取缓冲区长度。 注意 FastCGI 服务端这个函数单次最大发送长度为 65535。 其他服务端未限制长度。 response.write 也可以用于发送 buffer，并且没有 65535 这个限制。 ## session 成员列表 # HTTP 服务端会话对象, session 对象必须由服务端框架自动维护， 用户发起不同的请求时 session 对象都是不同的， 并且由服务端框架自动设置为全局变量。 session 的接口规范由标准库中 fastcgi.client 定义， 目前 aardio 提供的所有 HTTP 服务端框架都兼容此接口。 ### session.* # 获取或设置 session 。 值不允许指定函数、类等包含可执行代码的对象。 ### session.authorized # 是否已使用 request.auth 函数成功登录。 如果已登录则属性值为登录用户名。 设为 null 或 false 则需要重新登录。 ### session.authorizedTime # request.auth 函数成功登录的时间。 ### session.clear() # 清空 session ### session.save() # 保存 session，此函数在请求结束时会自动调用 ### session.start() # 载入 session, 此函数会在 sessionHandler 命名空间下查找自定义的加载器。 如果没有找到默认会使用sessionHandler.default加载session, 可选在参数中指定过期时间,以秒为单位 如果没有调用此函数,首次访问 session 的键值时会自动调用