feat(apigw-manager): support merging extra resource files

[Han-Ya-Jun]

变更说明

支持将手动配置的路由合并到自动生成的 resource.yaml 文件中。

新增功能

1. merge_extra_resources 函数：加载 YAML 文件并将 paths/components 合并到主 schema 中
2. --extra-resource-file 命令行参数：支持指定多个额外资源文件（可多次使用）
3. BK_APIGW_EXTRA_RESOURCE_FILES Django 设置：支持在 Django 设置中配置默认文件路径列表
4. 重复检测：验证没有重复的 path+method 组合或组件名称，冲突时直接报错
5. 路径解析：相对路径会基于 BASE_DIR 进行解析

测试覆盖

• 8 个单元测试覆盖 merge_extra_resources 函数的各种场景
• 2 个集成测试验证命令行参数和 Django 设置的集成
• 覆盖正常合并、重复检测、文件不存在、格式无效等场景

使用示例

# 使用命令行参数
python manage.py generate_resources_yaml --extra-resource-file=manual_routes.yaml

# 使用多个文件
python manage.py generate_resources_yaml --extra-resource-file=file1.yaml --extra-resource-file=file2.yaml

# 在 Django 设置中配置
BK_APIGW_EXTRA_RESOURCE_FILES = ["manual_routes.yaml", "another_file.yaml"]

额外资源文件格式

paths:
  /api/v1/manual/{id}/:
    get:
      operationId: v1_manual
      description: 手动配置的 API
      x-bk-apigateway-resource:
        backend:
          name: default
          method: get
          path: /api/v1/manual/{id}/

components:
  schemas:
    ManualSchema:
      type: object
      properties:
        id:
          type: integer

[wklken]

PR Review

Review Scope

• PR: feat(apigw-manager): support merging extra resource files #287
• Repo: TencentBlueKing/bkpaas-python-sdk
• Base: master
• Worktree: .worktrees/review-pr-287-codex-20260605T002120
• Source of truth: latest fetched PR head in local worktree

变更概览

• generate_resources_yaml 新增 --extra-resource-file 参数，支持从命令行传入一个或多个额外资源文件。
• 新增 BK_APIGW_EXTRA_RESOURCE_FILES 设置项，允许通过 Django settings 配置默认额外资源文件。
• 新增 merge_extra_resources，把额外文件里的 paths 和 components 合并进生成的 schema，并对重复的 path+method 与组件名做冲突报错。
• 增加了对应单元测试和 CHANGE.md 记录。

历史评论核对

• 已修复/不再适用: 无历史评论。
• 仍然存在: 无。
• 无法从当前代码确认: 无。

发现的问题

未发现 Blocking / Important / Suggestion 级别的问题。

优点

• 变更范围集中，命令入口、合并逻辑、测试和变更日志对应关系清楚。
• 冲突检测覆盖了重复 path+method 和重复组件名，失败路径会明确抛出 CommandError。
• 新增测试覆盖了合并路径、组件、重复冲突、文件不存在、格式非法、命令参数和 settings 集成。

测试与文档建议

• 已在本地 review worktree 执行 PYENV_VERSION=apigw-manager make test，结果为 272 passed。
• 当前 sdks/apigw-manager/Makefile 没有 lint 目标，因此未运行单独 lint。

结论

基于最新 PR head 和本地测试结果，这个 PR 暂未发现需要修改后再合入的问题。

[from-codex local repo]