简单API Server框架

实现一个最最简单的数学计算：加、减、乘、除，给大家演示如何搭建简单的 API Server。

按照前面几章的写法，先来看看加法、减法示例代码：

  1. worker_processes  1;        #nginx worker 数量
  2. error_log logs/error.log;   #指定错误日志文件路径
  3. events {
  4.     worker_connections 1024;
  5. }
  6. http {
  7.     server {
  8.         listen 80;
  10.         # 加法
  11.         location /addition {
  12.            content_by_lua_block {
  13.                 local args = ngx.req.get_uri_args()
  14.                 ngx.say(args.a + args.b)
  15.             }
  16.         }
  18.         # 减法
  19.         location /subtraction {
  20.             content_by_lua_block {
  21.                 local args = ngx.req.get_uri_args()
  22.                 ngx.say(args.a - args.b)
  23.             }
  24.         }
  26.         # 乘法
  27.         location /multiplication {
  28.             content_by_lua_block {
  29.                 local args = ngx.req.get_uri_args()
  30.                 ngx.say(args.a * args.b)
  31.             }
  32.         }
  34.         # 除法
  35.         location /division {
  36.             content_by_lua_block {
  37.                 local args = ngx.req.get_uri_args()
  38.                 ngx.say(args.a / args.b)
  39.             }
  40.         }
  41.     }
  42. }

代码写多了一眼就可以看出来，这么简单的加减乘除，居然写了这么长，而且还要对每个 API 都写一个 location ，作为有追求的人士，怎能容忍这种代码风格？

  • 首先是需要把这些 location 合并；
  • 其次是这些接口的实现放到独立文件中，保持 Nginx 配置文件的简洁；

基于这两点要求，可以改成下面的版本，看上去有那么几分模样了：

nginx.conf 内容：

  1. worker_processes  1;        #nginx worker 数量
  2. error_log logs/error.log;   #指定错误日志文件路径
  3. events {
  4.     worker_connections 1024;
  5. }
  7. http {
  8.     # 设置默认 lua 搜索路径，添加 lua 路径
  9.     # 此处写相对路径时，对启动 Nginx 的路径有要求，必须在 Nginx 目录下启动，require 找不到
  10.     # comm.param 绝对路径当然也没问题，但是不可移植，因此应使用变量 $prefix 或
  11.     # ${prefix}，OR 会替换为 Nginx 的 prefix path。
  13.     # lua_package_path 'lua/?.lua;/blah/?.lua;;';
  14.     lua_package_path '$prefix/lua/?.lua;/blah/?.lua;;';
  16.     # 这里设置为 off，是为了避免每次修改之后都要重新 reload 的麻烦。
  17.     # 在生产环境上务必确保 lua_code_cache 设置成 on。
  18.     lua_code_cache off;
  20.     server {
  21.         listen 80;
  23.         # 在代码路径中使用 Nginx 变量
  24.         # 注意：使用 Nginx var 的变量一定要谨慎，否则将会带来非常大的风险
  25.         location ~ ^/api/([-_a-zA-Z0-9/]+) {
  26.             # 准入阶段完成参数验证
  27.             access_by_lua_file  lua/access_check.lua;
  29.             # 内容生成阶段
  30.             content_by_lua_file lua/$1.lua;
  31.         }
  32.     }
  33. }

其他文件内容：

  1. --========== {$prefix}/lua/addition.lua
  2. local args = ngx.req.get_uri_args()
  3. ngx.say(args.a + args.b)
  5. --========== {$prefix}/lua/subtraction.lua
  6. local args = ngx.req.get_uri_args()
  7. ngx.say(args.a - args.b)
  9. --========== {$prefix}/lua/multiplication.lua
  10. local args = ngx.req.get_uri_args()
  11. ngx.say(args.a * args.b)
  13. --========== {$prefix}/lua/division.lua
  14. local args = ngx.req.get_uri_args()
  15. ngx.say(args.a / args.b)

既然对外提供的是 API Server，作为一个服务端程序员，怎么可以容忍输入参数不检查呢？万一对方送过来的不是数字或者为空，这些都要过滤掉嘛。参数检查过滤的方法是统一，在这几个 API 中如何共享这个方法呢？这时候就需要 Lua 模块来完成了。

  • 使用统一的公共模块，完成参数验证；
  • 验证入口最好也统一，不要分散在不同地方；

nginx.conf 内容：

  1. worker_processes  1;        # Nginx worker 数量
  2. error_log logs/error.log;   # 指定错误日志文件路径
  3. events {
  4.     worker_connections 1024;
  5. }
  6. http {
  7.     server {
  8.         listen 80;
  10.         # 在代码路径中使用 Nginx 变量
  11.         # 注意：使用 Nginx var 的变量一定要谨慎，否则将会带来非常大的风险
  12.         location ~ ^/api/([-_a-zA-Z0-9/]+) {
  13.             access_by_lua_file  lua/access_check.lua;
  14.             content_by_lua_file lua/$1.lua;
  15.         }
  16.     }
  17. }

新增文件内容：

  1. --========== {$prefix}/lua/comm/param.lua
  2. local _M = {}
  4. -- 对输入参数逐个进行校验，只要有一个不是数字类型，则返回 false
  5. function _M.is_number(...)
  6.     local arg = {...}
  8.     local num
  9.     for _,v in ipairs(arg) do
  10.         num = tonumber(v)
  11.         if nil == num then
  12.             return false
  13.         end
  14.     end
  16.     return true
  17. end
  19. return _M
  21. --========== {$prefix}/lua/access_check.lua
  22. local param= require("comm.param")
  23. local args = ngx.req.get_uri_args()
  25. if not args.a or not args.b or not param.is_number(args.a, args.b) then
  26.     ngx.exit(ngx.HTTP_BAD_REQUEST)
  27.     return
  28. end

看看 curl 测试结果吧：

  1. $ curl '127.0.0.1:80/api/addition?a=1'
  2. <html>
  3. <head><title>400 Bad Request</title></head>
  4. <body bgcolor="white">
  5. <center><h1>400 Bad Request</h1></center>
  6. <hr><center>openresty/1.9.3.1</center>
  7. </body>
  8. </html>
  10. $ curl '127.0.0.1:80/api/addition?a=1&b=3'
  11. 4

基本是按照预期执行的。参数不全、错误时，会提示 400 错误。正常处理，可以返回预期结果。

来整体看一下目前的目录结构：

  1. .
  2. ├── conf
  3. │   ├── nginx.conf
  4. ├── logs
  5. │   ├── error.log
  6. │   └── nginx.pid
  7. ├── lua
  8. │   ├── access_check.lua
  9. │   ├── addition.lua
  10. │   ├── subtraction.lua
  11. │   ├── multiplication.lua
  12. │   ├── division.lua
  13. │   └── comm
  14. │       └── param.lua
  15. └── sbin
  16.     └── nginx

怎么样，有点 magic 的味道不？其实你的接口越是规范，有固定规律可寻，那么 OpenResty 就总是很容易能找到适合你的位置。当然这里你也可以把 access_check.lua 内容分别复制到加、减、乘、除实现的四个 Lua 文件中，肯定也是能用的。这里只是为了给大家提供更多的玩法，需要的时候可以有更多的选择。

本章目的是搭建一个简单 API Server，记住这绝对不是终极版本。这里面还有很多需要进一步去考虑的地方，但是作为最基本的框架已经有了。