3. 接口发布流程设计：发布前的代码审查、CI/CD流水线、灰度发布策略

接口发布是BFF层变更到达生产环境的最后一道关卡。与后端核心服务不同，BFF直接面向客户端，任何接口契约破坏、响应格式异常或性能退化都会在秒级内被终端用户感知。因此，发布流程必须围绕代码审查、CI/CD流水线和灰度发布策略三个核心环节进行设计。

3.1 发布前的代码审查：契约与安全双关卡

BFF代码审查不能只停留在逻辑正确性层面，必须增加接口契约审查和安全审查两个专项环节。审查清单如下：

3.2 CI/CD流水线：BFF专属的多阶段构建

BFF的CI/CD流水线需要比普通微服务多出接口兼容性检查和客户端模拟测试两个阶段。以下是一个典型的Go BFF流水线设计：

# .gitlab-ci.yml 关键阶段示意
stages:
  - lint
  - unit-test
  - contract-check
  - build
  - integration-test
  - deploy-canary
  - deploy-production

contract-check:
  stage: contract-check
  script:
    - go run tools/contract-checker/main.go \
        --old-spec=api/v1/old/openapi.yaml \
        --new-spec=api/v1/new/openapi.yaml
  only:
    - merge_requests
    - main

integration-test:
  stage: integration-test
  script:
    - docker-compose -f docker-compose.test.yml up -d
    - go test -tags=integration ./test/...
  services:
    - redis:7-alpine
    - postgres:15-alpine

流水线各阶段的核心职责：

• lint：执行 golangci-lint，检查代码风格和常见错误。
• unit-test：运行单元测试，覆盖率阈值不低于80%。
• contract-check：对比新旧OpenAPI规范，检测破坏性变更。
• build：多阶段Docker构建，最终镜像大小控制在100MB以内。
• integration-test：启动依赖服务（Redis、Postgres），运行端到端测试。
• deploy-canary：部署到灰度环境，自动执行冒烟测试。
• deploy-production：全量发布，触发监控告警规则。

3.3 灰度发布策略：从1%到100%的渐进式放量

BFF的灰度发布不能简单按IP或用户ID切分，必须结合客户端版本和接口版本两个维度。推荐使用流量染色 + 版本路由的组合策略：

1. 内部白名单灰度：将公司内部员工、测试账号的流量路由到新版本，验证基础功能。
2. 1% 金丝雀发布：随机选取1%的线上流量，监控错误率和P99延迟。
3. 客户端版本绑定：仅对指定客户端版本（如App v5.2.0以上）开放新接口。
4. 5% → 20% → 50% 阶梯放量：每阶段观察15分钟，确认无异常后继续。
5. 全量发布：100%流量切换，保留旧版本Pod作为回滚目标。

3.4 灰度期间的自动化验证与回滚决策

灰度发布不是简单的流量切换，必须配套自动化验证和回滚决策机制。以下是在灰度期间需要实时监控的关键指标：

3.5 发布流程的完整时序

将上述环节串联起来，一次完整的BFF接口发布流程如下：

1. 开发：在feature分支完成代码开发，编写单元测试和集成测试。
2. 提交PR：触发CI流水线，执行lint、单元测试、契约检查。
3. 代码审查：至少2名Reviewer批准，重点关注接口兼容性。
4. 合并到main：触发完整CI/CD流水线，构建Docker镜像并推送至镜像仓库。
5. 灰度部署：ArgoCD或自研部署系统将新版本部署到灰度命名空间。
6. 灰度验证：自动执行冒烟测试，监控错误率和延迟15分钟。
7. 阶梯放量：按1% → 5% → 20% → 50% → 100%逐步增加流量。
8. 全量发布：确认无异常后，将100%流量切换到新版本。
9. 观察期：全量发布后继续监控30分钟，确保稳定性。