路由与策略编排最佳实践

1.1 路由级策略的最佳调用顺序（推荐）

1. 创建路由：CreateHttpApiRoute

2. 创建策略：CreatePolicy

3. 挂载策略：CreatePolicyAttachment

4. 发布路由：DeployHttpApi

这是最稳妥的顺序：先把路由实体固定，再绑定策略，最后发布，避免发布后再改策略导致重复发布和状态竞争。

1.2 哪些步骤可以并发

1.3 如何确认生效

• 路由发布结果：查 GetHttpApiRoute 的 deployStatus 是否到 Deployed，并检查 deployErrorMessage。

• 策略挂载结果：查 GetPolicyAttachment 是否返回目标 attachResourceId / attachResourceType。

• 域名绑定结果：查 GetDomain（withStatistics=true）的统计信息，或查路由详情中的 domainInfos。

1.4 Conflict（HTTP 409）高频触发点

• 重复资源：同名服务/域名/API、同一路由名、同资源重复挂载同类策略。

• 状态竞争：路由处于 Deploying/Undeploying 时再次发布或变更。

• 绑定冲突：策略挂载类型不一致、同一策略跨环境/网关不符合约束。

2.1 创建/查询服务（CreateService / GetService）

详细 API 文档：

• CreateService

• GetService

POST CreateService
Content-Type: application/json

{
  "gatewayId": "gw-xxx",
  "sourceType": "DNS",
  "serviceConfigs": [
    {
      "name": "orders-backend",
      "addresses": [
        "orders.backend.svc.cluster.local:80"
      ]
    }
  ]
}

GET GetService

2.2 查询域名（GetDomain）

详细 API 文档：

GetDomain

GET GetDomain
Query: domainId=d-xxx&withStatistics=true

关键参数：

• domainId：域名 ID（d-...）。

• withStatistics：可选，true 时返回域名关联资源统计，便于发布后验收。

2.3 创建域名（CreateDomain）

详细 API 文档：

CreateDomain

POST CreateDomain
Content-Type: application/json

{
  "name": "api.example.com",
  "protocol": "HTTP",
  "gatewayType": "API"
}

关键参数：

• name：必填，域名名称。

• protocol：必填，HTTP 或 HTTPS。

• gatewayType：建议显式传 API（不传会走默认）。

• 若 protocol=HTTPS，需补齐证书相关参数（如 forceHttps、certIdentifier 等）。

3.1 创建策略（域名）（CreatePolicy）

详细 API 文档：

CreatePolicy

POST CreatePolicy
Content-Type: application/json

{
  "name": "domain-ip-whitelist",
  "className": "IpAccessControl",
  "description": "domain level ip whitelist",
  "config": "{\"name\":\"domain-ip-whitelist\",\"ipAccessControlResourceName\":\"api.example.com\",\"ipAccessControlResourceType\":\"Domain\",\"ipAccessControlType\":\"White\",\"ipAccessControlContent\":\"10.0.0.0/8,192.168.0.0/16\",\"enable\":true,\"protocolLayer\":\"L7\"}"
}

关键参数：

• name：必填，策略名（同网关下避免重名）。

• className：必填，策略类型。

• config：必填，JSON 字符串（不是 JSON 对象）。

3.2 创建策略挂载（域名）（CreatePolicyAttachment）

详细 API 文档：

CreatePolicyAttachment

POST CreatePolicyAttachment
Content-Type: application/json

{
  "policyId": "p-xxx",
  "attachResourceId": "d-xxx",
  "attachResourceType": "Domain",
  "gatewayId": "gw-xxx"
}

关键参数：

• policyId：必填，策略 ID。

• attachResourceId：必填，域名 ID（d-...）。

• attachResourceType：必填，域名级固定 Domain。

• gatewayId：必填。

• environmentId：域名级策略不敏感，服务端会统一处理为 *。

4.1 创建 HttpAPI（CreateHttpApi）

详细 API 文档：

CreateHttpApi

POST CreateHttpApi
Content-Type: application/json

{
  "name": "orders-http-api",
  "description": "orders route collection",
  "type": "Http",
  "protocols": [
    "HTTP",
    "HTTPS"
  ]
}

关键参数：

• name：必填，API 名称。

• type：必填，HTTP API 用 Http。

• protocols：可选，不传时通常按默认协议处理。

4.2 创建 HttpAPI 路由（CreateHttpApiRoute）

详细 API 文档：

CreateHttpApiRoute

POST CreateHttpApiRoute
Content-Type: application/json

参数：

• httpApiId：必填。

{
  "environmentId": "env-xxx",
  "name": "orders-route",
  "domainIds": [
    "d-xxx"
  ],
  "match": {
    "path": {
      "type": "Prefix",
      "value": "/orders"
    },
    "methods": [
      "GET",
      "POST"
    ]
  },
  "backendConfig": {
    "scene": "SingleService",
    "services": [
      {
        "serviceId": "svc-xxx",
        "protocol": "HTTP",
        "port": 80,
        "weight": 100
      }
    ]
  }
}

关键参数：

• environmentId、name、match、backendConfig 必填。

• name 要满足格式约束（小写字母/数字/短横线/点，且长度 <= 64）。

• backendConfig.scene=SingleService 时，services 建议仅一个后端。

• domainIds 创建时可为空，但发布时必须有可发布域名。

5.1 创建策略（路由）（CreatePolicy）

与域名级一致，仍使用：

POST CreatePolicy

路由级示例（IpAccessControl）：

{
  "name": "route-ip-whitelist",
  "className": "IpAccessControl",
  "description": "route level ip whitelist",
  "config": "{\"name\":\"route-ip-whitelist\",\"ipAccessControlResourceName\":\"orders-route\",\"ipAccessControlResourceType\":\"GatewayRoute\",\"ipAccessControlType\":\"White\",\"ipAccessControlContent\":\"10.10.0.0/16\",\"enable\":true,\"protocolLayer\":\"L7\"}"
}

5.2 创建策略挂载（路由）（CreatePolicyAttachment）

POST CreatePolicyAttachment
Content-Type: application/json

{
  "policyId": "p-yyy",
  "attachResourceId": "hr-yyy",
  "attachResourceType": "GatewayRoute",
  "environmentId": "env-xxx",
  "gatewayId": "gw-xxx"
}

关键参数：

• attachResourceId：路由 ID，前缀应为 hr-。

• attachResourceType：路由级固定 GatewayRoute。

• environmentId：路由级大多数策略建议显式传；IpAccessControl 是特例可不传。

• gatewayId：必填。

5.3 发布 API（DeployHttpApi）

详细 API 文档：

DeployHttpApi

POST DeployHttpApi
Content-Type: application/json

参数：

• httpApiId：必填。

{
  "routeId": "hr-yyy",
  "isInternalRoute": false
}

说明：

• HTTP API 场景下，核心参数是 routeId。

• 接口走异步发布语义，调用成功不等于已生效，需轮询状态确认。

5.4 可选：发布前冲突预检（DetectHttpApiConflicts）

POST DetectHttpApiConflicts
Content-Type: application/json

参数：

• httpApiId：必填。

{
  "routeId": "hr-yyy",
  "isInternalRoute": false
}

建议：

• 该预检尤其适合“自定义域名 + 多团队并行改路由”的场景。

• 发现冲突后先调整路径/方法/域名绑定，再执行 DeployHttpApi。