nginx-c-module-design

nginx.org Nginx C 模块指令设计最佳实践

面向 Nginx C 模块作者的全面指令设计指南，重点介绍如何创建清晰、一致且便于管理员使用的配置接口。包含 8 个类别中的 46 条规则，并按影响程度排序，帮助决定要开放哪些配置项、如何命名，以及如何安全地演进。

适用场景

在以下情况下，请参考这些指南：

• 决定哪些值应作为指令开放配置，哪些应硬编码
• 为新指令命名并选择参数类型
• 选择指令的作用域（http、server、location）
• 设置默认值和验证行为
• 设计用于运行时数据的 Nginx 变量
• 弃用或重命名现有指令

配套技能

此技能侧重于设计决策（“是什么”和“为什么”）。如需了解实现机制，请参阅：

• nginx-c-modules — C 语言实现：内存池、请求生命周期、配置解析、处理程序、过滤器
• nginx-c-perf — 性能：缓冲区、连接、锁、缓存、超时
• nginx-c-debug — 调试：崩溃诊断、GDB、跟踪、消毒器

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	配置开放决策	CRITICAL	expose-
2	命名约定	CRITICAL	naming-
3	指令类型	HIGH	type-
4	作用域设计	HIGH	scope-
5	默认值	MEDIUM-HIGH	default-
6	验证与错误消息	MEDIUM	valid-
7	变量设计	MEDIUM	var-
8	演进与兼容性	LOW-MEDIUM	compat-

快速参考

1. 配置开放决策（CRITICAL）

• expose-configurable-vs-hardcode - 可配置值与硬编码值的决策框架
• expose-escape-hatch - 为硬编码默认值提供调整入口
• expose-feature-gate - 使用功能开关控制可选行为
• expose-too-many-directives - 避免过度配置
• expose-path-resource - 始终开放外部资源路径供配置
• expose-security-surface - 审查每条开放指令的安全影响
• expose-environment-dependent - 开放会随部署环境变化的值供配置

2. 命名约定（CRITICAL）

• naming-module-prefix - 为所有指令使用一致的模块前缀
• naming-sub-prefix-groups - 使用子前缀对相关指令分组
• naming-noun-over-verb - 指令名称优先使用名词短语
• naming-no-abbreviations - 避免在指令名称中使用自定义缩写
• naming-cross-module-consistency - 为类似指令沿用 Nginx 核心的后缀模式
• naming-lowercase-underscore - 仅使用小写字母和下划线

3. 指令类型（HIGH）

• type-flag-for-toggles - 使用 NGX_CONF_FLAG 实现二元开关
• type-enum-over-string - 对已知值集合使用枚举槽位
• type-time-size-units - 使用时间和大小槽位函数处理时间和大小值
• type-take-n-fixed-args - 对固定数量的参数使用 TAKE1/TAKE2/TAKE12
• type-one-more-lists - 对可变长度的值列表使用 1MORE
• type-avoid-block - 避免使用块指令实现功能
• type-custom-handler-complex - 对复杂的指令解析使用自定义处理程序

4. 作用域设计（HIGH）

• scope-default-three-levels - 默认使用 http + server + location 作用域
• scope-http-only-shared-resources - 将共享资源指令限制在 http 级别
• scope-server-connection-level - 对连接级设置使用 http + server 作用域
• scope-avoid-if-context - 除非经过全面测试，否则不要支持 if 上下文
• scope-location-path-operations - 将路径路由指令限制在 location 上下文中

5. 默认值（MEDIUM-HIGH）

• default-zero-config-safe - 确保零配置也能产生安全行为
• default-performance-optin - 将性能功能设为可选启用
• default-safety-on - 将安全设置的默认值设为限制性值
• default-generous-timeouts - 将超时默认值设为宽裕值
• default-zero-unlimited - 对数值限制使用零表示不受限制或禁用
• default-platform-aware-buffers - 使用适应平台的缓冲区大小默认值

6. 验证与错误消息（MEDIUM）

• valid-parse-time-check - 在配置解析时验证所有指令值
• valid-show-invalid-value - 在错误消息中包含无效值
• valid-suggest-range - 在错误消息中包含有效范围或格式
• valid-conflict-detection - 在合并时检测冲突指令
• valid-actionable-guidance - 在错误消息中提供可执行的指导

7. 变量设计（MEDIUM）

• var-runtime-data-only - 仅为每个请求的运行时数据公开变量
• var-naming-convention - 使用模块前缀和描述性后缀命名变量
• var-dynamic-prefix - 对键值数据使用动态前缀变量
• var-lazy-evaluation - 利用惰性求值处理开销较大的变量
• var-in-directive-values - 仅在需要针对每个请求进行变化时，才支持在指令值中使用变量
• var-read-only-diagnostics - 公开只读诊断变量以便进行可观测性分析

8. 演进与兼容性（低-中）

• compat-deprecation-warning - 移除弃用指令前记录警告
• compat-alias-old-directive - 将旧指令名称保留为别名
• compat-multi-version-window - 保持多版本弃用窗口
• compat-document-migration - 在新旧指令文档中记录迁移路径

如何使用

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息