nginx 扩展模块开发

apache的插件以动态库方式存在，通过配置动态加载；nginx插件则需要编译至nginx可执行程序中，openresty也是如此，直接将lua解释器嵌入至nginx，使其具备解析lua脚本能力。nginx 内置插件目录在 src/http/modules 下。

编写nginx插件过程比较麻复杂，需要对nginx源码及数据结构有一定的了解。nginx实现了字符串，定时器，容器（HashTable，Queue，红黑树），内存池，日志，网络处理，线程等常用函数，学习价值非常高。

本文是来自淘宝Tengine文档，根据自己理解做了一些注释。

 

 一. hello world模块

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>


// hello 配置结构
typedef struct 
{
  ngx_int_t hello_counter;  // 计数配置
} ngx_http_hello_loc_conf_t;


// 上下文回调函数
static ngx_int_t ngx_http_hello_init( ngx_conf_t *cf );
static void *ngx_http_hello_create_loc_conf( ngx_conf_t *cf );

// 配置处理函数
static char *ngx_hello_set( ngx_conf_t *, ngx_command_t *, void * );
// 回调函数
static ngx_int_t ngx_http_hello_handler( ngx_http_request_t * );


// 配置项
static ngx_command_t ngx_http_hello_commands[] = {
  {
    ngx_string("hello_counter"),    // 配置名称hello_counter
    NGX_HTTP_LOC_CONF | NGX_CONF_FLAG,  // 配置为bool类型，取值为on/off
    ngx_hello_set,            // 配置处理函数
    NGX_HTTP_LOC_CONF_OFFSET,
    0,
    NULL
  },
  ngx_null_command  // 以null结尾 
};

// 模块上下文
static ngx_http_module_t ngx_hello_ctx = {
  NULL, 
  ngx_http_hello_init,        // 读取该模块配置后调用 
  NULL, 
  NULL, 
  NULL, 
  NULL, 
  ngx_http_hello_create_loc_conf,   // 读取到location配置后调用(每个location创建一个)
  NULL
};

// 模块定义
ngx_module_t ngx_http_hello_module = {
  NGX_MODULE_V1,
  &ngx_hello_ctx,
  ngx_http_hello_commands,
  NGX_HTTP_MODULE,
  NULL, NULL, NULL, NULL, NULL, NULL, NULL,
  NGX_MODULE_V1_PADDING
};



static char *ngx_hello_set( ngx_conf_t *cf, ngx_command_t *cmd, void *conf ) {
  ngx_http_hello_loc_conf_t *local_conf;
  local_conf = conf;
  char *rv = NULL;

  // 读取NGX_CONF_FLAG类型参数
  rv = ngx_conf_set_flag_slot(cf, cmd, conf);

  ngx_conf_log_error( NGX_LOG_INFO, cf, 0, "hello_counter:%d", local_conf->hello_counter );
  return rv;
}


static void *ngx_http_hello_create_loc_conf(ngx_conf_t *cf)
{
  ngx_http_hello_loc_conf_t* local_conf = NULL;
  local_conf = ngx_pcalloc( cf->pool, sizeof(ngx_http_hello_loc_conf_t) );
  if ( local_conf == NULL )
  {
    return NULL;
  }

  // 初始设置默认值
  local_conf->hello_counter = NGX_CONF_UNSET;
  return local_conf;
}

static ngx_int_t ngx_http_hello_init(ngx_conf_t *cf)
{
  ngx_http_handler_pt *h;
  ngx_http_core_main_conf_t *cmcf;

  cmcf = ngx_http_conf_get_module_main_conf( cf, ngx_http_core_module );

  h = ngx_array_push( &cmcf->phases[NGX_HTTP_CONTENT_PHASE].handlers );
  if (h == NULL) {
    return NGX_ERROR;
  }

  // 在 NGX_HTTP_CONTENT_PHASE 阶段设置回调函数
  *h = ngx_http_hello_handler;
  return NGX_OK;
}


static int ngx_hello_visited_times = 0; // 访问次数

static ngx_int_t ngx_http_hello_handler( ngx_http_request_t *r ) {
  ngx_int_t rc;
  ngx_buf_t *b;
  ngx_chain_t out;
  ngx_http_hello_loc_conf_t *my_conf;
  ngx_uint_t content_length = 0;
  u_char ngx_hello_string[1024] = {0};
  
  ngx_log_error( NGX_LOG_EMERG, r->connection->log, 0, "ngx_http_hello_handler is called!" );
  
  // 获取配置值 
  my_conf = ngx_http_get_module_loc_conf( r, ngx_http_hello_module );
  if ( my_conf->hello_counter == NGX_CONF_UNSET || my_conf->hello_counter == 0 )
  {
    ngx_sprintf( ngx_hello_string, "<h1>Non counter</h1>" );
  }
  else
  {
    ngx_sprintf( ngx_hello_string, 
          "<h1>Visited Times:%d</h1>", 
          ++ngx_hello_visited_times );
  }
  
  ngx_log_error( NGX_LOG_EMERG, r->connection->log, 0, "hello_string:%s", ngx_hello_string );
  content_length = ngx_strlen( ngx_hello_string );
  
  // 分配响应缓冲区
  b = ngx_pcalloc( r->pool, sizeof(ngx_buf_t) );
  out.buf = b;  // attach 
  out.next = NULL;
  
  b->pos = ngx_hello_string;
  b->last = ngx_hello_string + content_length;
  b->memory = 1;
  b->last_buf = 1;

  // 设置响应
  ngx_str_set( &r->headers_out.content_type, "text/html" );
  r->headers_out.status = NGX_HTTP_OK;
  r->headers_out.content_length_n = content_length;
  
  // 发送响应
  rc = ngx_http_send_header( r );

  // 传递至其它过滤器处理
  return ngx_http_output_filter( r, &out );
}

 

 二. 编译

插件目录：

~/hlmodule

-- config

-- ngx_http_hello_module.c

 

准备config文件，内容如下：

ngx_addon_name=ngx_http_hello_module
HTTP_MODULES="$HTTP_MODULES ngx_http_hello_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_module.c"

 

编译：

./configure --prefix=~/nginx --add-module=~/hlmodule
make && make install

 

三. 配置启用hello_counter 

vi conf/nginx.conf 
 
 
location /hello {
  hello_counter on;   // 启用计数
}

 

四. 测试 

hello_counter设置on:

 

hello_counter设置off:

 

 

 参考链接：

淘宝nginx模块开发  

​​http://tengine.taobao.org/book/chapter_03.html#hello-handler​​

官方reference

​​http://nginx.org/en/docs/dev/development_guide.html#core_modules​​