Bfe Rd Workflow

BFE 代码库研发流程

本 Skill 适用于在 bfe/ 目录中新增或修改 BFE 功能（例如 AI Gateway 的多 API-Key 会话亲和性、限流、计费、路由、协议支持等）的完整研发流程。

触发语

当用户提出以下类型请求时启用本流程：

• “我要实现 xxx 功能”
• “请帮我完成 xxx 的代码与测试”
• “请在 BFE 中增加/修改 xxx”

执行原则

1. 分阶段暂停确认：本流程将研发拆分为多个 Phase。每个 Phase 执行完毕后，必须暂停并等待用户确认“可以继续”后，再进入下一个 Phase。不要在未获得用户确认的情况下自动推进到下一阶段。
2. Git 提交前确认：在任何 git commit、git push 或其他会改变 Git 仓库状态的操作之前，必须先向用户说明变更内容并取得明确同意。禁止自动执行 Git 提交或推送。
3. Git push 默认目标为 origin：如果获得用户授权执行 git push，默认推送到 origin 远程仓库，而不是 upstream。除非用户明确指定其他 remote，否则不使用 upstream。

研发阶段

Phase 0. 需求澄清与范围界定

1. 让用户明确：
   • 功能目标（一句话描述）
   • 验收标准（必须通过的测试/行为）
   • 影响范围（是否改配置协议、是否改 Redis/状态、是否影响既有请求路径）
2. 判断是否为“非平凡改动”（多文件、有架构选择、用户偏好影响实现）：
   • 是 → 调用 EnterPlanMode，先出设计文档/plan 再执行。
   • 否 → 直接进入 Phase 1。

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 1. 修改 modifications 文档

BFE 侧的改动必须在 bfe/docs/zh_cn/modifications/ 留下修改说明，便于后续维护与审计。

1. 在 bfe/docs/zh_cn/modifications/ 下新建日期化目录，例如：

   bfe/docs/zh_cn/modifications/2026-08-26-ai-key-session-affinity/
   

2. 在该目录下创建 design-changes.md，包含：
   • 背景与目标
   • 主要改动点（数据结构、模块行为、新增字段）
   • 配置影响
   • 兼容性说明
3. 如已有同主题目录，则更新其中的文档，不要重复创建。

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 2. 更新 configuration 文档

如果改动涉及配置文件（cluster_conf.data、mod_*.conf、bfe.conf 等），必须同步更新中英文配置文档：

1. 中文：bfe/docs/zh_cn/configuration/
2. 英文：bfe/docs/en_us/configuration/

更新原则：

• 新增字段要说明类型、默认值、是否必填、示例。
• 修改字段要说明前后行为差异。
• 两个语言目录尽量保持内容一致。

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 3. 更新 sys_design 文档

如果改动涉及系统设计、协议交互或状态存储，需要更新 bfe/docs/zh_cn/sys_design/：

1. 查找现有相关文档（例如 multi_api_key.md）。
2. 在文档中新增/修改对应章节，说明：
   • 方案选型
   • 数据流
   • 状态存储（如 Redis key 格式、TTL）
   • 边界情况与优化
3. 如需新增独立文档，直接创建 .md 文件，并在相关文档中建立链接。

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 4. 代码实现

1. 阅读相关源码，确认：
   • 配置结构体（bfe_config/bfe_cluster_conf/cluster_conf/）
   • 模块加载与处理逻辑（bfe_modules/mod_*）
   • 反向代理与 Key 选择逻辑（bfe_server/reverseproxy.go 及相关测试）
2. 做最小改动，优先匹配现有代码风格：
   • 不引入未使用的依赖。
   • 不修改与本次需求无关的逻辑。
3. 关键实现完成后，先跑模块级单元测试：

   cd bfe
   go test ./bfe_server/... ./bfe_modules/<相关模块>/...
   

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 5. 编写集成测试设计文档

BFE 的集成测试设计文档位于 bfe/tests/integration/测试设计文档/。在写测试代码之前，先补充对应场景的设计文档，便于后续维护与评审。

1. 在 bfe/tests/integration/测试设计文档/ 下新建 scenario 目录，命名规范：

   scenario-SC<序号>-<简短中文描述>
   

2. 编写 场景说明.md，包含：
   • 场景背景与目的
   • 运行模式
   • 涉及的 BFE 配置文件
   • 测试 Cluster 与关键配置（AIConf、KeyPolicy、路由表等）
   • 测试例列表
   • 每个测试例的详细说明（目的、前置条件、请求构造、执行步骤、预期结果、清理）
   • 公共基础设施
   • 与其他场景的依赖关系
3. 为每个测试例编写独立的 TC-<序号>-<测试例名称>.md，结构与现有 TC 文档保持一致。
4. 更新 bfe/tests/integration/测试设计文档/测试场景总体说明.md：
   • 在“场景清单”中新增一行；
   • 在“场景与测试例对应关系”中新增该 scenario 的 TC 列表。

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 6. 编写集成测试代码

BFE 的集成测试代码位于 bfe/tests/integration/implementation/。

1. 选择最接近的现有 scenario 作为模板（例如需要 Redis 的可参考 scenario-SC07-ai-rate-limit-redis-key）。
2. 新建 scenario 目录，命名规范：

   scenario-SC<序号>-<简短英文描述>
   

3. 复制模板后，修改 testdata/ 中的：
   • server_data_conf/host_rule.data：host
   • server_data_conf/route_rule.data：cluster
   • cluster_conf/gslb.data：cluster 名称
   • mod_ai_route/ai_route.data：apikey owner / route binding
   • mod_ai_token_auth/mod_ai_token_auth.conf、mod_ai_rate_limit/mod_ai_rate_limit.conf 等
4. 编写 _test.go，覆盖：
   • 正常路径
   • 功能开关开启/关闭对比
   • 边界场景（单 Key、多 ClientKeyId、BFE 重启后状态保持、错误码/降级）
5. 运行集成测试：

   cd bfe
   go test ./tests/integration/implementation/scenario-SC<xx>-<描述>/... -v
   

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 7. 回归验证

1. 运行本次新增 scenario 的测试。
2. 运行与被改动模块相关的既有 scenario：
   • 多 API-Key 轮换：scenario-SC02-multi-api-key
   • Redis 限流：scenario-SC07-ai-rate-limit-redis-key
3. 运行相关单元测试：

   go test ./bfe_server/... ./bfe_modules/mod_ai_route/... ./bfe_modules/mod_ai_token_auth/...
   

4. 如有失败，优先修复；修复后再次回归，直到全部通过。

完成本阶段后暂停，等待用户确认后再进入下一阶段。

Phase 8. 收尾与总结

1. 检查是否有注释/文档描述的是旧行为，及时同步更新。

2. 向用户汇报：

   • 改动了哪些文件
   • 新增/修改了哪些测试
   • 验证结果
   • 仍存在的风险或待决策点（如有）

3. Git 提交前必须人工确认：如果用户要求或流程需要执行 git commit、git push 等 Git 操作，必须先向用户清晰说明本次提交内容（包含文件清单与主要变更摘要），并取得明确同意后再执行。禁止在未获授权的情况下自动提交或推送。获得授权后，git push 默认推送到 origin，不要推送到 upstream，除非用户明确指定。

常见陷阱

• cluster 名称不一致：route_rule.data、gslb.data、ai_route 中的 cluster 名称必须一致，否则 BFE 启动会报 no backend conf。
• ApikeyRouteTableBindings 遗漏：新增 client apiKey 时，必须在 mod_ai_route/ai_route.data 的 ApikeyRouteTableBindings 中为其绑定路由表。
• Redis 绑定 key 格式：确认代码中实际使用的 key 格式（如 bfe:ai:key_affinity:<cluster>:<client_key_id>）。
• 单 Key 优化：如果实现了“单 Key 不走 Redis”，需要同时避免读和写，否则集成测试里 Exists 会误判。
• BFE 端口冲突：集成测试里 processEnv.StartBFE 会自动分配端口，不要手动写死。

推荐命令速查

# 模块单元测试
cd bfe
go test ./bfe_server/... ./bfe_modules/mod_ai_route/... ./bfe_modules/mod_ai_token_auth/...

# 单个集成测试场景（详细日志）
go test ./tests/integration/implementation/scenario-SC<xx>-<描述>/... -v

# 相关场景回归
go test ./tests/integration/implementation/scenario-SC02-multi-api-key/...
go test ./tests/integration/implementation/scenario-SC07-ai-rate-limit-redis-key/...