apigee-x-proxy-development

Apigee X API 代理开发

用于在 Google Cloud 的 Apigee X 平台上构建 API 代理的综合技能。涵盖代理开发的完整生命周期：软件包结构、端点配置、流程设计、策略实现、故障处理、JavaScript 扩展、共享流程和高级模式。

此技能涵盖： API 代理软件包编写、策略配置（42 种以上策略类型）、流程执行设计、条件路由、故障处理、JavaScript 调用代码、共享流程和高级开发模式。

此技能不涵盖： Apigee X 部署/预配、CI/CD 管道、Apigee Hybrid 专属配置、GCP 基础设施设置或 Apigee 管理 API 的使用。仅聚焦于代理开发构件。

何时使用此技能

在用户进行以下操作时使用此技能：

• 从头开始构建新的 API 代理软件包
• 编写或配置 Apigee 策略（安全、消息中介、流量管理等）
• 设计流程管道（PreFlow、条件流程、PostFlow、PostClientFlow）
• 配置 ProxyEndpoints、TargetEndpoints 或 RouteRules
• 实现故障处理（FaultRules、DefaultFaultRule、RaiseFault）
• 为 Apigee 代理编写 JavaScript 调用代码
• 创建或使用共享流程
• 调试代理执行或策略错误
• 检查现有代理配置的正确性或最佳实践
• 询问有关 Apigee X 策略行为、流程变量或条件的问题

在用户进行以下操作时，不要使用此技能：

• 将代理部署到 Apigee 环境（请改用部署工具）
• 配置 Apigee Hybrid 运行时基础设施
• 为代理软件包设置 CI/CD
• 通过 API 管理 Apigee 组织、环境或环境组
• 使用非 Apigee API 网关

查阅官方文档

需要查询特定策略语法、验证行为或查找最新变更时：

• 网页搜索：使用 site:cloud.google.com/apigee 将搜索结果限制为 Apigee X 官方文档
• 策略参考：获取 https://cloud.google.com/apigee/docs/api-platform/reference/policies/[policy-name]-policy
• 配置参考：获取 https://cloud.google.com/apigee/docs/api-platform/reference/api-proxy-configuration-reference
• 流程变量：获取 https://cloud.google.com/apigee/docs/api-platform/reference/variables-reference
• 条件：获取 https://cloud.google.com/apigee/docs/api-platform/reference/conditions-reference
• 经过验证的示例：浏览 https://github.com/GoogleCloudPlatform/apigee-samples，查找生产环境模式

重要： 不要使用 docs.apigee.com——这是旧版 Apigee Edge 文档。Apigee X 始终使用 cloud.google.com/apigee。

API 代理软件包快速参考

apiproxy/
├── MyProxy.xml                    # Root proxy definition (name + revision)
├── proxies/                       # ProxyEndpoint definitions
│   └── default.xml
├── targets/                       # TargetEndpoint definitions
│   └── default.xml
├── policies/                      # All policy XML files
│   ├── AM-SetHeaders.xml
│   ├── EV-ExtractPath.xml
│   └── ...
└── resources/                     # Custom code and resources
    ├── jsc/                       # JavaScript files
    ├── java/                      # Java JAR files
    └── xsl/                       # XSLT transformations

策略命名约定

遵循 GoogleCloudPlatform/apigee-samples 中的 [Abbreviation]-[Purpose].xml 模式：

缩写	策略类型	示例
AM	AssignMessage	AM-SetHeaders.xml
EV	ExtractVariables	EV-ExtractUserId.xml
SC	ServiceCallout	SC-CallBackend.xml
RF	RaiseFault	RF-InvalidInput.xml
FC	FlowCallout	FC-AuthSharedFlow.xml
SA	SpikeArrest	SA-ProtectBackend.xml
Q	Quota	Q-DailyLimit.xml
RC	ResponseCache	RC-CacheResponse.xml
LC	LookupCache	LC-GetCachedValue.xml
PC	PopulateCache	PC-StoreValue.xml
IC	InvalidateCache	IC-ClearCache.xml
KVM	KeyValueMapOperations	KVM-GetConfig.xml
JS	JavaScript	JS-TransformResponse.xml
JWT	JWT policies	JWT-GenerateToken.xml
OAuth	OAuthV2	OAuth-VerifyToken.xml
VAK	VerifyAPIKey	VAK-CheckKey.xml
ML	MessageLogging	ML-LogToCloud.xml
DC	DataCapture	DC-CaptureMetrics.xml
CORS	CORS	CORS-AllowOrigins.xml
JTP	JSONThreatProtection	JTP-ValidatePayload.xml
XTP	XMLThreatProtection	XTP-ValidateXML.xml
OAS	OASValidation	OAS-ValidateRequest.xml

完整详情请参阅 proxy_bundle_anatomy.md。

开发工作流

阶段 1：定义代理结构

1. 创建 apiproxy/ 目录，其中包含根 XML 文件、proxies/、targets/、policies/
2. 配置 ProxyEndpoint：设置 BasePath，定义 HTTPProxyConnection
3. 配置 TargetEndpoint：设置后端 URL 或 LoadBalancer
4. 设置 RouteRules，将代理连接到目标

参考：proxy_bundle_anatomy.md、endpoints_and_routing.md

阶段 2：设计流管道

1. 使用动词 + 路径条件，将 API 操作映射到条件流
2. 将安全策略放在 PreFlow 中（对每个请求执行）
3. 将业务逻辑放在条件流中（按操作执行）
4. 将响应标头和缓存放在 PostFlow 中
5. 将 MessageLogging 放在 PostClientFlow 中（即使发生故障也能确保执行——如果代理在到达 PostFlow 前出错，则会跳过 PostFlow）

参考：flows_and_execution.md、flow_variables_and_conditions.md

阶段 3：实施策略

在流中按以下顺序排列——先安全策略，再中介策略，最后流量管理策略：

1. 安全：VerifyAPIKey、OAuthV2、VerifyJWT、AccessControl、威胁防护
2. 中介：ExtractVariables、AssignMessage、转换
3. 流量管理：SpikeArrest、Quota
4. 缓存：ResponseCache（通常放在 PostFlow 响应中）
5. 日志记录：MessageLogging（通常放在 PostClientFlow 中）

参考：policies_security.md、policies_mediation.md、policies_traffic_management.md、policies_caching.md、policies_integration.md

阶段 4：添加故障处理

1. 为已知错误类型（身份验证失败、超出配额、后端错误）定义 FaultRules
2. 添加 DefaultFaultRule 作为兜底规则，并采用一致的错误格式
3. 使用 RaiseFault 处理自定义验证错误
4. 仅在允许策略失败的情况下设置 continueOnError

参考：fault_handling.md

阶段 5：优化和扩展

1. 将可复用的策略序列提取到共享流中
2. 在适当位置添加响应缓存
3. 考虑高级模式：代理链、组合式 API、断路器
4. 仅在策略无法满足需求时，才为复杂转换添加 JavaScript callout

参考：shared_flows.md、javascript_development.md、advanced_patterns.md、anti_patterns_and_best_practices.md

流执行模型

CLIENT REQUEST
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PROXY ENDPOINT                                 │
│  ┌──────────┐  ┌────────────────┐  ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional    │→ │PostFlow │ │
│  │ (Request)│  │ Flows (Request)│  │(Request)│ │
│  └──────────┘  └────────────────┘  └─────────┘ │
│                                                 │
│  RouteRule evaluation → select TargetEndpoint   │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  TARGET ENDPOINT                                │
│  ┌──────────┐  ┌────────────────┐  ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional    │→ │PostFlow │ │
│  │ (Request)│  │ Flows (Request)│  │(Request)│ │
│  └──────────┘  └────────────────┘  └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
  BACKEND SERVICE (request sent, response received)
     │
     ▼
┌─────────────────────────────────────────────────┐
│  TARGET ENDPOINT                                │
│  ┌──────────┐  ┌─────────────────┐ ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional     │→│PostFlow │ │
│  │(Response)│  │ Flows (Response)│ │(Response│ │
│  └──────────┘  └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PROXY ENDPOINT                                 │
│  ┌──────────┐  ┌─────────────────┐ ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional     │→│PostFlow │ │
│  │(Response)│  │ Flows (Response)│ │(Response│ │
│  └──────────┘  └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
CLIENT RESPONSE SENT
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PostClientFlow (async — after response sent)   │
│  Only: MessageLogging, FlowCallout              │
└─────────────────────────────────────────────────┘

关键规则：

• 条件流：只有条件求值结果为 true 的第一个流会执行。顺序很重要。
• PostClientFlow：即使代理出错也会执行。只允许使用 MessageLogging 和 FlowCallout 策略。
• FaultRules：当策略引发故障时执行。跳过剩余的流步骤并进入错误流。

策略目录

流量管理

策略	用途	参考
SpikeArrest	限制请求速率以保护后端	policies_traffic_management.md
Quota	在一段时间内强制执行用量限制	policies_traffic_management.md
ResetQuota	在周期中动态调整配额计数器	policies_traffic_management.md

缓存

策略	用途	参考
ResponseCache	根据请求属性缓存后端响应	policies_caching.md
LookupCache	从通用缓存中检索值	policies_caching.md
PopulateCache	将值存储到通用缓存中	policies_caching.md
InvalidateCache	从缓存中删除条目	policies_caching.md

安全

策略	用途	参考
VerifyAPIKey	验证标头或查询参数中的 API 密钥	policies_security.md
BasicAuthentication	对 Base64 Basic 身份验证凭据进行编码/解码	policies_security.md
OAuthV2	生成/验证 OAuth 2.0 令牌	policies_security.md
GenerateJWT	创建已签名或加密的 JWT 令牌	policies_security.md
VerifyJWT	验证 JWT 签名和声明	policies_security.md
DecodeJWT	在不验证签名的情况下解码 JWT	policies_security.md
HMAC	计算/验证基于哈希的消息身份验证码	policies_security.md
CORS	启用跨源资源共享	policies_security.md
AccessControl	基于 IP 的允许/拒绝规则	policies_security.md
VerifyIAM	基于 Google Cloud IAM 的授权	policies_security.md
JSONThreatProtection	防范恶意 JSON 负载	policies_security.md
XMLThreatProtection	防范恶意 XML 负载	policies_security.md

中介

Policy	用途	参考
AssignMessage	修改／创建请求或响应消息	policies_mediation.md
ExtractVariables	从消息中提取内容并存入变量	policies_mediation.md
HTTPModifier	添加／移除／设置 HTTP 标头和参数	policies_mediation.md
XMLtoJSON	将 XML 负载转换为 JSON	policies_mediation.md
JSONtoXML	将 JSON 负载转换为 XML	policies_mediation.md
JavaScript	执行自定义 JavaScript 代码	javascript_development.md

集成与扩展

Policy	用途	参考
ServiceCallout	在流程中调用外部 REST 服务	policies_integration.md
FlowCallout	调用共享流程	policies_integration.md
ExternalCallout	向外部服务发送 gRPC 请求	policies_integration.md
KeyValueMapOperations	读取／写入键值映射条目	policies_integration.md
ReadPropertySet	将属性集值读入变量	policies_integration.md
AccessEntity	在运行时查找实体配置文件	policies_integration.md
RaiseFault	生成自定义故障响应	fault_handling.md
AssertCondition	评估条件语句	policies_integration.md
MessageLogging	记录到 Cloud Logging 或 syslog	policies_integration.md
PublishMessage	发布到 Pub/Sub 主题	policies_integration.md
DataCapture	将自定义分析数据采集到 Data Collectors	policies_integration.md

验证

Policy	用途	参考
OASValidation	根据 OpenAPI 3.0 规范进行验证	policies_security.md
GraphQL	解析并验证 GraphQL 负载	policies_security.md

AI/LLM

Policy	用途	参考
LLMTokenQuota	限制令牌消耗量	advanced_patterns.md
PromptTokenLimit	限制每个请求的令牌消耗量	advanced_patterns.md
SanitizeUserPrompt	过滤提示词中的有害内容	advanced_patterns.md
SanitizeModelResponse	过滤大模型响应中的有害内容	advanced_patterns.md
SemanticCacheLookup	查找语义相似缓存	advanced_patterns.md
SemanticCachePopulate	根据语义相似度缓存响应	advanced_patterns.md

参考文档

文档	说明
proxy_bundle_anatomy.md	Bundle 目录结构、文件类型、命名约定
endpoints_and_routing.md	ProxyEndpoint、TargetEndpoint、RouteRules、代理链
flows_and_execution.md	Flow 管道、PreFlow/PostFlow/条件 Flow、执行顺序
flow_variables_and_conditions.md	变量系统、条件语法、消息模板
policies_traffic_management.md	SpikeArrest、Quota、ResetQuota
policies_caching.md	ResponseCache、缓存旁路模式、PopulateCache、LookupCache、InvalidateCache
policies_security.md	API 密钥、OAuth 2.0、JWT、CORS、威胁防护、IAM
policies_mediation.md	AssignMessage、ExtractVariables、JSON/XML 转换
policies_integration.md	ServiceCallout、FlowCallout、KVM 深入讲解、PropertySets、日志记录、RaiseFault
load_balancing_and_routing.md	目标服务器、负载均衡算法、运行状况监控器、高级路由
fault_handling.md	FaultRules、DefaultFaultRule、错误 Flow、错误响应
javascript_development.md	JavaScript 对象模型、模式、最佳实践
shared_flows.md	创建和使用共享 Flow、Flow 钩子
advanced_patterns.md	代理链、复合 API、熔断器、AI/LLM
anti_patterns_and_best_practices.md	常见错误、生产环境最佳实践
debugging_and_performance.md	调试会话、跟踪方法、性能优化
multi_tenant_patterns.md	多租户路由、隔离、按租户配置和速率限制
websockets_and_streaming.md	WebSocket 代理、SSE、HTTP 流式传输、超时注意事项
end_to_end_examples.md	4 个完整的代理 Bundle 演练

快速入门：最小代理 Bundle

apiproxy/MinimalProxy.xml

<?xml version="1.0" encoding="UTF-8"?>
<APIProxy name="MinimalProxy" revision="1">
  <DisplayName>Minimal Proxy</DisplayName>
  <Description>Simple passthrough proxy</Description>
</APIProxy>

apiproxy/proxies/default.xml

<?xml version="1.0" encoding="UTF-8"?>
<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/minimal</BasePath>
  </HTTPProxyConnection>

  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>

  <Flows/>

  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>

  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

apiproxy/targets/default.xml

<?xml version="1.0" encoding="UTF-8"?>
<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>https://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>

  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>

  <Flows/>

  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
</TargetEndpoint>

常见开发方案

添加 API 密钥保护

将 VerifyAPIKey 添加到 PreFlow — 所有请求都必须包含有效密钥：

<PreFlow name="PreFlow">
  <Request>
    <Step>
      <Name>VAK-VerifyKey</Name>
    </Step>
  </Request>
</PreFlow>

请参阅 policies_security.md，了解 VerifyAPIKey 策略 XML。

添加 OAuth 2.0

创建令牌端点 Flow，并在资源 Flow 中验证令牌：

<Flow name="token">
  <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
  <Request>
    <Step><Name>OAuth-GenerateToken</Name></Step>
  </Request>
</Flow>
<Flow name="protected-resource">
  <Condition>proxy.pathsuffix MatchesPath "/resource"</Condition>
  <Request>
    <Step><Name>OAuth-VerifyToken</Name></Step>
  </Request>
</Flow>

请参阅 policies_security.md，了解 OAuthV2 策略配置。

添加速率限制

结合使用 SpikeArrest（防护）和 Quota（SLA 强制执行）：

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>SA-ProtectBackend</Name></Step>
    <Step><Name>Q-DailyLimit</Name></Step>
  </Request>
</PreFlow>

请参阅 policies_traffic_management.md。

添加响应缓存

将 ResponseCache 放入 Flow 中 — 它会同时处理缓存查找和填充：

<PostFlow name="PostFlow">
  <Response>
    <Step><Name>RC-CacheResponse</Name></Step>
  </Response>
</PostFlow>

请参阅 policies_caching.md。

添加 CORS

在 PreFlow 中附加 CORS 策略，以处理预检请求和响应标头：

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>CORS-AllowOrigins</Name></Step>
  </Request>
</PreFlow>

请参阅 policies_security.md，了解 CORS 策略 XML。

调用外部服务

使用 ServiceCallout 在请求处理期间调用外部 API：

<Flow name="enrich-request">
  <Request>
    <Step><Name>SC-GetUserProfile</Name></Step>
    <Step><Name>EV-ExtractProfile</Name></Step>
  </Request>
</Flow>

请参阅 policies_integration.md。

构建一致的错误响应

向 ProxyEndpoint 添加 FaultRules + DefaultFaultRule：

<FaultRules>
  <FaultRule name="auth-error">
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
    <Step><Name>AM-AuthError</Name></Step>
  </FaultRule>
</FaultRules>
<DefaultFaultRule>
  <AlwaysEnforce>true</AlwaysEnforce>
  <Step><Name>AM-GenericError</Name></Step>
</DefaultFaultRule>

请参阅 fault_handling.md。

创建和使用共享流

将可复用逻辑提取到共享流中，并通过 FlowCallout 调用：

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>FC-AuthSharedFlow</Name></Step>
  </Request>
</PreFlow>

请参阅 shared_flows.md。

最佳实践摘要

• 策略排序：安全（PreFlow）→ 中介处理 → 流量管理 → 缓存（PostFlow）→ 日志记录（PostClientFlow）
• 命名：策略文件始终使用 [Abbreviation]-[Purpose].xml
• 优先使用策略而非代码：先使用内置策略；只有在策略无法表达相关逻辑时才使用 JavaScript
• 故障处理：每个代理都应有一个 DefaultFaultRule，并采用一致的错误响应格式
• 共享流：将 2 个或更多代理中使用的策略序列提取到共享流中
• 基础路径：使用带版本号的路径（/v1/resource），并确保每个环境中的路径唯一
• 条件：将最具体的条件流放在最前面（匹配到第一个即生效）
• PostClientFlow：始终使用 PostClientFlow 进行 MessageLogging，以确保无论是否发生错误都会执行
• 缓存：将 ResponseCache 上的 ExcludeErrorResponse 设为 true，以避免缓存错误响应
• 大型负载：尽量减少解析大型负载的策略；在直通场景中启用流式处理
• 反模式：完整目录请参阅 anti_patterns_and_best_practices.md