12-factor-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community Cloud-Native Applications Best Practices

社区云原生应用最佳实践

Comprehensive methodology for building modern software-as-a-service applications that are portable, scalable, and maintainable. Contains 51 rules across 12 categories, covering the entire application lifecycle from codebase management to production operations.

这是一套构建可移植、可扩展且易于维护的现代软件即服务（SaaS）应用的综合方法论。涵盖12个类别共51条规则，覆盖了从代码库管理到生产运营的整个应用生命周期。

When to Apply

适用场景

Reference these guidelines when:

Designing new backend services or APIs
Containerizing applications for Kubernetes or Docker
Setting up CI/CD pipelines
Managing configuration across environments
Implementing logging and monitoring
Planning application scaling strategy
Debugging deployment or environment issues

在以下场景中参考这些指南：

设计新的后端服务或API
为Kubernetes或Docker容器化应用
搭建CI/CD流水线
跨环境管理配置
实现日志记录与监控
规划应用扩容策略
排查部署或环境相关问题

Rule Categories by Priority

按优先级划分的规则类别


code-
dep-
config-
svc-
build-
proc-
scale-
disp-
port-
parity-
log-
admin-

Priority	Category	Impact	Prefix
1	Codebase & Version Control	CRITICAL	`code-`
2	Dependencies	CRITICAL	`dep-`
3	Configuration	CRITICAL	`config-`
4	Backing Services	HIGH	`svc-`
5	Build, Release, Run	HIGH	`build-`
6	Processes & State	HIGH	`proc-`
7	Concurrency & Scaling	HIGH	`scale-`
8	Disposability	HIGH	`disp-`
9	Port Binding	MEDIUM	`port-`
10	Dev/Prod Parity	MEDIUM	`parity-`
11	Logging	MEDIUM	`log-`
12	Admin Processes	MEDIUM	`admin-`


code-
dep-
config-
svc-
build-
proc-
scale-
disp-
port-
parity-
log-
admin-

优先级	类别	影响程度	前缀
1	代码库与版本控制	关键	`code-`
2	依赖管理	关键	`dep-`
3	配置管理	关键	`config-`
4	后端服务	高	`svc-`
5	构建、发布、运行	高	`build-`
6	进程与状态	高	`proc-`
7	并发与扩容	高	`scale-`
8	可处置性	高	`disp-`
9	端口绑定	中	`port-`
10	开发/生产环境一致性	中	`parity-`
11	日志记录	中	`log-`
12	管理进程	中	`admin-`

Quick Reference

快速参考

1. Codebase & Version Control (CRITICAL)

1. 代码库与版本控制（关键）

```
code-single-codebase
```
- Maintain one codebase per application in version control
```
code-one-app-one-repo
```
- Enforce one-to-one correlation between codebase and application
```
code-deploys-not-branches
```
- Use deploys not branches to represent environments
```
code-shared-as-libraries
```
- Factor shared code into libraries managed by dependency manager

```
code-single-codebase
```
- 在版本控制系统中为每个应用维护一个代码库
```
code-one-app-one-repo
```
- 强制代码库与应用一一对应
```
code-deploys-not-branches
```
- 使用部署而非分支来表示环境
```
code-shared-as-libraries
```
- 将共享代码提取为由依赖管理器管理的库

2. Dependencies (CRITICAL)

2. 依赖管理（关键）

```
dep-explicit-declaration
```
- Declare all dependencies explicitly in a manifest file
```
dep-isolate-execution
```
- Isolate dependencies to prevent system package leakage
```
dep-no-system-tools
```
- Never rely on implicit system tools being available
```
dep-deterministic-builds
```
- Use lockfiles for deterministic dependency resolution

```
dep-explicit-declaration
```
- 在清单文件中显式声明所有依赖
```
dep-isolate-execution
```
- 隔离依赖以防止系统包泄漏
```
dep-no-system-tools
```
- 绝不依赖隐含的系统工具可用性
```
dep-deterministic-builds
```
- 使用锁定文件实现确定性依赖解析

3. Configuration (CRITICAL)

3. 配置管理（关键）

```
config-separate-from-code
```
- Strictly separate configuration from code
```
config-use-env-vars
```
- Store configuration in environment variables
```
config-no-env-groups
```
- Treat environment variables as granular controls not grouped environments
```
config-validate-on-startup
```
- Validate required configuration at application startup
```
config-never-commit-secrets
```
- Never commit secrets or credentials to version control

```
config-separate-from-code
```
- 严格将配置与代码分离
```
config-use-env-vars
```
- 将配置存储在环境变量中
```
config-no-env-groups
```
- 将环境变量视为细粒度控制项，而非分组环境
```
config-validate-on-startup
```
- 在应用启动时验证所需配置
```
config-never-commit-secrets
```
- 绝不将密钥或凭据提交到版本控制系统

4. Backing Services (HIGH)

4. 后端服务（高）

```
svc-as-attached-resources
```
- Treat backing services as attached resources
```
svc-connection-strings
```
- Reference all backing services via connection URLs in config
```
svc-no-local-vs-remote
```
- Make no distinction between local and third-party services
```
svc-detach-attach-without-code
```
- Design services to be detachable and attachable without code changes

```
svc-as-attached-resources
```
- 将后端服务视为附加资源
```
svc-connection-strings
```
- 通过配置中的连接URL引用所有后端服务
```
svc-no-local-vs-remote
```
- 不区分本地服务与第三方服务
```
svc-detach-attach-without-code
```
- 设计无需修改代码即可分离和附加的服务

5. Build, Release, Run (HIGH)

5. 构建、发布、运行（高）

```
build-separate-stages
```
- Strictly separate build, release, and run stages
```
build-immutable-releases
```
- Create immutable releases with unique identifiers
```
build-no-runtime-changes
```
- Never modify code at runtime - changes require new release
```
build-complexity-in-build
```
- Push complexity into build stage keep run stage minimal
```
build-artifact-per-commit
```
- Generate one build artifact per commit deploy same artifact everywhere

```
build-separate-stages
```
- 严格分离构建、发布和运行阶段
```
build-immutable-releases
```
- 创建带有唯一标识符的不可变发布版本
```
build-no-runtime-changes
```
- 绝不允许在运行时修改代码，变更需通过新发布版本实现
```
build-complexity-in-build
```
- 将复杂度转移到构建阶段，保持运行阶段极简
```
build-artifact-per-commit
```
- 每次提交生成一个构建制品，在所有环境部署相同制品

6. Processes & State (HIGH)

6. 进程与状态（高）

```
proc-stateless-processes
```
- Execute the application as stateless processes
```
proc-no-sticky-sessions
```
- Never use sticky sessions - store session data in backing services
```
proc-no-local-filesystem
```
- Never assume local filesystem persists between requests
```
proc-compile-at-build
```
- Perform asset compilation and bundling at build time not runtime
```
proc-share-nothing
```
- Design processes to share nothing with each other

```
proc-stateless-processes
```
- 以无状态进程的方式运行应用
```
proc-no-sticky-sessions
```
- 绝不使用粘性会话，将会话数据存储在后端服务中
```
proc-no-local-filesystem
```
- 绝不假设本地文件系统会在请求之间持久化
```
proc-compile-at-build
```
- 在构建时而非运行时执行资源编译与打包
```
proc-share-nothing
```
- 设计进程之间不共享任何资源

7. Concurrency & Scaling (HIGH)

7. 并发与扩容（高）

```
scale-process-model
```
- Scale out via the process model with multiple process types
```
scale-process-types
```
- Assign workloads to appropriate process types
```
scale-no-daemonize
```
- Never daemonize or write PID files let process manager handle it
```
scale-horizontal-not-vertical
```
- Design for horizontal scaling over vertical scaling
```
scale-process-formation
```
- Define process formation as declarative configuration

```
scale-process-model
```
- 通过多进程类型的进程模型实现横向扩容
```
scale-process-types
```
- 将工作负载分配到合适的进程类型
```
scale-no-daemonize
```
- 绝不以守护进程运行或写入PID文件，交由进程管理器处理
```
scale-horizontal-not-vertical
```
- 优先设计为横向扩容而非纵向扩容
```
scale-process-formation
```
- 将进程组成定义为声明式配置

8. Disposability (HIGH)

8. 可处置性（高）

```
disp-disposable-processes
```
- Design processes to be disposable started or stopped at any moment
```
disp-fast-startup
```
- Minimize startup time to enable rapid scaling and recovery
```
disp-graceful-shutdown
```
- Implement graceful shutdown on SIGTERM
```
disp-crash-only
```
- Design for crash-only software that recovers from sudden death
```
disp-idempotent-operations
```
- Make operations idempotent to safely retry after failures

```
disp-disposable-processes
```
- 设计可随时启动或停止的可处置进程
```
disp-fast-startup
```
- 最小化启动时间以支持快速扩容与恢复
```
disp-graceful-shutdown
```
- 实现SIGTERM信号触发的优雅关闭
```
disp-crash-only
```
- 设计为仅崩溃恢复的软件，可从突发故障中恢复
```
disp-idempotent-operations
```
- 使操作具有幂等性，以便在故障后安全重试

9. Port Binding (MEDIUM)

9. 端口绑定（中）

```
port-self-contained
```
- Make the application completely self-contained with embedded server
```
port-export-via-binding
```
- Export services via port binding using PORT environment variable
```
port-any-protocol
```
- Use port binding to export any protocol not just HTTP

```
port-self-contained
```
- 使应用完全自包含，内置服务器
```
port-export-via-binding
```
- 使用PORT环境变量通过端口绑定暴露服务
```
port-any-protocol
```
- 使用端口绑定暴露任何协议，而不仅仅是HTTP

10. Dev/Prod Parity (MEDIUM)

10. 开发/生产环境一致性（中）

```
parity-minimize-gaps
```
- Minimize gaps between development and production environments
```
parity-same-backing-services
```
- Use the same type and version of backing services in all environments
```
parity-deploy-frequently
```
- Deploy frequently to minimize the time gap
```
parity-developers-deploy
```
- Involve developers in deployment to minimize personnel gap

```
parity-minimize-gaps
```
- 最小化开发与生产环境之间的差异
```
parity-same-backing-services
```
- 在所有环境中使用相同类型和版本的后端服务
```
parity-deploy-frequently
```
- 频繁部署以最小化时间差异
```
parity-developers-deploy
```
- 让开发者参与部署以缩小人员差异

11. Logging (MEDIUM)

11. 日志记录（中）

```
log-event-streams
```
- Treat logs as event streams not files
```
log-no-routing
```
- Never route or store logs from within the application
```
log-structured-format
```
- Use structured logging for machine-readable event streams
```
log-unbuffered-stdout
```
- Write logs unbuffered to stdout for real-time streaming

```
log-event-streams
```
- 将日志视为事件流而非文件
```
log-no-routing
```
- 绝不从应用内部路由或存储日志
```
log-structured-format
```
- 使用结构化日志实现机器可读的事件流
```
log-unbuffered-stdout
```
- 无缓冲地将日志写入stdout以实现实时流式传输

12. Admin Processes (MEDIUM)

12. 管理进程（中）

```
admin-one-off-processes
```
- Run admin tasks as one-off processes not special scripts
```
admin-same-environment
```
- Run admin processes against a release with same codebase and config
```
admin-repl-access
```
- Provide REPL access for debugging and data inspection

```
admin-one-off-processes
```
- 将管理任务作为一次性进程运行，而非特殊脚本
```
admin-same-environment
```
- 使用相同代码库和配置的发布版本运行管理进程
```
admin-repl-access
```
- 提供REPL访问以进行调试和数据检查

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	版本与参考信息