How to correctly name dev/staging/prod environments in code?

Question

**常见技术问题：** 团队在代码中硬编码环境标识（如 `if env == 'staging'` 或 `ENVIRONMENT = 'prod'`），导致配置耦合、部署易出错——例如误将 staging 配置推至 prod，或因命名不一致（`'dev'`/`'development'`/`'local'` 混用）引发条件判断失效；更严重的是，某些服务依赖环境名生成资源 ID（如 AWS S3 bucket 名 `myapp-${env}-logs`），若命名未遵循统一规范（如大小写、分隔符、保留字冲突），会导致跨环境资源污染或创建失败。此外，CI/CD 流水线、日志系统、监控告警常通过环境名路由行为，一旦命名不标准化（如前端用 `staging`、后端用 `stage`、Infra 用 `preprod`），将造成可观测性断裂与故障定位困难。如何设计一套**可扩展、不可变、语义明确且全栈一致**的环境命名策略，并在代码、配置、工具链中安全落地？

Answer 1

```html

一、问题表征：硬编码环境标识的“七宗罪”

• 耦合性爆炸：业务逻辑中散落 if env == 'staging'，导致配置与代码双向污染；
• 命名混沌：同一环境在不同组件中表现为 'dev' / 'development' / 'local'，条件分支永远漏判；
• 资源ID冲突：S3 bucket 名 myapp-${env}-logs 在 ENV=Prod 下生成 myapp-Prod-logs（AWS 不允许大写），创建失败；
• 可观测性断裂：前端日志打标 env: staging，后端指标上报 env: stage，监控告警无法关联链路；
• CI/CD 路由失效：流水线脚本用 if [[ $ENV == "preprod" ]] 触发灰度发布，但 Infra Terraform 中定义为 environment = "staging"；
• 安全边界模糊：硬编码 if env == 'prod' then enable_payment_gateway()，测试分支误提 prod 环境变量即触发真实支付；
• 演进僵化：新增 canary 环境需手动修改 17 个服务的 if 判断、4 类配置模板、3 套告警规则。

二、根因分析：为什么“统一命名”总在落地时崩塌？

表面是命名不一致，深层是缺乏契约治理机制：

维度	典型反模式	后果
语义层	用 stage 表示预发布，preprod 表示准生产，staging 表示集成测试	同一词义分裂为三套实现
语法层	大小写混用（PROD/prod）、分隔符不一（dev-us-east/dev_us_east）、含空格或特殊字符	云资源创建失败、K8s label 校验拒绝
生命周期层	未区分 部署环境（runtime）与 配置环境（build-time），如 CI 构建时读取 ENV 决定打包策略，运行时又读一次	构建产物不可复现，回滚即故障

三、设计原则：四维不可变契约

1. 可扩展性：支持未来新增环境（如 canary, dr, demo）无需重构判断逻辑；
2. 不可变性：环境标识一旦生成即固化为全局唯一 ID（如 env-001），禁止运行时计算或拼接；
3. 语义明确性：名称直接反映其 隔离级别（shared/isolated）、数据敏感度（synthetic/production）、变更风险（immutable/ephemeral）；
4. 全栈一致性：从开发本地 .env.local → CI job name → K8s namespace → CloudFormation stack name → Prometheus label 全链路强制同源。

四、落地架构：三层收敛模型

graph LR
  A[源头：中央环境注册中心] -->|颁发不可变ID| B[中间层：环境元数据服务]
  B --> C[代码层：EnvContext SDK]
  B --> D[配置层：Schema-Driven Config Bundle]
  B --> E[工具链层：CLI + Pre-commit Hook + CI Gate]
  C --> F[业务代码零硬编码]
  D --> G[所有YAML/Terraform/JSON配置引用${env_id}]
  E --> H[PR合并前校验env_name合规性]

五、标准化命名规范（v1.0）

采用 <purpose>-<scope>-<region> 三段式，全部小写、短横线分隔、无保留字：

• prod-global：面向真实用户的全球生产环境（强隔离、审计级日志）；
• staging-shared-us：跨团队共享的美国预发布环境（数据脱敏、自动销毁）；
• dev-isolated-eu：欧洲开发者独占的隔离环境（快照备份、按需启停）；
• canary-prod-us-east：生产流量 5% 的金丝雀发布环境（与 prod 同数据源，独立资源栈）；
• demo-ephemeral-apac：亚太区客户演示用临时环境（TTL=24h，自动清理）。

六、安全落地关键实践

1. 编译期注入：通过构建参数（而非运行时 env var）注入 ENV_ID=env-007，杜绝 os.Getenv("ENV")；
2. SDK 封装：提供 EnvContext.IsProduction() / EnvContext.ResourcePrefix() 接口，内部查表映射，业务代码只调方法；
3. 基础设施即代码强约束：Terraform module 输入变量 environment_id 必须匹配正则 ^env-[0-9]{3}$；
4. 可观测性对齐：OpenTelemetry exporter 自动注入 env.id, env.purpose, env.scope 三个标准标签；
5. 变更熔断：当检测到新环境名未在中央注册中心备案，CI 流水线立即失败并推送 Slack 告警至 Platform Team。

```