Back to Details

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:
  1. Architecture Planning - When designing new applications or microservices
  2. PRP/PRD Creation - When documenting technical requirements and specifications
  3. Code Reviews - When evaluating whether implementations follow best practices
  4. Migration Planning - When modernising legacy applications for cloud deployment
  5. Technical Debt Assessment - When identifying architectural improvements
在以下场景中应应用十五要素原则：
  1. 架构规划 - 设计新应用或微服务时
  2. PRP/PRD编写 - 记录技术需求与规格说明时
  3. 代码评审 - 评估实现是否符合最佳实践时
  4. 迁移规划 - 将遗留应用现代化以适配云部署时
  5. 技术债务评估 - 识别架构改进方向时

The Fifteen Factors at a Glance

十五要素概览

FactorPrincipleKey Concept
I. CodebaseOne codebase, many deploysSingle repo per app, version controlled
II. DependenciesExplicitly declare and isolateNo implicit system-wide packages
III. ConfigStore in environmentNever hardcode configuration
IV. Backing ServicesTreat as attached resourcesDatabases, caches are swappable resources
V. Build, Release, RunStrict separationImmutable releases, no runtime changes
VI. ProcessesStateless and share-nothingHorizontal scaling, no sticky sessions
VII. Port BindingExport via portSelf-contained, no runtime injection
VIII. ConcurrencyScale out via process modelHorizontal over vertical scaling
IX. DisposabilityFast startup, graceful shutdownMaximise robustness
X. Dev/Prod ParityKeep environments similarContinuous deployment
XI. LogsTreat as event streamsSeparate generation from processing
XII. Admin ProcessesRun as one-off processesSame environment as app
XIII. API FirstDesign contracts firstEnable parallel development
XIV. TelemetryMonitor everythingAPM, health checks, domain metrics
XV. SecurityAuthentication & AuthorisationRBAC, 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/