Nginx模块开发中必须通过ngx_connection_t接口进行I/O操作，不可直接调用系统read/write；它统一管理事件、缓冲区、超时、SSL及资源生命周期，正确使用ngx_recv/ngx_send/ngx_close_connection等封装函数才能保障事件驱动模型稳定运行。
在 Nginx 模块开发中，直接操作底层套接字需谨慎——ngx_connection_t 并非裸 socket 封装，而是 Nginx 事件驱动模型下的连接抽象，承载着读写事件、缓冲区、超时、SSL 状态等关键上下文。绕过它而自行调用 read()/write() 或 send()/recv() 极易破坏事件循环、引发内存泄漏或连接状态错乱。
理解 ngx_connection_t 的核心职责
它不是“连接句柄”，而是 Nginx 连接生命周期的管理者：
-
绑定事件机制：每个
ngx_connection_t*关联一个ngx_event_t读/写事件，由 epoll/kqueue/select 驱动，回调触发handler（如ngx_http_wait_request_handler） -
统一缓冲管理：自带
read->buf和write->buf，数据收发应走ngx_recv()/ngx_send()等封装函数，它们自动处理 EAGAIN、缓冲区满、零拷贝（如 sendfile）等细节 -
状态与资源归属清晰：持有 socket fd、SSL 结构（若启用）、内存池（
pool）、日志上下文；销毁连接时会自动关闭 fd、清理 SSL、释放缓冲区内存 -
超时与限速集成：读写超时由
read->timer/write->timer控制；限速逻辑（如limit_rate）也基于此结构实现流量整形
正确使用连接进行 I/O 操作
避免直接系统调用，始终通过 Nginx 提供的连接层接口：
-
接收数据：调用
ngx_recv(c, buf, size, flags)，内部自动处理 EAGAIN/EWOULDBLOCK，并在阻塞时将读事件重新添加到事件队列 -
发送数据：优先用
ngx_send(c, buf, size, flags)；若需异步写且缓冲区可能未满，用ngx_output_chain()+ngx_chain_writer()组合，配合c->write->handler回调处理后续发送 -
主动关闭：调用
ngx_close_connection(c)，它会触发c->close_handler、清理 SSL、释放 pool、关闭 fd，并从事件循环中移除该连接 -
错误判断：检查返回值是否为
NGX_ERROR、NGX_AGAIN或具体负值（如NGX_ECONNRESET），而非直接查 errno
常见误用与规避方式
以下行为在生产模块中应严格禁止：
-
手动 close(fd)：会导致
ngx_close_connection()再次关闭已关闭的 fd，可能触发 SIGPIPE 或干扰其他模块 -
复用已关闭连接的 c->data：连接关闭后
c->data可能被重用或释放，访问它属于悬垂指针行为 -
在 handler 中长期阻塞：如调用
sleep()或同步 DNS 查询，会卡住 worker 进程；必须改用异步机制（如ngx_resolver_create()+ 回调） -
忽略连接引用计数：Nginx 在多阶段（如子请求、upstream）中会增减
c->number；调用ngx_reusable_connection(c, 0)前需确认无其他模块持有引用
调试与诊断要点
当连接行为异常时，可借助以下方式定位：
- 开启
debug_connection指令，配合error_log ... debug;查看连接创建、事件触发、关闭全过程日志 - 检查
c->read->ready和c->write->ready标志，确认事件是否真正就绪，而非仅靠定时器轮询 - 用
ngx_log_debugX打印c->fd、c->recv、c->send函数指针，验证是否被其他模块篡改（如某些 SSL 模块会替换 recv/send） - 注意
c->requests计数：HTTP 模块中它表示当前连接上活跃的请求数，为 0 时连接可能被 idle timeout 关闭
