12-factor-app

社区云原生应用最佳实践

构建现代软件即服务应用的全面方法，确保应用具备可移植性、可扩展性和可维护性。包含 12 个类别中的 51 条规则，涵盖从代码库管理到生产环境运维的完整应用生命周期。

适用场景

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

• 设计新的后端服务或 API
• 将应用容器化，以用于 Kubernetes 或 Docker
• 设置 CI/CD 流水线
• 管理不同环境中的配置
• 实施日志记录和监控
• 规划应用扩展策略
• 排查部署或环境问题

按优先级划分的规则类别

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

快速参考

1. 代码库与版本控制（严重）

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

2. 依赖项（严重）

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

3. 配置（严重）

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

4. 后端服务（高）

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

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

• build-separate-stages - 严格分离构建、发布和运行阶段
• build-immutable-releases - 使用唯一标识符创建不可变的发布版本
• build-no-runtime-changes - 绝不在运行时修改代码；更改必须通过新版本发布
• build-complexity-in-build - 将复杂性放在构建阶段，让运行阶段保持精简
• build-artifact-per-commit - 每次提交生成一个构建产物，并在所有环境中部署同一个产物

6. 进程与状态（HIGH）

• proc-stateless-processes - 将应用作为无状态进程运行
• proc-no-sticky-sessions - 绝不使用粘性会话；将会话数据存储在后端服务中
• proc-no-local-filesystem - 绝不假设本地文件系统会在请求之间持久保留
• proc-compile-at-build - 在构建时而非运行时编译和打包资源
• proc-share-nothing - 设计进程，使它们之间互不共享

7. 并发与扩展（HIGH）

• scale-process-model - 通过包含多种进程类型的进程模型进行横向扩展
• scale-process-types - 将工作负载分配给适当的进程类型
• scale-no-daemonize - 绝不将进程转为守护进程或写入 PID 文件；交由进程管理器处理
• scale-horizontal-not-vertical - 优先设计为横向扩展，而非纵向扩展
• scale-process-formation - 将进程编队定义为声明式配置

8. 可弃置性（HIGH）

• disp-disposable-processes - 将进程设计为可弃置，能够随时启动或停止
• disp-fast-startup - 尽量缩短启动时间，以便快速扩展和恢复
• disp-graceful-shutdown - 实现对 SIGTERM 的优雅关机
• disp-crash-only - 将软件设计为仅考虑崩溃的模式，使其能够从突然终止中恢复
• disp-idempotent-operations - 使操作具有幂等性，以便在故障后安全重试

9. 端口绑定（MEDIUM）

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

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

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

11. 日志记录（中）

• log-event-streams - 将日志视为事件流，而非文件
• log-no-routing - 切勿在应用程序内部路由或存储日志
• log-structured-format - 使用结构化日志记录，以便生成机器可读的事件流
• log-unbuffered-stdout - 将日志未经缓冲地写入 stdout，以便实时流式传输

12. 管理进程（中）

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

使用方法

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

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

参考文件

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