3、资源清单管理：API资源清单的编制、版本管理、资源命名规范

API资源清单是网关交付验收的核心交付物之一，它记录了所有被网关代理的后端服务、接口路径、请求方法、参数约束及归属信息。一份规范、完整的资源清单，直接决定了后续运维排障、版本追溯和自动化测试的效率。本章从编制方法、版本管理策略和命名规范三个维度展开。

3.1 资源清单的编制

资源清单的编制应遵循“一服务一表、一接口一行”的原则，确保每个API端点都有唯一的标识和完整的元数据。推荐使用YAML或JSON格式存储，便于版本管理和自动化解析。

3.2 版本管理

API资源清单的版本管理应与网关配置版本、后端服务版本解耦但保持关联。推荐采用语义化版本（SemVer）策略：

• 主版本号：当资源清单结构发生不兼容变更时递增（如新增必填字段、删除字段）。
• 次版本号：当新增资源或向后兼容的字段扩展时递增。
• 修订号：当修正描述错误、路径拼写错误或补充元数据时递增。

版本管理流程应包含以下环节：

1. 基线锁定：每次网关发布前，将当前资源清单打上版本标签（如 v2.1.0），并归档至版本仓库。
2. 变更记录：在清单头部维护 changelog 字段，记录每次变更的日期、作者和变更摘要。
3. 差异审计：使用 diff 工具对比两个版本间的资源路径、方法、参数差异，确保无遗漏或误删。

3.3 资源命名规范

统一的资源命名规范是降低团队沟通成本、提升自动化工具解析效率的基础。以下规范适用于RESTful API资源路径的命名：

3.4 资源清单与命名规范的关系图

下图展示了资源清单编制、版本管理与命名规范三者之间的协作流程：

3.5 资源清单示例（YAML片段）

以下是一个符合命名规范、包含版本元数据的资源清单示例：

# API资源清单 - 订单服务
# 版本: v2.1.0
# 更新日期: 2025-03-20
# 变更摘要: 新增批量查询接口，废弃v1路径

service:
  id: order-svc-v2
  name: 订单服务
  base_path: /api/v2

resources:
  - path: /orders
    methods: [GET, POST]
    description: 订单列表查询与创建
    auth_type: JWT
    rate_limit: 200 req/min
    status: active

  - path: /orders/{order_id}
    methods: [GET, PUT, DELETE]
    description: 单个订单的查询、更新与删除
    auth_type: JWT
    rate_limit: 100 req/min
    status: active

  - path: /orders/batch
    methods: [POST]
    description: 批量查询订单（新增）
    auth_type: JWT
    rate_limit: 50 req/min
    status: active

  - path: /v1/orders
    methods: [GET]
    description: 旧版订单查询（已废弃）
    auth_type: 
    rate_limit: 50 req/min
    status: deprecated
    alias: /api/v1/orders