12-Factor App
构建现代 SaaS 应用的 12 条设计原则，云原生应用开发的方法论基础。
[!info] related notes
- 所属 MOC: 云原生 MOC
- 前置概念: cloud-native-development
- 并列概念: cloud-native-resilience, cloud-native-security
- 实践: BodySense 云原生实践 MOC
12-Factor App
一句话定义
12-Factor App 是一套用于构建现代、可扩展、可维护 SaaS 应用的方法论，由 Heroku 联合创始人 Adam Wiggins 于 2011 年提出。它定义了 12 条设计原则，是云原生应用开发的基石。
12 条因素
1. Codebase — 一份代码，多份部署
一份代码（tracked in version control）对应多个部署（dev、staging、prod）。不同环境的差异通过配置（因素 3）体现，而不是不同的代码分支。
2. Dependencies — 显式声明依赖
所有依赖必须显式声明，不能隐式依赖系统级包。
- Node.js:
package.json - Go:
go.mod - Python:
pyproject.toml/requirements.txt
3. Config — 配置存于环境变量
应用在不同环境间变化的配置（数据库地址、API Key、外部服务 URL）应存储在环境变量中，而非代码里硬编码。
原则：代码不变，配置变。
4. Backing Services — 视后端服务为附加资源
数据库、消息队列、SMTP、缓存等后端服务，应通过 URL（统一资源定位符）连接，与本地文件一样对待。切换服务只需改 URL，不改代码。
5. Build/Release/Run — 严格分离构建和运行
- Build 阶段：代码 → 可执行包（如 Docker 镜像）
- Release 阶段：可执行包 + 配置 → 唯一发布版本
- Run 阶段：在目标环境运行发布版本
每个 Release 有唯一版本号，支持快速回滚。
6. Processes — 进程无状态
进程不存储任何本地状态。会话、缓存、任务队列等都应存入外部服务（Redis、数据库、对象存储）。进程可以随时销毁和重建。
7. Port Binding — 通过端口绑定提供服务
应用通过绑定端口来对外提供 HTTP 服务，而非依赖外部 Web 服务器注入。应用自包含，可以被其他应用作为后端服务使用。
8. Concurrency — 通过进程模型扩展
通过增加进程数量来扩展（水平扩展），而非增大单进程（垂直扩展）。不同类型的进程可以独立扩展。
9. Disposability — 快速启动，优雅停机
- 快速启动：进程可以在几秒内启动，适合弹性扩缩容
- 优雅停机：收到 SIGTERM 后，处理完当前请求，关闭连接，然后退出
- 不会因为突然退出导致数据损坏
10. Dev/Prod Parity — 保持开发/生产环境尽可能一致
缩小开发环境与生产环境之间的差异：
- 时间差异：代码提交后尽快部署
- 人员差异：开发者参与部署和运维
- 工具差异：开发和生产使用相同的技术栈
Docker 容器化是实现这一点的关键手段。
11. Logs — 视日志为事件流
应用不管理日志文件，只将日志作为事件流输出到 stdout/stderr。由运行环境负责收集、路由、存储和分析日志。
12. Admin Processes — 后台管理任务作为一次性进程
数据库迁移、脚本任务等管理操作，应作为一次性进程运行，与应用进程共享代码库和配置。
与云原生的关系
12-Factor App 是云原生应用设计的方法论基础。它描述的不是具体技术，而是设计原则。Kubernetes、Docker、CI/CD 等云原生技术栈，本质上都是为了让这些原则更容易落地。