【原文】 http://leafo.net/lapis/reference/getting_started.html

Lapis 是一个 Lua/MoonScript 的 Web 框架，本译文主要翻译 Lua 部分；同时 Lapis 是基于章亦春的 OpenResty ，这样你的 web 应用可以直接运行在 Nginx 内部。Nginx 的事件循环可以让你轻松使用异步Http请求、数据库查询和其他 OpenResty 提供的模块。基于 Lua 的协程你可以编写在幕后事件驱动的同步代码。

lapis 除了提供你一个 Web 框架，同时还提供了一个可以在不同配置环境中控制 OpenResty 的工具。即使你不是用这个框架 Web 相关的模块，在基于 OpenResty 做开发过程中它也可以节省你的开发成本。

这个框架包含 URL 路由模块、模板、CSRF 和 Session ，同时支持 PostgreSQL 、MySQL 的 DB 的常规的操作，以及其他 Web 相关的其他功能。

希望本文档在你使用的过程中给你提供参考。

基本设置

首先，需要在你的环境中安装 OpenResty ，然后使用 LuaRocks 安装 Lapis (记得 Lua 安装 5.1，这个框架不支持 5.3 版本)

1
$ luarocks install lapis

安装完成之后，命令行敲一下 lapis 验证一下是否安装成功，如果有类似下面的输出代表你已经安装成功了

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/ # lapis
Lapis 1.7.0
usage: lapis <action> [arguments]
using nginx: /usr/local/openresty/nginx/sbin/nginx
default environment: development

Available actions:

  new                              create a new lapis project in the current
                                   directory
  server [environment]             build config and start server
  build [environment]              build config, send HUP if server running
  term                             sends TERM signal to shut down a running
                                   server
  exec <lua-string>                execute Lua on the server
  migrate [environment]            run migrations
  generate <template> [args...]    generates a new file from template
  help                             show this text

通过 Lapis 创建一个 Lua 应用

lapis 命令行工具

Lapis 提供了一个命令行工具，可以创建新项目，也可以启动服务器。要是想看它都提供了哪些功能，你可以在命令敲下以下命令：

1
$ lapis help

现在进入一个新创建的目录中，创建一个新的项目：

1
2
3
4
5
/srv/www # lapis new --lua
wrote	nginx.conf
wrote	mime.types
wrote	app.lua
wrote	models.lua

这时候 Lapis 会创建一个基础版本的 Nginx 配置文件和一个空的 Lapis 应用。

下面我们先来查看一下生成的配置文件（ nginx.conf 是唯一的核心文件）。以下会简单概述一下这个配置文件都做了什么：

  • 所有的 /static/ 开头的请求都会到 static 目录里查找指定的内容
  • /favicon.ico 会从 static/favicon.ico 位置读取
  • 其他的请求都会在落在你的 Lua 代码逻辑中

当你通过命令行工具启动指定的环境，nginx.conf 里面的变量会从指定的环境的配置文件里面查询指定的值。下面我们我们会进一步讨论里面的细节。

Nginx 配置文件

让我们看下刚刚新建项目时创建的配置文件，这对于我们不管是做一个简单的发布操作还是后期开发更复杂的应用都是很有必要的。

下面是刚刚生成的 nginx.conf :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
worker_processes ${{NUM_WORKERS}};
error_log stderr notice;
daemon off;
pid logs/nginx.pid;

events {
  worker_connections 1024;
}

http {
  include mime.types;

  server {
    listen ${{PORT}};
    lua_code_cache ${{CODE_CACHE}};

    location / {
      default_type text/html;
      content_by_lua '
        require("lapis").serve("app")
      ';
    }

    location /static/ {
      alias static/;
    }

    location /favicon.ico {
      alias static/favicon.ico;
    }
  }
}

需要注意的是，这和我们的常规的 Nginx 配置文件存在一定的差异。比如 $ 这样的语法，在启动服务器之前会使用 Lapis 应用里面的指定环境的配置文件中的值进行填充。

当然也有一些有趣的配置。 error_log stderr notice 和 daemon off 让服务运行在前台，以及可以在控制台打印出日志。这对于开发的过程中是非常友好的，不过在线上还是要关闭它们的。

lua_code_cache 在开发环境中尽量关闭这个开关，将其设置为 off 这在调试的过程中可以避免很多懵逼现象。当然线上对性能要求比较高的话，还是建议打开这个开关的，只要将其设置为 on 。不过该变量的默认值是 off.

content_by_lua 里面的 Lua 代码逻辑处理不匹配其他 location 的剩余的请求。它会加载 Lapis 同时告诉服务器模块名称叫 app 。同时在执行 lapis new 命令之前会提供一个精简版的 app 模块。

启动服务

Lapis 将 build 配置和启动服务器集成一个很简单的命令。

只需要在命令行之行 lapis server 。 Lapis 就会去查找你的 OpenResty 的安装目录，最后去查找 nginx 的二进制文件。（最后一个代表你的系统变量 PATH ）

1
2
3
4
"/usr/local/openresty/nginx/sbin/"
"/usr/local/opt/openresty/bin/"
"/usr/sbin/"
""

提醒 ：记得安装 OpenResty，而不是一个普通的 Nginx ， Lapis 会忽略掉普通的 Nginx 。

下面我们介绍一下如何启动服务器，只需要简单的一个命令：

1
$ lapis server

那些默认的配置文件会在前台引入到服务器中，只需要 CTRL + C 就可以停止服务器。

如果服务器运行在后台可以使用 lapis term 停止服务器。当然这个命令必须运行在应用的根目录下。这个命令会去查找 PID 文件，如果这个进程存在的话，会向它发送一个 TERM 指令。