name: nginx-c-module-design description: nginx C模块指令设计指南，用于创建管理员友好的配置界面。此技能应用于设计nginx模块指令时 — 决定哪些值暴露为指令与硬编码、命名规范、作用域放置、默认值、变量设计和验证模式。触发任务涉及ngx_command_t设计、指令命名、配置API设计、nginx模块公共接口或指令弃用。
nginx.org C模块指令设计最佳实践
全面的指令设计指南，面向nginx C模块作者，专注于创建清晰、一致且管理员友好的配置界面。包含8个类别中的46条规则，按影响优先级排序，以指导关于暴露什么、如何命名以及如何安全演化的决策。
何时应用
参考这些指南当：
- 决定哪些值作为指令暴露与硬编码
- 命名新指令和选择参数类型
- 选择作用域放置（http、server、location）
- 设置默认值和验证行为
- 设计nginx变量用于运行时数据
- 弃用或重命名现有指令
配套技能
此技能侧重于设计决策（“什么”和“为什么”）。对于实现机制，请参见：
- nginx-c-modules — C实现：内存池、请求生命周期、配置解析、处理程序、过滤器
- nginx-c-perf — 性能：缓冲区、连接、锁、缓存、超时
- nginx-c-debug — 调试：崩溃诊断、GDB、跟踪、消毒剂
规则类别按优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 暴露决策 | 关键 | expose- |
| 2 | 命名规范 | 关键 | naming- |
| 3 | 指令类型 | 高 | type- |
| 4 | 作用域设计 | 高 | scope- |
| 5 | 默认值 | 中高 | default- |
| 6 | 验证与错误消息 | 中 | valid- |
| 7 | 变量设计 | 中 | var- |
| 8 | 演进与兼容性 | 低中 | compat- |
快速参考
1. 暴露决策（关键）
expose-configurable-vs-hardcode- 可配置与硬编码值框架expose-escape-hatch- 为硬编码默认值提供逃生舱口expose-feature-gate- 使用功能门控用于可选行为expose-too-many-directives- 避免过度配置expose-path-resource- 总是暴露外部资源路径expose-security-surface- 审计每个暴露指令的安全影响expose-environment-dependent- 暴露因部署环境而异的
2. 命名规范（关键）
naming-module-prefix- 为所有指令使用一致的模块前缀naming-sub-prefix-groups- 使用子前缀分组相关指令naming-noun-over-verb- 优先使用名词短语作为指令名称naming-no-abbreviations- 避免在指令名称中使用自定义缩写naming-cross-module-consistency- 镜像Nginx核心后缀模式用于类似指令naming-lowercase-underscore- 仅使用小写字母和下划线
3. 指令类型（高）
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. 作用域设计（高）
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. 默认值（中高）
default-zero-config-safe- 确保零配置产生安全行为default-performance-optin- 使性能功能选择加入default-safety-on- 默认安全设置为限制性值default-generous-timeouts- 默认超时到慷慨值default-zero-unlimited- 使用零表示无限制或禁用用于数字限制default-platform-aware-buffers- 使用平台感知的缓冲区大小默认值
6. 验证与错误消息（中）
valid-parse-time-check- 在配置解析时验证所有指令值valid-show-invalid-value- 在错误消息中包含无效值valid-suggest-range- 在错误消息中包含有效范围或格式valid-conflict-detection- 在合并时检测冲突指令valid-actionable-guidance- 在错误消息中提供可操作的指导
7. 变量设计（中）
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 | 版本和参考信息 |