lor

local lor = require("lor.index")

lor框架暴露出来的最重要对象, 通过调用该对象的方法和属性即可使用绝大部分lor框架提供的功能。

lor()  

local lor = require("lor.index")
local app = lor()

该方法是框架暴露出来的最重要的方法,用于创建一个app对象,之后大部分api将通过app对象展开.
如无特别说明,下文中出现的app均指通过lor()方法创建的application对象.

lor:Router()  

生成一个group router对象,group router对象指一个路由组,用来在业务上聚合一组相关的路由,它具有getpostdeleteput等等HTTP方法,这些API与下文介绍的app上的getpostdeleteput等方法使用方式一致。

app对象

app对象即为由lor()方法生成的对象, 用它来配置各种参数和路由。

app:conf(key, value)  

application配置项,目前主要用于html模板配置,提供一下四个配置项:

app:use(path, middleware)  

app:use(function(req, res, next)
-- 注入一个参数
req.params.inject_param = "from all path middleware"
next() -- 注意,如果不调用next()方法,请求到这里就截止了,不在匹配后面的路由
end)
app:use("/user", function(req, res, next)
if not req.params or req.params.token ~= "authorized token" then
-- 注意,这里没有调用next()方法,请求到这里就截止了,不在匹配后面的路由
res:status(403):send("not allowed reqeust")
else
next() -- 满足以上条件,那么继续匹配下一个路由
end
end)

app:erroruse(path, middleware) 

-- 统一错误处理插件
app:erroruse(function(err, req, res, next)
-- err是错误对象,直接将err打到response,生产环境请勿这样做
res:status(500):send(err)
end)
app:erroruse("/user", function(err, req, res, next)
-- ...
end)

app:erruse(path, middleware)  

app:erroruse的别名方法

app:[METHOD](path, func…)  

-- 简单使用
app:get("/index", function(req, res, next)
res:send("hello world!")
end)
-- 前置处理
local check_name = function(req, res, next) --①
if not req.query.name or req.query.name == "" then
res:send("error param: name")
else
next()
end
end
local check_age = function(req, res, next) --②
local age = req.query.age
if age and tonumber(age) > 0 then
next()
else
res:send("error param: age should be larger than 0")
end
end
local save_user = function(req, res, next) --③
res:send("save user:" .. req.query.name .. " " .. req.query.age)
end
app:get("/user/save", check_name, check_age, save_user)

app:gen_graph()

用于生成当前应用的路由树graph, 此方法应仅在开发时使用。

示例

graph TD
node-6611((root))
node-6611-->node-1144(<center>auth<br/>node-1144</center>)
node-1144-->node-548(<center>login<br/>node-548</center>)
node-1144-->node-1759(<center>logout<br/>node-1759</center>)
node-6611-->node-4724(<center>admin<br/>node-4724</center>)
node-4724-->node-6790(<center>user<br/>node-6790</center>)
node-6790-->node-5751(<center>delete<br/>node-5751</center>)
node-6790-->node-4517(<center>new<br/>node-4517</center>)
node-6790-->node-5967(<center>manage<br/>node-5967</center>)
node-6790-->node-8299(<center>modify<br/>node-8299</center>)
node-4724-->node-6600(<center>users<br/>node-6600</center>)
node-6611-->node-247(<center>*EMPTY*<br/>node-247</center>)
node-6611-->node-496(<center>status<br/>node-496</center>)
node-6611-->node-6265(<center>help<br/>node-6265</center>)
node-6611-->node-1807(<center>machine<br/>node-1807</center>)
node-1807-->node-2555(<center>list<br/>node-2555</center>)
node-1807-->node-3169(<center>*EMPTY*<br/>node-3169</center>)
node-6611-->node-9210(<center>_graph<br/>node-9210</center>)

将以上内容粘贴到路由树查看页面, 就可以看到当前项目中路由的可视化图:

app:run()

启动lor项目,开始接受请求并处理

group router

group router(组路由)可以收到一组相关的路由, 可形如local group_router = lor:Router()来初始化, 可通过app:use("/group_test", group_router())来加载到app对象里。

group_router:[METHOD](path, func…)  

-- 简单使用
local test_router = lor:Router()
test_router:get("/test/abc", function(req, res, next)
res:send("!")
end)
app:use("test", test_router())
local test_router = lor:Router()
-- 前置处理
local check_name = function(req, res, next) --①
if not req.query.name or req.query.name == "" then
res:send("error param: name")
else
next()
end
end
local check_age = function(req, res, next) --②
local age = req.query.age
if age and tonumber(age) > 0 then
next()
else
res:send("error param: age should be larger than 0")
end
end
local save_user = function(req, res, next) --③
res:send("save user:" .. req.query.name .. " " .. req.query.age)
end
test_router:get("/save", {check_name, check_age}, save_user)
app:use("test", test_router())

request对象

我们注意到有大量的地方出现了形如function(req, res, next) end的函数,这个函数其实就是lor框架的核心机制,也就是lor的常规插件。
其中的req指的就是request对象,它包装了OpenResty收到的HTTP请求参数,并附带了一些方法来完成session、cookie数据交互,路由处理等其他后续操作。

req的常用属性和方法介绍如下:

req.path

请求的uri,一般用作框架内部使用,如处理路由,解析参数,重定向请求等等,若用户不清楚修改该值会有什么影响,切勿随意更改此值。

req.query

这是一个table,指的是url解析后的query string,比如”/find/user?id=1&name=sumory&year=2016”被解析后会生成对象req.query,它的值为:

{
id = "1",
name = "sumory",
year = "2016"
}

req.params

这是一个table,指的是url解析后的path variable,比如声明了以下路由处理方法

app:get("/query/:id/book/:name", function(req, res, next)
local params = req.params
end)

那么访问”/query/123/book/abc”这个uri时得到的req.params值为:

{
id = "123",
name = "abc"
}

req.body

这是一个table,指的是form表单提交上来的数据。

req:is_found()  

用于判断uri是否被路由到,如果这个方法返回值最终为false,说明404了。

response对象

reponse对象指的是function(req, res, next) end函数中的res,它包装了OpenResty处理HTTP响应的一些API,并附带了一些方法来完成诸如模板渲染、重定向、json返回、session/cookie处理等其他后续操作。

res的常用属性和方法介绍如下:

res:render(view, data)  

res:html(content)  

res:json(data)  

res:send(text)  

res:set_header(key, value)  

res:redirect(url)  

next函数

function(req, res, next) end函数中的形参next是lor pipeline式路由能顺利进行的关键,它有两种调用方式: