fifteen-factor-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fifteen-Factor App Methodology

Fifteen-Factor App 方法论

Overview

概述

The Fifteen-Factor App methodology extends the original Twelve-Factor App principles (created by Heroku in 2012) with three additional factors essential for modern cloud-native applications: API First, Telemetry, and Security.

This methodology provides architectural principles and guidelines for building software-as-a-service applications that are:

Performant - Optimised for speed and efficiency
Scalable - Designed for horizontal scaling without significant changes
Manageable - Easy to deploy, monitor, and maintain
Resilient - Robust against failures with graceful degradation

Fifteen-Factor App方法论在Heroku于2012年提出的原有Twelve-Factor App原则基础上，新增了三个适用于现代云原生应用的关键要素：API First、Telemetry、Security。

该方法论为构建软件即服务（SaaS）应用提供了架构原则与指南，确保应用具备以下特性：

高性能 - 针对速度与效率优化
可扩展性 - 无需大幅修改即可实现水平扩展
易管理性 - 便于部署、监控与维护
高韧性 - 具备故障容错能力，可优雅降级

When to Apply This Methodology

适用场景

Apply the Fifteen-Factor principles during:

Architecture Planning - When designing new applications or microservices
PRP/PRD Creation - When documenting technical requirements and specifications
Code Reviews - When evaluating whether implementations follow best practices
Migration Planning - When modernising legacy applications for cloud deployment
Technical Debt Assessment - When identifying architectural improvements

在以下场景中应应用十五要素原则：

架构规划 - 设计新应用或微服务时
PRP/PRD编写 - 记录技术需求与规格说明时
代码评审 - 评估实现是否符合最佳实践时
迁移规划 - 将遗留应用现代化以适配云部署时
技术债务评估 - 识别架构改进方向时

The Fifteen Factors at a Glance

十五要素概览

Factor	Principle	Key Concept
I. Codebase	One codebase, many deploys	Single repo per app, version controlled
II. Dependencies	Explicitly declare and isolate	No implicit system-wide packages
III. Config	Store in environment	Never hardcode configuration
IV. Backing Services	Treat as attached resources	Databases, caches are swappable resources
V. Build, Release, Run	Strict separation	Immutable releases, no runtime changes
VI. Processes	Stateless and share-nothing	Horizontal scaling, no sticky sessions
VII. Port Binding	Export via port	Self-contained, no runtime injection
VIII. Concurrency	Scale out via process model	Horizontal over vertical scaling
IX. Disposability	Fast startup, graceful shutdown	Maximise robustness
X. Dev/Prod Parity	Keep environments similar	Continuous deployment
XI. Logs	Treat as event streams	Separate generation from processing
XII. Admin Processes	Run as one-off processes	Same environment as app
XIII. API First	Design contracts first	Enable parallel development
XIV. Telemetry	Monitor everything	APM, health checks, domain metrics
XV. Security	Authentication & Authorisation	RBAC, identity per request

要素	原则	核心概念
I. 代码库	单一代码库，多环境部署	每个应用对应单一代码仓库，版本受控
II. 依赖项	显式声明与隔离	无隐式系统级依赖包
III. 配置	存储于环境变量	绝不硬编码配置
IV. 支撑服务	视为附加资源	数据库、缓存为可替换资源
V. 构建、发布、运行	严格分离	不可变发布版本，运行时禁止修改
VI. 进程	无状态、无共享	水平扩展，无粘性会话
VII. 端口绑定	通过端口暴露服务	自包含，无运行时注入
VIII. 并发	通过进程模型扩展	优先水平扩展而非垂直扩展
IX. 可处置性	快速启动、优雅关闭	最大化韧性
X. 开发/生产环境一致性	保持环境相似	持续部署
XI. 日志	视为事件流	日志生成与处理分离
XII. 管理进程	作为一次性进程运行	与应用使用相同环境
XIII. API First	先设计契约	支持并行开发
XIV. Telemetry	全面监控	APM、健康检查、领域指标
XV. Security	认证与授权	RBAC、请求级身份验证

Applying Factors in Planning Sessions

规划会议中的要素应用

When creating a PRP, PRD, or architecture plan, evaluate the design against each factor:

在编写PRP、PRD或架构方案时，需针对每个要素评估设计合理性：

Foundation Factors (I-VI)

基础要素（I-VI）

These establish the baseline for any cloud-native application:

Codebase: Define repository structure and branching strategy
Dependencies: Specify package manager and dependency isolation approach
Config: Plan environment variable strategy and secrets management
Backing Services: Identify all external services and abstraction layers
Build/Release/Run: Design CI/CD pipeline with immutable artifacts
Processes: Ensure stateless design, plan session/state storage

这些要素为所有云原生应用奠定基础：

代码库：定义仓库结构与分支策略
依赖项：指定包管理器与依赖隔离方案
配置：规划环境变量策略与密钥管理方案
支撑服务：识别所有外部服务与抽象层
构建/发布/运行：设计包含不可变制品的CI/CD流水线
进程：确保无状态设计，规划会话/状态存储方案

Operational Factors (VII-XII)

运营要素（VII-XII）

These ensure smooth operation and maintenance:

Port Binding: Define service exposure strategy
Concurrency: Plan horizontal scaling approach
Disposability: Design for container orchestration
Dev/Prod Parity: Minimise environment differences
Logs: Plan logging infrastructure (ELK, Fluentd, etc.)
Admin Processes: Automate one-off tasks

这些要素保障应用的顺畅运营与维护：

端口绑定：定义服务暴露策略
并发：规划水平扩展方案
可处置性：针对容器编排设计
开发/生产环境一致性：最小化环境差异
日志：规划日志基础设施（ELK、Fluentd等）
管理进程：自动化一次性任务

Modern Extensions (XIII-XV)

现代扩展要素（XIII-XV）

These address contemporary requirements:

API First: Define OpenAPI/Swagger contracts before implementation
Telemetry: Plan APM, health endpoints, and observability
Security: Design authentication/authorisation (OAuth2, RBAC)

这些要素应对当下的应用需求：

API First：在实现前定义OpenAPI/Swagger契约
Telemetry：规划APM、健康端点与可观测性方案
Security：设计认证/授权机制（OAuth2、RBAC）

Architecture Checklist

架构检查清单

Use this checklist when reviewing or planning an application:

□ Single codebase in version control
□ All dependencies explicitly declared
□ Configuration externalised to environment
□ Backing services abstracted and swappable
□ Build, release, run stages separated
□ Stateless processes (no sticky sessions)
□ Services self-contained with port binding
□ Designed for horizontal scaling
□ Fast startup and graceful shutdown
□ Dev/staging/prod environments aligned
□ Logs streamed to external aggregator
□ Admin tasks automated and reproducible
□ API contracts defined before implementation
□ Telemetry: APM, health checks, metrics
□ Security: Authentication and authorisation

在评审或规划应用时，使用以下检查清单：

□ 单一代码库已纳入版本控制
□ 所有依赖项均已显式声明
□ 配置已外部化至环境变量
□ 支撑服务已抽象且可替换
□ 构建、发布、运行阶段已分离
□ 进程无状态（无粘性会话）
□ 服务通过端口绑定实现自包含
□ 应用针对水平扩展设计
□ 支持快速启动与优雅关闭
□ 开发/预发布/生产环境保持一致
□ 日志已流转至外部聚合器
□ 管理任务已自动化且可重复执行
□ API契约在实现前已定义
□ Telemetry：已配置APM、健康检查与指标
□ Security：已实现认证与授权

Resources

资源

Detailed documentation for each factor is available in the references directory:

```
references/overview.md
```
- Complete factor summary with diagrams
```
references/original-factors.md
```
- Factors I-XII with implementation examples
```
references/modern-extensions.md
```
- Factors XIII-XV (API First, Telemetry, Security)
```
references/setup-and-tools.md
```
- Tooling recommendations and quick start

To load detailed information about specific factors, read the appropriate reference file. For example, when planning API design, load

references/modern-extensions.md

for API First guidance.

每个要素的详细文档可在参考目录中获取：

```
references/overview.md
```
- 包含图表的完整要素摘要
```
references/original-factors.md
```
- 要素I-XII的实现示例
```
references/modern-extensions.md
```
- 要素XIII-XV（API First、Telemetry、Security）的详细说明
```
references/setup-and-tools.md
```
- 工具推荐与快速入门指南

如需了解特定要素的详细信息，请阅读对应的参考文件。例如，在规划API设计时，可加载

references/modern-extensions.md

获取API First的相关指导。

Searching References

参考文档搜索

For specific implementation patterns, search the references:

API contracts:
```
grep -i "swagger\|openapi" references/
```
Logging patterns:
```
grep -i "log\|fluentd\|elk" references/
```

Security patterns:

grep -i "oauth\|rbac\|authentication" references/

Container patterns:
```
grep -i "docker\|container" references/
```

如需查找特定实现模式，可搜索参考文档：

API契约：
```
grep -i "swagger\|openapi" references/
```
日志模式：
```
grep -i "log\|fluentd\|elk" references/
```

安全模式：

grep -i "oauth\|rbac\|authentication" references/

容器模式：
```
grep -i "docker\|container" references/
```