nginx-c-module-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

nginx.org C Module Directive Design Best Practices

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

Comprehensive directive design guide for nginx C module authors, focused on creating clear, consistent, and admin-friendly configuration interfaces. Contains 46 rules across 8 categories, prioritized by impact to guide decisions about what to expose, how to name it, and how to evolve it safely.

这是一份面向Nginx C模块开发者的全面指令设计指南，专注于创建清晰、一致且管理员友好的配置界面。指南包含8个类别共46条规则，按影响优先级排序，用于指导开发者决定暴露哪些内容、如何命名以及如何安全地演进指令。

When to Apply

适用场景

Reference these guidelines when:

Deciding which values to expose as directives vs hardcode
Naming new directives and choosing argument types
Selecting scope placement (http, server, location)
Setting default values and validation behavior
Designing nginx variables for runtime data
Deprecating or renaming existing directives

在以下场景中参考本指南：

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

Companion Skills

配套技能

This skill focuses on design decisions (the "what" and "why"). For implementation mechanics, see:

nginx-c-modules — C implementation: memory pools, request lifecycle, config parsing, handlers, filters
nginx-c-perf — Performance: buffers, connections, locks, caching, timeouts
nginx-c-debug — Debugging: crash diagnosis, GDB, tracing, sanitizers

本指南聚焦于设计决策（即“做什么”和“为什么”）。如需了解实现细节，请参考：

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

Rule Categories by Priority

按优先级划分的规则类别


expose-
naming-
type-
scope-
default-
valid-
var-
compat-

Priority	Category	Impact	Prefix
1	Exposure Decisions	CRITICAL	`expose-`
2	Naming Conventions	CRITICAL	`naming-`
3	Directive Types	HIGH	`type-`
4	Scope Design	HIGH	`scope-`
5	Default Values	MEDIUM-HIGH	`default-`
6	Validation & Error Messages	MEDIUM	`valid-`
7	Variable Design	MEDIUM	`var-`
8	Evolution & Compatibility	LOW-MEDIUM	`compat-`


expose-
naming-
type-
scope-
default-
valid-
var-
compat-

优先级	类别	影响程度	前缀
1	暴露决策	关键	`expose-`
2	命名规范	关键	`naming-`
3	指令类型	高	`type-`
4	作用域设计	高	`scope-`
5	默认值	中高	`default-`
6	验证与错误信息	中	`valid-`
7	变量设计	中	`var-`
8	演进与兼容性	中低	`compat-`

Quick Reference

快速参考

1. Exposure Decisions (CRITICAL)

1. 暴露决策（关键）

```
expose-configurable-vs-hardcode
```
- Framework for Configurable vs Hardcoded Values
```
expose-escape-hatch
```
- Provide Escape Hatches for Hardcoded Defaults
```
expose-feature-gate
```
- Use Feature Gates for Optional Behavior
```
expose-too-many-directives
```
- Avoid Over-Configuration
```
expose-path-resource
```
- Always Expose External Resource Paths
```
expose-security-surface
```
- Audit Security Implications of Every Exposed Directive
```
expose-environment-dependent
```
- Expose Values That Vary by Deployment Environment

```
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 Conventions (CRITICAL)

2. 命名规范（关键）

```
naming-module-prefix
```
- Use a Consistent Module Prefix for All Directives
```
naming-sub-prefix-groups
```
- Group Related Directives with Sub-Prefixes
```
naming-noun-over-verb
```
- Prefer Noun Phrases for Directive Names
```
naming-no-abbreviations
```
- Avoid Custom Abbreviations in Directive Names
```
naming-cross-module-consistency
```
- Mirror Nginx Core Suffix Patterns for Analogous Directives
```
naming-lowercase-underscore
```
- Use Lowercase with Underscores Only

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

3. Directive Types (HIGH)

3. 指令类型（高）

```
type-flag-for-toggles
```
- Use NGX_CONF_FLAG for Binary Toggles
```
type-enum-over-string
```
- Use Enum Slot for Known Value Sets
```
type-time-size-units
```
- Use Time and Size Slot Functions for Time and Size Values
```
type-take-n-fixed-args
```
- Use TAKE1/TAKE2/TAKE12 for Fixed Argument Counts
```
type-one-more-lists
```
- Use 1MORE for Variable-Length Value Lists
```
type-avoid-block
```
- Avoid Block Directives for Features
```
type-custom-handler-complex
```
- Use Custom Handlers for Complex Directive Parsing

```
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 Design (HIGH)

4. 作用域设计（高）

```
scope-default-three-levels
```
- Default to http + server + location Scope
```
scope-http-only-shared-resources
```
- Restrict Shared Resource Directives to http Level Only
```
scope-server-connection-level
```
- Use http + server Scope for Connection-Level Settings
```
scope-avoid-if-context
```
- Do Not Support the if Context Unless Fully Tested
```
scope-location-path-operations
```
- Restrict Path-Routing Directives to Location Context

```
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 Values (MEDIUM-HIGH)

5. 默认值（中高）

```
default-zero-config-safe
```
- Ensure Zero-Config Produces Safe Behavior
```
default-performance-optin
```
- Make Performance Features Opt-In
```
default-safety-on
```
- Default Security Settings to Restrictive Values
```
default-generous-timeouts
```
- Default Timeouts to Generous Values
```
default-zero-unlimited
```
- Use Zero to Mean Unlimited or Disabled for Numeric Limits
```
default-platform-aware-buffers
```
- Use Platform-Aware Buffer Size Defaults

```
default-zero-config-safe
```
- 确保零配置下的行为安全
```
default-performance-optin
```
- 性能特性设为可选启用
```
default-safety-on
```
- 安全设置默认使用严格值
```
default-generous-timeouts
```
- 默认超时时间设为较宽松的值
```
default-zero-unlimited
```
- 用零表示数值限制的无限制或禁用
```
default-platform-aware-buffers
```
- 使用感知平台的缓冲区大小默认值

6. Validation & Error Messages (MEDIUM)

6. 验证与错误信息（中）

```
valid-parse-time-check
```
- Validate All Directive Values at Config Parse Time
```
valid-show-invalid-value
```
- Include the Invalid Value in Error Messages
```
valid-suggest-range
```
- Include Valid Range or Format in Error Messages
```
valid-conflict-detection
```
- Detect Conflicting Directives at Merge Time
```
valid-actionable-guidance
```
- Provide Actionable Guidance in Error Messages

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

7. Variable Design (MEDIUM)

7. 变量设计（中）

```
var-runtime-data-only
```
- Expose Variables for Per-Request Runtime Data Only
```
var-naming-convention
```
- Name Variables with Module Prefix and Descriptive Suffix
```
var-dynamic-prefix
```
- Use Dynamic Prefix Variables for Key-Value Data
```
var-lazy-evaluation
```
- Leverage Lazy Evaluation for Expensive Variables
```
var-in-directive-values
```
- Support Variables in Directive Values Only When Per-Request Variation Is Needed
```
var-read-only-diagnostics
```
- Expose Read-Only Diagnostic Variables for Observability

```
var-runtime-data-only
```
- 仅为每请求运行时数据暴露变量
```
var-naming-convention
```
- 变量名称使用模块前缀加描述性后缀
```
var-dynamic-prefix
```
- 为键值数据使用动态前缀变量
```
var-lazy-evaluation
```
- 对开销较大的变量使用延迟求值
```
var-in-directive-values
```
- 仅当需要每请求变化时才支持在指令值中使用变量
```
var-read-only-diagnostics
```
- 暴露只读诊断变量以支持可观测性

8. Evolution & Compatibility (LOW-MEDIUM)

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

```
compat-deprecation-warning
```
- Log Warnings for Deprecated Directives Before Removal
```
compat-alias-old-directive
```
- Keep Old Directive Name as an Alias
```
compat-multi-version-window
```
- Maintain a Multi-Version Deprecation Window
```
compat-document-migration
```
- Document Migration Path in Both Old and New Directive Documentation

```
compat-deprecation-warning
```
- 在移除弃用指令前记录警告日志
```
compat-alias-old-directive
```
- 将旧指令名称保留为别名
```
compat-multi-version-window
```
- 维护多版本的弃用过渡期
```
compat-document-migration
```
- 在新旧指令文档中都记录迁移路径

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

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

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

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