Nginx 开发者文档翻译 - 介绍

由于我的一个Private Cloud FaaS（函数计算）项目 Navagraha 使用Nginx作为实现Service Mesh和API Gateway的基础框架，需要对Nginx有深入的了解，因此在这里翻译Nginx官方文档，用于之后的开发提供辅助参考。

介绍

代码组织结构

• auto - 编译构建脚本
• src
  • core - 基础类型和函数 - 包括string，array，log，pool等内容
  • event - 核心事件类型
    • modules - 事件通知模块，包括epoll、kqueue、select等内容
  • http - 核心HTTP模块以及通用代码
    • modules - 其他的HTTP模块
    • v2 - HTTP/2
  • mail - 邮件模块
  • os - 特定平台代码
    • unix
    • win32
  • stream - 数据流模块

头文件

在每个Nginx源文件里，必然包含两个头文件 分别为

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

如果需要实现的是HTTP模块，则需要添加HTTP相关的头文件：

#include <ngx_http.h>

邮件模块则添加头文件：

#include <ngx_mail.h>

数据流模块需要添加头文件：

#include <ngx_stream.h>

整型类型

在通常开发Nginx模块过程中，通常使用两种整型类型ngx_int_t或者ngx_uint_t，对应的指针类型为intptr_t和uintptr_t。

通用返回类型

在Nginx模块中，很多函数使用通用的返回值类型：

• NGX_OK - 代表操作执行成功。
• NGX_ERROR - 代表操作执行失败。
• NGX_AGAIN - 代表操作未执行完毕；要求重新调用该函数。
• NGX_DECLINED - 代表操作被拒绝。
• NGX_BUSY - 代表资源不可用
• NGX_DONE - 代表操作执行完成或通知调用者继续执行其他操作。
• NGX_ABORT - 代表操作的执行被中断。

错误处理

调用宏定义ngx_errno将返回最后一个系统错误代码。如果是POSIX平台的话，这个宏定义将返回errno，如果是Windows平台的是返回GetLastError()。ngx_socket_errno是返回socket最后出现错误的错误码。如果要设置errno的错误码的话，可以使用ngx_set_errno(errno) 或者 ngx_set_socket_errno(errno)。

使用ngx_errno的实例如下:

void
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;

    if (kill(pid, signo) == -1) {
        err = ngx_errno;

        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) Failed", pid, signo);

        if (err == NGX_ESRCH) {
            return 2;
        }

        return 1;
    }

    return 0;
}